ref: d1896124dd21f6ab33049e395acc7a961e83b90b
parent: 60784a2200ad63293db4309ae5d8c72e826084dc
author: Werner Lemberg <[email protected]>
date: Tue Oct 31 02:36:53 EST 2000
Revised/formatted/corrected.
--- a/docs/design/design-4.html
+++ b/docs/design/design-4.html
@@ -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>
+<body text="#000000"
+ bgcolor="#ffffff">
-<center><h1>The Design of FreeType 2</h1></center>
+<h1 align=center>
+ The Design of FreeType 2
+</h1>
-<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
-<h1>III. Internal Objects and Classes</h1>
-</td></tr></table>
+<center>
+<table width="75%">
+<tr><td>
-<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>
+ <table width="100%">
+ <tr bgcolor="#ccccee"><td>
+ <h1>
+ III. Internal Objects and Classes
+ </h1>
+ </td></tr>
+ </table>
-<h2>1. Memory management:</h2>
+ <p>Let us have a look now at the <em>internal</em> objects that
+ FreeType 2 uses, i.e., those not directly available to client
+ applications, and see how they fit into the picture.</p>
-<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>
+ <h2>
+ 1. Memory management
+ </h2>
-<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>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>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>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>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>
+ <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>
-<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><freetype/ftsystem.h></tt>.
- </p></li>
+ <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>
- <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>
+ <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><freetype/ftsystem.h></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>
- <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>
-<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><freetype/ftsystem.h></tt>, which allows client developers to
+ provide their own implementation of streams if they wish so.</p>
-<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><freetype/ftsystem.h></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 <tt>ftsystem</tt> component.
+ As the latter is replaceable, the implementation of streams may vary
+ greatly between platforms.</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>, and <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>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
+ <em>frames</em>, and temporarily buffered similarly through typical
+ seek/read operations.</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
+ ensuring complete safety in the case of a "broken file".</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>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>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>
-<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>
-<hr>
-<h2>3. Modules:</h2>
+ <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>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><freetype/ftmodule.h></tt>, and is detailed
- heavily later in this document:</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><freetype/ftmodule.h></tt>, and is described 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>
+ <p>You need a pointer to an <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>
+ <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>
+ <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>
+ <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 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>
- <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>
+ <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 :-)</p>
- <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>
+ <p>Finally, it is 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 will list for
+ now the following types:</p>
- <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>
+ <ul>
+ <li>
+ <p><em>Renderer</em> modules are used to convert native glyph images
+ to bitmaps/pixmaps. FreeType 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>
- <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>
+ <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>
-</ul>
+ <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>
-<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>
+ <hr>
-<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>
+ <h2>
+ 4. Libraries
+ </h2>
-<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>
+ <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>
- <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>
+ <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>
- <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>
+ <p>There is however another object owned by the library instance that
+ hasn't been described yet: the <em>raster pool</em>.</p>
- <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>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 :-).</p>
-<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>
+ <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>
-<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>
+ <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>
-<hr>
-<h2>4. Libraries:</h2>
+ <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>
-<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>
+ <hr>
-<ul>
- <li><p>
- a memory manager object (<tt>FT_Memory</tt>), used for all
- allocation/releases within the instance.
- </p></li>
+ <h2>
+ 5. Summary
+ </h2>
- <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>
+ <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>
- <li><p>
- finally, remember that face objects are owner by font drivers
- that are themselves modules owned by the library.
- </p></li>
-</ul>
+ <center>
+ <img alt="to be done">
+ </center>
-<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>
+</td></tr>
+</table>
+</center>
</body>
</html>
--- a/docs/design/design-5.html
+++ b/docs/design/design-5.html
@@ -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>
+<body text="#000000"
+ bgcolor="#ffffff">
-<center><h1>FreeType 2 Design - Modules Classes</h1></center>
+<h1 align=center>
+ The design of FreeType 2
+</h1>
-<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
-<h1>IV. Module Classes</h1>
-</td></tr></table>
+<center>
+<table width="75%">
+<tr><td>
-<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>
+ <table width="100%">
+ <tr bgcolor="#ccccee"><td>
+ <h1>
+ IV. Module Classes
+ </h1>
</td></tr>
+ </table>
- </td></tr></table></center>
+ <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>
- <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>
+ <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>
- <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>
+ <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 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>
+ <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>
- <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><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>
- <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>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>
- <p>This module's purpose and design is also heavily described
- on the FreeType web site.</p>
- </li>
-</ul>
+ <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>We will now study how modules are described, then managed by
- the library.</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>
-<h3>1. The <tt>FT_Module_Class</tt> structure:</h3>
+ <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>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>This module's purpose and design is also heavily described on the
+ FreeType web site.</p>
+ </li>
+ </ul>
-<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>
+ <p>We will now study how modules are described, then managed by the
+ library.</p>
-<pre><font color="blue">
- extern FT_Error FT_Add_Module( FT_Library library,
- const FT_Module_Class* clazz );
-</font></pre>
+ <h3>
+ 1. The <tt>FT_Module_Class</tt> structure
+ </h3>
-<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>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>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>
+ <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>
-<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;
+ <font color="blue"><pre>
+ extern FT_Error FT_Add_Module(
+ FT_Library library,
+ const FT_Module_Class* clazz );</pre>
+ </font>
- const void* module_interface;
+ <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>
- FT_Module_Constructor module_init;
- FT_Module_Destructor module_done;
- FT_Module_Requester get_interface;
+ <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>
- } FT_Module_Class;
-</font></pre>
+ <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;
-<p>here's a description of its fields:</p>
+ const void* module_interface;
-<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>
+ FT_Module_Constructor module_init;
+ FT_Module_Destructor module_done;
+ FT_Module_Requester get_interface;
- <li><p>
- <b>ft_module_renderer</b> if the module is a renderer
- </p></li>
+ } FT_Module_Class;</pre>
+ </font>
- <li><p>
- <b>ft_module_hinter</b> if the module is an auto-hinter
- </p></li>
+ <p>A description of its fields:</p>
- <li><p>
- <b>ft_module_driver_scalable</b> if the module is a font
- driver supporting scalable glyph formats.
- </p></li>
+ <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>
- <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>
+ <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>
- <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>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><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>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><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>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>
-<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>
+ <h3>
+ 2. The <tt>FT_Module</tt> type
+ </h3>
-<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>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>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>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><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>Note that the library defines several sub-classes of
+ <tt>FT_ModuleRec</tt>, which are, as you could have guessed:</p>
-<p>Most module classes set it to NULL to indicate that no extra
-initialisation is necessary</p>
-</td></tr><tr valign=top><td>
+ <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><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>Helper modules use the base <tt>FT_ModuleRec</tt> type. We will
+ describe these classes in the next chapters.</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>
+</td></tr>
+</table>
+</center>
</body>
</html>