| <html> |
| <head><title>FreeType 2 - Modules</title> |
| <basefont face="Georgia, Arial, Helvetica, Geneva"> |
| <style content="text/css"> |
| P { text-align=justify } |
| H1 { text-align=center } |
| H2 { text-align=center } |
| LI { text-align=justify } |
| </style> |
| </head> |
| <body text=#000000 bgcolor=#ffffff> |
| |
| <center><table width="500"><tr><td> |
| |
| <center><h1>FreeType 2 Modules</h1></center> |
| |
| <table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
| <h1>Introduction</h1> |
| </td></tr></table> |
| |
| <p> |
| 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:</p> |
| |
| <ul> |
| <li><p> |
| what is a module, and what kind of modules are recognized |
| by the library? |
| </p></li> |
| |
| <li><p> |
| how are modules registered and managed by the library? |
| </p></li> |
| |
| <li><p> |
| how to write a new module, especially new font drivers? |
| </p></li> |
| |
| <li><p> |
| how to select specific modules for a given build of the |
| library ? |
| </p></li> |
| |
| <li><p> |
| how to compile modules as stand-alone DLLs / shared objects? |
| </p></li> |
| |
| </ul> |
| |
| <table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
| <h1>Overview</h1> |
| </td></tr></table> |
| |
| |
| <h3>1. Library design:</h3> |
| |
| <p>The design of the library is pretty basic:</p> |
| <ul> |
| <li><p> |
| client applications typically call the FreeType 2 high-level |
| API, whose functions are implemented in a single component |
| called the <em>Base Layer</em>. |
| </p></li> |
| |
| <li><p> |
| depending on the context or the task, the base |
| layer then calls one or more modules to perform the |
| work. In most cases, the client application doesn't |
| need to know what module was called. |
| </p></li> |
| |
| <li><p> |
| 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, and they form what is called the "low-level |
| base API". |
| </p></li> |
| </ul> |
| |
| <p>This is illustrated by the following graphics:</p> |
| |
| <center><img src="basic-design.png" width="312" height="312"></center> |
| |
| <p>Note that, however, FT2 comes with a set of <em>optional</em> |
| components that can be ommited from certain builds, and whose |
| purpose vary between two situations:</p> |
| |
| <ul> |
| <li><p> |
| some are located on top of the high-level API and provide |
| convenience functions that make certain things easier |
| for typical applications. They typically do not call |
| modules directly, though they can use the low level |
| base API for certain tasks.</p> |
| |
| <p>As an example, see the the <tt>ftglyph</tt> component |
| that is used to manipulate glyph images more conveniently |
| than the default API.</p> |
| </p></li> |
| |
| <li><p> |
| some other components complement the base layer, by providing |
| additional routines. Most of them allow client applications |
| to access format-specific data.</p> |
| |
| <p>For example, the <tt>ftmm</tt> component provides high-level |
| functions to specify Multiple Master coordinates for MM Type 1 |
| fonts.</p> |
| </p></li> |
| </ul> |
| |
| <p>This is illustrated by the following graphics:</p> |
| |
| <center><img src="detailed-design.png" width="365" height="392"></center> |
| |
| <table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
| <h1>Module Classes</h1> |
| </td></tr></table> |
| |
| <p> |
| The library is capable of managing and using several kinds of |
| modules:</p> |
| |
| <ul> |
| <li><p> |
| <b>renderer</b> modules are used to convert scalable glyph images |
| to bitmaps. FreeType 2 comes by default with two of them:</p> |
| |
| <center><table cellpadding=5><tr valign=top><td> |
| <p><b><tt>raster1</tt></b></p> |
| </td><td> |
| <p>supports the conversion of vectorial outlines (described by a |
| <tt>FT_Outline</tt> object) to <em>monochrome</em> bitmaps. |
| </td></tr><tr valign=top><td></p> |
| |
| <p><b><tt>smooth</tt></b></p> |
| </td><td> |
| <p>supports the conversion of the same outlines to high-quality |
| <em>anti-aliased</em> pixmaps.</p> |
| </td></tr></table></center> |
| |
| |
| <p>The specification and interface of renderers is described in |
| details within this document.</p> |
| |
| <p>Note that most font formats use <tt>FT_Outline</tt> objects |
| to describe scalable glyph images. However, FT2 is flexible |
| and allows specific modules to register and support other |
| formats. As an example, it's (at least theorically :-) perfectly |
| possible to write a renderer module that is capable of directly |
| converting MetaFont glyph definitions to bitmaps or pixmaps ! |
| (of course, this assumes that you also write a MetaFont font |
| driver to load the definitions :-). |
| </p></li> |
| |
| <li><p> |
| <b>font driver</b> modules are used to support one or more specific |
| font format. By default, FT2 comes with the following modules:</p> |
| |
| <center><table cellpadding=5><tr valign=top><td> |
| <p><tt><b>truetype</b></tt></p> |
| </td><td> |
| <p>supports TrueType font files</p> |
| </td></tr><tr valign=top><td> |
| |
| <p><tt><b>type1</b></tt></p> |
| </td><td> |
| <p>supports Postscript Type 1 fonts, both in binary (.pfb) or ASCII |
| (.pfa) formats, including Multiple Master fonts.</p> |
| </td></tr><tr valign=top><td> |
| |
| <p><tt><b>cid</b></tt></p> |
| </td><td> |
| <p>supports Postscript CID-keyed fonts</p> |
| </td></tr><tr valign=top><td> |
| |
| <p><tt><b>cff</b></tt></p> |
| </td><td> |
| <p>supports OpenType, CFF as well as CEF fonts (CEF is a derivative |
| of CFF used by Adobe in its SVG viewer).</p> |
| </td></tr><tr valign=top><td> |
| |
| <p><tt><b>winfonts</b></tt></p> |
| </td><td> |
| <p>supports Windows bitmap fonts (i.e. ".FON" and ".FNT").</p> |
| </td></tr> |
| |
| </td></tr></table></center> |
| |
| <p>Note that font drivers can support bitmapped or scalable glyph |
| images. A given font driver that supports bezier outlines through |
| the <tt>FT_Outline</tt> can also provide its own hinter, or rely |
| on FreeType's <b>autohinter</b> module. |
| </p></li> |
| |
| <li><p> |
| <b>helper</b> modules are used to hold shared code that is |
| often used by several font drivers, or even other modules. |
| Here are a few examples of helper modules that come with |
| FreeType 2:</p> |
| |
| <table cellpadding=5><tr valign=top><td> |
| <b><tt>sfnt</tt></b> |
| </td><td> |
| used to support font formats based on the "<tt>SFNT</tt>" |
| storage scheme. This means TrueType & OpenType fonts as |
| well as other variants (like TrueType fonts that only |
| contain embedded bitmaps). |
| </td></tr><tr valign=top><td> |
| |
| <b><tt>psnames</tt></b> |
| </td><td> |
| used to provide various useful function 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. |
| </td></tr></table></center> |
| </p></li> |
| |
| |
| <li><p> |
| finally, the <b>autohinter</b> 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. |
| </p></li> |
| </ul> |
| |
| <p>We will now study how modules are described, then managed by |
| the library.</p> |
| |
| <h3>1. The <tt>FT_Module_Class</tt> structure:</h3> |
| |
| <p>As described later in this document, library initialisation is |
| performed by calling the <tt>FT_Init_FreeType</tt> function. The |
| latter is in charge of creating a new "empty" <tt>FT_Library</tt> |
| object, then register each "default" module by repeatedly calling |
| the <tt>FT_Add_Module</tt> function.</p> |
| |
| <p>Similarly, client applications can call <tt>FT_Add_Module</tt> |
| any time they wish in order to register a new module in the library. |
| Let's take a look at this function's declaration:</p> |
| |
| <pre><font color="blue"> |
| extern FT_Error FT_Add_Module( FT_Library library, |
| const FT_Module_Class* clazz ); |
| </font></pre> |
| |
| <p>As one can see, this function expects a handle to a library object, |
| as well as a pointer to a <tt>FT_Module_Class</tt> 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 !.</p> |
| |
| <p>Let's study the definition of <tt>FT_Module_Class</tt>, and explain it |
| a bit. The following code is taken from |
| <tt><freetype/ftmodule.h></tt>:</p> |
| |
| <pre><font color="blue"> |
| 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; |
| </font></pre> |
| |
| <p>here's a description of its fields:</p> |
| |
| <center><table cellpadding=5><tr valign=top><td> |
| <p><b>module_flags</b></p> |
| </td><td> |
| <p>this is a set of bit flags used to describe the module's |
| category. Valid values are:</p> |
| <ul> |
| <li><p> |
| <b>ft_module_font_driver</b> if the module is a font driver |
| </p></li> |
| |
| <li><p> |
| <b>ft_module_renderer</b> if the module is a renderer |
| </p></li> |
| |
| <li><p> |
| <b>ft_module_hinter</b> if the module is an auto-hinter |
| </p></li> |
| |
| <li><p> |
| <b>ft_module_driver_scalable</b> if the module is a font |
| driver supporting scalable glyph formats. |
| </p></li> |
| |
| <li><p> |
| <b>ft_module_driver_no_outlines</b> if the module is a |
| font driver supporting scalable glyph formats that <em>cannot</em> |
| be described by a <tt>FT_Outline</tt> object |
| </p></li> |
| |
| <li><p> |
| <b>ft_module_driver_has_hinter</b> if the module is a font |
| driver that provides its own hinting scheme/algorithm |
| </p></li> |
| </ul> |
| </td></tr><tr valign=top><td> |
| |
| <p><b>module_size</b></p> |
| </td><td> |
| <p>an integer that gives the size in <em>bytes</em> of a given module |
| object. This should <em>never</em> be less than |
| <tt>sizeof(FT_ModuleRec)</tt>, but can be more when the module |
| needs to sub-class the base <tt>FT_ModuleRec</tt> class.</p> |
| </td></tr><tr valign=top><td> |
| |
| <p><b>module_name</b></p> |
| </td><td> |
| <p>this is 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 <tt>FT_Library</tt> object. However, <tt>FT_Add_Module</tt> |
| uses the <b>module_version</b> field to detect module upgrades |
| and perform them cleanly, even at run-time.</p> |
| </td></tr><tr valign=top><td> |
| |
| <p><b>module_version</b></p> |
| </td><td> |
| <p>a 16.16 fixed float number giving the module's major and minor |
| version numbers. It is used to determine wether a module needs |
| to be upgraded when calling <tt>FT_Add_Module</tt>.</p> |
| </td></tr><tr valign=top><td> |
| |
| <p><b>module_requires</b></p> |
| </td><td> |
| <p>a 16.16 fixed float number giving the version of FreeType 2 that |
| is required to install this module. By default, should be 0x20000 |
| for FreeType 2.0</p> |
| </td></tr><tr valign=top><td> |
| |
| <p><b>module_requires</b></p> |
| </td><td> |
| <p>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, |
| where there is one. It's 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.</p> |
| |
| <p>Note that is is optional, and can be set to NULL. Other interfaces |
| can also be accessed through the <b>get_interface</b> field.</p> |
| </td></tr><tr valign=top><td> |
| |
| <p><b>module_init</b></p> |
| </td><td> |
| <p>this is a pointer to a function used to initialise the fields of |
| a fresh new <tt>FT_Module</tt> object. It is called <em>after</em> the module's |
| base fields have been set by the library, and is generally used to |
| initialise the fields of <tt>FT_ModuleRec</tt> subclasses.</p> |
| |
| <p>Most module classes set it to NULL to indicate that no extra |
| initialisation is necessary</p> |
| </td></tr><tr valign=top><td> |
| |
| <p><b>module_done</b></p> |
| </td><td> |
| <p>this is a pointer to a function used to finalise the fields of |
| a given <tt>FT_Module</tt> object. Note that it is called <em>before</em> the |
| library unsets the module's base fields, and is generally used to |
| finalize the fields of <tt>FT_ModuleRec</tt> subclasses.</p> |
| |
| <p>Most module classes set it to NULL to indicate that no extra |
| finalisation is necessary</p> |
| </td></tr><tr valign=top><td> |
| |
| <p><b>get_interface</b></p> |
| </td><td> |
| <p>this is 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.</p> |
| </td></tr><tr valign=top><td> |
| |
| </td></tr></table></center> |
| |
| |
| <h3>2. The <tt>FT_Module</tt> type:</h3> |
| |
| <p>the <tt>FT_Module</tt> type is a handle (i.e. a pointer) to a given |
| module object / instance, whose base structure is given by the |
| internal <tt>FT_ModuleRec</tt> type (we will not detail its |
| structure here).</p> |
| |
| <p>When <tt>FT_Add_Module</tt> is called, it first allocate a new |
| module instance, using the <tt><b>module_size</b></tt> class |
| field to determine its byte size. The function initializes |
| a the root <tt>FT_ModuleRec</tt> fields, then calls |
| the class-specific initializer <tt><b>module_init</b></tt> |
| when this field is not set to NULL.</p> |
| |
| |
| |
| |
| <table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
| <h1>Renderer Modules</h1> |
| </td></tr></table> |
| |
| <p>As said previously, <b>renderers</b> are used to convert scalable |
| glyph images to bitmaps or pixmaps. Each renderer module is defined |
| through a <b>renderer class</b>, whose definition is found in the |
| file <tt><freetype/ftrender.h></tt>. However, a few concepts |
| need to be explained before having a detailed look at this structure. |
| </p> |
| |
| <h3>1. Glyph formats:</h3> |
| |
| <p>Each glyph image that is loaded by FreeType (either through |
| <tt>FT_Load_Glyph</tt> or <tt>FT_Load_Char</tt>), has a given |
| <em>image format</em>, described by the field |
| <tt>face->glyph->format</tt>. It is a 32-byte integer that |
| can take any value. However, the file <tt><freetype/ftimage.h></tt> |
| defines at least the following values:</p> |
| |
| <center><table cellpadding=5> |
| <tr valign=top><td> |
| <tt><b>ft_glyph_format_bitmap</b></tt> |
| </td><td> |
| this value is used to indicate that the glyph image is a bitmap or pixmap. |
| Its content can then be accessed directly from |
| <tt>face->glyph->bitmap</tt> after the glyph was loaded. |
| </td></tr> |
| |
| <tr valign=top><td> |
| <tt><b>ft_glyph_format_outline</b></tt> |
| </td><td> |
| this value is used to indicate that the glyph image is a scalable vectorial |
| outline, that can be described by a <tt>FT_Outline</tt> object. Its content |
| can be accessed directly from |
| <tt>face->glyph->outline</tt> after the glyph was loaded. |
| this is the format that is commonly returned by TrueType, Type1 and |
| OpenType / CFF fonts. |
| </td></tr> |
| |
| <tr valign=top><td> |
| <tt><b>ft_glyph_format_plotter</b></tt> |
| </td><td> |
| this value is equivalent to <tt><b>ft_glyph_format_outline</b></tt> except |
| that the outline stored corresponds to path strokes, instead of filled |
| outlines. It can be returned from certain Type 1 fonts (notably the Hershey |
| collection of free fonts). |
| </td></tr> |
| |
| <tr valign=top><td> |
| <tt><b>ft_glyph_format_composite</b></tt> |
| </td><td> |
| this value is used to indicate that the glyph image is really a "compound" |
| of several other "sub-glyphs". This value is only returned when a glyph |
| is loaded with the <tt><b>FT_LOAD_NO_RECURSE</b></tt> flag. The list of |
| subglyphs that make up the composite can be accessed directly as |
| <tt>face->glyph->subglyphs</tt> after the glyph was loaded. |
| </td></tr> |
| |
| </table></center> |
| |
| <p>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 <tt>face->glyph->other</tt>.</p> |
| |
| <h3>2. The <tt>FT_Outline</tt> type:</h3> |
| |
| <p>This structure, which is also defined, and heavily commented, in |
| the file <tt><freetype/ftimage.h></tt>, 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.</p> |
| |
| <p>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.</p> |
| |
| <p>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:</p> |
| |
| <p><ul> |
| <li><b>raster1</b>, used to convert them to monochrome bitmaps</li> |
| <li><b>smooth</b>, used to convert them to high-quality anti-aliased |
| pixmaps</li> |
| </ul></p> |
| |
| <h3>3. Bitmaps and scan-conversion:</h3> |
| |
| <p>Bitmaps and pixmaps are described through a <tt>FT_Bitmap</tt> |
| structure, which is defined and heavily commented in |
| <tt><freetype/ftimage.h></tt> |
| |
| |
| <pre><font color="blue"> |
| 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; |
| </font></pre> |
| |
| <table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
| <h1>Font Driver Modules</h1> |
| </td></tr></table> |
| |
| <table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
| <h1>Library Initialisation & Dynamic Builds</h1> |
| </td></tr></table> |
| |
| <p>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</p> |
| |
| <p>Such applications must normally call the <tt>FT_Init_FreeType</tt> |
| function before using the library. This function is in charge of |
| two things:</p> |
| |
| <ul> |
| <li><p> |
| First, it creates a <tt>FT_Library</tt> object (by calling |
| the public function <tt>FT_New_Library</tt>). This new |
| object is "empty" and has no module registered in it. |
| </p></li> |
| |
| <li><p> |
| Then, it registers all "default modules" by repeatedly calling |
| <tt>FT_Add_Module</tt>. |
| </p></li> |
| </ul> |
| |
| <p>It is important to notice that the default implementation of |
| <tt>FT_Init_FreeType</tt>, which is located in the source |
| file <tt>"src/base/ftinit.c"</tt> always uses a <em>static</em> |
| list of modules that is generated at compile time from the |
| configuration file <tt><freetype/config/ftmodule.h></tt>. |
| </p> |
| |
| <p>There are cases where this may be inadequate. For example, one |
| might want to compile modules as independent DLLs in a specific |
| location (like <tt>"/usr/lib/freetype/module/"</tt>), and have |
| the library initialisation function load the modules dynamically |
| by parsing the directory's content</p> |
| |
| <p>This is possible, and we're going to explain how to do it.</p> |
| |
| |
| <h4>a. Building the library as a DLL (i.e. "shared object" on Unix)</h4> |
| |
| <p>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.</p> |
| |
| <p>When building dynamic libraries, certain compilers require specific |
| directives to <em>declare</em> exported DLL entry points. For example, the |
| "<tt>__cdecl</tt>" 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).</p> |
| |
| <p>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.</p> |
| |
| <p>To allow such compilations, the <tt>FT_EXPORT_DEF()</tt> 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 |
| <tt><freetype/freetype.h></tt>:</p> |
| |
| <pre><font color="blue"> |
| FT_EXPORT_DEF(FT_Error) FT_Init_FreeType( void ); |
| </font></pre> |
| |
| <p>the definition of <tt>FT_EXPORT_DEF(x)</tt> defaults to <tt>"extern x"</tt>, |
| except when a specific definition is given in the library's system-specific |
| configuration file <tt><freetype/config/ftconfig.h></tt>. This |
| allows project builders to specify the exact compilation directive |
| they need.</p> |
| |
| <p>Similarly, the <tt>FT_EXPORT_FUNC(x)</tt> macro is defined and used to |
| <em>define</em> exported functions within the FreeType 2 source code. |
| However, it is only used at compilation time.</p> |
| |
| |
| <p>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).</p> |
| |
| |
| <h4>b. Building modules as DLLs</h4> |
| |
| <p>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.</p> |
| |
| <p>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 |
| <tt>BASE_DEF(x)</tt> macro. The latter is similar to |
| <tt>FT_EXPORT_DEF</tt> and defaults to <tt>"extern x"</tt> unless |
| you specify a specific definition in |
| <tt><freetype/config/ftconfig.h></tt>.</p> |
| <p> |
| |
| <hr> |
| |
| <table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
| <h1>Conclusion</h1> |
| </td></tr></table> |
| |
| </td></tr></table></center> |
| </body> |
| </html> |