kmx git

Commit d1896124dd21f6ab33049e395acc7a961e83b90b

2000-10-31T07:36:53
Revised/formatted/corrected.
diff --git a/docs/design/design-4.html b/docs/design/design-4.html
index 0a0c633..f71cf07 100644
--- 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>
-
-<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>
diff --git a/docs/design/design-5.html b/docs/design/design-5.html
index 3e366ab..76634d2 100644
--- 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>
-
-<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>
kc3-lang/freetype

Commit d1896124dd21f6ab33049e395acc7a961e83b90b
