嵌入式点阵字库:从零到跑通

1三分钟看懂点阵字库

电脑和手机上的字体文件(TTF/OTF)存的是矢量轮廓——每个字是一组贝塞尔曲线, 显示时由 FreeType 这样的引擎实时"画"出来。这需要相当的 CPU 和内存,小型嵌入式设备(手表、仪表、 家电面板)跑不动,也没必要跑。

嵌入式的做法是预先把每个字"画"成小图片——点阵位图,存进 Flash; 显示时按编号查出来贴到屏幕上即可,查表 + 拷贝,任何单片机都能轻松胜任。这个"把字体变成点阵图集合"的 过程就是字库生成,Py_FontMaker 干的就是这件事:

两个马上会遇到的概念

这套方案带来的效果

2五分钟跑通第一个字库

不需要安装任何软件,打开 pyfontmaker.com 即可。

正式生成

1. 选生成模式:保持默认的「外挂字库」(pyf_lib.bin + 全套 C 代码)。 每个模式下方有"做什么/什么场景选它"的说明,拿不准就用默认。
2. 选字体:两种方式任选——上传你自己的 TTF,或直接勾选服务器内置的免费字体 (25 个 SIL OFL 授权字体,可商用可分发,一个文件都不用传)。 例如做中文产品:勾「Noto Sans CJK SC(简体中文全量)」。
3. 勾字符集:按语系勾选即可——「基本拉丁(ASCII)」默认已勾,做中文产品再勾 「中文(简/繁通用)」;也可以把界面会显示的文字直接粘贴进"需要生成的文本"框—— 只生成用到的字,库最小。语系之外的特殊区间才需要用"自定义码点范围"手填。
4. 字号列表填 16,24(要几个字号写几个),其余参数保持默认 (每个参数右侧都有说明)。点开始生成。
5. 看结果:完成后页面直接显示两张预览图——「字形预览」(字库数据直绘)和 「LVGL 实机渲染」;可改预览文本实时刷新,也可用"查字符"确认某个字在不在库里。 浏览器同时自动下载 result.zip。

模式选型与功能一览

拿不准就选「外挂字库」。另有两个命令行专属功能: emoji 图片字库(--EMOJI,Noto Emoji PNG 转灰度字库,绕开点阵码点只到 BMP 的限制)与 多语言 Excel 转 .c(--LANG,翻译表一键生成 pyf_language.c/h,依赖本机 Excel)。

预览与查字符(所见即设备所得)

• 生成结果预览:每个字库两张图——「字形预览」用 XBF 数据直绘(bpp 量化/整形簇与设备一致), 「LVGL 实机渲染」经官方 binfont + LVGL 排版(含 RTL 按行 bidi);预览文本改什么渲染什么,预览图同时打进 zip;
• 查字符:输入单个字符或码点(如 中 或 0xE010),立即返回是否在字库、 字形度量、参与了哪些预整形簇——"某个字显示不出来"先来这里查。

3生成了什么:产物逐个认识

解开 result.zip,每个文件的职责:

4集成到你的工程(四步)

1. 烧字库:把 pyf_lib.bin 烧进外挂 Flash(任意起始地址,记住它)。
2. 加代码:把 zip 里所有 .c/.h 加进工程编译。
3. 实现读接口:在你自己的代码里写一个 Flash 读函数(生成的 .c/.h 一行都不用改):

   static uint32_t my_flash_read(uint32_t offset, uint8_t *pbuf, uint32_t size)
   {
       /* 从 pyf_lib.bin 烧写起始地址 + offset 处读 size 字节到 pbuf,
          返回实际读到的字节数(成功即 size,失败返回 0) */
       bsp_flash_read(pbuf, size, PYF_LIB_START_ADDR + offset);
       return size;
   }

   引擎与具体 Flash 型号完全解耦——SPI NOR、SD 卡、甚至文件系统都行。
4. 用起来:启动时把读函数注册给字库引擎:pyf_font_init(my_flash_read, printf)(第二个参数是可选的日志输出回调,printf 风格,传 NULL 则引擎静默),之后——
   LVGL(v8/v9 自动适配):字库就是标准 lv_font_t:

   lv_obj_set_style_text_font(label, &SourceHanCJK_24_2Bpp, 0);
   lv_label_set_text(label, "你好,世界");

   裸机:引擎暴露"取字形描述 + 取位图"两个回调,按位图逐像素画即可 (pyf_lib.h 里 LVGL_FONT_ENABLE 设 0)。

5参数详解:每一项的含义与效果

页面上每个参数旁都有简要说明;这里给出完整含义、效果与选择建议。数据格式层面的图解见下篇。

灰度 bpp(1 / 2 / 4 / 8)

字号列表 / 字高(像素)

外挂字库一次可打包多个字号(如 16,24,32),其余模式填单一字高。 渲染器直接按像素设定字号(FreeType FT_Set_Pixel_Sizes),所得行高、基线为字体真实度量。

字符范围 + 文本(取并集)

范围段每行一对十六进制码点(如中文常用区 0x4e00, 0x9fa5);文本框里直接粘贴界面会出现的文字,两者取并集。 效果:只打包界面用到的几百个字,能把字库从几 MB 降到几十 KB,生成时间同步降一个量级。 码点连续时自动用"连续 cmap"(设备端 O(1) 直算),不连续时自动用"稀疏 cmap"(hash / 二分查表)。

LVGL 接口(True / False)

True:生成的 public_font_t 就是 lv_font_t,可直接赋给 style; 编译期通过 LVGL_VERSION_MAJOR 自动适配 v8 与 v9 官方版 (v9 按 v9.3 契约把字形展开为 A8 写入 draw_buf)。False:走裸机回调 get_glyph_dsc() + get_glyph_bitmap()。

hash 查表(True / False)

稀疏字库的 cmap 查找方式。True:开放寻址 hash 表,平均接近 O(1);False:排序数组二分,O(log n)。 两套表都生成在 C 文件里(XIP,不占 RAM),宏一键切换。

RLE 压缩(True / False)

效果:逐字形独立压缩,随机访问不受影响;1 bpp 字库(大片空白)收益最大,bpp 越高收益递减。 代价是解压需要双份字形缓冲(几百字节)。编码规则图解见 §11.5。此开关随 bin 写死到 pyf_lib.h,两者必须一致,不可手改。

字形缓存(True / False)

设备端缓存最近 100 条字形描述(可在 pyf_lib.h 改条数)。界面上反复出现的字符命中后 0 次 Flash 读,滚动列表明显更顺。

位流存储(True / False,默认 True)

True:打包时去掉每行末尾的补位,字形内按位连续,box_w 上报真实宽度——与 LVGL 官方打包方式一致。 效果:位图体积再省 5%~25%(1 bpp 收益最大)。False:退回行字节对齐布局(裸机代码不想处理位偏移时用)。两种布局图解见 §11.4。

基线坐标系(top / bottom)

约定标记写在 XBF 头部,打包器自动生成 BASELINE_TOP_REFERENCED 宏; 同一个 bin 内混用两种约定会在打包时直接报错。坐标系图解见 §11.6。

hinting(auto / normal / light / mono / none / autohint)

变形字体(Variable Font)轴参数

上传含 fvar 表的 VF 字体(如内置思源黑体,wght 250~900)后页面自动出现轴滑条, 服务器用 fontTools instancer 固化成静态实例再进管线。效果:一个 VF 文件产出任意字重的点阵字库。

kerning(自动,无需开关)

渲染时自动从 TTF 的 kern/GPOS 表提取字偶距(如 AV、To 的间距修正), 按目标字号缩放为 1/16 px 精度,随字库生成 XIP 查找表;设备端按"当前字符+下一字符"二分查找修正 advance。 效果:西文排版质量对齐 lv_font_conv;中文方块字无字偶距、零开销;字体没有 kerning 数据时表为空。 命令行打包可用 --kern False 关闭 XIP kern 表——全字库场景该表可达数百 KB 内部 Flash,空间紧张时建议关闭。

6变形文字:阿拉伯语、印地语、泰语……

有一大类语言,两个字符组合后字形会变——简单查表渲染必然出错:

6.1 背景:哪些语言需要变形,为什么

需要"组合变形"(专业上叫 text shaping / 复杂文本布局)的语言覆盖 40+ 个国家,集中在四大类文字系统:

• ① 阿拉伯字母系——连写变形最典型:每个字母有 独立/词首/词中/词尾 最多 4 种形态,相邻字母决定用哪种, 还有强制连字(如 ل+ا = لا)。语言:阿拉伯语(20 多国)、波斯语(伊朗)、达里语/普什图语(阿富汗)、 乌尔都语(巴基斯坦/印度,传统用 Nastaliq 体,本工具按 Naskh 风格支持)、库尔德语、维吾尔语/老哈萨克文/柯尔克孜语(中国新疆)、 信德语/俾路支语。同类还有叙利亚文和西非 N'Ko 文(提供字形直通,暂无整形语言包)。
• ② 蒙古文系——竖排 + 连写变形:传统蒙古文(内蒙古/蒙古国)、满文/锡伯文。 本工具生成横排位置形,竖排由应用层把 label 旋转 90°。
• ③ 印度婆罗米系——辅音簇合体 + 元音重排:两个辅音相拼生成合体字(如天城文 क+्+ष → क्ष), 有的元音显示时要跳到辅音前面。文字:天城文(印地语/马拉地语/尼泊尔语)、孟加拉文、古木基文、古吉拉特文、 奥里亚文、泰米尔文、泰卢固文、卡纳达文、马拉雅拉姆文、僧伽罗文(斯里兰卡)、藏文(纵向叠字)。
• ④ 东南亚系:高棉文(第二辅音下标 + 元音重排)、缅甸文(介音变形)、泰文/老挝文(声调与上下元音动态堆叠)、 爪哇文/巴厘文/占文(合体辅音)。

特殊情况:韩文谚文的音节已被 Unicode 全部预组合成独立码点,按普通字符处理即可; 希伯来文只是从右向左,字母不连写变形,不算变形文字;拉丁、西里尔、希腊、CJK、假名等都不需要变形。

6.2 三组语言包:机制与动态文本支持

字体 vs 语言包的分工:字体决定"字形从哪来"(原材料),语言包决定"如何整形"(加工工艺)。 只勾字体不勾语言 → 合体/连写散开;只勾语言没有对应字形 → 方框。勾选语言时 Web 会自动勾上对应内置字体。

多个 C 组语言合打一个字库时,簇字典共享 6400 个 PUA 码位(物理上限), 工具会按覆盖率自动削减并打印明细;单语言生成可达 99.9% 覆盖。 完整的方案论证(语言分级/体积估算/风险对策)见变形文字方案技术评审。

6.3 在本工具里怎么用

支持它们只需要两个勾选:

1. 在「变形语言支持」勾选目标语言(如 天城文/阿拉伯字母系)—— 对应的内置字体会自动勾上;
2. 正常生成。完成后在预览框粘一段该语言文字,亲眼确认连写/合体正确。

设备端唯一的额外动作:送显前把字符串过一次整形函数(生成包里的 pyf_shaper.c,约 3KB 查表代码):

char shaped[256];
pyf_font_shape_utf8("مرحبا بالعالم", shaped, sizeof(shaped), FONT_SHAPE_FLAG_BIDI_VISUAL);
lv_label_set_text(label, shaped);   /* LVGL 开了 LV_USE_BIDI 时 flags 传 0 */

7多字体组合(fallback 链)

没有任何一个 TTF 能覆盖所有文字(Noto 全家桶都是按文字系统分成上百个文件的)。 要做多语言产品,把多个字体组成一条链:

• 上传时按住 Cmd/Ctrl 一次选择多个字体,或直接勾选多个内置字体;
• 第一个是主字体:决定行高、基线、kerning、字库名和变形字体轴参数(上传框下方会列出链顺序);
• 普通文字(拉丁/中文/泰文等)缺的字,按顺序由后续字体补齐——最终合成单一字库对象, 一个 lv_font_t 混排中文+印地语+阿拉伯语;
• 变形语言(印度系/高棉/缅甸/藏文/僧伽罗等)不由顺序决定:生成时对链中每个覆盖该文字的 字体做标记定位健康检查(抽样几十个音节,看下标/元音是否落在基字外、叠加符号是否互相压住), 自动取第一个健康的字体来渲染该文字的全部字形(基字与合体簇同源);
• 结果区每个字库下方会显示 主字体(行高/基线): X ｜ 高棉文: Y,看一眼就知道各语言实际用的是谁。

内置免费字体清单(全部 SIL OFL,可商用/嵌入/分发)

Web 上传框下方可直接勾选这些服务器内置字体;勾选"变形语言"时自动勾上对应文字的字体。 OFL 授权唯一要求:随产品保留字体版权声明,不得单独出售字体文件本身。

授权提醒:操作系统自带字体(macOS 冬青黑/GeezaPro/各 MN 系列、 Windows 微软雅黑等)多为商业授权,转成点阵字库分发给第三方通常超出授权范围——分发场景请使用本清单的 OFL 字体。

8进阶能力

8.1 LVGL 官方格式(零集成)

只想要标准 LVGL 字库、不想集成引擎?用「XBF 字库」模式,产物自动附带: pyf_lvgl_*.c(LV_FONT_DECLARE 即用)与 pyf_lvgl_*.bin (lv_binfont_create() 运行时从文件系统动态加载,可 OTA 换字库)。 官方格式同样携带变形文字簇——纯 LVGL 也能正确显示印地语。 注意位图超 1MB 的大字库需在 lv_conf.h 开 LV_FONT_FMT_TXT_LARGE。

8.2 BDF 导出:预览与逐字修饰

参数区勾「BDF 导出」,可用 BdfEditor/FontForge 打开预览、逐像素修饰个别字符 (小字号笔画粘连的手工优化),再用命令行回填:

python pyf_xbf_to_bdf.py --xbf xxx.xbf --patch edited.bdf --out-xbf new.xbf   # 1bpp 无损

8.3 命令行与批量化

Web 的每个能力都有对应的命令行版本(CI/批量生成场景)。源码暂未公开, 如需命令行/批量集成请通过页尾的公众号或 QQ 群联系作者;参数形式如下,供了解能力边界:

# 环境(Python ≥ 3.9)
python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

# 多字体链 + 变形语言, 生成 XBF(自动附带 LVGL 官方格式)
python Py_FontMaker.py --XBF True --min 0x20 --max 0xfeff \
  --ttf main.ttf,NotoSansDevanagari.ttf,NotoNaskhArabic.ttf \
  --langs devanagari,arabic --bpp 2 --height 24

# 打包外挂字库(先按字号生成 XBF, 再打包)
python Py_FontMaker.py --LIB True --lib_file ./font_type/my_lib.txt --ttf main.ttf --bpp 2 --height 24

全部参数详解见第 5 章;需要"全语言通用字库"(25 字体链、覆盖全部内置语言) 可直接联系作者获取成品 bin,不必自己生成。

与 LVGL 官方字库如何选型,见下篇第 14 章逐维度对比。

9排错手册与常见问题

下篇面向使用/评估本方案的嵌入式开发者，回答三个问题：

1. 当前点阵字库方案是什么（数据格式、生成管线、设备端引擎）；
2. 它的优点和缺点分别是什么（逐条给依据，含代码位置）；
3. 它和 LVGL 官方点阵字库（lv_font_conv 产物）的差异在哪里（逐维度对比 + 选型建议）。

文中所有结论均以本仓库代码为准（pyf_ttf_to_fontcvtst_xbf.py、pyf_xbf_to_fontlib_bin.py、pyf_engine_code.py 等）；LVGL 侧以 v8.3 的 lv_font_fmt_txt 与 lv_font_conv 官方文档为参照，v9 的接口差异在 §14.5 单独说明。

10方案总览

一句话概括：PC 端把 TTF 逐字栅格化成灰度点阵，打包成一个 pyf_lib.bin 烧进外挂 SPI Flash；设备端用自动生成的 C 引擎按需逐字形读取、解压、渲染，向上以 lv_font_t（LVGL）或裸机回调两种接口暴露。

(总体架构图见第 1 章。)

整条链路分两段：

PC 端工具链（Python，跨平台，另有 Web 在线生成与本地 GUI）：

变形字体（Variable Font）先用 fontTools instancer 按轴（如 wght 字重）固化成静态实例再进管线，一个 VF 文件可产出任意字重的点阵字库。

设备端(自动生成的 C 代码,见 pyf_engine_code.py 模板):各文件职责见第 3 章产物表,引擎内部机制见第 12 章。

11数据格式详解

11.1 字符集与 Unicode:字是怎么编号的

计算机里每个字符都有一个全球统一的编号——Unicode 码点,写作 U+XXXX。 比如 A 是 U+0041、中 是 U+4E2D。常用汉字集中在 U+4E00~U+9FA5(约 2 万个)。文件与网络传输时,码点按 UTF-8 规则变成 1~4 个字节存储; 你在网页上填的"字符范围"就是码点区间,粘贴的文本会被自动转回码点。 点阵字库本质上就是一张「码点 → 位图」的大表。

11.2 XBF 中间格式

XBF 是①阶段的产物，格式兼容 FontCvtST（ST 提供的 emWin 字体转换工具），因此也可以脱离本方案单独给 emWin/裸机工程使用。本工具直接生成 XBF，不依赖任何第三方 exe。

要点（对应 pyf_ttf_to_fontcvtst_xbf.py:34-157）：

• 18 字节头：名称(4B) + YSize/YDist/BaseLine(各 u16) + bpp(u8) + px(u8) + 保留(u16) + FirstCode/LastCode(各 u16)，小端；
• 密集 cmap：[FirstCode, LastCode] 区间内每个码点一条 {u32 offset, u16 size}（6 B），缺字条目全 0。按码点直接下标寻址，O(1)；
• 字形记录 = 12 字节属性（adv_w/box_w/box_h/ofs_x/ofs_y/bytes_per_line，各 u16/s16）+ 行对齐灰度位图；
• 码点为 u16，只覆盖 BMP（≤ 0xFFFF）；增补平面的 emoji 走图片字库产线；
• 栅格化默认由 freetype-py 直连 FreeType：精确像素字号、原生覆盖度灰度量化到目标 bpp（gray >> (8 - bpp)，MSB 在前），1bpp 默认 mono 渲染；头部 0x0C 保留字段标记坐标约定（0=legacy，1=freetype+top，2=freetype+bottom），并输出 .kern.json kerning sidecar。

11.3 pyf_lib.bin 外挂字库格式

②阶段把若干 XBF 按各自的码点配置文件（font_type/*.txt，"范围段 + 文本段取并集"）裁剪后打进一个 bin。

要点（对应 pyf_xbf_to_fontlib_bin.py:85-111, 732-741, 1164-1361）：

cmap 有两种形态，打包时自动判定（码点集合连续 → 连续表，否则稀疏表，pyf_xbf_to_fontlib_bin.py:722-727）：

• 连续表：6 B/字 {u32 offset, u16 size}，设备端按 (code - first_code) 直算偏移后读 Flash；
• 稀疏表：bin 内 8 B/字 {u16 code, u32 offset, u16 size}；同时生成 XIP 的 C 常量表（pyf_cmap_*.c），运行时实际查的是 C 表（排序数组走二分，或 hash 表走开放寻址线性探测，CMAP_HASH_ENABLE 切换），bin 内的稀疏表当前为预留。

字形记录 = 6 字节属性头（u8 adv_w/box_w/box_h、s8 ofs_x/ofs_y、u8 bytes_per_line，比 XBF 的 12 B 减半）+ 位图（可 RLE）。

版本闭环是这个格式的特色：每次打包生成随机 magic，同时写进 bin 头与 pyf_lib.h 的 PYF_LIB_MAGIC 宏；设备启动时引擎校验二者一致，不一致（固件与字库脱节）则全部退回 fake 字库并可由 pyf_font_version_ok() 触发字库 OTA，保证字库可以独立于固件发布/升级而不会花屏。

11.4 位图打包方式

2026-09 更新：--bitstream（默认开）已支持字形内连续位流存储——打包进 bin 时去掉行尾补位，box_w 上报真实宽度，与 LVGL 原生打包方式一致；--bitstream False 退回下图左侧的行字节对齐布局。下图描述的是两种可选布局的差异。

XBF 中间格式每行按字节对齐（bytes_per_line = ceil(box_w × bpp / 8)，保持 FontCvtST/emWin 兼容）；打包为 pyf_lib.bin 时默认重打包为连续位流，LVGL 官方也是连续位流：

历史行为说明：旧版（--bitstream False）设备端上报的 box_w 按 bytes_per_line × 8 / bpp 反推，即对齐后的宽度——真实 13 列、2 bpp 会上报 16 列，右侧 3 列为补 0 空白列。位流模式下该问题不复存在（pyf_lib.h 的 BITMAP_BIT_CONTINUOUS_ENABLE 宏由工具随 bin 写死，两者必须一致）。

11.5 RLE 压缩

--rle True（默认开）时对每个字形的位图单独做字节级 RLE（pyf_run_length_encoding.py），cmap 中的 size 记录压缩后长度，解码器约 30 行 C（pyf_rle_glyph_bitmap_decode）：

• 连续 ≥3 个相同字节 → [0x80|count][value]；不重复串 → [count][字面量…]；count ≤ 0x7F；
• 逐字形独立压缩意味着随机访问不受影响（无需从头解压整个字库）；
• 收益与 bpp 负相关：1 bpp（大片空白/整行重复）收益最大，4/8 bpp 抗锯齿灰度丰富时收益递减，最坏情况反而多出控制字节；
• 代价：静态缓冲模式需要双份位图缓冲（压缩流 + 解压结果，pyf_glyph_bitmap_buf[2][MAX_STATIC_BITMAP_BUF_SIZE]），或改用 malloc 模式（--rlemalloc）；
• RLE 开关必须与生成 bin 时一致（pyf_lib.h 中 BITMAP_RLE_ENCODE_ENABLE 由工具写死，不可手改）。

11.6 基线与坐标系

2026-09 更新：基线坐标系已做成可选（--baseline top|bottom）。top 为 FontCvtST 顶部基准（默认，兼容 emWin 生态）；bottom 直接按 LVGL 底部基准存储（ofs_y = yMin、baseline 从行框底起算），LVGL 路径零换算。约定标记写在 XBF 头 0x0C 保留字段，打包器自动检测并生成 BASELINE_TOP_REFERENCED 宏，引擎按宏对齐换算；同一个 bin 内混用两种约定会在打包时报错。

top 模式下，存储侧的垂直量以行框顶部为原点向下计（baseline = ascent、ofs_y = ascent − yMax + 1）；而 LVGL 以基线为原点向上计，引擎在 get_glyph_dsc 里做一次整数换算：

12设备端引擎

取一个字形的完整路径如下（pyf_engine_code.py 生成的 pyf_engine.c）：

几个关键设计：

1. 两级缓存

   • 字形描述缓存：全局 font_cache[100]（PYF_FONT_DSC_CACHE_CNT，可改），按 (unicode, font_type) 线性扫描命中则 0 次 Flash 读——界面上反复出现的字符（数字、标点、固定文案）基本全命中；
   • 单条 cmap 缓存：每个字体记住上一次查过的 {code, offset, size}，get_glyph_dsc 和紧随其后的 get_glyph_bitmap 查同一个字时第二次 cmap 查找免掉。
   • 位图本体没有缓存：每次绘制都要从 Flash 读一次位图（详见 §13.2）。

2. 三种 cmap 查找

   • 连续（全字库/连续区间）：直算偏移 + 读 Flash 6 B；
   • 稀疏 + hash（默认）：XIP C 表开放寻址，平均接近 O(1)；
   • 稀疏 + 二分：XIP 排序数组，O(log n)。

3. fake 字库兜底：码点越界、cmap 查不到、size == 0（生成时就缺字）、bin 版本 magic 不匹配——统统落到编译进固件的 fake 字库显示占位字形，任何情况下不花屏。

4. 与存储解耦：引擎只通过 pfunc_get_data（offset/buf/size）拉数据，SPI NOR、QSPI、eMMC、甚至文件系统都能接。

5. LVGL / 裸机双接口：LVGL_FONT_ENABLE=1 时 public_font_t 就是 lv_font_t，pyf_font_create() 填好 get_glyph_dsc/get_glyph_bitmap/line_height/base_line 后可直接赋给 style；=0 时是等价的自定义结构体，裸机直接调两个回调。

6. LVGL v8 / v9 双版本支持（2026-09 新增）：生成代码通过 LVGL_VERSION_MAJOR 自动识别大版本。v8 下 get_glyph_bitmap 直接返回位流位图（v8 渲染器原生按 width_bit = box_w × bpp 位寻址）；v9（按 v9.3 官方发布版契约）下走包装回调——从 g_dsc->gid.index 取码点、读 Flash 解码后，由共享的 pyf_font_bitmap_to_a8_draw_buf() 展开为 A8（每像素 1 字节，按 draw_buf->header.stride 对齐）写入 LVGL 分配的 draw_buf 并返回，与官方 lv_font_fmt_txt 同一行为；glyph_dsc 按版本填 bpp（v8）或 format + gid（v9）。fake/内部/图标/emoji 四类 C 字库同样双版本适配。

13方案优点与缺点

13.1 方案优点

按重要性排序：

1. 内部 Flash / RAM 占用极小，CJK 全量字库可用。字库数据全部在外挂 SPI Flash；固件里只有引擎（~2 KB 代码）、稀疏 cmap C 表（仅裁剪字库需要）和 fake 字库。RAM 只需 1~2 个字形位图缓冲（MAX_STATIC_BITMAP_BUF_SIZE = 最大字号的 y_dist²·bpp/8，如 24px/2bpp 约 256 B；56px/2bpp 约 900 B）+ 100 条 dsc 缓存。这是 LVGL 官方两条路径（C 数组占内部 Flash、binfont 占 RAM）都做不到的。

2. 字库独立升级的版本闭环。bin 与 C 头文件用随机 magic 配对，版本错落 fake 字库 + pyf_font_version_ok() 上报，OTA 时字库和固件可以分开发布、分开烧写，工程上非常实用。

3. 多字体多字号一包。一个 pyf_lib.bin 打包 N 个字体×M 个字号（含图标字库、emoji 字库），信息表统一管理，应用层用枚举取字体；固件与字库的对应关系只有一处。

4. 全套 C 代码自动生成，拿来即用。用户唯一要写的是一个 Flash 读函数；LVGL/裸机、hash/二分、RLE 开关、缓存条数都是 pyf_lib.h 里的宏。

5. 缺字兜底。fake 字库保证任何异常路径都有占位显示，不会出现乱码/花屏——对量产设备是刚需。

6. 按需裁剪，体积可控。码点配置支持"范围 + 界面文案文本"取并集，"只打包界面用到的几百个字"能把字库从几 MB 降到几十 KB，生成时间也降一个量级。

7. 查表结构为外挂场景优化。连续区间直算 O(1)；稀疏区间 hash 平均 O(1) 且表在 XIP 不占 RAM；dsc 缓存吸收热点字符的重复查询。

8. RLE 逐字形压缩，随机访问不受影响，1 bpp 字库收益显著；解码器极简（无状态、无查找表）。

9. 工具链友好：纯 Python 跨平台（服务器无头环境可跑）、Web 在线生成（上传 TTF 选参数下载 zip）、变形字体一个文件出全字重、XBF 兼容 emWin 生态、附带 iconfont/emoji/多语言 Excel 一条龙。

10. emoji 图片字库：把 Noto Emoji PNG 转成同一 bin 里的一个"字体"，用同一引擎渲染——LVGL 官方点阵字库路线没有对应能力（需另接 lv_imgfont）。

13.2 方案缺点与限制

同样按影响面排序，均给出代码依据：

1. 渲染吞吐受 SPI 总线限制，位图无缓存。每个字形每次绘制都要 1~2 次 Flash 读（dsc 未命中缓存时 6 B 属性 + 位图本体）；滚动长文本、跑马灯时同一个字反复读取。dsc 缓存只缓存 6 B 描述，不缓存位图（__user_font_get_bitmap 每次都走 Flash）。对比 LVGL C 数组的零 IO，这是外挂方案的本质代价，但位图 LRU 缓存是明确的补强空间（见 §15）。

2. 无 kerning（字距调整）（2026-09 已解决）。freetype 渲染器自动从 TTF 的 kern/GPOS 表提取字偶对（含 PairPos format1/2 与 Extension），按目标字号缩放为 1/16 px 定点写入 XIP kern 表；引擎在 get_glyph_dsc 按 (left<<16)|right 二分查找修正 adv_w（与 lv_font_fmt_txt 同款舍入），dsc 缓存存基础值不受污染。

3. advance 存储为整数像素（bin 中 u8，2026-09 部分改进）。freetype 渲染器按 26.6 定点四舍五入，逐字形精确；kern 修正按 1/16 px 定点计算后舍入——这已达到 LVGL 自定义字体回调接口（dsc->adv_w 为整数）能表达的精度上限。与官方剩余差距仅在无 kern 长串的亚像素累积（官方 fmt_txt 同样逐字形舍入输出，实际无差）；u8 存储仍限制单字形 advance ≤255 px（72 px 字号内安全）。

4. 码点仅支持 BMP。XBF 头与 cmap 都是 u16（pyf_ttf_to_fontcvtst_xbf.py:43-44），增补平面（含大多数 emoji）必须走图片字库产线；bin 的稀疏 cmap 条目也是 u16 码点（emoji 字体单独用 u32 变体）。

5. 部分字体度量硬编码（2026-09 已解决）。y_size/y_dist/baseline 全部渲染路径（freetype / pygame / FontCvtST 导入）均直接取 XBF 头的实测值；按字号查的经验值表已删除，"字号不在表内沿用上一个字体度量"的隐患随之消除。 注意：legacy(pygame) 路径旧表输出的行高偏大（如 16px 为 18/18/16，实测为 16/16/13），依赖旧值排版的存量工程升级后需过一遍视觉确认。

6. 强依赖文件命名约定。bpp 从文件名 ..._2Bpp 解析、字号取 name[-7:-5] 两位数字（pyf_xbf_to_fontlib_bin.py:1112-1113, 1295）；文件名不合规会产出错误的元数据，且字号只支持两位数。

7. hash 表装载因子为 1.0。生成时 hash 表大小 = 字符数（pyf_xbf_to_fontlib_bin.py:1436），满载的开放寻址线性探测在聚簇处会退化，未命中查找最坏遍历整表（先被 first/last 区间过滤挡掉大部分）。README 所说 O(1) 是平均意义上的。

8. 位图行对齐带来的宽度虚报（2026-09 已解决）。--bitstream（默认开）改为字形内连续位流存储，box_w 上报真实宽度；仅 --bitstream False 的兼容模式仍是旧行为。实测 ASCII 测试字库（16px/2bpp + 24px/1bpp）位流化单独可省约 25% 位图体积（1bpp 收益最大；RLE 开启时行尾 0 本就可压缩，叠加后净收益缩小）。

9. 静态缓冲非线程安全。pyf_glyph_bitmap_buf 是全局静态，get_glyph_bitmap 返回其指针，多线程同时取字会互相踩；LVGL 单线程模型下没问题，裸机双核/RTOS 多任务需自行加锁。RLE 静态模式还要双倍缓冲。

10. 生成侧渲染质量依赖 pygame（2026-09 已解决）。XBF 默认由 pyf_ttf_freetype_to_xbf.py 直连 FreeType：FT_Set_Pixel_Sizes 精确像素字号（不再 pt 扫描）、原生覆盖度灰度（不再亮度反推）、hinting 五档可选（1bpp 默认 mono 渲染更锐利）、生成速度快一个量级。fake/内部/图标字库生成器仍走 pygame（占位/图标字形对渲染精度不敏感），--renderer pygame 可整体退回旧链路。

11. 生成的 LVGL 接口是 v8 签名（2026-09 已解决）。生成代码按 LVGL_VERSION_MAJOR 自动适配 v8 与 v9（v9.3 官方发布版契约），见 §14.5。

12. 工程细节类：字体信息区 0x100~0x1000 上限约 60 个字体；pyf_cmap_*.c 稀疏表同时以二分数组 + hash 表两份形态生成（XIP 体积 ×2，好在仅裁剪字库有此表）；bin 内稀疏 cmap 为预留未被引擎使用。

14与 LVGL 官方字库对比与选型

14.1 LVGL 官方点阵字库简介

LVGL 官方的静态点阵字库由 lv_font_conv（Node.js CLI，亦有官方在线转换器）生成，运行时格式是 lv_font_fmt_txt：

lv_font_t
 └─ lv_font_fmt_txt_dsc_t
     ├─ glyph_bitmap[]           位流紧凑打包的位图池
     ├─ glyph_dsc[]              每字形 {bitmap_index:20, adv_w:12(8.4 定点), box_w/h, ofs_x/y}
     ├─ cmaps[]                  多段 cmap（FORMAT0_FULL/TINY、SPARSE_FULL/TINY 四种）
     ├─ kern_dsc                 kerning：pair（字偶对）或 class（字距类矩阵），1/16 px 精度
     ├─ bpp: 1/2/3/4             抗锯齿位深（--lcd/--lcd-v 另有 ×3 子像素）
     └─ bitmap_format            RAW 或 COMPRESSED（XOR 行预滤波 + 位级 RLE）

两条使用路径：

• C 数组（--format lvgl）：.c 文件编译进固件，内部 Flash XIP，渲染直接取址，零 IO 零额外 RAM；内置 Montserrat 等字体即此形态；
• binfont（--format bin）：运行时 lv_binfont_create()（v8 为 lv_font_load()）经文件系统整体载入 RAM。

另有运行时矢量方案（Tiny TTF、FreeType 接口），不属于点阵字库，此处不展开。

14.2 存储与资源占用

14.3 格式能力

14.4 工具链与生态

14.5 LVGL 版本兼容性

2026-09 更新：生成代码已同时支持 LVGL v8 与 v9 官方发布版，编译期通过 LVGL_VERSION_MAJOR 自动切换，无需手工适配。

两个大版本的回调契约不同：

/* v8：get_glyph_bitmap 返回位流位图指针, 渲染器按 width_bit = box_w*bpp 位寻址 */
const uint8_t * (*get_glyph_bitmap)(const lv_font_t *, uint32_t);

/* v9(按 v9.3 契约)：由字体把字形展开为 A8(每像素 1 字节)写入 LVGL 分配的
 * draw_buf(行按 header.stride 对齐), 返回 draw_buf; 码点从 g_dsc->gid.index 取 */
const void * (*get_glyph_bitmap)(lv_font_glyph_dsc_t *, lv_draw_buf_t *);

引擎的实现方式：内部保留 v8 风格的裸回调（pyf_font_get_bitmap_raw / pyf_fake_font_get_bitmap_raw，跨字库兜底委托统一走裸回调，任何版本下都可直接调用）；v9 下再套一层包装回调，用共享的 pyf_font_bitmap_to_a8_draw_buf() 完成 A8 展开——与官方 lv_font_fmt_txt 的行为一致。glyph_dsc 填充由 FONT_GLYPH_DSC_SET_FORMAT 宏按版本落到 bpp（v8/裸机）或 format + gid.index（v9）。fake/内部/图标/emoji 字库同样适配。v9 的 release_glyph 置 NULL（引擎从不设置 g_dsc->entry，LVGL 不会调用它）。

参考工程当前基于 RT-Thread + LVGL v8 验证（https://gitee.com/woowill/ZJ_RT_Thread_LVGL_Font_Nordic.git）；v9 路径已在宿主机用 v9.3 结构桩做过运行时逐位验证（tests/test_host_c.py），上板验证欢迎反馈。

14.6 一图流总结

14.7 选型建议

选 LVGL 官方 lv_font_conv，当：

• 字符集小（拉丁/西里尔/固定文案），C 数组塞得进内部 Flash；
• 对西文排版质量敏感（需要 kerning 与 1/16 px advance）;
• 不想引入外挂 Flash 读路径，追求零 IO 的极致渲染性能；
• 使用 3 bpp、LCD 子像素等 lv_font_conv 独有特性。

选本方案（Py_FontMaker 外挂字库），当：

• 需要 CJK 大字符集、多字号，内部 Flash 放不下（最典型场景：手表/手环/仪表）；
• 字库需要独立于固件 OTA（版本闭环是现成的）；
• 平台是裸机或非 LVGL GUI（双接口 + XBF/emWin 兼容）；
• 需要 emoji 图片字库、iconfont、多语言表一条龙；
• 希望用 Web 服务给团队/客户提供在线字库生成。

两者混用也常见：界面骨架用 LVGL 内置 Montserrat（C 数组），中文正文/大字号用本方案外挂字库——lv_font_t 层面完全等价，可在同一个 label 样式体系里共存。

15可优化方向

结合 §13.2 的缺点，按投入产出排序。每一项都不是"免费的午餐"，收益与代价并列如下：

一句话排序：1 体验收益最大（做成可选项）→ 2 看产品形态（多语言裁剪字库才值得）→ 3、4 都会 break 格式，等真实需求出现再动，别白付兼容成本。

16深入阅读与交流

• 研究笔记——2022 年原始研究与开发记录全文(14 章,含 XBF/pyf_lib.bin 格式设计全过程)
• 工具质量:引擎与位流经四层验证(单元测试 / bin 逐位校验 / clang 双版本语法检查 / 宿主机运行时逐位比对), 并在 LVGL 9.3 官方模拟器实机验证;源码暂未公开,如需交流见下方联系方式。

本文由 2022 年的《嵌入式字库研究及 Py_FontMaker 工具编写》重写而来,内容与当前代码保持一致。 交流:公众号 Bluetooth-BLE · QQ 群 177341833 · 返回生成页