1. 代码开发工具生成的字体,为什么到了 LVGL v9.1 就一片空白
上个月把一块 320×240 的小屏从旧版本 LVGL 挪到 v9.1,界面重画、事件重接,最后卡在最不该卡的地方:所有中文变成一排空白方框。字库是用 LvglFontTool V0.5 生成的内部字体,glyph_bitmap[] 直接编进固件,不依赖文件系统,按说不该出问题。真正坏掉的是 v9.1 换了字形取模的回调签名——__user_font_get_glyph_dsc 和 __user_font_get_bitmap 这两个函数得按新结构体重写一遍,输出也不再是裸指针,而是往调用方递过来的 lv_draw_buf_t 里填像素。这篇按我实际改过的顺序,把从工具导出到屏幕上出字这条链完整走一遍,包含两份回调的实现、必须对齐的几个字段,以及我踩过的坑。适合已经在用 LVGL、要往固件里塞中文字库的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 读懂代码开发工具的产物:LvglFontTool V0.5 输出的三张表
动手改回调之前,得先弄清楚 LvglFontTool V0.5 到底往 .c 文件里写了什么。这一步跳过去,后面就是抄代码碰运气——抄对了不知道为什么对,抄错了连从哪查都不知道。
2.1 导出时选的四个参数,直接决定回调怎么写
导出面板上有四项必须在下笔前定死:字符范围、每像素位数 bpp、输出格式、是否压缩。它们不是随手勾的,因为工具会把这些选择原样记进生成的 lv_font_fmt_txt_dsc_t,而 bpp 和 bitmap_format 两个字段就是 __user_font_get_bitmap 里所有分支的判据。
字符范围决定 cmaps 长什么样。工具会把选中的码点整理成「区间 + 列表」的形式:连续的一段用 range_start 和 range_length 描述,区间里真正收录的字再列进 unicode_list,条数记在 list_length。所以汉字别贪多,选 3500 常用字,cmaps[0] 就是一个大区间配一张几千项的 unicode_list,后面必须用二分查,线性扫一遍太贵。
bpp 决定灰度档位。1bpp 只有黑白两值,小字号点阵够用,体积最小;4bpp 有 16 级灰度,抗锯齿边缘过得去,体积是 1bpp 的四倍;2bpp 是折中;8bpp 一般只在超大字号或者对边缘极挑的场景才用。我这边正文用 4bpp、图标字体用 1bpp,一份固件里混着放完全没问题,因为每个字体对象各自带自己的 fdsc。
输出格式一定要选「内部字体 / C 数组」,目标是编进固件而不是挂到文件系统上。生成结果至少包含 glyph_bitmap[]、glyph_dsc[]、cmaps[] 三组数据和一份 lv_font_fmt_txt_dsc_t 描述结构。格式选成 bin 文件,后面这套回调就白写了——那是另一条走文件系统的路。
2.2 cmaps、glyph_dsc、glyph_bitmap 各管一段
三张表分工很清楚,但第一次看容易搞混哪张表的下标是什么。
| 表 | 关键字段 | 管什么 | 回调里怎么用 |
|---|---|---|---|
cmaps[] |
range_start、range_length、unicode_list、list_length |
字符码点到字形序号的映射 | 先判范围,再 binsearch 拿到下标 i |
glyph_dsc[] |
adv_w、box_w、box_h、ofs_x、ofs_y、bitmap_index |
每个字形的步进、包围盒、偏移 | 填 dsc_out,并算出位图起点 |
glyph_bitmap[] |
连续字节流 | 字形像素本体 | 用 bitmap_index 定位源地址 |
binsearch 返回的 i 是「字形序号」,它同时是 glyph_dsc[] 的下标。拿到 gdsc 之后,gdsc->bitmap_index 给出该字形在 glyph_bitmap[] 里的位置。从代码写法 &fdsc->glyph_bitmap[gdsc->bitmap_index] 能看出来,这个 index 是字节偏移,不是位偏移,取地址直接索引就行,不用自己除 8 再算余数。
理解了这三者关系,回调要做的事就一句话:码点进来,先翻 cmaps 找到序号,用序号取 glyph_dsc 描述,用描述里的 bitmap_index 取像素。两份回调正好一人管一半。
2.3 先写一段检查代码,把结构体打出来
别急着改回调。先把字体对象挂上,写个函数把关键字段打印到串口,确认工具生成的东西真的按你预期写进去了。这一步花五分钟,能省掉后面两小时的猜。
c复制/* 把字体描述结构里的关键字段打出来,确认导出参数落地正确 */
static void font_probe(const lv_font_t * font)
{
/* font->dsc 就是工具生成的那份 lv_font_fmt_txt_dsc_t */
lv_font_fmt_txt_dsc_t * fdsc = (lv_font_fmt_txt_dsc_t *) font->dsc;
printf("bpp = %d\r\n", fdsc->bpp); /* 1 / 2 / 4 / 8 */
printf("bitmap_format = %d\r\n", fdsc->bitmap_format); /* 0 表示 PLAIN 不压缩 */
printf("range_start = 0x%04X\r\n", fdsc->cmaps[0].range_start);
printf("range_length = %d\r\n", fdsc->cmaps[0].range_length);
printf("list_length = %d\r\n", fdsc->cmaps[0].list_length);
printf("first box = %d x %d\r\n",
fdsc->glyph_dsc[0].box_w, fdsc->glyph_dsc[0].box_h);
}
这段代码只在调试阶段用,正式固件里记得关掉。看输出时抓三个点:bpp 是不是你导出的那个值;bitmap_format 是不是 PLAIN(不是的话,__user_font_get_bitmap 里那条 PLAIN 分支根本进不去);range_start 和 range_length 加起来能不能覆盖你要显示的第一个汉字。我遇到过一次 range_start 是 0x20、range_length 只到 ASCII 区,等于导字库时中文字符集压根没勾上,后面所有代码都是白改。
glyph_dsc[0] 打出来是 0×0 也正常,第一个字形通常是空格或者不可见字符,不用紧张。
2.4 v9.1 为什么必须自己接管取模
旧版本里,字体回调返回的是像素指针,LVGL 自己按字体对象的 bpp 去解释那块内存。v9.1 改成了 get_bitmap(g_dsc, draw_buf) 这种形式,lv_draw_buf_t 由调用方准备好,你的任务是往 draw_buf->data 里按它的行宽写入已经展开好的像素。
这个改动带来两个后果。第一,你输出的数据必须是自己算好 stride 的、目标格式的像素,而不是把源位图指针一交了事。第二,回调签名里带着 draw_buf 但这是标准的输出缓冲约定,源数据仍然要从 resolved_font->dsc 里自己捞——g_dsc->resolved_font 这一句就是拿回字体对象的入口,漏了它后面所有事都无从谈起。
看明白这两点,两份回调的行文顺序就定下来了:dsc 回调负责把「码点」翻译成「像素参数」,bitmap 回调负责把「像素参数」翻译成「内存里的字节」。
3. 重写 __user_font_get_glyph_dsc:先让字形描述对得上
字形描述回调是整条链的第一环。它返回 false,LVGL 就当这个字不存在,直接走缺省字形或者干脆不画;它返回 true 但字段填错,后面 bitmap 回调就拿着错参数去取像素,屏幕上是能出东西的,只不过是错的东西——这种比空白更难查。
3.1 一次查询要走的四步
不管代码怎么写,逻辑永远是这四步:取字体描述、判范围、二分查序号、搬字段。写成骨架大概是这样:
c复制static bool __user_font_get_glyph_dsc(const lv_font_t * font,
lv_font_glyph_dsc_t * dsc_out,
uint32_t unicode_letter,
uint32_t unicode_letter_next)
{
/* 第一步:从字体对象拿回工具生成的描述结构 */
lv_font_fmt_txt_dsc_t * fdsc = (lv_font_fmt_txt_dsc_t *) font->dsc;
/* 第二步:范围前置判断,区间外的码点连二分都不用做 */
if (unicode_letter < fdsc->cmaps[0].range_start ||
unicode_letter > fdsc->cmaps[0].range_start + fdsc->cmaps[0].range_length) {
return false;
}
/* 第三步:在 unicode_list 里二分,得到字形序号 */
int i = binsearch(fdsc->cmaps[0].unicode_list,
fdsc->cmaps[0].list_length,
unicode_letter);
if (i == -1) {
return false;
}
/* 第四步:把 glyph_dsc 里的东西搬到 dsc_out */
const lv_font_fmt_txt_glyph_dsc_t * gdsc = &fdsc->glyph_dsc[i];
dsc_out->adv_w = gdsc->adv_w;
dsc_out->box_h = (uint8_t)gdsc->box_h;
dsc_out->box_w = (uint8_t)gdsc->box_w;
dsc_out->ofs_x = (int8_t)gdsc->ofs_x;
dsc_out->ofs_y = (int8_t)gdsc->ofs_y;
dsc_out->format = fdsc->bpp; /* 关键:告诉下游是几 bpp */
dsc_out->gid.index = unicode_letter; /* 关键:把码点原样带下去 */
dsc_out->is_placeholder = 0; /* 别让 LVGL 当缺字去回退 */
return true;
}
binsearch 的写法和普通有序数组二分一致:拿 unicode_list[mid] 和 unicode_letter 比,小于就往右,大于就往左,命中返回下标,整段走完没找到返回 -1。工具生成时 unicode_list 就是按码点升序排的,别自己再排一遍,排错了下标就和 glyph_dsc[] 对不上,取出来的字全是别人的。
unicode_letter_next 在这个实现里用不上,但签名里得留着——它是给连字和字距调整留的口子,工具生成的字体不做 kerning 就可以忽略。
3.2 五个几何字段的搬运,和那个坑人的强制类型转换
adv_w、box_w、box_h、ofs_x、ofs_y 是字形的几何描述,缺一个都不行。
| 字段 | 含义 | 单位 | 常见错误 |
|---|---|---|---|
adv_w |
光标前进量 | 1/16 像素定点 | 强转 8 位导致大字号步进归零 |
box_w / box_h |
字形包围盒宽高 | 像素 | 和 adv_w 搞混,字间距全乱 |
ofs_x |
包围盒左边缘相对基线原点的偏移 | 像素,可负 | 有符号数被当成无符号 |
ofs_y |
包围盒顶边相对基线原点的偏移 | 像素,可负 | 同上,字整体上移或下移 |
ofs_x 和 ofs_y 一定是有符号的,工具生成时会给 int8_t 强转,照抄即可。真正坑人的是 adv_w。
我第一次是照着流出来的改法写成 dsc_out->adv_w = (uint8_t)gdsc->adv_w;,结果 16px 的字全部挤在一起,几乎重叠。原因很直接:adv_w 在 LVGL 里是 1/16 像素的定点数,一个 16px 宽的字 adv_w 就是 256,强转成 8 位立刻变 0,光标不前进,所有字叠在同一个位置。后来我把强转去掉,直接赋值,让编译器按 dsc_out->adv_w 自己的类型做隐式转换,问题消失。
提示:凡是看到把
adv_w强转成(uint8_t)的写法,先停下来确认字号。小字号可能侥幸不炸,一上大字号就原形毕露。
box_w 和 box_h 强转 uint8_t 一般没问题,字形包围盒很少超过 255 像素;真超过了,说明你在做超大标题字体,那时候得换一套数据结构,不是改个类型能解决的。
3.3 format 和 gid.index:两行漏了全盘皆输
这两行是最容易在看代码时被眼睛跳过去的,因为它们不参与任何计算,看着像可有可无的赋值。实际上它们是两份回调之间的唯一约定。
dsc_out->format = fdsc->bpp; 把源字库的位深告诉下游。如果你不填,dsc_out->format 是调用方传进来的初值,可能是 0 或者其他值,bitmap 回调里所有 if(fdsc->bpp == 4) 这类判断就全部失效,最后走哪条分支全凭运气。表现出来就是:字能出来,但灰度全错,或者干脆整块黑。
dsc_out->gid.index = unicode_letter; 更关键。__user_font_get_bitmap 的第一行就是 uint32_t unicode_letter = g_dsc->gid.index;,它指望从 gid.index 里拿回码点,然后重新查一遍 cmaps。工具生成的字库里,gid.index 本来就是按码点赋的,所以这里原样带下去即可。
要是你把 gid.index 填成字形序号 i,会发生什么?bitmap 回调拿着序号当码点去 binsearch,序号通常落在 0 到几千之间,正好撞进 ASCII 码点的范围,于是查出来一个不相干的字形,屏幕上出现一串莫名其妙的符号。这种错比全屏空白更折磨人,因为你会一直怀疑是字库生成错了,而实际上只是把一个变量填成了另一个变量。
is_placeholder 记得清 0。LVGL 的字体回退链会检查这个标志,置位就表示「这是个占位字形,接着往下找别的字体」,你辛辛苦苦填的尺寸全被忽略。
3.4 挂上去之前先自己空跑一次
回调写完了别急着上屏。在同一个 .c 文件里写个自测函数,手动构造 lv_font_glyph_dsc_t,直接调回调,把结果打出来。
c复制/* 不上屏,单独验证字形查询是否命中 */
static void glyph_dsc_selftest(const lv_font_t * font)
{
lv_font_glyph_dsc_t dsc;
memset(&dsc, 0, sizeof(dsc));
/* 拿一个确定收录在字库里的汉字试 */
if (__user_font_get_glyph_dsc(font, &dsc, 0x4E2D /* 中 */, 0)) {
printf("hit: box=%dx%d adv=%d ofs=(%d,%d) fmt=%d gid=%u\r\n",
dsc.box_w, dsc.box_h, dsc.adv_w,
dsc.ofs_x, dsc.ofs_y,
dsc.format, (unsigned)dsc.gid.index);
} else {
printf("miss\r\n");
}
}
打印出来应该满足几个条件:box_w 和 box_h 是 12 到 16 之间的合理值(取决于你选的字号),adv_w 大约是 box_w 的十六倍上下,fmt 等于你导出时选的 bpp,gid 等于 0x4E2D。
第一次跑出来 box_w = 0,基本就是 cmaps 没收录这个字;gid 打出来是 0,说明 gid.index 那行漏了;fmt 是 0 而你的字库是 4bpp,说明 format 那行漏了。这三条对上了,才轮到写位图回调。
4. 重写 __user_font_get_bitmap:把 1/2/4bpp 展开成 8bpp
位图回调是活儿最多的一段。描述回调只要把参数搬对就行,这里得真的做像素格式转换:把工具生成时按 1、2、4 位打包的紧凑数据,摊平成每像素一字节的 8 位数据,再按 lv_draw_buf_t 的行宽逐行写进去。
4.1 draw_buf 是别人给的,你只负责填
先看清楚入参。g_dsc 是上一环填好的描述,draw_buf 是调用方准备好的输出缓冲。开头三行是固定的:
c复制const lv_font_t *font = g_dsc->resolved_font; /* 从描述反查回字体对象 */
uint32_t unicode_letter = g_dsc->gid.index; /* 拿回码点,注意不是序号 */
uint8_t * bitmap_out = draw_buf->data; /* 输出起点 */
lv_font_fmt_txt_dsc_t * fdsc = (lv_font_fmt_txt_dsc_t *) font->dsc;
resolved_font 这一句不能省。g_dsc 里并没有直接放字体描述指针,得先回到 lv_font_t,再从 font->dsc 取出 lv_font_fmt_txt_dsc_t,后面的 cmaps、glyph_dsc、glyph_bitmap 全在这上面。
bitmap_out 直接取 draw_buf->data,不额外做偏移。字形在包围盒内的位置靠 ofs_x 和 ofs_y 对齐,输出缓冲本身就是这块 box_w × box_h 的矩形,你从第 0 行第 0 列开始写就对了。
4.2 PLAIN 格式下的源数据排布
工具默认导出的是 PLAIN 格式,也就是不压缩的连续位图。判断条件是 fdsc->bitmap_format == LV_FONT_FMT_TXT_PLAIN,非 PLAIN 的走另一条解压路线,这里不涉及。
PLAIN 的排布规则是:按行从上到下,每行内从左到右,每个像素占 bpp 位,行与行之间紧凑排列,不做字节对齐。所以取第 i 个字形的源起点就是 &fdsc->glyph_bitmap[gdsc->bitmap_index],从这个地址往后的 box_w × box_h × bpp / 8 个字节(向上取整)就是它的全部像素。
知道源排布还不够,还得知道目标排布。目标缓冲是 8bpp,每行占 stride 字节,而 stride 不一定等于 box_w——很多平台会按 4 字节对齐把行宽撑大。所以千万别用 box_w 当行宽推进指针,一定用 lv_draw_buf_width_to_stride(box_w, 输出格式) 算出来。
4.3 四条分支:bpp 为 1、2、4、8
完整实现如下,四条分支各自处理一种打包密度:
c复制/* 4bpp 灰度映射:0~15 线性拉到 0~255 */
static const uint8_t opa4_table[16] = {
0, 17, 34, 51, 68, 85, 102, 119,
136, 153, 170, 187, 204, 221, 238, 255
};
/* 2bpp 灰度映射:0~3 线性拉到 0~255 */
static const uint8_t opa2_table[4] = {0, 85, 170, 255};
static const void * __user_font_get_bitmap(lv_font_glyph_dsc_t * g_dsc,
lv_draw_buf_t * draw_buf)
{
const lv_font_t * font = g_dsc->resolved_font;
uint32_t unicode_letter = g_dsc->gid.index;
uint8_t * bitmap_out = draw_buf->data;
lv_font_fmt_txt_dsc_t * fdsc = (lv_font_fmt_txt_dsc_t *) font->dsc;
/* 范围判断:区间外直接返回 NULL,别进二分 */
if (unicode_letter < fdsc->cmaps[0].range_start ||
unicode_letter > fdsc->cmaps[0].range_start + fdsc->cmaps[0].range_length) {
return NULL;
}
int i = binsearch(fdsc->cmaps[0].unicode_list,
fdsc->cmaps[0].list_length,
unicode_letter);
if (i == -1) {
return NULL;
}
const lv_font_fmt_txt_glyph_dsc_t * gdsc = &fdsc->glyph_dsc[i];
int32_t gsize = (int32_t) gdsc->box_w * gdsc->box_h;
if (gsize == 0) {
return NULL; /* 空字形,比如空格 */
}
if (fdsc->bitmap_format == LV_FONT_FMT_TXT_PLAIN) {
const uint8_t * bitmap_in = &fdsc->glyph_bitmap[gdsc->bitmap_index];
uint8_t * row = bitmap_out;
int32_t x, y;
/* 目标缓冲按 8bpp 排,行宽必须按输出格式算,不能拿 box_w 顶 */
uint32_t stride = lv_draw_buf_width_to_stride(gdsc->box_w,
LV_COLOR_FORMAT_A8);
if (fdsc->bpp == 1) {
int32_t bit = 0;
for (y = 0; y < gdsc->box_h; y++) {
for (x = 0; x < gdsc->box_w; x++, bit++) {
/* 从高位到低位取,每 8 个像素吃掉一个源字节 */
uint8_t mask = 0x80 >> (bit & 0x7);
row[x] = (*bitmap_in & mask) ? 0xFF : 0x00;
if ((bit & 0x7) == 7) {
bitmap_in++;
}
}
row += stride;
}
}
else if (fdsc->bpp == 2) {
int32_t bit = 0;
for (y = 0; y < gdsc->box_h; y++) {
for (x = 0; x < gdsc->box_w; x++, bit++) {
/* 每字节 4 个像素,2 位一组 */
int shift = 6 - ((bit & 0x3) << 1);
row[x] = opa2_table[(*bitmap_in >> shift) & 0x3];
if ((bit & 0x3) == 3) {
bitmap_in++;
}
}
row += stride;
}
}
else if (fdsc->bpp == 4) {
for (y = 0; y < gdsc->box_h; y++) {
for (x = 0; x < gdsc->box_w; x++) {
/* 每字节两个像素,高半字节在前 */
if ((x & 0x1) == 0) {
row[x] = opa4_table[(*bitmap_in) >> 4];
} else {
row[x] = opa4_table[(*bitmap_in) & 0x0F];
bitmap_in++;
}
}
row += stride;
}
}
else if (fdsc->bpp == 8) {
for (y = 0; y < gdsc->box_h; y++) {
/* 8bpp 源数据已经是目标格式,整行搬过去 */
memcpy(row, bitmap_in, gdsc->box_w);
bitmap_in += gdsc->box_w;
row += stride;
}
}
else {
return NULL; /* 没实现的位深,宁可不出字也别乱画 */
}
return bitmap_out;
}
return NULL;
}
逻辑说明分几层看。最前面两段判断是防御:范围外的码点和空字形都直接返回 NULL,让 LVGL 走它自己的缺字处理,而不是让你在下面除以零或者读越界。gsize == 0 这条特别容易被忽略,空格、全角标点的包围盒就是 0×0,不拦下来就会进循环但一次都不写,返回值却非空,上层以为拿到了合法位图。
四条 bpp 分支的共同点是「读源、写目标、换行加 stride」。差别只在像素打包密度:1bpp 一个字节 8 个像素,靠 0x80 >> (bit & 0x7) 逐位取;2bpp 一个字节 4 个像素,靠 6 - ((bit & 0x3) << 1) 算出移位量;4bpp 一个字节 2 个像素,高半字节先、低半字节后,读完低半字节才推进源指针;8bpp 什么都不用转,整行 memcpy 最省事。
参数上要盯死 stride。它由 lv_draw_buf_width_to_stride(box_w, LV_COLOR_FORMAT_A8) 算出,含义是「目标缓冲里这一行占多少字节」。宽度 15 像素时,box_w 是 15,但 stride 很可能是 16,差的那一个字节是给对齐留的。用 box_w 推进指针,第二行就会整体左移一列,屏幕上看见的是字形斜着切开,越往下越歪。
4.4 opa4_table 和 opa2_table 的来历
这两张表不是随便写的魔数。4bpp 源数据的取值范围是 0 到 15,目标要的是 0 到 255,线性映射就是 v * 255 / 15,也就是 v * 17。表里那 16 个值正好是 17 的等差数列:0、17、34、51……255,用查表代替乘法,在没硬件乘法器的单片机上省的不只是几个周期,还有代码体积。
2bpp 同理,v * 255 / 3 等于 v * 85,表就是 0、85、170、255 四个值。
自己手写的时候最容易犯的错,是觉得「差不多就行」,把 4bpp 的值直接左移 4 位凑合。左移 4 位是把 0~15 拉到 0~240,最大灰度到不了纯白,浅色底上的字会整体发灰,看着像是渲染半透明。既然已经定义了表,就老老实实查表。
4.5 返回值的两种语义别搞混
__user_font_get_bitmap 的返回值在两个地方有不同期待:正常路径返回 bitmap_out,也就是你填好的输出缓冲首地址;异常路径返回 NULL,表示这个字形取不出来。
有一种写法是返回 bitmap_in(源数据地址),这在旧版本里能跑,因为那时候上层直接解释源指针。搬到 v9.1 就不行了:上层拿到的是输出缓冲,你返回源地址,它就当成像素去画,画出来是一片乱码。改的时候只要记住「返回的一定是自己写的那个缓冲」,就不会错。
5. 代码开发工具链上最容易翻车的五个点:避坑清单
下面五条都是我在真机上撞过的,症状、成因、改法按顺序写清楚。前三条属于「代码看着对但就是不显示」,后两条属于「显示了但不对」。
5.1 全屏空白,一个字都不出
现象:字体对象挂上去了,font_probe 打印的 bpp、range 都对,屏幕上却只有背景色,连方框都没有。
原因:dsc_out->format 没赋成 fdsc->bpp。这个字段是初值传递的,你不填它就保持调用方给的默认值,__user_font_get_bitmap 里所有 bpp 判断全部落空,最后走到 else 返回 NULL,LVGL 认为无字形可画,直接跳过。
解决:在 dsc 回调的最后检查三行赋值——format、gid.index、is_placeholder。三行齐了,先跑 glyph_dsc_selftest 看 fmt 打出来是不是你的 bpp,再上屏。
5.2 一部分字能出来,另一部分死活不出
现象:常用字正常,某个生僻字或者某个区间的汉字永远是空白,换成别的字又好了。
原因:范围前置判断写成了 unicode_letter > fdsc->cmaps[0].range_length,漏掉了 range_start。range_start 通常是 0x20(空格),range_length 是个相对长度值,不是结束码点。拿码点直接和长度比,几乎所有汉字
