1、 freetype 教程第一步 简易的字形装载 介绍 这是“FreeType2 教程”的第一部分。它将教会你如何： * 初始化库 * 通过创建一个新的 face 对象来打开一个字体文件 * 以点或者象素的形式选择一个字符大小 * 装载一个字形 (glyph)图像，并把它转换为位图 * 渲染一个简单的字符串 * 容易地渲染一个旋转的字符串 1.头文件 下面的内容是编译一个使用了 FreeType2 库的应用程序所需要的指令。请谨慎阅读，自最近一次版本更新后我们已经更改了少许东西。 1.FreeType2 include 目录 你必须把 FreeType2 头文件的目录添加到编译包含(includ
2、e)目录中。 注意，现在在 Unix 系统，你可以运行 freetype-config 脚本加上-cflags 选项来获得正确的编译标记。这个脚本也可以用来检查安装在你系统中的库的版本，以及需要的库和连接标记。2. 包含名为 ft2build.h 的文件 Ft2build.h 包含了接下来要#include 的公共 FreeType2 头文件的宏声明。 3. 包含主要的 FreeType2 API 头文件 你要使用 FT_FREETYPE_H 宏来完成这个工作，就像下面这样： #include #include FT_FREETYPE_H FT_FREETYPE_H 是在 ftheader.h
3、 中定义的一个特别的宏。 Ftheader.h 包含了一些安装所特定的宏，这些宏指名了 FreeType2 API 的其他公共头文件。 你可以阅读“FreeType 2 API 参考”的这个部分来获得头文件的完整列表。 include 语句中宏的用法是服从 ANSI 的。这有几个原因： * 这可以避免一些令人痛苦的与 FreeType 1.x 公共头文件的冲突。 * 宏名字不受限于 DOS 的 8.3 文件命名限制。象 FT_MULTIPLE_MASTERS_H 或FT_SFNT_NAMES_H 这样的名字比真实的文件名 ftmm.h 和 fsnames.h 更具可读性并且更容易理解。 * 它
4、允许特别的安装技巧，我们不在这里讨论它。 注意：从 FreeType 2.1.6 开始，旧式的头文件包含模式将不会再被支持。这意味着现在如果你做了象下面那样的事情，你将得到一个错误： #include #include . . . 2. 初始化库 简单地创建一个 FT_Library 类型的变量，例如 library，然后象下面那样调用函数FT_Init_FreeType： #include #include FT_FREETYPE_H FT_LIBRARY library; . . . Error = FT_Init_FreeType ( If ( error ) . . . 当初始化库时发
5、生了一个错误 . . . 这个函数负责下面的事情： * 它创建一个 FreeType 2 库的新实例，并且设置句柄 library 为它。 * 它装载库中 FreeType 所知道的每一个模块。除了别的以外，你新建的 library 对象可以优雅地处理 TrueType, Type 1, CID-keyed 和 OpenType/CFF 字体。 就像你所看到的，这个函数返回一个错误代码，如同 FreeType API 的大部分其他函数一样。值为 0 的错误代码始终意味着操作成功了，否则，返回值指示错误，library 设为 NULL。 3装载一个字体 face a.从一个字体文件装载 应用程序
6、通过调用 FT_New_Face 创建一个新的 face 对象。一个 face 对象描述了一个特定的字样和风格。例如， Times New Roman Regular和 Times New Roman Italic对应两个不同的 face。 FT_Library library; /* 库的句柄 */ FT_Face face; /* face 对象的句柄 */ error = FT_Init_FreeType( if ( error ) . error = FT_New_Face( library, “/usr/share/fonts/truetype/arial.ttf“, 0, if (
7、 error = FT_Err_Unknown_File_Format ) . 可以打开和读这个文件，但不支持它的字体格式 else if ( error ) . 其它的错误码意味着这个字体文件不能打开和读，或者简单的说它损坏了. 就如你所想到的，FT_NEW_Face 打开一个字体文件，然后设法从中提取一个 face。它的参数为： Library 一个 FreeType 库实例的句柄，face 对象从中建立 Filepathname 字体文件路径名（一个标准的 C 字符串） Face_index 某些字体格式允许把几个字体 face 嵌入到同一个文件中。 这个索引指示你想装载的 face。
8、如果这个值太大，函数将会返回一个错误。Index 0 总是正确的。 Face 一个指向新建的 face 对象的指针。 当失败时其值被置为 NULL。 要知道一个字体文件包含多少个 face，只要简单地装载它的第一个 face(把 face_index 设置为 0)，face-num_faces 的值就指示出了有多少个 face 嵌入在该字体文件中。 b.从内存装载 如果你已经把字体文件装载到内存，你可以简单地使用 FT_New_Memory_Face 为它新建一个 face 对象，如下所示： FT_Library library; /* 库的句柄 */ FT_Face face; /* fac
9、e 对象的句柄 */ error = FT_Init_FreeType( if ( error ) . error = FT_New_Memory_Face( library, buffer, /* 缓存的第一个字节 */ size, /* 缓存的大小（以字节表示） */ 0, /* face 索引 */ if ( error ) . 如你所看到的，FT_New_Memory_Face 简单地用字体文件缓存的指针和它的大小（以字节计算）代替文件路径。除此之外，它与 FT_New_Face 的语义一致。c.从其他来源装载（压缩文件，网络，等） 使用文件路径或者预装载文件到内存是简单的，但还不足够
10、。FreeType 2 可以支持通过你自己实现的 I/O 程序来装载文件。 这是通过 FT_Open_Face 函数来完成的。 FT_Open_Face 可以实现使用一个自定义的输入流，选择一个特定的驱动器来打开，乃至当创建该对象时传递外部参数给字体驱动器。我们建议你查阅“FreeType 2 参考手册 ”，学习如何使用它。 4访问 face 内容 一个 face 对象包含该 face 的全部全局描述信息。通常的，这些数据可以通过分别查询句柄来直接访问，例如 face-num_glyphs。 FT_FaceRec 结构描述包含了可用字段的完整列表。我们在这里详细描述其中的某些： Num_gly
11、phs 这个值给出了该字体 face 中可用的字形 (glyphs)数目。简单来说，一个字形就是一个字符图像。但它不一定符合一个字符代码。 Flags 一个 32 位整数，包含一些用来描述 face 特性的位标记。例如，标记FT_FACE_FLAG_SCALABLE 用来指示该 face 的字体格式是可伸缩并且该字形图像可以渲染到任何字符象素尺寸。要了解 face 标记的更多信息，请阅读“FreeType 2 API 参考” 。 Units_per_EM 这个字段只对可伸缩格式有效，在其他格式它将会置为 0。它指示了 EM 所覆盖的字体单位的个数。 Num_fixed_size 这个字段给出了
12、当前 face 中嵌入的位图的个数。简单来说，一个 strike 就是某一特定字符象素尺寸下的一系列字形图像。例如，一个字体 face 可以包含象素尺寸为 10、12 和 14 的strike。要注意的是即使是可伸缩的字体格式野可以包含嵌入的位图！ Fixed_sizes 一个指向 FT_Bitmap_Size 成员组成的数组的指针。每一个 FT_Bitmap_Size 指示 face 中的每一个 strike 的水平和垂直字符象素尺寸。 注意，通常来说，这不是位图 strike 的单元尺寸。 5设置当前象素尺寸 对于特定 face 中与字符大小相关的信息， FreeType 2 使用 siz
13、e 对象来构造。例如，当字符大小为 12 点时，使用一个 size 对象以 1/64 象素为单位保存某些规格（如 ascender 或者文字高度）的值。 当 FT_New_Face 或它的亲戚被调用，它会自动在 face 中新建一个 size 对象，并返回。该size 对象可以通过 face-size 直接访问。 注意：一个 face 对象可以同时处理一个或多个 size 对象，但只有很少程序员需要用到这个功能，因而，我们决定简化该 API， （例如，每个 face 对象只拥有一个 size 对象）但是这个特性我们仍然通过附加的函数提供。 当一个新的 face 对象建立时，对于可伸缩字体格式，
14、 size 对象默认值为字符大小水平和垂直均为 10 象素。对于定长字体格式，这个大小是未定义的，这就是你必须在装载一个字形前设置该值的原因。 使用 FT_Set_Char_Size 完成该功能。这里有一个例子，它在一个 300x300dpi 设备上把字符大小设置为 16pt。 error = FT_Set_Char_Size( face, /* face 对象的句柄 */ 0, /* 以 1/64 点为单位的字符宽度 */ 16*64, /* 以 1/64 点为单位的字符高度 */ 300, /* 设备水平分辨率 */ 300 ); /* 设备垂直分辨率 */ 注意： * 字符宽度和高度以
15、1/64 点为单位表示。一个点是一个 1/72 英寸的物理距离。通常，这不等于一个象素。 * 设备的水平和垂直分辨率以每英寸点数(dpi)为单位表示。显示设备（如显示器）的常规值为 72dpi 或 96dpi。这个分辨率是用来从字符点数计算字符象素大小的。 * 字符宽度为 0 意味着“与字符高度相同” ，字符高度为 0 意味着“与字符宽度相同” 。对于其他情况则意味着指定不一样的字符宽度和高度。 * 水平或垂直分辨率为 0 时表示使用默认值 72dpi。 * 第一个参数是 face 对象的句柄，不是 size 对象的。 这个函数计算对应字符宽度、高度和设备分辨率的字符象素大小。然而，如果你想自
16、己指定象素大小，你可以简单地调用 FT_Set_Pixel_Sizes，就像这样： error = FT_Set_Pixel_Sizes( face, /* face 对象句柄 */ 0, /* 象素宽度 */ 16 ); /* 象素高度 */ 这个例子把字符象素设置为 16x16 象素。如前所说的，尺寸中的任一个为 0 意味着“与另一个尺寸值相等” 。 注意这两个函数都返回错误码。通常，错误会发生在尝试对定长字体格式（如 FNT 或PCF）设置不在 face-fixed_size 数组中的象素尺寸值。 6装载一个字形图像 a.把一个字符码转换为一个字形索引 通常，一个应用程序想通过字符码来装
17、载它的字形图像。字符码是一个特定编码中代表该字符的数值。例如，字符码 64 代表了 ASCII 编码中的A 。 一个 face 对象包含一个或多个字符表(charmap)，字符表是用来转换字符码到字形索引的。例如，很多 TrueType 字体包含两个字符表，一个用来转换 Unicode 字符码到字形索引，另一个用来转换 Apple Roman 编码到字形索引。这样的字体既可以用在 Windows（使用Unicode）和 Macintosh（使用 Apple Roman） 。同时要注意，一个特定的字符表可能没有覆盖完字体里面的全部字形。 当新建一个 face 对象时，它默认选择 Unicode
18、字符表。如果字体没包含 Unicode 字符表，FreeType 会尝试在字形名的基础上模拟一个。注意，如果字形名是不标准的那么模拟的字符表有可能遗漏某些字形。对于某些字体，包括符号字体和旧的亚洲手写字体，Unicode模拟是不可能的。 我们将在稍后叙述如何寻找 face 中特定的字符表。现在我们假设 face 包含至少一个Unicode 字符表，并且在调用 FT_New_Face 时已经被选中。我们使用 FT_Get_Char_Index 把一个 Unicode 字符码转换为字形索引，如下所示： glyph_index = FT_Get_Char_Index( face, charcode
19、); 这个函数会在 face 里被选中的字符表中查找与给出的字符码对应的字形索引。如果没有字符表被选中，这个函数简单的返回字符码。 注意，这个函数是 FreeType 中罕有的不返回错误码的函数中的一个。然而，当一个特定的字符码在 face 中没有字形图像，函数返回 0。按照约定，它对应一个特殊的字形图像缺失字形，通常会显示一个框或一个空格。 b.从 face 中装载一个字形 一旦你获得了字形索引，你便可以装载对应的字形图像。在不同的字体中字形图像存储为不同的格式。对于固定尺寸字体格式，如 FNT 或者 PCF，每一个图像都是一个位图。对于可伸缩字体格式，如 TrueType 或者 Type1
20、，使用名为轮廓(outlines) 的矢量形状来描述每一个字形。一些字体格式可能有更特殊的途径来表示字形（如 MetaFont但这个格式不被支持） 。幸运的，FreeType2 有足够的灵活性，可以通过一个简单的 API 支持任何类型的字形格式。 字形图像存储在一个特别的对象字形槽(glyph slot)中。就如其名所暗示的，一个字形槽只是一个简单的容器，它一次只能容纳一个字形图像，可以是位图，可以是轮廓，或者其他。每一个 face 对象都有一个字形槽对象，可以通过 face-glyph 来访问。它的字段在FT_GlyphSlotRec 结构的文档中解释了。 通过调用 FT_Load_Glyp
21、h 来装载一个字形图像到字形槽中，如下： error = FT_Load_Glyph( face, /* face 对象的句柄 */ glyph_index, /* 字形索引 */ load_flags ); /* 装载标志，参考下面 */ load_flags 的值是位标志集合，是用来指示某些特殊操作的。其默认值是 FT_LOAD_DEFAULT即 0。 这个函数会设法从 face 中装载对应的字形图像： * 如果找到一个对应该字形和象素尺寸的位图，那么它将会被装载到字形槽中。嵌入的位图总是比原生的图像格式优先装载。因为我们假定对一个字形，它有更高质量的版本。这可以用 FT_LOAD_NO_
22、BITMAP 标志来改变。 * 否则，将装载一个该字形的原生图像，把它伸缩到当前的象素尺寸，并且对应如TrueType 和 Type1 这些格式，也会完成 hinted 操作。 字段 face-glyph-format 描述了字形槽中存储的字形图像的格式。如果它的值不是FT_GLYPH_FORMAT_BITMAP，你可以通过 FT_Render_Glyph 把它直接转换为一个位图。如下： error = FT_Render_Glyph( face-glyph, /* 字形槽 */ render_mode ); /* 渲染模式 */ render_mode 参数是一个位标志集合，用来指示如何渲染
23、字形图像。把它设为FT_RENDER_MODE_NORMAL 渲染出一个高质量的抗锯齿(256 级灰度)位图。这是默认情况，如果你想生成黑白位图，可以使用 FT_RENDER_MODE_MONO 标志。 一旦你生成了一个字形图像的位图，你可以通过 glyph-bitmap(一个简单的位图描述符)直接访问，同时用 glyph-bitmap_left 和 glyph-bitmap_top 来指定起始位置。 要注意，bitmap_left 是从字形位图当前笔位置到最左边界的水平距离，而 bitmap_top 是从笔位置（位于基线）到最高边界得垂直距离。他么是正数，指示一个向上的距离。 下一部分将给出
24、字形槽内容的更多细节，以及如何访问特定的字形信息（包括度量） 。 c.使用其他字符表 如前面所说的，当一个新 face 对象创建时，它会寻找一个 Unicode 字符表并且选择它。当前被选中的字符表可以通过 face-charmap 访问。当没有字符表被选中时，该字段为NULL。这种情况在你从一个不含 Unicode 字符表的字体文件（这种文件现在非常罕见）创建一个新的 FT_Face 对象时发生。 有两种途径可以在 FreeType 2 中选择不同的字符表。最轻松的途径是你所需的编码已经有对应的枚举定义在 FT_FREETYPE_H 中，例如 FT_ENCODING_BIG5。在这种情况下，
25、你可以简单地调用 FT_Select_CharMap，如下： error = FT_Select_CharMap( face, /* 目标 face 对象 */ FT_ENCODING_BIG5 ); /* 编码 */ 另一种途径是手动为 face 解析字符表。这通过 face 对象的字段 num_charmaps 和charmaps(注意这是复数)来访问。如你想到的，前者是 face 中的字符表的数目，后者是一个嵌入在 face 中的指向字符表的指针表 (a table of pointers to the charmaps)。 每一个字符表有一些可见的字段，用来更精确地描述它，主要用到的字
26、段是 charmap-platform_id 和 charmap-encoding_id。这两者定义了一个值组合，以更普 通的形式用来描述该字符表。 每一个值组合对应一个特定的编码。例如组合(3,1)对应 Unicode。组合列表定义在TrueType 规范中，但你也可以使用文件 FT_TRUETYPE_IDS_H 来处理它们，该文件定义了几个有用的常数。 要选择一个具体的编码，你需要在规范中找到一个对应的值组合，然后在字符表列表中寻找它。别忘记，由于历史的原因，某些编码会对应几个值组合。这里是一些代码： FT_CharMap found = 0; FT_CharMap charmap; in
27、t n; for ( n = 0; n num_charmaps; n+ ) charmap = face-charmapsn; if ( charmap-platform_id = my_platform_id break; if ( !found ) . /* 现在，选择 face 对象的字符表*/ error = FT_Set_CharMap( face, found ); if ( error ) . 一旦某个字符表被选中，无论通过 FT_Select_CharMap 还是通过 FT_Set_CharMap，它都会在后面的 FT_Get_Char_Index 调用使用。d.字形变换 当
28、字形图像被装载时，可以对该字形图像进行仿射变换。当然，这只适用于可伸缩（矢量）字体格式。 简单地调用 FT_Set_Transform 来完成这个工作，如下： error = FT_Set_Transform( face, /* 目标 face 对象 */ /* 指向 2 维矢量的指针 */ 这个函数将对指定的 face 对象设置变换。它的第二个参数是一个指向 FT_Matrix 结 构的指针。该结构描述了一个 2x2 仿射矩阵。第三个参数是一个指向 FT_Vector 结构的指针。该结构描述了一个简单的二维矢量。该矢量用来在 2x2 变换后对字形图像平移。 注意，矩阵指针可以设置为 NULL
29、，在这种情况下将进行恒等变换。矩阵的系数是 16.16 形式的固定浮点单位。 矢量指针也可以设置为 NULL，在这种情况下将使用(0, 0)的 delta。矢量坐标以一个象素的1/64 为单位表示（即通常所说的 26.6 固定浮点格式） 。 注意：变换将适用于使用 FT_Load_Glyph 装载的全部字形，并且完全独立于任何 hinting 处理。这意味着你对一个 12 象素的字形进行 2 倍放大变换不会得到与 24 象素字形相同的结果（除非你禁止 hints） 。 如果你需要使用非正交变换和最佳 hints，你首先必须把你的变换分解为一个伸缩部分和一个旋转/剪切部分。使用伸缩部分来计算一个
30、新的字符象素大小，然后使用旋转/剪切部分来调用 FT_Set_Transform。这在本教程的后面部分有详细解释。 同时要注意，对一个字形位图进行非同一性变换将产生错误。 7. 简单的文字渲染 现在我们将给出一个非常简单的例子程序，该例子程序渲染一个 8 位 Latin-1 文本字符串，并且假定 face 包含一个 Unicode 字符表。 该程序的思想是建立一个循环，在该循环的每一次迭代中装载一个字形图像，把它转换为一个抗锯齿位图，把它绘制到目标表面(surface)上，然后增加当前笔的位置。 a.基本代码 下面的代码完成我们上面提到的简单文本渲染和其他功能。 FT_GlyphSlot sl
31、ot = face-glyph; /* 一个小捷径 */ int pen_x, pen_y, n; . initialize library . . create face object . . set character size . pen_x = 300; pen_y = 200; for ( n = 0; n glyph, ft_render_mode_normal ); if ( error ) continue; /* 现在，绘制到我们的目标表面(surface) */ my_draw_bitmap( /* 增加笔位置 */ pen_x += slot-advance.x 6; p
32、en_y += slot-advance.y 6; /* 现在还是没用的 */ 这个代码需要一些解释： * 我们定义了一个名为 slot 的句柄，它指向 face 对象的字形槽。 （FT_GlyphSlot 类型是一个指针） 。这是为了便于避免每次都使用 face-glyph-XXX。 * 我们以 slot-advance 增加笔位置， slot-advance 符合字形的步进宽度（也就是通常所说的走格(escapement)） 。步进矢量以象素的 1/64 为单位表示，并且在每一次迭代中删减为整数象素。 * 函数 my_draw_bitmap 不是 FreeType 的一部分，但必须由应用程
33、序提供以用来绘制位图到目标表面。在这个例子中，该函数以一个 FT_Bitmap 描述符的指针和它的左上角位置为参数。 * Slot-bitmap_top 的值是正数，指字形图像顶点与 pen_y 的垂直距离。我们假定my_draw_bitmap 采用的坐标使用一样的约定（增加 Y 值对应向下的扫描线） 。我们用pen_y 减它，而不是加它。 b.精练的代码 下面的代码是上面例子程序的精练版本。它使用了 FreeType 2 中我们还没有介绍的特性和函数，我们将在下面解释： FT_GlyphSlot slot = face-glyph; /* 一个小捷径 */ FT_UInt glyph_ind
34、ex; int pen_x, pen_y, n; . initialize library . . create face object . . set character size . pen_x = 300; pen_y = 200; for ( n = 0; n bitmap, pen_x + slot-bitmap_left, pen_y - slot-bitmap_top ); /* 增加笔位置 */ pen_x += slot-advance.x 6; 我们简化了代码的长度，但它完成相同的工作： * 我们使用函数 FT_Loac_Char 代替 FT_Load_Glyph。如你大概
35、想到的，它相当于先调用GT_Get_Char_Index 然后调用 FT_Get_Load_Glyph。 * 我们不使用 FT_LOAD_DEFAULT 作为装载模式，使用 FT_LOAD_RENDER。它指示了字形图像必须立即转换为一个抗锯齿位图。这是一个捷径，可以取消明显的调用FT_Render_Glyph，但功能是相同的。 注意，你也可以指定通过附加 FT_LOAD_MONOCHROME 装载标志来获得一个单色位图。 c.更高级的渲染 现在，让我们来尝试渲染变换文字（例如通过一个环） 。我们可以用 FT_Set_Transform 来完成。这里是示例代码： FT_GlyphSlot sl
36、ot; FT_Matrix matrix; /* 变换矩阵 */ FT_UInt glyph_index; FT_Vector pen; /* 非变换原点 */ int n; . initialize library . . create face object . . set character size . slot = face-glyph; /* 一个小捷径 */ /* 准备矩阵 */ matrix.xx = (FT_Fixed)( cos( angle ) * 0x10000L ); matrix.xy = (FT_Fixed)(-sin( angle ) * 0x10000L );
37、 matrix.yx = (FT_Fixed)( sin( angle ) * 0x10000L ); matrix.yy = (FT_Fixed)( cos( angle ) * 0x10000L ); /* 26.6 笛卡儿空间坐标中笔的位置，以(300, 200)为起始 */ pen.x = 300 * 64; pen.y = ( my_target_height - 200 ) * 64; for ( n = 0; n bitmap, slot-bitmap_left, my_target_height - slot-bitmap_top ); /* 增加笔位置 */ pen.x +=
38、 slot-advance.x; pen.y += slot-advance.y; 一些说明： * 现在我们使用一个 FT_Vector 类型的矢量来存储笔位置，其坐标以象素的 1/64 为单位表示，并且倍增。该位置表示在笛卡儿空间。 * 不同于系统典型的对位图使用的坐标系（其最高的扫描线是坐标 0） ，FreeType 中，字形图像的装载、变换和描述总是采用笛卡儿坐标系（这意味着增加 Y 对应向上的扫描线） 。因此当我们定义笔位置和计算位图左上角时必须在两个系统之间转换。 * 我们对每一个字形设置变换来指示旋转矩阵以及使用一个 delta 来移动转换后的图像到当前笔位置（在笛卡儿空间，不是位
39、图空间） 。结果，bitmap_left 和 bitmap_top 的值对应目标空间象素中的位图原点。因此，我们在调用 my_draw_bitmap 时不在它们的值上加 pen.x或 pen.y。 * 步进宽度总会在变换后返回，这就是它可以直接加到当前笔位置的原因。注意，这次它不会四舍五入。 一个例子完整的源代码可以在这里找到。 要很注意，虽然这个例子比前面的更复杂，但是变换效果是完全一致的。因此它可以作为一个替换（但更强大） 。 然而该例子有少许缺点，我们将在本教程的下一部分中解释和解决。 结论 在这个部分，你已经学习了 FreeType2 的基础以及渲染旋转文字的充分知识。 下一部分将深入了解 FreeType 2 API 更详细的资料，它可以让你直接访问字形度量标准和字形图像，还能让你学习到如何处理缩放、hinting、自居调整，等等。 第三部分将讨论模块、缓存和其他高级主题，如如何在一个 face 中使用多个尺寸对象。
