| <!doctype html public "-//w3c//dtd html 4.0 transitional//en" |
| "http://www.w3.org/TR/REC-html40/loose.dtd"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" |
| content="text/html; charset=iso-8859-1"> |
| <meta name="Author" |
| content="David Turner"> |
| <title>FreeType 2 - Modules</title> |
| </head> |
| |
| <body text="#000000" |
| bgcolor="#ffffff"> |
| |
| <h1 align=center> |
| The design of FreeType 2 |
| </h1> |
| |
| <center> |
| <table width="75%"> |
| <tr><td> |
| |
| <table width="100%"> |
| <tr bgcolor="#ccccee"><td> |
| <h1> |
| IV. Module Classes |
| </h1> |
| </td></tr> |
| </table> |
| |
| <p>We will now try to explain more precisely the <em>types</em> 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.</p> |
| |
| <ul> |
| <li> |
| <p><em>Renderer</em> modules are used to manage scalable glyph images. |
| This means <em>transforming</em> them, computing their <em>bounding |
| box</em>, and <em>converting</em> them to either <em>monochrome</em> |
| or <em>anti-aliased</em> bitmaps</em>.</p> |
| |
| <p>Note that FreeType 2 is capable of dealing with <em>any</em> |
| kind of glyph images, as long as a renderer module is provided for it. |
| The library comes by default with two renderers:</p> |
| |
| <p><table cellpadding=8> |
| <tr valign=top> |
| <td> |
| <tt>raster</tt> |
| </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> |
| <tt>smooth</tt> |
| </td> |
| <td> |
| <p>Supports the conversion of the same outlines to high-quality |
| <em>anti-aliased</em> pixmaps (using 256 levels of gray). Note |
| that this renderer also supports direct span generation.</p> |
| </td> |
| </tr> |
| </table></p> |
| |
| <li> |
| <p><em>Font driver</em> modules are used to support one or more |
| specific font format. By default, FreeType 2 comes with the |
| following font drivers:</p> |
| |
| <p><table cellpadding=8> |
| <tr valign=top> |
| <td> |
| <tt>truetype</tt> |
| </td> |
| <td> |
| <p>supports TrueType font files</p> |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>type1</tt> |
| </td> |
| <td> |
| <p>supports Postscript Type 1 fonts, both in binary |
| (<tt>.pfb</tt>) or ASCII (<tt>.pfa</tt>) formats, including |
| Multiple Master fonts.</p> |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>cid</tt> |
| </td> |
| <td> |
| <p>supports Postscript CID-keyed fonts</p> |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>cff</tt> |
| </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> |
| <tt>winfonts</tt> |
| </td> |
| <td> |
| <p>supports Windows bitmap fonts (i.e. <tt>.fon</tt> and |
| <tt>.fnt</tt>)</p> |
| </td> |
| </tr> |
| </table></p> |
| |
| <p>Note that font drivers can support bitmapped or scalable glyph |
| images. A given font driver that supports Bézier outlines |
| through <tt>FT_Outline</tt> can also provide its own hinter, or rely |
| on FreeType's <tt>autohinter</tt> module.</p> |
| </li> |
| |
| <li> |
| <p><em>Helper</em> modules are used to hold shared code that is often |
| used by several font drivers, or even other modules. Here are the |
| default helpers:</p> |
| |
| <p><table cellpadding=8> |
| <tr valign=top> |
| <td> |
| <tt>sfnt</tt> |
| </td> |
| <td> |
| used to support font formats based on the <tt>SFNT</tt> storage |
| scheme: TrueType & OpenType fonts as well as other variants (like |
| TrueType fonts that only contain embedded bitmaps) |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>psnames</tt> |
| </td> |
| <td> |
| 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. |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>psaux</tt> |
| </td> |
| <td> |
| used to provide various useful functions related to Type 1 |
| charstring decoding, as this "feature" is needed by the |
| <tt>type1</tt>, <tt>cid</tt>, and <tt>cff</tt> drivers. |
| </td> |
| </tr> |
| </table></p> |
| </li> |
| |
| <li> |
| <p>Finally, the <em>autohinter</em> 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> |
| |
| <p>This module's purpose and design is also heavily described on the |
| FreeType web site.</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 initialization 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 us |
| take a look at this function's declaration:</p> |
| |
| <font color="blue"><pre> |
| extern FT_Error FT_Add_Module( |
| FT_Library library, |
| const FT_Module_Class* clazz );</pre> |
| </font> |
| |
| <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>Here the definition of <tt>FT_Module_Class</tt>, with some |
| explanation. The following code is taken from |
| <tt><freetype/ftmodule.h></tt>:</p> |
| |
| <font color="blue"><pre> |
| 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;</pre> |
| </font> |
| |
| <p>A description of its fields:</p> |
| |
| <p><table cellpadding=8> |
| <tr valign=top> |
| <td> |
| <tt>module_flags</tt> |
| </td> |
| <td> |
| <p>A set of bit flags used to describe the module's category. Valid |
| values are:</p> |
| |
| <ul> |
| <li> |
| <tt>ft_module_font_driver</tt> if the module is a font driver |
| </li> |
| <li> |
| <tt>ft_module_renderer</tt> if the module is a renderer |
| </li> |
| <li> |
| <tt>ft_module_hinter</tt> if the module is an auto-hinter |
| </li> |
| <li> |
| <tt>ft_module_driver_scalable</tt> if the module is a font |
| driver supporting scalable glyph formats |
| </li> |
| <li> |
| <tt>ft_module_driver_no_outlines</tt> if the module is a font |
| driver supporting scalable glyph formats that <em>cannot</em> be |
| described by an <tt>FT_Outline</tt> object |
| </li> |
| <li> |
| <tt>ft_module_driver_has_hinter</tt> if the module is a font |
| driver that provides its own hinting scheme/algorithm |
| </li> |
| </ul> |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>module_size</tt> |
| </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 if the module needs |
| to sub-class the base <tt>FT_ModuleRec</tt> class.</p> |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>module_name</tt> |
| </td> |
| <td> |
| <p>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 <tt>module_version</tt> field to |
| detect module upgrades and perform them cleanly, even at |
| run-time.</p> |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>module_version</tt> |
| </td> |
| <td> |
| <p>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 <tt>FT_Add_Module()</tt>.</p> |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>module_requires</tt> |
| </td> |
| <td> |
| <p>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</p> |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>module_requires</tt> |
| </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, 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.</p> |
| |
| <p>Note that is is optional, and can be set to NULL. Other |
| interfaces can also be accessed through the <tt>get_interface()</tt> |
| field.</p> |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>module_init</tt> |
| </td> |
| <td> |
| <p>A pointer to a function used to initialize 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 initialize the fields of <tt>FT_ModuleRec</tt> |
| subclasses.</p> |
| |
| <p>Most module classes set it to NULL to indicate that no extra |
| initialization is necessary.</p> |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>module_done</tt> |
| </td> |
| <td> |
| <p>A pointer to a function used to finalize 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 |
| finalization is necessary</p> |
| </td> |
| </tr> |
| <tr valign=top> |
| <td> |
| <tt>get_interface</tt> |
| </td> |
| <td> |
| <p>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> |
| </table></p> |
| |
| |
| <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 intentionally <em>not</em> describe |
| this structure here, as there is no point to look so far into the |
| library's design.</p> |
| |
| <p>When <tt>FT_Add_Module</tt> is called, it first allocates a new |
| module instance, using the <tt>module_size</tt> class field to determine |
| its byte size. The function initializes the root <tt>FT_ModuleRec</tt> |
| field, then calls the class-specific initializer <tt>module_init</tt> |
| when this field is not set to NULL.</p> |
| |
| <p>Note that the library defines several sub-classes of |
| <tt>FT_ModuleRec</tt>, which are, as you could have guessed:</p> |
| |
| <ul> |
| <li><p><tt>FT_Renderer</tt> for renderer modules</p> |
| <li><p><tt>FT_Driver</tt> for font driver modules</p> |
| <li><p><tt>FT_AutoHinter</tt> for the auto-hinter</p> |
| </ul> |
| |
| <p>Helper modules use the base <tt>FT_ModuleRec</tt> type. We will |
| describe these classes in the next chapters.</p> |
| |
| </td></tr> |
| </table> |
| </center> |
| </body> |
| </html> |