README.md
1@page freetype freetype
2
3[更正文档](https://gitee.com/alios-things/freetype/edit/master/README.md)      [贡献说明](https://help.aliyun.com/document_detail/302301.html)
4
5# 概述
6对于嵌入式系统应用中，尽管点阵字体在时间和空间性能上都有较佳的表现，但是由于缺乏灵活性，无法改变字体的大小、字形和风格，为解决这些问题，引入freetype2.5.3，FreeType库是一个开源的、可移植的字体引擎，它功能强大，简单说就是支持字体的花样显示。
7组件支持以下功能：
8- 支持多种字体格式文件，并提供了统一的访问接口；
9- 支持单色位图、反走样位图渲染；
10- 采用面向对象思想设计，用户可以灵活的根据需要裁剪。
11
12## 版权信息
13> FTL 一个类似BSD风格的license
14
15## 目录结构
16```tree
17├── FTL.TXT # license描述文件
18├── devel # DEBUG级别配置文件
19├── src # freetype实现文件
20├── include # freetype头文件
21├── package.yaml # 编译配置文件
22```
23
24## 依赖组件
25* vfs
26
27# 常用配置
28系统中相关配置已有默认值，如需修改配置，统一在yaml中**def_config**节点修改，具体如下：
29> 编译时允许引用内部头文件: 必须允许, 如果不允许会导致编译不过，在yaml中修改FT2_BUILD_LIBRARY配置
30```yaml
31def_config:
32 FT2_BUILD_LIBRARY: y
33```
34
35# API说明
36freetype API用法与开源版本一致，最重要最常用的API如下，其他API可以在网上搜索其用法。
37## FT_Init_FreeType初始化
38```C
39FT_Library pFTLib;
40// Init FreeType Lib to manage memory
41error = FT_Init_FreeType(&pFTLib);
42if (error)
43{
44 pFTLib = 0;
45 printf("There is some error when Init Library");
46 return -1;
47}
48```
49
50## FT_New_Face装载一个字体
51```C
52FT_Face pFTFace;
53// create font face from font file
54error = FT_New_Face(pFTLib, "arialuni.ttf", 0, &pFTFace);
55```
56
57## FT_Set_Char_Size和FT_Set_Pixel_Sizes设置当前字体大小跟像素尺寸
58当一个新的face对象建立时，所有成员都在初始化阶段设为0。调用FT_Set_Char_Size和FT_Set_Pixel_Sizes对这个结构进行赋值。
59```C
60FT_Set_Char_Size(face, /* handle to face object */
61 0, /* char_width in 1/64th of points */
62 16*64, /* char_height in 1/64th of points */
63 300, /* horizontal device resolution */
64 300 ); /* vertical device resolution */
65
66FT_Set_Pixel_Sizes(face, /* handle to face object */
67 0, /* pixel_width */
68 16 ); /* pixel_height */
69```
70
71## FT_Load_Glyph加载字符的glyph
72```C
73glyph_index = FT_Get_Char_Index(face, charcode);
74FT_Load_Glyph(face, /* handle to face object */
75 glyph_index, /* glyph index */
76 load_flags ); /* load flags, see below */
77```
78
79## FT_Set_Transform字体变换（旋转跟缩放）
80```C
81FT_Set_Transform(face, /* target face object */
82 &matrix, /* pointer to 2x2 matrix */
83 &delta); /* pointer to 2d vector */
84```
85
86# 使用示例
87用freetype显示一个字符的主要步骤：
880.初始化FT_Init_Freetype()
891.给定一个文字的ASCII码（例如‘A’是0x41）
902.提供一个字体文件
913.根据编码值到字体文件加载对应的glyph(glyph含有关键点，相对位置。实际上是根据字符的编码类型和编码值找到glyph，不同的编码类型的字符，要用不同的charmap来寻找其glyph,一个charmap支持一种编码,即有多个charmap以支持多种编码）可理解为字体文件含有charmap和字的对应glyph
924.设置字体大小
935.用某些函数把glyph里的关键点缩放为这个字体大小
946.转换为位图点阵（最终还是点阵）
957.在LCD上显示出来
96
97由于freetype是对矢量字体做显示，需要显示设备的配合，目前已经在SDL2中调用了freetype的接口去链接ttf字库，然后在屏幕上显示中英文字符，具体使用情况可以查看components/SDL2/src/ttf/SDL_TTF.c
98
99
100# FAQ
101Q1： 什么是charmap？
102> 答：字符影射表(charmap)。字符对应的字体数据称为glyph，字体文件中通常带有一个字符映射表，用来把字符映射到对应glyph的索引值。因为字符集的编码方式有多种，所以可以存在多个子映射表，以支持从不同编码的字符到glyph索引的映射。如果某个字符没有对应的glyph，返回索引 0 ，glyph 0 通常显示一个方块或者空格。
103
104Q2： freetype支持哪些字体格式？
105> 答：freetype提供统一的接口来访问多种字体格式文件，包括TrueType, OpenType, Type1, CID, CFF, Windows FON/FNT, X11 PCF等。
106