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

1三分钟看懂点阵字库

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

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

两个马上会遇到的概念

这套方案带来的效果

2五分钟跑通第一个字库

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

第 0 步:先玩一下实时预览(可选但推荐)

首页顶部"⚡ LVGL 模拟器实时预览"里输入或粘贴任意文字(中文、阿拉伯语、印地语随便混), 停止输入后立即显示 LVGL 渲染器真实画出来的效果——这就是字库在设备上的样子。

正式生成

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

模式选型与功能一览

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

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

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

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

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

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

1. 烧字库:把 Font_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)
   {
       /* 从 Font_Lib.bin 烧写起始地址 + offset 处读 size 字节到 pbuf,
          返回实际读到的字节数(成功即 size,失败返回 0) */
       bsp_flash_read(pbuf, size, FONT_LIB_START_ADDR + offset);
       return size;
   }

   引擎与具体 Flash 型号完全解耦——SPI NOR、SD 卡、甚至文件系统都行。
4. 用起来:启动时把读函数注册给字库引擎:app_font_init(my_flash_read),之后——
   LVGL(v8/v9 自动适配):字库就是标准 lv_font_t:

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

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

5核心概念与数据格式

这一章解释"为什么",不影响使用;但理解之后,所有参数你都能自己做决定。

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

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

5.2 XBF:单字号点阵的中间格式

每个字号先生成一个 .xbf:头部记录行高/基线/bpp,cmap 按码点直接下标寻址, 每个字形是 12 字节属性(宽/高/偏移/步进)+ 位图。渲染由 FreeType 直连完成——精确像素字号、 原生灰度、自动提取 kerning(字距微调,如 A 和 V 靠近些)。

5.3 Font_Lib.bin:多字库合一的外挂格式

打包时按你的字符集配置裁剪(没用到的字不进库),多个字号合成一个 bin。 设备端查字支持两种方式:hash 查表(O(1),推荐)或二分查找;版本 magic 保证 固件里的索引与 Flash 里的 bin 严格配套,不匹配自动兜底,不会显示乱码。

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

灰度 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 越高收益递减。 代价是解压需要双份字形缓冲(几百字节)。此开关随 bin 写死到 Font_Lib.h,两者必须一致,不可手改。

字形缓存(True / False)

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

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

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

基线坐标系(top / bottom)

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

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 数据时表为空。

5.5 设备端如何工作

• 两级缓存:100 条字形描述缓存 + 单条 cmap 缓存,热点字符 0 次 Flash 读;
• 三种查表:连续区间直算 O(1) / 稀疏 hash 平均 O(1) / 稀疏二分 O(log n);
• 永不花屏:码点越界、缺字、bin 版本不匹配统统落 fake 字库显示占位字形;
• 存储解耦:引擎只调用你注册的读回调(经 app_font_init() 传入), SPI NOR / QSPI / eMMC / 文件系统都能接。

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. 正常生成。完成后在预览框粘一段该语言文字,亲眼确认连写/合体正确。

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

char shaped[256];
ext_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 混排中文+印地语+阿拉伯语。

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

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

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

8进阶能力

8.1 LVGL 官方格式(零集成)

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

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

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

python 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.4 节;需要"全语言通用字库"(25 字体链、覆盖全部内置语言) 可直接联系作者获取成品 bin,不必自己生成。

8.4 与 LVGL 官方字库怎么选

9排错手册与常见问题

10深入阅读

• 点阵字库方案详解——数据格式规格、设计取舍与 LVGL 官方字库逐维度对比(SVG 图解)
• 变形文字方案技术评审——组合变形文字支持方案的完整论证与决策记录
• 研究笔记——2022 年原始研究与开发记录全文(14 章,含 XBF/Font_Lib.bin 格式设计全过程)
• 工具质量:引擎与位流经四层验证(单元测试 / bin 逐位校验 / clang 双版本语法检查 / 宿主机运行时逐位比对), 并在 LVGL 9.3 官方模拟器实机验证;源码暂未公开,如需交流见下方联系方式。

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