Edit File - File Manager

Edit File: design-5.html

<!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>The design of FreeType 2</title>
</head>

<h1 align=center>
 The design of FreeType&nbsp;2
</h1>

<h3 align=center>
 Copyright&nbsp;1998-2000 David Turner (<a
 href="mailto:david@freetype.org">david@freetype.org</a>) 
 Copyright&nbsp;2000, 2007 The FreeType Development Team (<a
 href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>

<center>
 <table width="100%"
 border=0
 cellpadding=5>
 <tr bgcolor="#CCFFCC"
 valign=center>
 <td align=center
 width="30%">
 <a href="design-4.html">Previous</a>
 </td>
 <td align=center
 width="30%">
 <a href="index.html">Contents</a>
 </td>
 <td align=center
 width="30%">
 <a href="design-6.html">Next</a>
 </td>
 </tr>
 </table>
 </center>

<hr>

<table width="100%">
 <tr bgcolor="#ccccee"><td>
 <h1>
 IV. Module Classes
 </h1>
 </td></tr>
 </table>

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

<ul>
 <li>
 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&nbsp;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:

<table cellpadding=8>
 <tr valign=top>
 <td>
 <tt>raster</tt>
 </td>
 <td>
 Supports the conversion of vectorial outlines (described by a
 <tt>FT_Outline</tt> object) to monochrome bitmaps.
 </td>
 </tr>
 <tr valign=top>
 <td>
 <tt>smooth</tt>
 </td>
 <td>
 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.
 </td>
 </tr>
 </table>

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

<table cellpadding=8>
 <tr valign=top>
 <td>
 <tt>truetype</tt>
 </td>
 <td>
 supports TrueType font files
 </td>
 </tr>
 <tr valign=top>
 <td>
 <tt>type1</tt>
 </td>
 <td>
 supports Postscript Type&nbsp;1 fonts, both in binary
 (<tt>.pfb</tt>) or ASCII (<tt>.pfa</tt>) formats, including
 Multiple Master fonts.
 </td>
 </tr>
 <tr valign=top>
 <td>
 <tt>cid</tt>
 </td>
 <td>
 supports Postscript CID-keyed fonts
 </td>
 </tr>
 <tr valign=top>
 <td>
 <tt>cff</tt>
 </td>
 <td>
 supports OpenType, CFF as well as CEF fonts (CEF is a
 derivative of CFF used by Adobe in its SVG viewer)
 </td>
 </tr>
 <tr valign=top>
 <td>
 <tt>winfonts</tt>
 </td>
 <td>
 supports Windows bitmap fonts (i.e. <tt>.fon</tt> and
 <tt>.fnt</tt>)
 </td>
 </tr>
 </table>

Note that font drivers can support bitmapped or scalable glyph
 images. A given font driver that supports B&eacute;zier outlines
 through <tt>FT_Outline</tt> can also provide its own hinter, or rely
 on FreeType's <tt>autohinter</tt> module.
 </li>

<li>
 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:

<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&nbsp;1 glyph name dictionary.
 </td>
 </tr>
 <tr valign=top>
 <td>
 <tt>psaux</tt>
 </td>
 <td>
 used to provide various useful functions related to Type&nbsp;1
 charstring decoding, as this "feature" is needed by the
 <tt>type1</tt>, <tt>cid</tt>, and <tt>cff</tt> drivers.
 </td>
 </tr>
 </table>
 </li>

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

This module's purpose and design is also heavily described on the
 FreeType web site.
 </li>
 </ul>

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

<h3>
 1. The <tt>FT_Module_Class</tt> structure
 </h3>

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.

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:

<pre>
 extern FT_Error FT_Add_Module(
 FT_Library library,
 const FT_Module_Class* clazz );</pre>

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!

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

<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>

A description of its fields:

<table cellpadding=8>
 <tr valign=top>
 <td>
 <tt>module_flags</tt>
 </td>
 <td>
 A set of bit flags used to describe the module's category. Valid
 values are:

<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 cannot 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>
 An integer that gives the size in bytes of a given
 module object. This should never 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.
 </td>
 </tr>
 <tr valign=top>
 <td>
 <tt>module_name</tt>
 </td>
 <td>
 The module's internal name, coded as a simple ASCII
 C&nbsp;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.
 </td>
 </tr>
 <tr valign=top>
 <td>
 <tt>module_version</tt>
 </td>
 <td>
 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>.
 </td>
 </tr>
 <tr valign=top>
 <td>
 <tt>module_requires</tt>
 </td>
 <td>
 A 16.16 fixed float number giving the version of FreeType&nbsp;2
 that is required to install this module. The default value is
 0x20000 for FreeType version&nbsp; 2.0
 </td>
 </tr>
 <tr valign=top>
 <td>
 <tt>module_interface</tt>
 </td>
 <td>
 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 <tt>get_interface()</tt>
 field.
 </td>
 </tr>
 <tr valign=top>
 <td>
 <tt>module_init</tt>
 </td>
 <td>
 A pointer to a function used to initialize the fields of a fresh
 new <tt>FT_Module</tt> 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 <tt>FT_ModuleRec</tt>
 subclasses.

Most module classes set it to NULL to indicate that no extra
 initialization is necessary.
 </td>
 </tr>
 <tr valign=top>
 <td>
 <tt>module_done</tt>
 </td>
 <td>
 A pointer to a function used to finalize the fields of a given
 <tt>FT_Module</tt> object. Note that it is called before
 the library unsets the module's base fields, and is generally used
 to finalize the fields of <tt>FT_ModuleRec</tt> subclasses.

Most module classes set it to NULL to indicate that no extra
 finalization is necessary
 </td>
 </tr>
 <tr valign=top>
 <td>
 <tt>get_interface</tt>
 </td>
 <td>
 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.
 </td>
 </tr>
 </table>

<h3>
 2. The <tt>FT_Module</tt> type
 </h3>

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 not describe
 this structure here, as there is no point to look so far into the
 library's design.

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.

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

<ul>
 <li><tt>FT_Renderer</tt> for renderer modules
 <li><tt>FT_Driver</tt> for font driver modules
 <li><tt>FT_AutoHinter</tt> for the auto-hinter
 </ul>

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

<hr>

<center>
 <table width="100%"
 border=0
 cellpadding=5>
 <tr bgcolor="#CCFFCC" valign=center>
 <td align=center
 width="30%">
 <a href="design-4.html">Previous</a>
 </td>
 <td align=center
 width="30%">
 <a href="index.html">Contents</a>
 </td>
 <td align=center
 width="30%">
 <a href="design-6.html">Next</a>
 </td>
 </tr>
 </table>
 </center>

</td></tr>
</table>
</center>

</body>
</html>

Back to File Manager