Chiebot-Mirror
/
freetype
mirror of https://github.com/freetype/freetype.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

Revised/formatted/corrected.

Browse Source
david-pic-changes
Werner Lemberg 25 years ago
parent 60784a2200
commit d1896124dd
2 changed files with 689 additions and 601 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 582
      docs/design/design-4.html
  2. 708
      docs/design/design-5.html

582
docs/design/design-4.html
Unescape View File

@ -1,289 +1,301 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head><title>The Design of FreeType 2 - Internal Objects</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>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="Author"
content="David Turner">
<title>The Design of FreeType 2 - Internal Objects</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<center><table width="500"><tr><td>
<center><h1>The Design of FreeType 2</h1></center>
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
<h1>III. Internal Objects and Classes</h1>
</td></tr></table>
<p>Let's have a look now at the <em>internal</em> objects that FreeType 2
uses, i.e. those not directly available to client applications, and
let's see how they fit in the picture.</p>
<h2>1. Memory management:</h2>
<p>All memory management operations are performed through three specific
routines of the base layer, namely: <tt>FT_Alloc</tt>, <tt>FT_Realloc</tt>,
and <tt>FT_Free</tt>. Each one of these functions expects a
<tt>FT_Memory</tt> handle as its first parameter.</p>
<p>The latter is a pointer to a simple object used to describe the current
memory pool/manager to use. It contains a simple table of
alloc/realloc/free functions. A memory manager is created at
library initialisation time by <tt>FT_Init_FreeType</tt> by calling
the function <tt>FT_New_Memory</tt> provided by the <b>ftsystem</b>
component.</p>
<p>By default, this manager uses the ANSI <tt>malloc</tt>, <tt>realloc</tt>
and <tt>free</tt> functions. However, as <b>ftsystem</b> is a replaceable
part of the base layer, a specific build of the library could provide
a different default memory manager.</p>
<p>Even with a default build, client applications are still able to provide
their own memory manager by not calling <tt>FT_Init_FreeType</tt> but
follow these simple steps:</p>
<ol>
<li><p>
create a new <tt>FT_Memory</tt> object by hand. The definition of
<tt>FT_MemoryRec</tt> is located in the public file
<tt>&lt;freetype/ftsystem.h&gt;</tt>.
</p></li>
<li><p>
call <tt>FT_New_Library</tt> to create a new library instance using
your custom memory manager. This new library is "virgin" and doesn't
contain any registered modules.
</p></li>
<li><p>
Register the set of default modules by calling the function
<tt>FT_Add_Default_Modules</tt> provided by the <b>ftinit</b>
component, or manually register your drivers by repeatedly
calling <tt>FT_Add_Module</tt>.
</p></li>
</ol>
<hr>
<h2>2. Input streams:</h2>
<p>Font files are always read through <tt>FT_Stream</tt> objects. The
definition of <tt>FT_StreamRec</tt> is located in the public file
<tt>&lt;freetype/ftsystem.h&gt;</tt>, which allows client developers
to provide their own implementation of streams if they wish so.</p>
<p>The function <tt>FT_New_Face</tt> will always automatically create a
new stream object from the C pathname given as its second argument.
This is achieved by calling the function <tt>FT_New_Stream</tt> provided
by the <b>ftsystem</b> component. As the latter is replaceable,
the implementation of streams may vary greatly between platforms.</p>
<p>As an example, the default implementation of streams is located in
the file "<tt>src/base/ftsystem.c</tt>" and uses the ANSI <tt>fopen</tt>,
<tt>fseek</tt>, <tt>fread</tt> calls. However, the Unix build of
FreeType 2 provides an alternative implementation that uses
memory-mapped files, when available on the host platform, resulting
in a significant access speed-up.</p>
<p>FreeType distinguishes between memory-based and disk-based
streams. In the first case, all data is directly accessed in memory
(e.g. ROM-based, write-only static data and memory-mapped files),
while in the second, portions of the font files are read in chunks
called "frames", and temorarily buffered adequately through typical
seek/read operations.</p>
<p>The FreeType stream sub-system also implements extremely efficient
algorithms to very quickly load structures from font files while
ensure complete safety in the case of "broken file".</p>
<p>The function <tt>FT_New_Memory_Face</tt> can be used
to directly create/open a <tt>FT_Face</tt> object from data that is
readily available in memory (including ROM-based fonts).</p>
<p>Finally, in the case where a custom input stream is needed, client
applications can use the function <tt>FT_Open_Face</tt>, which can
accept custom input streams.. This may be useful in the case of
compressed or remote font files, or even embedded font files that
need to be extracted from certain documents.</p>
<p>Note that each face owns a single stream, which is also destroyed
by <tt>FT_Done_Face</tt>. Generally speaking, it's certainly
<em>not a good idea</em> to keep numerous <tt>FT_Face</tt> objects
opened.</p>
<hr>
<h2>3. Modules:</h2>
<p>A FreeType 2 module is itself a piece of code. However, the library
creates a single <tt>FT_Module</tt> object for each module that is
registered when <tt>FT_Add_Module</tt> is called.</p>
<p>The definition of <tt>FT_ModuleRec</tt> is not publicly available
to client applications. However, each <em>module type</em> is described
by a simple and public structure named <tt>FT_Module_Class</tt>,
defined in <tt>&lt;freetype/ftmodule.h&gt;</tt>, and is detailed
heavily later in this document:</p>
<p>You need a pointer to a <tt>FT_Module_Class</tt> structure when
calling <tt>FT_Add_Module</tt>, whose declaration is:</p>
<pre><font color="blue">
FT_Error FT_Add_Module( FT_Library library,
const FT_Module_Class* clazz );
</font></pre>
<p>Calling this function will do the following:</p>
<ul>
<li><p>
it will check if the library already holds a module object corresponding
to the same module name as the one found in the <tt>FT_Module_Class</tt>.
</p></li>
<li><p>
it this is the case, it will compare the module version number to see
if it is possible to <em>upgrade</em> the module to a new version. If
the module class's version number is smaller than the already
installed one, the function returns immediately. Similarly, it checks
that the version of FreeType 2 that is running is correct compared
to the one required by the module.
</p></li>
<li><p>
it creates a new <tt>FT_Module</tt> object, using data and flags
of the module class to determine its byte size and how to properly
initialize it.
</p></li>
<li><p>
when a module initializer is present in the module class, it will
be called to complete the module object's initialisation.
</p></li>
<li><p>
the new module is added to the library's list of "registered"
modules. In case of an upgrade, the previous module object is
simply destroyed.
</p></li>
</ul>
<p>Note that this function doesn't return a <tt>FT_Module</tt> handle,
given that module objects are completely internal to the library
(and client applications shouldn't normally mess with them :-)</p>
<p>Finally, it's important to understand that FreeType 2 recognizes
and manages several kinds of modules. These will be explained in
more details later in this document, but we'll list for now the
following types:</p>
<ul>
<li><p>
<b>renderer</b> modules are used to convert native glyph images to
bitmaps/pixmaps. FT2 comes with two renderer modules
by default: one to generate monochrome bitmaps, the other to generate
high-quality anti-aliased pixmaps.
</p></li>
<li><p>
<b>font driver</b> modules are used to support one or more specific
font format. Typically, each font driver provides a specific
implementation/derivative of <tt>FT_Face</tt>, <tt>FT_Size</tt>,
<tt>FT_GlyphSlot</tt> as well as <tt>FT_CharMap</tt>.
</p></li>
<li><p>
<b>helper</b> modules are used to contain code that is shared
by several font drivers. For example, the <b>sfnt</b> module is
used to parse and manage tables found in SFNT-based font formats;
it is then used by both the TrueType and OpenType font drivers.
</p></li>
<li><p>
finally, the <b>auto-hinter</b> module has a specific place in
the library's design, as its role is to process vectorial glyph
outlines, independently of their native font format, to produce
optimal results at small pixel sizes..
</p></li>
</ul>
<p>Note that every <tt>FT_Face</tt> object is <em>owned</em> by the
corresponding font driver (that depends on the original font file's
format). This means that all face objects are destroyed when a module
is removed/unregistered from a library instance (typically by calling
<tt>FT_Remove_Module</tt>).</p>
<font color="red">
<p>Because of this, you should always take care that no <tt>FT_Face</tt>
object is opened when you upgrade or remove a module from a library,
as this could cause unexpected object deletion !!</p>
</font>
<hr>
<h2>4. Libraries:</h2>
<p>And we now come back to our well-known <tt>FT_Library</tt> objects.
From what have been said here, we already know that a library
instance owns at least the following:</p>
<ul>
<li><p>
a memory manager object (<tt>FT_Memory</tt>), used for all
allocation/releases within the instance.
</p></li>
<li><p>
a list of <tt>FT_Module</tt> objects, corresponding to the
"installed" or "registered" modules of the instance. This
list can be changed at any time through <tt>FT_Add_Module</tt>
and <tt>FT_Remove_Module</tt>.
</p></li>
<li><p>
finally, remember that face objects are owner by font drivers
that are themselves modules owned by the library.
</p></li>
</ul>
<p>There is however another object owned by the library instance that
hasn't been described until now, and it's the <em>raster pool</em>.</p>
<p>The <b>raster pool</b> is simply a block of memory of fixed size
that is used internally as a "scratch area" for various memory-hungry
transient operations. For example, it is used by each renderer when
converting a vectorial glyph outline into a bitmap (actually,
that's where its name comes from :-).</p>
<p>The advantage of using a raster pool comes from the fact that it
allows us to completely avoid memory allocation during certain
memory-intensive though common transient operations (like
glyph bitmap generation), speeding up the overall process.</p>
<p>The size of the raster pool is fixed at initialisation time
(it defaults to 16 Kb) and cannot be changed at run-time
(though we could fix this if there's a real need for that).</p>
<p>When a transient operation needs more memory than the pool's
size, it can decide to either allocate a heap block as an
exceptional condition, or sub-divide recursively the task to
perform in order to never exceed the pool's threshold..</p>
<p>This extremely memory-conservative behaviour is certainly one of
the keys to FreeType's performance in certain areas (most importantly
in glyph rendering / scanline-conversion ).</p>
<hr>
<h2>5. Summary</h2>
<p>Finally, the following picture illustrates what has been said
in this section, as well as the previous, by presenting the
complete object graph of FreeType 2's base design:</p>
<center><img src="to-be-done.png" width="100" height="100"></center>
</td></tr></table></center>
<body text="#000000"
bgcolor="#ffffff">
<h1 align=center>
The Design of FreeType&nbsp;2
</h1>
<center>
<table width="75%">
<tr><td>
<table width="100%">
<tr bgcolor="#ccccee"><td>
<h1>
III. Internal Objects and Classes
</h1>
</td></tr>
</table>
<p>Let us have a look now at the <em>internal</em> objects that
FreeType&nbsp;2 uses, i.e., those not directly available to client
applications, and see how they fit into the picture.</p>
<h2>
1. Memory management
</h2>
<p>All memory management operations are performed through three specific
routines of the base layer, namely: <tt>FT_Alloc()</tt>,
<tt>FT_Realloc()</tt>, and <tt>FT_Free()</tt>. Each one of these
functions expects a <tt>FT_Memory</tt> handle as its first
parameter.</p>
<p>The latter is a pointer to a simple object used to describe the
current memory pool/manager. It contains a simple table of
alloc/realloc/free functions. A memory manager is created at library
initialization time by <tt>FT_Init_FreeType()</tt>, calling the function
<tt>FT_New_Memory()</tt> provided by the <tt>ftsystem</tt>
component.</p>
<p>By default, this manager uses the ANSI <tt>malloc()</tt>,
<tt>realloc()</tt>, and <tt>free()</tt> functions. However, as
<tt>ftsystem</tt> is a replaceable part of the base layer, a specific
build of the library could provide a different default memory
manager.</p>
<p>Even with a default build, client applications are still able to
provide their own memory manager by not calling
<tt>FT_Init_FreeType()</tt> but follow these simple steps:</p>
<ol>
<li>
<p>Create a new <tt>FT_Memory</tt> object by hand. The definition
of <tt>FT_MemoryRec</tt> is located in the public file
<tt>&lt;freetype/ftsystem.h&gt;</tt>.</p>
</li>
<li>
<p>Call <tt>FT_New_Library()</tt> to create a new library instance
using your custom memory manager. This new library doesn't yet
contain any registered modules.</p>
</li>
<li>
<p>Register the set of default modules by calling the function
<tt>FT_Add_Default_Modules()</tt> provided by the <tt>ftinit</tt>
component, or manually register your drivers by repeatedly
calling <tt>FT_Add_Module()</tt>.</p>
</li>
</ol>
<hr>
<h2>
2. Input streams
</h2>
<p>Font files are always read through <tt>FT_Stream</tt> objects. The
definition of <tt>FT_StreamRec</tt> is located in the public file
<tt>&lt;freetype/ftsystem.h&gt;</tt>, which allows client developers to
provide their own implementation of streams if they wish so.</p>
<p>The function <tt>FT_New_Face()</tt> will always automatically create
a new stream object from the C&nbsp;pathname given as its second
argument. This is achieved by calling the function
<tt>FT_New_Stream()</tt> provided by the <tt>ftsystem</tt> component.
As the latter is replaceable, the implementation of streams may vary
greatly between platforms.</p>
<p>As an example, the default implementation of streams is located in
the file <tt>src/base/ftsystem.c</tt> and uses the ANSI
<tt>fopen()</tt>, <tt>fseek()</tt>, and <tt>fread()</tt> calls.
However, the Unix build of FreeType&nbsp;2 provides an alternative
implementation that uses memory-mapped files, when available on the host
platform, resulting in a significant access speed-up.</p>
<p>FreeType distinguishes between memory-based and disk-based streams.
In the first case, all data is directly accessed in memory (e.g.
ROM-based, write-only static data and memory-mapped files), while in the
second, portions of the font files are read in chunks called
<em>frames</em>, and temporarily buffered similarly through typical
seek/read operations.</p>
<p>The FreeType stream sub-system also implements extremely efficient
algorithms to very quickly load structures from font files while
ensuring complete safety in the case of a "broken file".</p>
<p>The function <tt>FT_New_Memory_Face()</tt> can be used to directly
create/open a <tt>FT_Face</tt> object from data that is readily
available in memory (including ROM-based fonts).</p>
<p>Finally, in the case where a custom input stream is needed, client
applications can use the function <tt>FT_Open_Face()</tt>, which can
accept custom input streams. This may be useful in the case of
compressed or remote font files, or even embedded font files that need
to be extracted from certain documents.</p>
<p>Note that each face owns a single stream, which is also destroyed by
<tt>FT_Done_Face()</tt>. Generally speaking, it is certainly
<em>not</em> a good idea to keep numerous <tt>FT_Face</tt> objects
opened.</p>
<hr>
<h2>
3. Modules
</h2>
<p>A FreeType&nbsp;2 module is itself a piece of code. However, the
library creates a single <tt>FT_Module</tt> object for each module that
is registered when <tt>FT_Add_Module()</tt> is called.</p>
<p>The definition of <tt>FT_ModuleRec</tt> is not publicly available to
client applications. However, each <em>module type</em> is described by
a simple public structure named <tt>FT_Module_Class</tt>, defined in
<tt>&lt;freetype/ftmodule.h&gt;</tt>, and is described later in this
document:</p>
<p>You need a pointer to an <tt>FT_Module_Class</tt> structure when
calling <tt>FT_Add_Module()</tt>, whose declaration is:</p>
<font color="blue"><pre>
FT_Error FT_Add_Module( FT_Library library,
const FT_Module_Class* clazz );</pre>
</font>
<p>Calling this function will do the following:</p>
<ul>
<li>
<p>It will check whether the library already holds a module object
corresponding to the same module name as the one found in
<tt>FT_Module_Class</tt>.</p>
</li>
<li>
<p>If this is the case, it will compare the module version number to
see whether it is possible to <em>upgrade</em> the module to a new
version. If the module class's version number is smaller than the
already installed one, the function returns immediately. Similarly,
it checks that the version of FreeType&nbsp;2 that is running is
correct compared to the one required by the module.</p>
</li>
<li>
<p>It creates a new <tt>FT_Module</tt> object, using data and flags
of the module class to determine its byte size and how to properly
initialize it.</p>
</li>
<li>
<p>If a module initializer is present in the module class, it will
be called to complete the module object's initialization.</p>
</li>
<li>
<p>The new module is added to the library's list of "registered"
modules. In case of an upgrade, the previous module object is
simply destroyed.</p>
</li>
</ul>
<p>Note that this function doesn't return an <tt>FT_Module</tt> handle,
given that module objects are completely internal to the library (and
client applications shouldn't normally mess with them&nbsp;:-)</p>
<p>Finally, it is important to understand that FreeType&nbsp;2
recognizes and manages several kinds of modules. These will be
explained in more details later in this document, but we will list for
now the following types:</p>
<ul>
<li>
<p><em>Renderer</em> modules are used to convert native glyph images
to bitmaps/pixmaps. FreeType&nbsp;2 comes with two renderer modules
by default: one to generate monochrome bitmaps, the other to
generate high-quality anti-aliased pixmaps.</p>
</li>
<li>
<p><em>Font driver</em> modules are used to support one or more font
formats. Typically, each font driver provides a specific
implementation/derivative of <tt>FT_Face</tt>, <tt>FT_Size</tt>,
<tt>FT_GlyphSlot</tt>, as well as <tt>FT_CharMap</tt>.</p>
</li>
<li>
<p><em>Helper</em> modules are shared by several font drivers. For
example, the <tt>sfnt</tt> module parses and manages tables found in
SFNT-based font formats; it is then used by both the TrueType and
OpenType font drivers.</p>
</li>
<li>
<p>Finally, the <em>auto-hinter</em> module has a specific place in
the library's design, as its role is to process vectorial glyph
outlines, independently of their native font format, to produce
optimal results at small pixel sizes.</p>
</li>
</ul>
<p>Note that every <tt>FT_Face</tt> object is <em>owned</em> by the
corresponding font driver, depending on the original font file's format.
This means that all face objects are destroyed when a module is
removed/unregistered from a library instance (typically by calling the
<tt>FT_Remove_Module()</tt> function).</p>
<p><em>Because of this, you should always take care that no
<tt>FT_Face</tt> object is opened when you upgrade or remove a module
from a library, as this could cause unexpected object deletion!</em></p>
<hr>
<h2>
4. Libraries
</h2>
<p>We now come back to our well-known <tt>FT_Library</tt> object. From
what have been said before, we already know that a library instance owns
at least the following:</p>
<ul>
<li>
<p>A memory manager object (<tt>FT_Memory</tt>), used for all
allocation/releases within the instance.</p>
</li>
<li>
<p>A list of <tt>FT_Module</tt> objects, corresponding to the
"installed" or "registered" modules of the instance. This list can
be changed at any time through <tt>FT_Add_Module()</tt> and
<tt>FT_Remove_Module()</tt>.</p>
</li>
<li>
<p>Remember that face objects are owner by font drivers that are
themselves modules owned by the library.</p>
</li>
</ul>
<p>There is however another object owned by the library instance that
hasn't been described yet: the <em>raster pool</em>.</p>
<p>The <em>raster pool</em> is simply a block of memory of fixed size
that is used internally as a "scratch area" for various memory-hungry
transient operations, avoiding memory allocation. For example, it is
used by each renderer when converting a vectorial glyph outline into a
bitmap (actually, that's where its name comes from&nbsp;:-).</p>
<p>The size of the raster pool is fixed at initialisation time (it
defaults to 16kByte) and cannot be changed at run-time (though we could
fix this if there is a real need for that).</p>
<p>When a transient operation needs more memory than the pool's size, it
can decide to either allocate a heap block as an exceptional condition,
or sub-divide recursively the task to perform in order to never exceed
the pool's threshold.</p>
<p>This extremely memory-conservative behaviour is certainly one of the
keys to FreeType's performance in certain areas (most importantly in
glyph rendering/scanline-conversion).</p>
<hr>
<h2>
5. Summary
</h2>
<p>Finally, the following picture illustrates what has been said in this
section, as well as the previous, by presenting the complete object
graph of FreeType&nbsp;2's base design:</p>
<center>
<img alt="to be done">
</center>
</td></tr>
</table>
</center>
</body>
</html>

708
docs/design/design-5.html
Unescape View File

@ -1,324 +1,400 @@
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<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>
<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>
<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>
<body text="#000000"
bgcolor="#ffffff">
<h1 align=center>
The design of FreeType&nbsp;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&nbsp;2 is capable of managing. Note that each one of them
is decribed with more details in the following chapters of this
document.</p>
</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>&lt;freetype/ftmodule.h&gt;</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>
<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&nbsp;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&nbsp;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&nbsp;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&eacute;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&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></p>
</li>
<li>
<p>Finally, the <em>autohinter</em> 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 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>
</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>
<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>&lt;freetype/ftmodule.h&gt;</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&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.</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&nbsp;2
that is required to install this module. The default value is
0x20000 for FreeType version&nbsp; 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>

Write Preview
Loading…
Cancel
Save