2. FreeType库入门：编译、移植与核心对象

做嵌入式字体渲染，FreeType 几乎是绕不开的库。我最早接触它是在一个智能手表项目上，那时候屏幕只有 1.3 寸，内存 64KB，跑 FreeType 简直是在刀尖上跳舞。但话说回来，只要把它的编译和核心对象搞明白，后面的事情就顺了。

这一章，咱们就聚焦三件事：怎么把 FreeType 编译进你的嵌入式环境、FT_Library 和 FT_Face 这两个核心对象到底怎么用、以及如何从字体文件里拿到你需要的度量信息。

2.1 FreeType的编译与移植

FreeType 的源码结构其实挺清晰的。你从官网下载源码包后，解压出来会看到 include、src、builds 这几个目录。我个人习惯直接拿源码编译，而不是用系统包管理器——因为嵌入式环境往往需要裁剪。

核心思路：FreeType 的编译本质是配置头文件 ftoption.h，把不需要的功能关掉，减小库体积。

具体步骤我总结为四步：

配置编译选项：进入 include/freetype/config，打开 ftoption.h。这里你会看到一堆 #define，比如 FT_CONFIG_OPTION_USE_PNG、FT_CONFIG_OPTION_USE_HARFBUZZ。嵌入式场景下，我建议先把这些全注释掉，只保留最基础的 TrueType 和 OpenType 支持。
选择编译模块：在 include/freetype/config/ftmodule.h 里，可以启用或禁用具体模块。比如你只需要 TrueType，那就只保留 tt_ 开头的模块。
交叉编译：用你的交叉工具链执行 ./configure --host=arm-linux-gnueabihf --prefix=/your/install/path。注意加上 --without-zlib 和 --without-png，除非你确实需要。
裁剪后编译：执行 make 和 make install。编译出来的库大概在 100KB 到 300KB 之间，取决于你开了多少功能。

我的经验：曾经在一个资源极度受限的项目里，我把 FreeType 裁剪到了 80KB 左右。方法是只保留 tt_ 和 sfnt 模块，连 truetype 的光栅化器都换成了 ftraster。效果还行，但渲染质量会下降一点。

移植到嵌入式系统时，你还需要注意内存分配。FreeType 默认使用 malloc/free，但你可以通过 FT_Set_Default_Properties 或自定义内存管理函数来替换。我一般会写一个简单的内存池，避免频繁的动态分配。

2.2 FT_Library 与 FT_Face 对象

这两个对象是 FreeType 的基石。你可以把 FT_Library 想象成整个 FreeType 引擎的“上下文”，而 FT_Face 是具体某个字体文件的“句柄”。

FT_Library 负责管理全局状态，比如内存分配器、缓存、模块注册等。整个程序只需要一个 FT_Library 实例，别重复创建。

FT_Face 则代表一个字体文件加载后的对象。它包含了字体的所有信息：字符映射、字形数量、度量数据、名称表等等。

初始化流程很简单：

FT_Library  library;
FT_Face     face;
FT_Error    error;

// 1. 初始化 FreeType 库
error = FT_Init_FreeType(&library);
if (error) {
    // 处理错误，比如返回 -1
}

// 2. 加载字体文件
error = FT_New_Face(library, "/path/to/font.ttf", 0, &face);
if (error == FT_Err_Unknown_File_Format) {
    // 字体格式不支持
} else if (error) {
    // 文件无法打开或读取
}

// 3. 使用完毕后释放
FT_Done_Face(face);
FT_Done_FreeType(library);

注意：我曾经犯过一个低级错误——在释放 FT_Face 之前就调用了 FT_Done_FreeType，结果导致内存泄漏。正确的顺序是：先释放所有 FT_Face，最后释放 FT_Library。

另外，FT_New_Face 的第三个参数是字体索引。对于包含多个字体的字体集（比如 TTC 文件），你需要指定索引 0、1、2... 来加载不同的字体。

2.3 加载字体文件与获取字体度量

字体度量是排版的基础。说白了，就是知道每个字符该画多大、间距多少、基线在哪。FreeType 提供了丰富的度量信息，我挑几个最常用的讲。

加载字体后，你可以直接访问 FT_Face 的成员来获取全局度量：

度量字段	含义	单位
`face->units_per_EM`	字体的 EM 方格大小	字体单位
`face->ascender`	上升高度（基线以上）	字体单位
`face->descender`	下降深度（基线以下，负值）	字体单位
`face->height`	行高（ascender - descender + line_gap）	字体单位
`face->max_advance_width`	最大字符宽度	字体单位

但这些是“字体单位”，要转换成像素，你需要设置字符大小：

// 设置字符大小为 16 像素，水平分辨率 96 DPI
FT_Set_Pixel_Sizes(face, 0, 16);

// 或者用点数和 DPI 设置
// FT_Set_Char_Size(face, 0, 16*64, 96, 96);

设置之后，face->size->metrics 里就包含了像素单位的度量：

FT_Size_Metrics  metrics = face->size->metrics;

// 上升高度（像素）
int ascender = metrics.ascender / 64;
// 下降深度（像素）
int descender = metrics.descender / 64;
// 行高（像素）
int height = metrics.height / 64;
// 最大字符宽度（像素）
int max_advance = metrics.max_advance / 64;

关键点：FreeType 内部使用 26.6 定点数格式，所以所有度量值都要除以 64 才能得到像素值。这个坑我踩过好几次，渲染出来的文字忽大忽小，最后发现是忘了除 64。

获取单个字符的度量，需要加载字形：

FT_UInt  glyph_index = FT_Get_Char_Index(face, 'A');
FT_Load_Glyph(face, glyph_index, FT_LOAD_DEFAULT);

// 字形度量
FT_GlyphSlot  slot = face->glyph;
int width   = slot->metrics.width / 64;
int height  = slot->metrics.height / 64;
int horiBearingX = slot->metrics.horiBearingX / 64;
int horiBearingY = slot->metrics.horiBearingY / 64;
int horiAdvance  = slot->metrics.horiAdvance / 64;

你想想看，有了这些数据，你就能精确地计算出每个字符的绘制位置。比如基线位置加上 horiBearingY 就是字符的顶部，horiAdvance 就是下一个字符的起始 X 坐标。

避坑指南：我曾经在处理阿拉伯语时发现字符间距不对。后来才意识到，FT_Load_Glyph 默认不应用 kerning（字距调整）。你需要用 FT_Get_Kerning 手动获取字距值，然后加到 advance 上。对于嵌入式场景，如果不需要复杂排版，可以忽略 kerning，能省不少计算量。

最后，我用一张图来总结 FreeType 的核心流程：

嗯，到这里，FreeType 的入门内容就差不多了。你只要掌握了编译裁剪、两个核心对象的生命周期、以及度量数据的读取，后面渲染字符、处理缓存、优化性能就都有了基础。记住，嵌入式环境里，能少调一个 API 就少调一个，能少算一个值就少算一个——这是我在无数次内存溢出后悟出来的道理。

📚 课程目录

2. FreeType库入门：编译、移植与核心对象

2.1 FreeType的编译与移植

2.2 FT_Library 与 FT_Face 对象

2.3 加载字体文件与获取字体度量