The design of FreeType 2

From Mxtctp

原文链接：http://www.freetype.org/freetype2/docs/design/index.html
翻译人员：HappyLiu

英文

中文

The design of FreeType 2

FreeType 2的设计

This document describes the details of FreeType 2's internals. Read this carefully if you need to understand the innards of the library in order to hack or extend it.

Table of Contents

Introduction
I. Components and APIs
II. Public Objects and Classes
III. Internal Objects and Classes
IV. Module Classes

介绍
一、组件和API
二、公共对象和类
三、内部对象和类
四、模块类

Introduction

介绍

This document provides details on the design and implementation of the FreeType 2 library. Its goal is to allow developers to better understand the way how FreeType 2 is organized, in order to let them extend, customize, and debug it.

这份文档提供了FreeType 2函数库设计与实现的细节。本文档的目标是让开发人员更好的理解FreeType 2是如何组织的，并让他们扩充、定制和调试它。

Before anything else, it is important to understand the purpose of this library, i.e., why it has been written:

It allows client applications to access font files easily, wherever they could be stored, and as independently of the font format as possible.

Easy retrieval of global font data most commonly found in normal font formats (i.e. global metrics, encoding/charmaps, etc.).

It allows easy retrieval of individual glyph data (metrics, images, name, anything else).

Access to font format-specific "features" whenever possible (e.g. SFNT tables, Multiple Masters, OpenType Layout tables, etc.).

首先，我们先了解这个库的目的，也就是说，为什么会写这个库：

它让客户应用程序方便的访问字体文件，无论字体文件存储在哪里，并且与字体格式无关。

方便的提取全局字体数据，这些数据在平常的字体格式中普遍存在。（例如：全局度量标准，字符编码/字符映射表，等等）

方便的提取某个字符的字形数据（度量标准，图像，名字，其他任何东西）

访问字体格式特定的功能（例如，SFNT表，多重控制，OpenType轮廓表）

Its design has also severely been influenced by the following requirements:

High portability. The library must be able to run on any kind of environment. This requirement introduces a few drastic choices that are part of FreeType 2's low-level system interface.

Extendability. New features should be added with the least modifications in the library's code base. This requirement induces an extremely simple design where nearly all operations are provided by modules.

Customization. It should be easy to build a version of the library that only contains the features needed by a specific project. This really is important when you need to integrate it in a font server for embedded graphics libraries.

Compactness and efficiency. The primary target for this library are embedded systems with low cpu and memory resources.

Freetype 2的设计也受如下要求很大的影响：

高可移植性。这个库必须可以运行在任何环境中。这个要求引入了一些非常激烈的选择，这些是FreeType2的低级系统界面的一部分。

可扩展性。新特性应该可以在极少改动库基础代码的前提下添加。这个要求引入了非常简单的设计：几乎所有操作都是以模块的形式提供的。

可定制。它应该能够很容易建立一个只包含某个特定项目所需的特性的版本。当你需要集成它到一个嵌入式图形库的字体服务器中时，这是非常重要的。

简洁高效。这个库的主要目标是只有很少cpu和内存资源的嵌入式系统。

The rest of this document is divided in several sections. First, a few chapters will present the library's basic design as well as the objects/data managed internally by FreeType 2.

这份文档的其他部分分为几个部分。首先，一些章节介绍了库的基本设计以及Freetype 2内部对象/数据的管理。

A later section is then dedicated to library customization, relating such topics as system-specific interfaces, how to write your own module and how to tailor library initialization & compilation to your needs.

接下来的章节专注于库的定制和与这个话题相关的系统特定的界面，如何写你自己的模块和如何按需裁减库初始化和编译。

I. Components and APIs

一、组件和API

It's better to describe FreeType 2 as a collection of components. Each one of them is a more or less abstract part of the library that is in charge of one specific task. We will now explicit the connections and relationships between them.

FT可以看作是一组组件，每个组件负责一部分任务，它们包括

A first brief description of this system of components could be:

Client applications typically call the FreeType 2 high-level API, whose functions are implemented in a single component called the Base Layer.

Depending on the context or the task, the base layer then calls one or more module components to perform the work. In most cases, the client application doesn't need to know which module was called.

The base layer also contains a set of routines that are used for generic things like memory allocation, list processing, i/o stream parsing, fixed point computation, etc. these functions can also be called by a module at any time, and they form what is called the low-level base API.

客户应用程序一般会调用FT高层API，它的功能都在一个组件中，叫做基础层。

根据上下文和环境，基础层会调用一个或多个模块进行工作，大多数情况下，客户应用程序不需要知道使用那个模块。

基础层还包含一组例程来进行一些共通处理，例如内存分配，列表处理、io流解析、固定点计算等等，这些函数可以被模块随意调用，它们形成了一个底层基础API。

This is illustrated by the following graphics (note that component entry points are represented as colored triangles):

如下图，表明它们的关系

Now, a few additional things must be added to complete this picture:

Some parts of the base layer can be replaced for specific builds of the library, and can thus be considered as components themselves. This is the case for the ftsystem component, which is in charge of implementing memory management & input stream access, as well as ftinit, which is in charge of library initialization (i.e. implementing the FT_Init_FreeType() function).

FreeType 2 comes also with a set of optional components, which can be used either as a convenience for client applications (e.g. the ftglyph component, used to provide a simple API to manage glyph images independently of their internal representation), or to access format-specific features (e.g. the ftmm component used to access and manage Multiple Masters data in Type 1 fonts).

Finally, a module is capable of calling functions provided by another module. This is very useful to share code and tables between several font driver modules (for example, the truetype and cff modules both use the routines provided by the sfnt module).

另外，

为了一些特殊的构建，基础层的有些部分可以替换掉，也可以看作组件。例如ftsystem组件，负责实现内存管理和输入流访问，还有ftinit，负责库初始化。

FT还有一些可选的组件，可以根据客户端应用灵活使用，例如ftglyph组件提供一个简单的API来管理字形映象，而不依赖它们内部表示法。或者是访问特定格式的特性，例如ftmm组件用来访问和管理Type1字体中Multiple Masters数据。

最后，一个模块可以调用其他模块提供的函数，这对在多个字体驱动模块中共享代码和表非常有用，例如truetype和cff模块都使用sfnt模块提供的函数。

Hence, a more complete picture would be:

见下图，是对上图的一个细化。

Please take note of the following important points:

An optional component can use either the high-level or base API. This is the case of ftglyph in the above picture.

Some optional components can use module-specific interfaces ignored by the base layer. In the above example, ftmm directly accesses the Type 1 module to set/query data.

A replacable component can provide a function of the high-level API. For example, ftinit provides FT_Init_FreeType() to client applications.

请注意一些要点：

一个可选的组件可以用在高层API，也可以用在底层API，例如上面的ftglyph；

有些可选组件使用模块特定的接口，而不是基础层的接口，上例中，ftmm直接访问Type1模块来访问数据；

一个可替代的组件能够提供一个高层API的函数，例如，ftinit提供FT_Init_FreeType()。

II. Public Objects and Classes

二、公共对象和类

We will now explain the abstractions provided by FreeType 2 to client applications to manage font files and data. As you would normally expect, these are implemented through objects/classes.

1. Object Orientation in FreeType 2

1、FT中的面向对象

Though written in ANSI C, the library employs a few techniques, inherited from object-oriented programming, to make it easy to extend. Hence, the following conventions apply in the FreeType 2 source code:

虽然FT是使用ANSI C编写，但是采用面向对象的思想，是这个库非常容易扩展。因此，下面有一些代码规约：

1. Each object type/class has a corresponding structure type and a corresponding structure pointer type. The latter is called the handle type for the type/class.

Consider that we need to manage objects of type "foo" in FreeType 2. We would define the following structure and handle types as follows:

   typedef struct FT_FooRec_*  FT_Foo;
 
   typedef struct  FT_FooRec_
   {
     // fields for the "foo" class
     ...
 
   } FT_FooRec;

As a convention, handle types use simple but meaningful identifiers beginning with FT_, as in FT_Foo, while structures use the same name with a Rec suffix appended to it ("Rec" is short for "record"). Note that each class type has a corresponding handle type.

1. 每个对象类型/类都有一个对应的结构类型和一个对应的结构指针类型。后者称为类型/类的句柄类型。

设想我们需要管理FT中一个foo类的对象，可以定义如下

   typedef struct FT_FooRec_*  FT_Foo;
 
   typedef struct  FT_FooRec_
   {
     // fields for the "foo" class
     ...
 
   } FT_FooRec;

依照规约，句柄类型使用简单而有含义的标识符，并以FT_开始，如FT_Foo，而结构体使用相同的名称但是加上Rec后缀。Rec是记录的缩写。每个类类型都有对应的句柄类型；

2. Class derivation is achieved internally by wrapping base class structures into new ones. As an example, we define a "foobar" class that is derived from "foo". We would do something like:

   typedef struct FT_FooBarRec_*  FT_FooBar;
 
   typedef struct  FT_FooBarRec_
   {
     // the base "foo" class fields
     FT_FooRec  root;
 
     // fields proper to the "foobar" class
     ...
   } FT_FooBarRec;

As you can see, we ensure that a "foobar" object is also a "foo" object by placing a FT_FooRec at the start of the FT_FooBarRec definition. It is called root by convention.

Note that a FT_FooBar handle also points to a "foo" object and can be typecasted to FT_Foo. Similarly, when the library returns a FT_Foo handle to client applications, the object can be really implemented as a FT_FooBar or any derived class from "foo".

2. 类继承通过将基类包装到一个新类中实现，例如，我们定义一个foobar类，从foo类继承，可以实现为

   typedef struct FT_FooBarRec_*  FT_FooBar;
 
   typedef struct  FT_FooBarRec_
   {
     // the base "foo" class fields
     FT_FooRec  root;
 
     // fields proper to the "foobar" class
     ...
   } FT_FooBarRec;

可以看到，将一个FT_FooRec放在FT_FooBarRec定义的开始，并约定名为root，可以确保一个foobar对象也是一个foo对象。

在实际使用中，可以进行类型转换。

In the following sections of this chapter, we will refer to "the FT_Foo class" to indicate the type of objects handled through FT_Foo pointers, be they implemented as "foo" or "foobar".

后面

2. The FT_Library class

2、FT_Library类

This type corresponds to a handle to a single instance of the library. Note that the corresponding structure FT_LibraryRec is not defined in public header files, making client applications unable to access its internal fields.

这个类型对应一个库的单一实例句柄，没有定义相应的FT_LibraryRec，使客户应用无法访问它的内部属性。

The library object is the parent of all other objects in FreeType 2. You need to create a new library instance before doing anything else with the library. Similarly, destroying it will automatically destroy all its children (i.e. faces and modules).

库对象是所有FT其他对象的父亲，你需要在做任何事情前创建一个新的库实例，销毁它时会自动销毁他所有的孩子，如face和module等。

Typical client applications should call FT_Init_FreeType() in order to create a new library object, ready to be used for further actions.

通常客户程序应该调用FT_Init_FreeType()来创建新的库对象，准备作其他操作时使用。

Another alternative is to create a fresh new library instance by calling the function FT_New_Library(), defined in the <freetype/ftmodule.h> public header file. This function will however return an "empty" library instance with no module registered in it. You can "install" modules in the instance by calling FT_Add_Module() manually.

另一个方式是通过调用函数FT_New_Library()来创建一个新的库对象，它在中定义，这个函数返回一个空的库，没有任何模块注册，你可以通过调用FT_Add_Module()来安装模块。

Calling FT_Init_FreeType() is a lot more convenient, because this function basically registers a set of default modules into each new library instance. The way this list is accessed and/or computed is determined at build time, and depends on the content of the ftinit component. This process is explained in details later in this document.

调用FT_Init_FreeType()更方便一些，因为他会缺省地注册一些模块。这个方式中，模块列表在构建时动态计算，并依赖ftinit部件的内容。（译注：见ftinit.c[l73]行，include FT_CONFIG_MODULES_H，其实就是包含ftmodule.h，在ftmodule.h中定义缺省的模块，所以模块数组 ft_default_modules的大小是在编译时动态确定的。）

For now, one should consider that library objects are created with FT_Init_FreeType(), and destroyed along with all children with FT_Done_FreeType().

3. The FT_Face class

3、FT_Face类

A face object corresponds to a single font face, i.e., a specific typeface with a specific style. For example, "Arial" and "Arial Italic" correspond to two distinct faces.

一个外观对象对应单个字体外观，即一个特定风格的特定外观类型，例如Arial和Arial Italic是两个不同的外观。

A face object is normally created through FT_New_Face(). This function takes the following parameters: an FT_Library handle, a C file pathname used to indicate which font file to open, an index used to decide which face to load from the file (a single file may contain several faces in certain cases), and the address of a FT_Face handle. It returns an error code:

   FT_Error  FT_New_Face( FT_Library   library,
                          const char*  filepathname,
                          FT_Long      face_index,
                          FT_Face*     face );

In case of success, the function will return 0, and the handle pointed to by the face parameter will be set to a non-NULL value.

一个外观对象通常使用FT_New_Face()来创建，这个函数接受如下参数：一个FT_Library句柄，一个表示字体文件的C文件路径名，一个决定从文件中装载外观的索引（一个文件中可能有不同的外观），和FT_Face句柄的地址，它返回一个错误码。

   FT_Error  FT_New_Face( FT_Library   library,
                          const char*  filepathname,
                          FT_Long      face_index,
                          FT_Face*     face );

函数调用成功，返回0，face参数将被设置成一个非NULL值。

Note that the face object contains several fields used to describe global font data that can be accessed directly by client applications. For example, the total number of glyphs in the face, the face's family name, style name, the EM size for scalable formats, etc. For more details, look at the FT_FaceRec definition in the FreeType 2 API Reference.

外观对象包含一些用来描述全局字体数据的属性，可以被客户程序直接访问。例如外观中字形的数量、外观家族的名称、风格名称、EM大小等，详见FT_FaceRec定义。

4. The FT_Size class

4、FT_Size类

Each FT_Face object has one or more FT_Size objects. A size object is used to store data specific to a given character width and height. Each newly created face object has one size, which is directly accessible as face->size.

每个FT_Face对象都有一个或多个FT_Size对象，一个尺寸对象用来存放指定字符宽度和高度的特定数据，每个新创建的外观对象有一个尺寸，可以通过face->size直接访问。

The contents of a size object can be changed by calling either FT_Set_Pixel_Sizes() or FT_Set_Char_Size().

尺寸对象的内容可以通过调用FT_Set_Pixel_Sizes()或FT_Set_Char_Size()来改变。

A new size object can be created with FT_New_Size(), and destroyed manually with FT_Done_Size(). Note that typical applications don't need to do this normally: they tend to use the default size object provided with each FT_Face.

一个新的尺寸对象可以通过FT_New_Size()创建，通过FT_Done_Size()销毁，一般客户程序无需做这一步，它们通常可以使用每个FT_Face缺省提供的尺寸对象。

The public fields of FT_Size objects are defined in a very small structure named FT_SizeRec. However, it is important to understand that some font drivers define their own derivatives of FT_Size to store important internal data that is re-computed each time the character size changes. Most of the time, these are size-specific font hints./p>

FT_Size 公共属性定义在FT_SizeRec中，但是需要注意的是有些字体驱动定义它们自己的FT_Size的子类，以存储重要的内部数据，在每次字符大小改变时计算。大多数情况下，它们是尺寸特定的字体hint。

For example, the TrueType driver stores the scaled CVT table that results from the execution of the "cvt" program in a TT_Size structure, while the Type 1 driver stores scaled global metrics (like blue zones) in a T1_Size object. Don't worry if you don't understand the current paragraph; most of this stuff is highly font format specific and doesn't need to be explained to client developers :-)

例如，TrueType驱动存储CVT表，通过cvt程序执行将结果放入TT_Size结构体中，而 Type1驱动将scaled global metrics放在T1_Size对象中。

5. The FT_GlyphSlot class

5、FT_GlyphSlot类

The purpose of a glyph slot is to provide a place where glyph images can be loaded one by one easily, independently of the glyph image format (bitmap, vector outline, or anything else).

字形槽的目的是提供一个地方，可以很容易地一个个地装入字形映象，而不管它的格式（位图、向量轮廓或其他）。

Ideally, once a glyph slot is created, any glyph image can be loaded into it without additional memory allocation. In practice, this is only possible with certain formats like TrueType which explicitly provide data to compute a slot's maximum size.

理想的，一旦一个字形槽创建了，任何字形映象可以装入，无需其他的内存分配。在实际中，只对于特定格式才如此，像TrueType，它显式地提供数据来计算一个槽的最大尺寸。

Another reason for glyph slots is that they are also used to hold format-specific hints for a given glyphs as well as all other data necessary to correctly load the glyph.

另一个字形槽地原因是他用来为指定字形保存格式特定的hint，以及其他为正确装入字形的必要数据。

The base FT_GlyphSlotRec structure only presents glyph metrics and images to client applications, while actual implementation may contain more sophisticated data.

基本的FT_GlyphSlotRec结构体只向客户程序展现了字形metics和映象，而真正的实现回包含更多的数据。

As an example, the TrueType-specific TT_GlyphSlotRec structure contains additional fields to hold glyph-specific bytecode, transient outlines used during the hinting process, and a few other things. The Type 1-specific T1_GlyphSlotRec structure holds glyph hints during glyph loading, as well as additional logic used to properly hint the glyphs when a native Type 1 hinter is used.

例如，TrueType特定的TT_GlyphSlotRec结构包含附加的属性，存放字形特定的字节码、在hint过程中暂时的轮廓和其他一些东西。

Finally, each face object has a single glyph slot that is directly accessible as face->glyph.

最后，每个外观对象有一个单一字形槽，可以用face->glyph直接访问。

6. The FT_CharMap class

6、FT_CharMap类

The FT_CharMap type is used as a handle to character map objects, or charmaps. A charmap is simply some sort of table or dictionary which is used to translate character codes in a given encoding into glyph indices for the font.

FT_CharMap类型用来作为一个字符地图对象的句柄，一个字符图是一种表或字典，用来将字符码从某种编码转换成字体的字形索引。

A single face may contain several charmaps. Each one of them corresponds to a given character repertoire, like Unicode, Apple Roman, Windows codepages, and other encodings.

单个外观可能包含若干字符图，每个对应一个指定的字符指令系统，例如Unicode、Apple Roman、Windows codepages等等。

Each FT_CharMap object contains a "platform" and an "encoding" field used to identify precisely the character repertoire corresponding to it.

每个FT_CharMap对象包含一个platform和encoding属性，用来标识它对应的字符指令系统。

Each font format provides its own derivative of FT_CharMapRec and thus needs to implement these objects.

每个字体格式都提供它们自己的FT_CharMapRec的继承类型并实现它们。

7. Objects relationships

7、对象关系

The following diagram summarizes what we have just said regarding the public objects managed by the library, as well as explicitely describes their relationships

Note that this picture will be updated at the end of the next chapter, related to internal objects.

III. Internal Objects and Classes

三、内部对象和类

Let us have a look now at the internal objects that FreeType 2 uses, i.e., those not directly available to client applications, and see how they fit into the picture.

1. Memory management

1、内存管理

All memory management operations are performed through three specific routines of the base layer, namely: FT_Alloc(), FT_Realloc(), and FT_Free(). Each one of these functions expects a FT_Memory handle as its first parameter.

所有内存管理操作通过基础层中3个特定例程完成，叫做FT_Alloc()、FT_Realloc()、 FT_Free()。每个函数需要一个 FT_Memory句柄作为它的第一个参数。

The latter is a pointer to a simple object used to describe the current memory pool/manager. It contains a simple table of alloc/realloc/free functions. A memory manager is created at library initialization time by FT_Init_FreeType(), calling the function FT_New_Memory() provided by the ftsystem component.

它是一个用来描述当前内存池/管理器对象的指针。在库初始化时，在FT_Init_FreeType中调用函数FT_New_Memory创建一个内存管理器，这个函数位于ftsystem部件当中。

By default, this manager uses the ANSI malloc(), realloc(), and free() functions. However, as ftsystem is a replaceable part of the base layer, a specific build of the library could provide a different default memory manager.

缺省情况下，这个管理器使用ANSI malloc、realloc和free函数，不过ftsystem是基础层中一个可替换的部分，库的特定构建可以提供不同的内存管理器。

Even with a default build, client applications are still able to provide their own memory manager by not calling FT_Init_FreeType() but follow these simple steps:

Create a new FT_Memory object by hand. The definition of FT_MemoryRec is located in the public file <freetype/ftsystem.h>.
Call FT_New_Library() to create a new library instance using your custom memory manager. This new library doesn't yet contain any registered modules.
Register the set of default modules by calling the function FT_Add_Default_Modules() provided by the ftinit component, or manually register your drivers by repeatedly calling FT_Add_Module().

即使使用缺省的版本，客户程序仍然可以提供自己的内存管理器，通过如下的步骤，调用FT_Init_FreeType实现：

手工创建一个FT_Memory对象，FT_MemoryRec位于公共文件<freetype/ftsystem.h>中。
使用你自己的内存管理器，调用FT_New_Library()创建一个新的库实例。新的库没有包含任何已注册的模块。
通过调用函数FT_Add_Default_Modules()（在ftinit部件中）注册缺省的模块，或者通过反复调用FT_Add_Module()手工注册你的驱动。

2. Input streams

2、输入流

Font files are always read through FT_Stream objects. The definition of FT_StreamRec is located in the public file <freetype/ftsystem.h>, which allows client developers to provide their own implementation of streams if they wish so.

字体文件总是通过FT_Stream对象读取，FT_StreamRec的定义位于公共文件<freetype/ftsystem.h>中，可以允许客户开发者提供自己的流实现。

The function FT_New_Face() will always automatically create a new stream object from the C pathname given as its second argument. This is achieved by calling the function FT_New_Stream() provided by the ftsystem component. As the latter is replaceable, the implementation of streams may vary greatly between platforms.

FT_New_Face()函数会自动根据他第二个参数，一个 C路径名创建一个新的流对象。它通过调用由 ftsystem部件提供的FT_New_Stream()完成，后者时可替换的，在不同平台上，流的实现可能大不一样。

As an example, the default implementation of streams is located in the file src/base/ftsystem.c and uses the ANSI fopen(), fseek(), and fread() calls. However, the Unix build of FreeType 2 provides an alternative implementation that uses memory-mapped files, when available on the host platform, resulting in a significant access speed-up.

举例来说，流的缺省实现位于文件src/base/ftsystem.c并使用ANSI fopen/fseek和fread函数。不过在FT2的Unix版本中，提供了另一个使用内存映射文件的实现，对于主机系统来说，可以大大提高速度。

FreeType distinguishes between memory-based and disk-based streams. In the first case, all data is directly accessed in memory (e.g. ROM-based, write-only static data and memory-mapped files), while in the second, portions of the font files are read in chunks called frames, and temporarily buffered similarly through typical seek/read operations.

FT区分基于内存和基于磁盘的流，对于前者，所有数据在内存直接访问（例如ROM、只写静态数据和内存映射文件），而后者，使用帧（frame）的概念从字体文件中读出一部分，使用典型的seek/read操作并暂时缓冲。

The FreeType stream sub-system also implements extremely efficient algorithms to very quickly load structures from font files while ensuring complete safety in the case of a "broken file".

The function FT_New_Memory_Face() can be used to directly create/open a FT_Face object from data that is readily available in memory (including ROM-based fonts).

FT_New_Memory_Face() 函数可以用来直接从内存中可读取的数据创建/打开一个FT_Face对象。

Finally, in the case where a custom input stream is needed, client applications can use the function FT_Open_Face(), which can accept custom input streams. This may be useful in the case of compressed or remote font files, or even embedded font files that need to be extracted from certain documents.

最后，如果需要客户输入流，客户程序能够使用FT_Open_Face()函数接受客户输入流。这在压缩或远程字体文件的情况下，以及从特定文档抽取嵌入式字体文件非常有用。

Note that each face owns a single stream, which is also destroyed by FT_Done_Face(). Generally speaking, it is certainly not a good idea to keep numerous FT_Face objects opened.

注意每个外观拥有一个流，并且通过FT_Done_Face被销毁。总的来说，保持多个FT_Face在打开状态不是一个很好的主意。

3. Modules

3、模块

A FreeType 2 module is itself a piece of code. However, the library creates a single FT_Module object for each module that is registered when FT_Add_Module() is called.

FT2 模块本身是一段代码，库调用FT_Add_Moudle（）函数注册模块，并为每个模块创建了一个FT_Module对象。

The definition of FT_ModuleRec is not publicly available to client applications. However, each module type is described by a simple public structure named FT_Module_Class, defined in <freetype/ftmodule.h>, and is described later in this document.

FT_ModuleRec的定义对客户程序不是公开的，但是每个模块类型通过一个简单的公共结构FT_Module_Class描述，它定义在< freetype/ftmodule.h>中，后面将详述。

You need a pointer to an FT_Module_Class structure when calling FT_Add_Module(), whose declaration is:

   FT_Error  FT_Add_Module( FT_Library              library,
                            const FT_Module_Class*  clazz );

当调用FT_Add_Module是，需要指定一个FT_Module_Class结构的指针，它的声明如下：

   FT_Error  FT_Add_Module( FT_Library              library,
                            const FT_Module_Class*  clazz );

Calling this function will do the following:

It will check whether the library already holds a module object corresponding to the same module name as the one found in FT_Module_Class.

If this is the case, it will compare the module version number to see whether it is possible to upgrade the module to a new version. If the module class's version number is smaller than the already installed one, the function returns immediately. Similarly, it checks that the version of FreeType 2 that is running is correct compared to the one required by the module.

It creates a new FT_Module object, using data and flags of the module class to determine its byte size and how to properly initialize it.

If a module initializer is present in the module class, it will be called to complete the module object's initialization.

The new module is added to the library's list of "registered" modules. In case of an upgrade, the previous module object is simply destroyed.

调用这个函数将作如下操作：

检查库中是否已经有对应FT_Module_Class指名的模块对象；

如果是，比较模块的版本号看是否可以升级，如果模块类的版本号小于已装入的模块，函数立即返回。当然，还要检查正在运行的FT版本是否满足待装模块所需FT的版本。

创建一个新的FT_Module对象，使用模块类的数据的标志决定它的大小和如何初始化；

如果在模块类中有一个模块初始器，它将被调用完成模块对象的初始化；

新的模块加入到库的"已注册"模块列表中，对升级的情况，先前的模块对象只要简单的销毁。

Note that this function doesn't return an FT_Module handle, given that module objects are completely internal to the library (and client applications shouldn't normally mess with them :-)

注意这个函数并不返回FT_Module句柄，它完全是库内部的事情，客户程序不应该摆弄他。

Finally, it is important to understand that FreeType 2 recognizes and manages several kinds of modules. These will be explained in more details later in this document, but we will list for now the following types:

Renderer modules are used to convert native glyph images to bitmaps/pixmaps. FreeType 2 comes with two renderer modules by default: one to generate monochrome bitmaps, the other to generate high-quality anti-aliased pixmaps.

Font driver modules are used to support one or more font formats. Typically, each font driver provides a specific implementation/derivative of FT_Face, FT_Size, FT_GlyphSlot, as well as FT_CharMap.

Helper modules are shared by several font drivers. For example, the sfnt module parses and manages tables found in SFNT-based font formats; it is then used by both the TrueType and OpenType font drivers.

Finally, the auto-hinter module has a specific place in the library's design, as its role is to process vectorial glyph outlines, independently of their native font format, to produce optimal results at small pixel sizes.

最后，要知道FT2识别和管理若干种模块，这在后面将有详述，这里列举如下：

渲染器模块用来将原始字形映象转换成位图或象素图。FT2自带两个渲染器，一个是生成单色位图，另一个生成高质量反走样的象素图。

字体驱动模块用来支持多种字体格式，典型的字体驱动需要提供特定的FT_Face、FT_Size、FT_GlyphSlot和FT_CharMap的实现；

助手模块被多个字体驱动共享，例如sfnt模块分析和管理基于SFNT字体格式的表，用于TrueType和OpenType字体驱动；

最后，auto-hinter模块在库设计中有特殊位置，它不管原始字体格式，处理向量字形轮廓，使之产生优质效果。

Note that every FT_Face object is owned by the corresponding font driver, depending on the original font file's format. This means that all face objects are destroyed when a module is removed/unregistered from a library instance (typically by calling the FT_Remove_Module() function).

注意每个FT_Face对象依据原始字体文件格式，都属于相应的字体驱动。这就是说，当一个模块从一个库实例移除/取消注册后，所有的外观对象都被销毁（通常是调用FT_Remove_Module()函数）。

Because of this, you should always take care that no FT_Face object is opened when you upgrade or remove a module from a library, as this could cause unexpected object deletion!

因此，你要注意当你升级或移除一个模块时，没有打开FT_Face对象，因为这会导致不预期的对象删除。

4. Libraries

4、库

We now come back to our well-known FT_Library object. From what have been said before, we already know that a library instance owns at least the following:

A memory manager object (FT_Memory), used for all allocation/releases within the instance.

A list of FT_Module objects, corresponding to the "installed" or "registered" modules of the instance. This list can be changed at any time through FT_Add_Module() and FT_Remove_Module().

Remember that face objects are owner by font drivers that are themselves modules owned by the library.

现在来说说FT_Library对象，如上所述，一个库实例至少包含如下：

一个内存管理对象（FT_Memory），用来在实例中分配、释放内存；

一个FT_Module对象列表，对应"已安装"或"已注册"的模块，它可以随时通过FT_Add_Module()和FT_Remove_Module()管理；

记住外观对象属于字体驱动，字体驱动模块属于库。

There is however another object owned by the library instance that hasn't been described yet: the raster pool.

还有一个对象属于库实例，但仍未提到：raster pool

The raster pool is simply a block of memory of fixed size that is used internally as a "scratch area" for various memory-hungry transient operations, avoiding memory allocation. For example, it is used by each renderer when converting a vectorial glyph outline into a bitmap (actually, that's where its name comes from :-).

光栅池是一个固定大小的一块内存，为一些内存需要大的操作作为内部的"草稿区域"，避免内存分配。例如，它用在每个渲染器转换一个向量字形轮廓到一个位图时（这其实就是它为何叫光栅池的原因）。

The size of the raster pool is fixed at initialisation time (it defaults to 16kByte) and cannot be changed at run-time (though we could fix this if there is a real need for that).

光栅池的大小在初始化的时候定下来的（缺省为16k字节），运行期不能修改。

When a transient operation needs more memory than the pool's size, it can decide to either allocate a heap block as an exceptional condition, or sub-divide recursively the task to perform in order to never exceed the pool's threshold.

当一个瞬时操作需要的内存超出这个池的大小，可以另外分配一块作为例外条件，或者是递归细分任务，以确保不会超出池的极限。

This extremely memory-conservative behaviour is certainly one of the keys to FreeType's performance in certain areas (most importantly in glyph rendering/scanline-conversion).

这种极度的内存保守行为是为了FT的性能考虑，特别在某些地方，如字形渲染、扫描线转换等。

5. Summary

5、总结

Finally, the following picture illustrates what has been said in this section, as well as the previous, by presenting the complete object graph of FreeType 2's base design:

最后，下图展示的上面所述内容，他表示FT基本设计的对象图

IV. Module Classes

四、模块类

We will now try to explain more precisely the types of modules that FreeType 2 is capable of managing. Note that each one of them is decribed with more details in the following chapters of this document.

在FT中有若干种模块

Renderer modules are used to manage scalable glyph images. This means transforming them, computing their bounding box, and converting them to either monochrome or anti-aliased bitmaps.

Note that FreeType 2 is capable of dealing with any kind of glyph images, as long as a renderer module is provided for it. The library comes by default with two renderers:

raster	Supports the conversion of vectorial outlines (described by a FT_Outline object) to monochrome bitmaps.
smooth	Supports the conversion of the same outlines to high-quality anti-aliased pixmaps (using 256 levels of gray). Note that this renderer also supports direct span generation.

渲染模块，用来管理可缩放的字形映象。这意味这转换它们、计算边框、并将它们转换成单色和反走样位图。

FT可以处理任何类型的字形映像，只要为它提供了一个渲染模块，FT缺省带了两个渲染器：

raster	支持从向量轮廓（由FT_Outline对象描述）到单色位图的转换
smooth	支持同样的轮廓转换到高质量反走样的象素图，使用256级灰度。这个渲染器也支持直接生成span。

Font driver modules are used to support one or more specific font format. By default, FreeType 2 comes with the following font drivers:

truetype	supports TrueType font files
type1	supports Postscript Type 1 fonts, both in binary (.pfb) or ASCII (.pfa) formats, including Multiple Master fonts.
cid	supports Postscript CID-keyed fonts
cff	supports OpenType, CFF as well as CEF fonts (CEF is a derivative of CFF used by Adobe in its SVG viewer)
winfonts	supports Windows bitmap fonts (i.e. .fon and .fnt)

Note that font drivers can support bitmapped or scalable glyph images. A given font driver that supports Bézier outlines through FT_Outline can also provide its own hinter, or rely on FreeType's autohinter module.

字体驱动模块，用来支持一种或多种特定字体格式，缺省情况下，FT由下列字体驱动

truetype	支持TrueType字体文件
type1	支持PostScript Type1字体，可以是二进制（.pfb）和ASCII(.pfa)格式，包括Multiple Master字体
cid	支持Postscript CID-keyed字体
cff	支持OpenType、CFF和CEF字体（CEF是CFF的一个变种，在Adobe的SVG Viewer中使用
winfonts	支持Windows位图字体，.fon和.fnt

字体驱动可以支持位图和可缩放的字形映象，一个特定支持Bezier轮廓的字体驱动通过FT_Outline可以提供他自己的hinter，或依赖FT的autohinter模块。

Helper modules are used to hold shared code that is often used by several font drivers, or even other modules. Here are the default helpers:

sfnt	used to support font formats based on the SFNT storage scheme: TrueType & OpenType fonts as well as other variants (like TrueType fonts that only contain embedded bitmaps)
psnames	used to provide various useful functions related to glyph names ordering and Postscript encodings/charsets. For example, this module is capable of automatically synthetizing a Unicode charmap from a Type 1 glyph name dictionary.
psaux	used to provide various useful functions related to Type 1 charstring decoding, as this "feature" is needed by the type1, cid, and cff drivers.

助手模块，用来处理一些共享代码，通常被多个字体驱动，甚至是其他模块使用，缺省的助手如下：

sfnt	用来支持基于SFNT存储纲要的字体格式，TrueType和OpenType字体和其他变种
psnames	用来提供有关字形名称排序和Postscript编码/字符集的函数。例如他可以从一个Type1字形名称字典中自动合成一个Unicode字符图。
psaux	用来提供有关Type1字符解码的函数，type1、cid和cff都需要这个特性

Finally, the autohinter module has a specific role in FreeType 2, as it can be used automatically during glyph loading to process individual glyph outlines when a font driver doesn't provide it's own hinting engine.

This module's purpose and design is also heavily described on the FreeType web site.

最后，autohinter模块在FT中是特殊角色，当一个字体驱动没有提供自己的hint引擎时，他可以在字形装载时处理各自的字形轮廓。

We will now study how modules are described, then managed by the library.

我们现在来学习模块是如何描述以及如何被FreeType2库管理的。

1. The FT_Module_Class structure

1 FT_Module_Class结构

As described later in this document, library initialization is performed by calling the FT_Init_FreeType() function. The latter is in charge of creating a new "empty" FT_Library object, then register each "default" module by repeatedly calling the FT_Add_Module() function.

Similarly, client applications can call FT_Add_Module() any time they wish in order to register a new module in the library. Let us take a look at this function's declaration:

   extern FT_Error  FT_Add_Module(
                      FT_Library              library,
                      const FT_Module_Class*  clazz );

As one can see, this function expects a handle to a library object, as well as a pointer to a FT_Module_Class structure. It returns an error code. In case of success, a new module object is created and added to the library. Note by the way that the module isn't returned directly by the call!

Here the definition of FT_Module_Class, with some explanation. The following code is taken from <freetype/ftmodule.h>:

   typedef struct  FT_Module_Class_
   {
     FT_ULong               module_flags;
     FT_Int                 module_size;
     const FT_String*       module_name;
     FT_Fixed               module_version;
     FT_Fixed               module_requires;
 
     const void*            module_interface;
 
     FT_Module_Constructor  module_init;
     FT_Module_Destructor   module_done;
     FT_Module_Requester    get_interface;
 
   } FT_Module_Class;

A description of its fields:

module_flags	A set of bit flags used to describe the module's category. Valid values are: ft_module_font_driver if the module is a font driver ft_module_renderer if the module is a renderer ft_module_hinter if the module is an auto-hinter ft_module_driver_scalable if the module is a font driver supporting scalable glyph formats ft_module_driver_no_outlines if the module is a font driver supporting scalable glyph formats that cannot be described by an FT_Outline object ft_module_driver_has_hinter if the module is a font driver that provides its own hinting scheme/algorithm
module_size	An integer that gives the size in bytes of a given module object. This should never be less than sizeof(FT_ModuleRec), but can be more if the module needs to sub-class the base FT_ModuleRec class.
module_name	The module's internal name, coded as a simple ASCII C string. There can't be two modules with the same name registered in a given FT_Library object. However, FT_Add_Module() uses the module_version field to detect module upgrades and perform them cleanly, even at run-time.
module_version	A 16.16 fixed float number giving the module's major and minor version numbers. It is used to determine whether a module needs to be upgraded when calling FT_Add_Module().
module_requires	A 16.16 fixed float number giving the version of FreeType 2 that is required to install this module. The default value is 0x20000 for FreeType version 2.0
module_requires	Most modules support one or more "interfaces", i.e. tables of function pointers. This field is used to point to the module's main interface, if there is one. It is a short-cut that prevents users of the module to call "get_interface()" each time they need to access one of the object's common entry points. Note that is is optional, and can be set to NULL. Other interfaces can also be accessed through the get_interface() field.
module_init	A pointer to a function used to initialize the fields of a fresh new FT_Module object. It is called after the module's base fields have been set by the library, and is generally used to initialize the fields of FT_ModuleRec subclasses. Most module classes set it to NULL to indicate that no extra initialization is necessary.
module_done	A pointer to a function used to finalize the fields of a given FT_Module object. Note that it is called before the library unsets the module's base fields, and is generally used to finalize the fields of FT_ModuleRec subclasses. Most module classes set it to NULL to indicate that no extra finalization is necessary
get_interface	A pointer to a function used to request the address of a given module interface. Set it to NULL if you don't need to support additional interfaces but the main one.

2. The FT_Module type

2 FT_Module类型

The FT_Module type is a handle (i.e. a pointer) to a given module object/instance, whose base structure is given by the internal FT_ModuleRec type. We will intentionally not describe this structure here, as there is no point to look so far into the library's design.

When FT_Add_Module is called, it first allocates a new module instance, using the module_size class field to determine its byte size. The function initializes the root FT_ModuleRec field, then calls the class-specific initializer module_init when this field is not set to NULL.

Note that the library defines several sub-classes of FT_ModuleRec, which are, as you could have guessed:

FT_Renderer for renderer modules

FT_Driver for font driver modules

FT_AutoHinter for the auto-hinter

Helper modules use the base FT_ModuleRec type. We will describe these classes in the next chapters.

取自"http://mxtctp.sourceforge.net/index.php/The_design_of_FreeType_2"

The design of FreeType 2

From Mxtctp

Views

Personal tools

导航

搜索

工具