added page 5 of design documentation
This commit is contained in:
David Turner
parent
6043b2404e
commit
31fa0bdcd8
324
docs/design/design-5.html
Normal file
324
docs/design/design-5.html
Normal file
@ -0,0 +1,324 @@
|
||||
<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 Design - Modules Classes</h1></center>
|
||||
|
||||
<table width="100%" cellpadding=5><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>
|
||||
<b>renderer</b> 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 or anti-aliased
|
||||
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>
|
||||
|
||||
<center><table cellpadding=5><tr valign=top><td>
|
||||
<p><b><tt>raster</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 (using 256 levels of gray). Note
|
||||
that this renderer also supports direct span generation.</p>
|
||||
</td></tr></table></center>
|
||||
|
||||
|
||||
<li><p>
|
||||
<b>font driver</b> modules are used to support one or more specific
|
||||
font format. By default, FT2 comes with the following font drivers:</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 the default helpers:</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 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>
|
||||
|
||||
<b><tt>psaux</tt></b>
|
||||
</td><td>
|
||||
used to provide various useful functions related to Type 1
|
||||
charstring decoding, as this "feature" is needed by the
|
||||
<b>type1</b>, <b>cid</b> and <b>cff</b> drivers.
|
||||
</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>
|
||||
|
||||
<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 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 intentionally <em>not</em>
|
||||
describe this structure here, as there's not point to look so far
|
||||
in the library's design.</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>
|
||||
|
||||
<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 now detail these classes in the next chapters</p>
|
||||
|
||||
</td></tr></table></center>
|
||||
</body>
|
||||
</html>
|
||||
Loading…
Reference in New Issue
Block a user