<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=utf-8">
<meta http-equiv="Content-Style-Type"
content="text/css">
<meta http-equiv="Content-Script-Type"
content="text/javascript">
<meta name="description"
content="FreeType Documentation">
<meta name="Author"
content="David Turner">
<link rel="icon"
href="../image/favicon_-90.ico">
<link rel="shortcut icon"
href="../image/favicon_-90.ico">
<link rel="stylesheet"
type="text/css"
href="../css/freetype2_-90.css">
<script type="text/javascript"
src="../../../js/jquery-1.11.0.min.js">
</script>
<script type="text/javascript"
src="../../../js/jquery.ba-resize.min.js">
</script>
<script type="text/javascript"
src="../../../js/freetype2.js">
</script>
<title>FreeType Design / IV</title>
</head>
<body>
<div id="top"
class="bar">
<h1><a href="http://freetype.org/index.html">FreeType</a>
Design / IV</h1>
</div>
<div id="wrapper">
<div class="colmask leftmenu">
<div class="colright">
<div class="col1wrap">
<div class="col1">
<!-- ************************************************** -->
<div id="module-classes">
<h2>IV. Module Classes</h2>
<p>We will now try to explain more precisely
the <em>types</em> of modules that FreeType 2 is
capable of managing.</p>
<ul>
<li>
<p><em>Renderer</em> modules 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.</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>
<table>
<tr valign=top>
<td>
<p><tt>raster</tt></p>
</td>
<td>
<p>Supports the conversion of vectorial outlines
(described by
an <a href="../reference/ft2-outline_processing.html#FT_Outline"><code>FT_Outline</code></a>
object) to <em>monochrome</em> bitmaps.</p>
</td>
</tr>
<tr valign=top>
<td>
<p><tt>smooth</tt></p>
</td>
<td>
<p>Supports the conversion of the same outlines to
<em>anti-aliased</em> pixmaps (using 256 levels of
gray). Note that this renderer also supports
direct span generation, this is, it provides a
hook into the engine so that the application can
manipulate the rendering results itself, instead
of letting the rasterizer fill a pixmap.
See <a href="../tutorial/example4.cpp">this
tutorial demo file</a> for an example.</p>
</td>
</tr>
</table>
</li>
<li>
<p><em>Font driver</em> modules support one or more
specific font formats. Here is a list with the most
important ones.</p>
<table>
<tr valign=top>
<td>
<p><tt>truetype</tt></p>
</td>
<td>
<p>TrueType fonts.</p>
</td>
</tr>
<tr valign=top>
<td>
<p><tt>type1</tt></p>
</td>
<td>
<p>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>
<p><tt>cid</tt></p>
</td>
<td>
<p>Postscript CID-keyed fonts.</p>
</td>
</tr>
<tr valign=top>
<td>
<p><tt>cff</tt></p>
</td>
<td>
<p>OpenType CFF and CFF2, bare CFF, and CEF fonts
(CEF is a derivative of CFF used by Adobe in its
SVG viewer).</p>
</td>
</tr>
<tr valign=top>
<td>
<p><tt>winfonts</tt></p>
</td>
<td>
<p>Windows bitmap fonts (i.e., <tt>.fon</tt> and
<tt>.fnt</tt>).</p>
</td>
</tr>
</table>
<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>autofit</tt>
module for auto-hinting.</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. The most important are as follows.</p>
<table>
<tr valign=top>
<td>
<p><tt>sfnt</tt></p>
</td>
<td>
<p>Support for font formats based on
the <tt>SFNT</tt> storage scheme: TrueType,
OpenType, as well as other variants (like
TrueType fonts that only contain embedded
bitmaps).</p>
</td>
</tr>
<tr valign=top>
<td>
<p><tt>psnames</tt></p>
</td>
<td>
<p>Various useful functions related to glyph name
ordering and Postscript encodings and charsets.
For example, this module is capable of
automatically synthetizing a Unicode charmap
from a Type 1 glyph name dictionary.</p>
</td>
</tr>
<tr valign=top>
<td>
<p><tt>psaux</tt></p>
</td>
<td>
<p>Auxiliary functions related to Postscript
charstring decoding, as needed by
the <tt>type1</tt>, <tt>cid</tt>,
and <tt>cff</tt> drivers.</p>
</td>
</tr>
</table>
</li>
<li>
<p>Finally, the <em>auto-hinter</em> module
(<tt>autofit</tt>) 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 its own
hinting engine.</p>
<p>A paper published in the EuroTeX 2003 proceedings,
titled <a href="http://www.tug.org/TUGboat/tb24-3/lemberg.pdf"><em>Real-Time
Grid Fitting of Typographic Outlines</em></a>, gives
further insight into the auto-hinting system's inner
workings.</p>
</li>
</ul>
<p>We will now study how modules are described, then managed
by the library.</p>
<h3 id="section-1">1. The <tt>FT_Module_Class</tt>
Structure</h3>
<p>Here is the definition of <tt>FT_Module_Class</tt>, with
some explanations. The following code is taken from
<tt>ftmodapi.h</tt>.</p>
<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>
<p>A description of its fields.</p>
<table>
<tr valign=top>
<td>
<p><tt>module_flags</tt></p>
</td>
<td>
<p>A set of bit flags to describe the module's
category. Valid values are listed below.</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>
<li>
<tt>FT_MODULE_DRIVER_HINTS_LIGHTLY</tt> if the
module is a font driver that generates
‘light’ hints (this is, only along the
vertical axis).
</li>
</ul>
</td>
</tr>
<tr valign=top>
<td>
<p><tt>module_size</tt></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 if the module needs to sub-class the
base <tt>FT_ModuleRec</tt> class.</p>
</td>
</tr>
<tr valign=top>
<td>
<p><tt>module_name</tt></p>
</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>
<p><tt>module_version</tt></p>
</td>
<td>
<p>A 16.16 fixed-point 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>
<p><tt>module_requires</tt></p>
</td>
<td>
<p>A 16.16 fixed-point number giving the version of
FreeType 2 that is required to install this
module. The default value is 0x20000 for FreeType
version 2.x</p>
</td>
</tr>
<tr valign=top>
<td>
<p><tt>module_interface</tt></p>
</td>
<td>
<p>Most modules support one or more
‘interfaces’, i.e., tables of function
pointers. This field points to the module's main
interface, if there is one. It is a short-cut that
prevents users of the module to
call <tt>get_interface</tt> each time they need to
access one of the object's common entry points.</p>
<p>Note that it 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>
<p><tt>module_init</tt></p>
</td>
<td>
<p>A pointer to a function 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>
<p><tt>module_done</tt></p>
</td>
<td>
<p>A pointer to a function 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>
<p><tt>get_interface</tt></p>
</td>
<td>
<p>A pointer to a function 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>
<h3 id="section-2">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 or 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>.</p>
<ul>
<li>
<p><tt>FT_Renderer</tt> for renderer modules</p>
</li>
<li>
<p><tt>FT_Driver</tt> for font driver modules</p>
</li>
<li>
<p><tt>FT_AutoHinter</tt> for the auto-hinter</p>
</li>
</ul>
<p>Helper modules use the base <tt>FT_ModuleRec</tt>
type.</p>
</div>
<!-- ************************************************** -->
<div class="updated">
<p>Last update: 13-Feb-2018</p>
</div>
</div>
</div>
<!-- ************************************************** -->
<div class="col2">
</div>
</div>
</div>
<!-- ************************************************** -->
<div id="TOC">
<ul>
<li class="funding">
<form action="https://www.paypal.com/cgi-bin/webscr"
method="post"
target="_top">
<input type="hidden"
name="cmd"
value="_s-xclick">
<input type="hidden"
name="hosted_button_id"
value="SK827YKEALMT4">
<input type="image"
src="https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif"
name="submit"
alt="PayPal - The safer, easier way to pay online!">
<img alt=""
border="0"
src="https://www.paypalobjects.com/de_DE/i/scr/pixel.gif"
width="1"
height="1">
</form>
</li>
<li class="primary">
<a href="http://freetype.org/index.html">Home</a>
</li>
<li class="primary">
<a href="http://freetype.org/index.html#news">News</a>
</li>
<li class="primary">
<a href="../index.html">Overview</a>
</li>
<li class="primary">
<a href="../documentation.html">Documentation</a>
</li>
<li class="primary">
<a href="http://freetype.org/developer.html">Development</a>
</li>
<li class="primary">
<a href="http://freetype.org/contact.html"
class="emphasis">Contact</a>
</li>
<li>
<!-- separate primary from secondary entries -->
</li>
<li class="secondary">
<a href="index.html">FreeType Design</a>
</li>
<li class="tertiary">
<a href="design-1.html">Introduction</a>
</li>
<li class="tertiary">
<a href="design-2.html">Components and APIs</a>
</li>
<li class="tertiary">
<a href="design-3.html">Public Objects and Classes</a>
</li>
<li class="tertiary">
<a href="design-4.html">Internal Objects and Classes</a>
</li>
<li class="tertiary">
<a href="design-5.html" class="current">Module Classes</a>
</li>
<li class="tertiary">
<a href="design-6.html">Interfaces and Services</a>
</li>
</ul>
</div>
</div> <!-- id="wrapper" -->
<div id="TOC-bottom">
</div>
</body>
</html>