+
+FreeType 2 Modules
+The purpose of this document is to present in great details the way +FreeType 2 uses and manages modules. Among other things, it answers +the following questions: + +
1. Library design:+ +The design of the library is pretty basic: +
This is illustrated by the following graphics: + + Note that, however, FT2 comes with a set of optional +components that can be ommited from certain builds, and whose +purpose vary between two situations: + +
This is illustrated by the following graphics: + +
+The library is capable of managing and using several kinds of +modules: + +
We will now study how modules are described, then managed by + the library. + +1. The FT_Module_Class structure:+ +As described later in this document, library initialisation 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's 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 !. + +Let's study the definition of FT_Module_Class, and explain it + a bit. 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;
+
+
+here's a description of its fields: + +
2. The FT_Module type:+ +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 not detail its + structure here). + +When FT_Add_Module is called, it first allocate a new + module instance, using the module_size class + field to determine its byte size. The function initializes + a the root FT_ModuleRec fields, then calls + the class-specific initializer module_init + when this field is not set to NULL. + + + + +
As said previously, renderers are used to convert scalable + glyph images to bitmaps or pixmaps. Each renderer module is defined + through a renderer class, whose definition is found in the + file <freetype/ftrender.h>. However, a few concepts + need to be explained before having a detailed look at this structure. + + +1. Glyph formats:+ +Each glyph image that is loaded by FreeType (either through + FT_Load_Glyph or FT_Load_Char), has a given + image format, described by the field + face->glyph->format. It is a 32-byte integer that + can take any value. However, the file <freetype/ftimage.h> + defines at least the following values: + +
Note that this is only a list of pre-defined formats supported by + FreeType. Nothing prevents an application to install a new font + driver that creates other kinds of glyph images. For example, one + could imagine a MetaFont font driver, that would be capable to + parse font definition files and create in-memory "glyph programs", + that could be returned in face->glyph->other. + +2. The FT_Outline type:+ +This structure, which is also defined, and heavily commented, in + the file <freetype/ftimage.h>, is used to hold + a scalable glyph image that is made of one or more contours, each + contour being described by line segments or bezier arcs (either + quadratic or cubic). The outline itself is stored in a compact + way that makes processing it easy. + +Points are placed in a 2D plane that uses the y-upwards convention, + and their coordinates are stored in 1/64th of pixels (also known + as the 26.6 fixed point format). Pixels correspond to single squares + whose borders are on integer coordinates (i.e. mutiples of 64). + In other words, pixel centers are located on half pixel coordinates. + +Outlines can be very easily transformed (translated, rotated, etc..) + before being converted to bitmap, which allows for sophisticated + use of text. FreeType 2 comes by default with two "outline renderer" + modules: + +
3. Bitmaps and scan-conversion:+ +Bitmaps and pixmaps are described through a FT_Bitmap + structure, which is defined and heavily commented in + <freetype/ftimage.h> + + +
+ typedef struct FT_Renderer_Class_
+ {
+ FT_Module_Class root;
+
+ FT_Glyph_Format glyph_format;
+
+ FTRenderer_render render_glyph;
+ FTRenderer_transform transform_glyph;
+ FTRenderer_getCBox get_glyph_cbox;
+ FTRenderer_setMode set_mode;
+
+ FT_Raster_Funcs* raster_class;
+
+ } FT_Renderer_Class;
+
+
+
By default, all components of FreeType 2 are compiled independently, + then grouped into a single static library file that can be installed + or used directly to compile client applications + +Such applications must normally call the FT_Init_FreeType + function before using the library. This function is in charge of + two things: + +
It is important to notice that the default implementation of + FT_Init_FreeType, which is located in the source + file "src/base/ftinit.c" always uses a static + list of modules that is generated at compile time from the + configuration file <freetype/config/ftmodule.h>. + + +There are cases where this may be inadequate. For example, one + might want to compile modules as independent DLLs in a specific + location (like "/usr/lib/freetype/module/"), and have + the library initialisation function load the modules dynamically + by parsing the directory's content + +This is possible, and we're going to explain how to do it. + + +a. Building the library as a DLL (i.e. "shared object" on Unix)+ +But first of all, let's explain how to build FreeType 2 as a single + DLL or shared object, i.e. one that includes the base layer, all + default modules and optional components into a single file. + +When building dynamic libraries, certain compilers require specific + directives to declare exported DLL entry points. For example, the + "__cdecl" directive is required by Win32 compilers, as it forces + the use of the "C" parameter passing convention (instead of "smarter" + schemes, which usually use registers and the stack to pass parameters). + +To make matter worse, some of these compilers require the directive + before the function's return type, while some others want it between + the return type and the function's identifier. + +To allow such compilations, the FT_EXPORT_DEF() macro is + used in all public header files in order to declare each high-level + API function of FreeType 2, as in the following example, taken from + <freetype/freetype.h>: + ++ FT_EXPORT_DEF(FT_Error) FT_Init_FreeType( void ); ++ + the definition of FT_EXPORT_DEF(x) defaults to "extern x", + except when a specific definition is given in the library's system-specific + configuration file <freetype/config/ftconfig.h>. This + allows project builders to specify the exact compilation directive + they need. + +Similarly, the FT_EXPORT_FUNC(x) macro is defined and used to + define exported functions within the FreeType 2 source code. + However, it is only used at compilation time. + + +Note that on Unix, there is no need for specific exportation directives. + However, the code must be compiled in a special way, named Position + Independent Code ("PIC"), which is normally selected through specific + compiler flags (like "-PIC" with gcc). + + +b. Building modules as DLLs+ +In order to build modules as dynamic libraries, we first need to compile + the base layer (and optional components) as a single DLL. This is very + similar to the case we just described, except that we also need to + export all functions that are part of the "low level base API", + as these will get called by the modules in various cases. + +Similarly to the high-level API, all functions of the low-level base + API are declared in the internal header files of FreeType 2 with the + BASE_DEF(x) macro. The latter is similar to + FT_EXPORT_DEF and defaults to "extern x" unless + you specify a specific definition in + <freetype/config/ftconfig.h>. ++ + + +
|