9. 高通字库
在工程的 gt_gui_driver.h 中,可以看到项目使用的字体类型定义在 font_option_et 枚举。字体类型分为灰度字库(推荐)、点阵字库和矢量字库。
新工程以新版字库体系为主,在 gt_conf.h 中显式配置:
/* 新工程:使用新版 family / option 字库体系 */
#define GT_FONT_FAMILY_OLD_ENABLE 0
/* 仅接入自有字库时改为 1;只使用 GT-HMI Designer2 / 字库芯片字库可保持 0 */
#define GT_CUSTOM_FONT_ENABLE 0
GT_FONT_FAMILY_OLD_ENABLE=1 只用于维护仍调用 gt_*_set_font_family_cn/en/fl/numb() 的旧工程,不建议新工程继续采用。部分引擎源码的兼容默认值仍可能为 1,因此不要依赖默认值;若与 Designer2 导出配置不同,以当前工程生成物及其配套引擎版本为准。
字库方案怎么选
GT-HMI 工程的字库有两条芯片路径和一条可选路径:
| 路径 | 前置条件 | 适用场景 | 参考 |
|---|---|---|---|
| 标准字库芯片 | 外挂字库芯片(SPI 等总线) | 需要芯片内置字库、多语言覆盖、灰度/矢量字形,按型号采购芯片并配合驱动使用 | 9.4;字库芯片规格书、字库芯片开发手册 |
| 自定义字库芯片 | 需要使用 GUI 芯片 | 基于 GUI 芯片的 GT-HMI 方案:在 GT-HMI Designer2 中配置字库组与字号后有两种使用方式——GT-HMI 的 GUI 工程内直接使用(设计界面、仿真预览,导出工程时自动生成字库数据与 font_option_et 定义),或导出字库组集并烧录为自定义字库芯片,供任何 MCU 工程经驱动读取;生僻字、小语种或特定字体的选配同样在 GT-HMI Designer2 中完成 | 9.4;GT-HMI Designer2 用户手册、自定义字库芯片开发指南 |
| 自有/第三方字库(可选) | 具备固件开发资源 | 少量固定字符、评估与原型,或已有第三方字库数据,自制点阵并注册读取回调 | 9.5 |
字库方案以芯片路径为主:标准字库芯片外挂提供字库,自定义字库芯片经 GT-HMI Designer2 配置导出。自有/第三方字库是可选路径,适合原型验证、教学与少量固定字符;量产、多语言或灰度/矢量需求请优先评估芯片路径。
9.1 矢量字库
矢量字库是高通专为嵌入式产品打造的精品矢量字库。具有丰富多样的字体,占用资源小(RAM 5-8K),支持文字大小无极缩放,支持边缘平滑的灰度显示,语言覆盖 180 国多种文字语言。
9.2 灰度字库
灰度字库融合点阵与矢量字库之精髓,无需 MCU 渲染,以超低资源消耗,呈现媲美手机与 PC 的细腻字体显示。包含中文的 GB2312 和 GBK 编码的 16 点黑体、20 点黑体等多种字体。
9.3 点阵字库
点阵字库以像素点阵的形式存储字符信息,相比于矢量字库,点阵字库通常占用更少的存储空间,适合在资源受限的嵌入式系统中使用。渲染速度较快,在一些对速度要求较高的场景下能够提供更快的显示效果。
9.4 字库获取与使用
高通字库为商业字库,不随开源引擎提供,通过以下三种方式获得:
| 获取方式 | 适用场景 | 教程入口 |
|---|---|---|
| GUI 工程内直接使用 | 用 GT-HMI Designer2 设计界面时,配置字库组与字号,界面控件直接使用所选字库;仿真预览所见即所得,导出工程时自动生成字库数据与 font_option_et 对应定义,字库随工程一并编译,无需另外制作芯片 | GT-HMI Designer2 用户手册 |
| 购买高通标准字库芯片 | 需要芯片内置字库、多语言覆盖或特定字形(灰度/矢量/点阵)时,按型号采购标准字库芯片并配合驱动使用 | 字库芯片规格书、字库芯片开发手册 |
| 自定义字库芯片(自助选配烧录) | 标准字库无法满足生僻字、小语种或特定字体风格需求,或非 GT-HMI 工程也要用高通字库时:在 GT-HMI Designer2 中选配字库组集,导出并编译生成资源文件,烧录到 16–128Mb 自定义字库芯片,任何 MCU 工程经驱动读取 | 自定义字库芯片开发指南 |
字库芯片与 GT-HMI Engine 的对接方式(SPI/QSPI 驱动、地址表、字库 ID 配置)见对应手册;Designer2 工程导出的
gt_gui_driver.h会包含本项目实际使用的font_option_et枚举值,请以工程生成物为准。
9.5 使用自有字库与开源替代方案
本节为可选路径:适合原型验证、教学演示、少量固定字符的自制字库,或已有第三方字库数据的场景。字库规模、语言覆盖或字号体系增长时,建议回到 9.4 评估芯片路径。
GT-FontLab 字库生成工具
系统字体或 TTF/OTF 在线转点阵、灰度与 LVGL 字体,免安装导出 Bin / C / PNG。
GT-HMI Engine 可以使用用户自行制作的字库,但普通控件与 GT-MD 是两条独立接入链路,不要混用注册接口:
| 使用位置 | 注册接口 | 字库数据由谁读取 | 绘制由谁完成 |
|---|---|---|---|
| 标签、按钮、文本区等普通控件 | gt_custom_register_font | 用户实现点阵/矢量读取与字形尺寸回调 | GT-HMI Engine |
| GT-MD / LaTeX 渲染 | gt_latex_font_register、gt_latex_render_register | 用户按 Unicode 码点提供字形尺寸与位图 | 用户实现绘制回调 |
9.5.1 普通控件:注册自定义点阵字库
以下接口按 GT-HMI Engine v1.4.16 源码核对,示例已通过 Emscripten 编译检查。示例数据约定为 U+0020~U+007E 连续排列、16×16、1bpp、每字 32 字节;其他宽高、扫描方式、灰度或编码需要同步调整数据生成和读取函数。
-
在
gt_conf.h中启用新版字库体系和自定义字库:#define GT_FONT_FAMILY_OLD_ENABLE 0 #define GT_CUSTOM_FONT_ENABLE 1 -
准备字库数据并实现读取回调。
my_font_bin可由取模工具生成后以 C 数组编入固件,也可放在用户自己的 Flash 文件系统中:#include "gt.h" #include "src/font/gt_custom_font.h" #define MY_FONT_OPTION GT_CUSTOM_FONT_OPTION(1) #define MY_FONT_FAMILY (GT_FONT_FAMILY_ONE_TYPE | MY_FONT_OPTION) #define MY_FONT_WIDTH 16 #define MY_FONT_HEIGHT 16 #define MY_FONT_BYTES (MY_FONT_WIDTH * MY_FONT_HEIGHT / 8) #define MY_FONT_FIRST 0x20u #define MY_FONT_LAST 0x7Eu /* U+0020~U+007E 连续排列,每字 32 字节,无文件头。 */ extern const unsigned char my_font_bin[]; static int my_read_dot_font(unsigned long code, unsigned int option, unsigned char *buffer) { if (MY_FONT_OPTION != option || code < MY_FONT_FIRST || code > MY_FONT_LAST) { return 0; } memcpy(buffer, &my_font_bin[(code - MY_FONT_FIRST) * MY_FONT_BYTES], MY_FONT_BYTES); return MY_FONT_BYTES; } static int my_get_width(gt_custom_font_st *font, uint32_t code) { (void)font; return (code >= MY_FONT_FIRST && code <= MY_FONT_LAST) ? MY_FONT_WIDTH : 0; } static int my_get_height(gt_custom_font_st *font, uint32_t code) { (void)font; return (code >= MY_FONT_FIRST && code <= MY_FONT_LAST) ? MY_FONT_HEIGHT : 0; } static gt_custom_font_st my_font = { .ffs = { .option = MY_FONT_OPTION, .func.read_dot_font = my_read_dot_font, .type = GT_FONT_TYPE_FLAG_DOT_MATRIX, }, .get_dot_width = my_get_width, .get_width = my_get_width, .get_height = my_get_height, }; -
在
gt_init()之后、创建使用该字库的控件之前注册。引擎会复制注册结构体,但不会复制my_font_bin指向的数据,点阵数据必须长期有效:void my_font_init(void) { gt_custom_register_font(&my_font); } -
新版体系下,用
GT_FONT_FAMILY_ONE_TYPE将单一option作为 family 设置给控件,不需要调用旧版的gt_label_set_font_family_cn/en():void my_label_use_custom_font(gt_obj_st *label) { gt_label_set_font_size(label, MY_FONT_HEIGHT); gt_label_set_font_family(label, MY_FONT_FAMILY); }
自定义字库各字段的职责如下:
| 字段 / 宏 | 作用 | 本例约定 |
|---|---|---|
GT_CUSTOM_FONT_OPTION(option) | 设置自定义字库标记位;引擎按完整 ffs.option 精确查找 | 自定义 ID 为 1 |
ffs.func.read_dot_font | 按字符编码和 option 读取一个字形的点阵,返回实际字节数 | 返回 32;不支持的字符返回 0 |
ffs.type | 告诉引擎点阵、矢量等数据类型 | GT_FONT_TYPE_FLAG_DOT_MATRIX |
get_width / get_height | 返回排版使用的字形宽高 | 固定 16×16 |
get_dot_width | 启用点阵宽度查询时返回点阵宽度 | 等宽字库与 get_width 相同 |
GT_FONT_FAMILY_ONE_TYPE | 新版 family 的单字库直选标记 | 与 MY_FONT_OPTION 按位或 |
数据布局必须与引擎绘制约定一致。
read_dot_font没有缓冲区容量参数,调用方按当前字号、灰度和字库类型准备缓冲区;返回数据不能超过该容量。字符编码还会受控件文本编码和转码配置影响:本例只覆盖 UTF-8 文本中的 ASCII,不代表已经覆盖 GBK、中文、变宽字体、灰度或矢量字库。移植到目标工程后,应先用 ASCII、缺字和边界字符做仿真/真机验证。
9.5.2 GT-MD:复用已有字库驱动并提供绘制回调
GT-MD 不经过 gt_custom_register_font。它按 Unicode 码点调用 gt_latex_font_register 注册的字形尺寸回调,再调用 gt_latex_render_register 注册的字形与线条绘制回调。回调内部可以复用已有高通字库芯片驱动,也可以读取用户自己的点阵数据,无需另做一套仅供 GT-MD 使用的字库:
gt_latex_font_register(my_font_get, NULL);
gt_latex_render_register(my_draw_glyph, my_draw_hline,
my_draw_line, NULL);
完整回调签名、画布字段和流式调用示例见 GT-MD 流式渲染引擎 的“初始化:注册字库与绘制回调”。
9.5.3 免费取模工具与开源字体
- GT-FontLab Lite:高通提供的专业免费桌面工具。当前 v1.1.00.2604 可枚举 Windows 已安装字体,设置字号、样式、字符集、自定义字符/编码范围、点阵宽高、偏移和阈值,并预览、导出 1bpp 单色点阵的 Bin/C 数据、编码范围说明及逐字符图片。下载见 GT-FontLab Lite 官网工具页。
- GT-FontLab Plus:高通提供的免费在线取模工具,字体解析、取模与导出均在浏览器本地完成,字体文件不上传。支持系统字体与 TTF/OTF、1/2/4/8bpp 通用 RAW、24/48/96 字分页整批检查、文本效果预览与配置复用,参数记录与字符对照表随 ZIP 导出。其"连续排列、定长槽位"的导出布局与本节 9.5.1 示例的对应关系见 GT-FontLab Plus 使用手册。
- 输出接入方式:Lite 导出的是点阵数据及说明,不是自带统一文件头、可被任意引擎直接识别的字体文件。接入 9.5.1 时,应按“字符数 × 每字符字节数”读取有效点阵,并按导出的编码范围、扫描方向和位序实现索引,不要直接以 Bin 文件总长度计算字符数。
- 开源字体方案:可选择思源黑体、思源宋体等具有明确再分发许可的字体,安装到 Windows 后用 Lite 取模,再接入上述回调。字体开源不等于可以忽略许可,发布固件或字库数据前仍须核对对应字体许可证及 NOTICE 要求。
选择建议:评估/原型阶段可用合规字体 + GT-FontLab Lite 验证自有字库链路;量产且需要多语言、生僻字、灰度/矢量字库或芯片内置字库时,再选用高通商业字库芯片。
9.6 彩色 Emoji 字库
彩色 Emoji 是高通字库体系中的彩色位图字库资源,与矢量、灰度、点阵等文字字库独立选配,面向需要在界面上显示彩色 emoji 的产品。档位、字号、容量与芯片选型对照详见GUI 自定义字库芯片使用指南 · 彩色 Emoji 字库。
档位:分 Common 128(128 个常用 emoji)与 Emoji 14.0(1,357 个单码点)两档,各提供 16/20/24/32 px 四种字号。Common 128 按 Unicode 官方 2019 Emoji Frequency 从高到低选码,按此官方数据估算,约覆盖全部 emoji 使用量的 82%。
Common 128 档 24 px 全部 128 个字形(图形源 Twemoji 14.0.2)
查询接口:彩色 emoji 按单个 Unicode 码点查询(接口 GT_Emoji)。
能力边界:
- 仅支持单码点 emoji;旗帜、肤色变化、发型变化、ZWJ 组合人物、keycap 组合等多码点序列不在当前资源内;
- 彩色 emoji 为位图字形数据(RGB565+A8),不是矢量字形;
- 图形源为 Twemoji v14.0.2(CC-BY 4.0),对外发布与产品交付须保留 attribution,详见上述指南第 8.4 节。

