22

✏️ Editing: design-5.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
          "http://www.w3.org/TR/html4/loose.dtd">

<title>FreeType Design / IV</title>
</head>

<body>

<div id="top"
     class="bar">
  <h1><a href="http://freetype.org/index.html">FreeType</a>
    Design&nbsp;/&nbsp;IV</h1>
</div>

<div id="module-classes">
          <h2>IV. Module Classes</h2>

<p>We will now try to explain more precisely
            the <em>types</em> of modules that FreeType&nbsp;2 is
            capable of managing.</p>

<ul>
            <li>
              <p><em>Renderer</em> modules manage scalable glyph
                images.  This means <em>transforming</em> them,
                computing their <em>bounding box</em>,
                and <em>converting</em> them to
                either <em>monochrome</em> or <em>anti-aliased</em>
                bitmaps.</p>

<p>Note that FreeType&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>

<table>
                <tr valign=top>
                  <td>
                    <p><tt>raster</tt></p>
                  </td>
                  <td>
                    <p>Supports the conversion of vectorial outlines
                    (described by
                    an <a href="../reference/ft2-outline_processing.html#FT_Outline"><code>FT_Outline</code></a>
                    object) to <em>monochrome</em> bitmaps.</p>
                  </td>
                </tr>
                <tr valign=top>
                  <td>
                    <p><tt>smooth</tt></p>
                  </td>
                  <td>
                    <p>Supports the conversion of the same outlines to
                    <em>anti-aliased</em> pixmaps (using 256 levels of
                    gray).  Note that this renderer also supports
                    direct span generation, this is, it provides a
                    hook into the engine so that the application can
                    manipulate the rendering results itself, instead
                    of letting the rasterizer fill a pixmap.
                    See <a href="../tutorial/example4.cpp">this
                    tutorial demo file</a> for an example.</p>
                  </td>
                </tr>
              </table>
            </li>
            <li>
              <p><em>Font driver</em> modules support one or more
                specific font formats.  Here is a list with the most
                important ones.</p>

<table>
                <tr valign=top>
                  <td>
                    <p><tt>truetype</tt></p>
                  </td>
                  <td>
                    <p>TrueType fonts.</p>
                  </td>
                </tr>
                <tr valign=top>
                  <td>
                    <p><tt>type1</tt></p>
                  </td>
                  <td>
                    <p>Postscript Type&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>
                    <p><tt>cid</tt></p>
                  </td>
                  <td>
                    <p>Postscript CID-keyed fonts.</p>
                  </td>
                </tr>
                <tr valign=top>
                  <td>
                    <p><tt>cff</tt></p>
                  </td>
                  <td>
                    <p>OpenType CFF and CFF2, bare CFF, and CEF fonts
                      (CEF is a derivative of CFF used by Adobe in its
                      SVG viewer).</p>
                  </td>
                </tr>
                <tr valign=top>
                  <td>
                    <p><tt>winfonts</tt></p>
                  </td>
                  <td>
                    <p>Windows bitmap fonts (i.e., <tt>.fon</tt> and
                      <tt>.fnt</tt>).</p>
                  </td>
                </tr>
              </table>

<p>Note that font drivers can support bitmapped or
                scalable glyph images.  A given font driver that
                supports B&eacute;zier outlines
                through <tt>FT_Outline</tt> can also provide its own
                hinter, or rely on FreeType's <tt>autofit</tt>
                module for auto-hinting.</p>
            </li>
            <li>
              <p><em>Helper</em> modules are used to hold shared code
                that is often used by several font drivers, or even
                other modules.  The most important are as follows.</p>

<table>
                <tr valign=top>
                  <td>
                    <p><tt>sfnt</tt></p>
                  </td>
                  <td>
                    <p>Support for font formats based on
                      the <tt>SFNT</tt> storage scheme: TrueType,
                      OpenType, as well as other variants (like
                      TrueType fonts that only contain embedded
                      bitmaps).</p>
                  </td>
                </tr>
                <tr valign=top>
                  <td>
                    <p><tt>psnames</tt></p>
                  </td>
                  <td>
                    <p>Various useful functions related to glyph name
                      ordering and Postscript encodings and charsets.
                      For example, this module is capable of
                      automatically synthetizing a Unicode charmap
                      from a Type&nbsp;1 glyph name dictionary.</p>
                  </td>
                </tr>
                <tr valign=top>
                  <td>
                    <p><tt>psaux</tt></p>
                  </td>
                  <td>
                    <p>Auxiliary functions related to Postscript
                      charstring decoding, as needed by
                      the <tt>type1</tt>, <tt>cid</tt>,
                      and <tt>cff</tt> drivers.</p>
                  </td>
                </tr>
              </table>
            </li>
            <li>
              <p>Finally, the <em>auto-hinter</em> module
                (<tt>autofit</tt>) has a specific role in
                FreeType&nbsp;2, as it can be used automatically
                during glyph loading to process individual glyph
                outlines when a font driver doesn't provide its own
                hinting engine.</p>

<p>A paper published in the EuroTeX 2003 proceedings,
                titled <a href="http://www.tug.org/TUGboat/tb24-3/lemberg.pdf"><em>Real-Time
                Grid Fitting of Typographic Outlines</em></a>, gives
                further insight into the auto-hinting system's inner
                workings.</p>
            </li>
          </ul>

<p>We will now study how modules are described, then managed
            by the library.</p>

<h3 id="section-1">1. The <tt>FT_Module_Class</tt>
            Structure</h3>

<p>Here is the definition of <tt>FT_Module_Class</tt>, with
            some explanations.  The following code is taken from
            <tt>ftmodapi.h</tt>.</p>

<pre>
typedef struct  FT_Module_Class_
{
  FT_ULong               module_flags;
  FT_Int                 module_size;
  const FT_String*       module_name;
  FT_Fixed               module_version;
  FT_Fixed               module_requires;

const void*            module_interface;

FT_Module_Constructor  module_init;
  FT_Module_Destructor   module_done;
  FT_Module_Requester    get_interface;

} FT_Module_Class;</pre>

<p>A description of its fields.</p>

<table>
            <tr valign=top>
              <td>
                <p><tt>module_flags</tt></p>
              </td>
              <td>
                <p>A set of bit flags to describe the module's
                  category.  Valid values are listed below.</p>

<ul>
                  <li>
                    <tt>FT_MODULE_FONT_DRIVER</tt> if the module is a
                    font driver
                  </li>
                  <li>
                    <tt>FT_MODULE_RENDERER</tt> if the module is a
                    renderer
                  </li>
                  <li>
                    <tt>FT_MODULE_HINTER</tt> if the module is an
                    auto-hinter
                  </li>
                  <li>
                    <tt>FT_MODULE_DRIVER_SCALABLE</tt> if the module
                    is a font driver supporting scalable glyph formats
                  </li>
                  <li>
                    <tt>FT_MODULE_DRIVER_NO_OUTLINES</tt> if the
                    module is a font driver supporting scalable glyph
                    formats that <em>cannot</em> be described by
                    an <tt>FT_Outline</tt> object
                  </li>
                  <li>
                    <tt>FT_MODULE_DRIVER_HAS_HINTER</tt> if the module
                    is a font driver that provides its own hinting
                    scheme/algorithm
                  </li>
                  <li>
                    <tt>FT_MODULE_DRIVER_HINTS_LIGHTLY</tt> if the
                    module is a font driver that generates
                    &lsquo;light&rsquo; hints (this is, only along the
                    vertical axis).
                  </li>
                </ul>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>module_size</tt></p>
              </td>
              <td>
                <p>An integer that gives the size in <em>bytes</em> of
                  a given module object.  This should <em>never</em>
                  be less than <tt>sizeof(FT_ModuleRec)</tt>, but can
                  be more if the module needs to sub-class the
                  base <tt>FT_ModuleRec</tt> class.</p>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>module_name</tt></p>
              </td>
              <td>
                <p>The module's internal name, coded as a simple ASCII
                  C&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>
                <p><tt>module_version</tt></p>
              </td>
              <td>
                <p>A 16.16 fixed-point number giving the module's
                  major and minor version numbers.  It is used to
                  determine whether a module needs to be upgraded when
                  calling <tt>FT_Add_Module</tt>.</p>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>module_requires</tt></p>
              </td>
              <td>
                <p>A 16.16 fixed-point number giving the version of
                  FreeType&nbsp;2 that is required to install this
                  module.  The default value is 0x20000 for FreeType
                  version&nbsp;2.x</p>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>module_interface</tt></p>
              </td>
              <td>
                <p>Most modules support one or more
                  &lsquo;interfaces&rsquo;, i.e., tables of function
                  pointers.  This field points to the module's main
                  interface, if there is one.  It is a short-cut that
                  prevents users of the module to
                  call <tt>get_interface</tt> each time they need to
                  access one of the object's common entry points.</p>

<p>Note that it is optional, and can be set to NULL.
                  Other interfaces can also be accessed through
                  the <tt>get_interface</tt> field.</p>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>module_init</tt></p>
              </td>
              <td>
                <p>A pointer to a function to initialize the fields of
                  a fresh new <tt>FT_Module</tt> object.  It is
                  called <em>after</em> the module's base fields have
                  been set by the library, and is generally used to
                  initialize the fields of <tt>FT_ModuleRec</tt>
                  subclasses.</p>

<p>Most module classes set it to NULL to indicate that
                  no extra initialization is necessary.</p>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>module_done</tt></p>
              </td>
              <td>
                <p>A pointer to a function to finalize the fields of a
                  given <tt>FT_Module</tt> object.  Note that it is
                  called <em>before</em> the library unsets the
                  module's base fields, and is generally used to
                  finalize the fields of <tt>FT_ModuleRec</tt>
                  subclasses.</p>

<p>Most module classes set it to NULL to indicate that
                  no extra finalization is necessary</p>
              </td>
            </tr>
            <tr valign=top>
              <td>
                <p><tt>get_interface</tt></p>
              </td>
              <td>
                <p>A pointer to a function to request the address of a
                  given module interface.  Set it to NULL if you don't
                  need to support additional interfaces but the main
                  one.</p>
              </td>
            </tr>
          </table>

<h3 id="section-2">2. The <tt>FT_Module</tt> Type</h3>

<p>The <tt>FT_Module</tt> type is a handle (i.e., a pointer)
            to a given module object or instance, whose base structure
            is given by the internal <tt>FT_ModuleRec</tt> type.  We
            will intentionally <em>not</em> describe this structure
            here, as there is no point to look so far into the
            library's design.</p>

<p>When <tt>FT_Add_Module</tt> is called, it first allocates
            a new module instance, using the <tt>module_size</tt>
            class field to determine its byte size.  The function
            initializes the root <tt>FT_ModuleRec</tt> field, then
            calls the class-specific initializer <tt>module_init</tt>
            when this field is not set to NULL.</p>

<p>Note that the library defines several sub-classes of
            <tt>FT_ModuleRec</tt>.</p>

<ul>
            <li>
              <p><tt>FT_Renderer</tt> for renderer modules</p>
            </li>
            <li>
              <p><tt>FT_Driver</tt> for font driver modules</p>
            </li>
            <li>
              <p><tt>FT_AutoHinter</tt> for the auto-hinter</p>
            </li>
          </ul>

<p>Helper modules use the base <tt>FT_ModuleRec</tt>
            type.</p>
        </div>

<div class="updated">
          <p>Last update: 13-Feb-2018</p>
        </div>
      </div>
    </div>

<div id="TOC">
  <ul>
    <li class="funding">
      <form action="https://www.paypal.com/cgi-bin/webscr"
            method="post"
            target="_top">
        <input type="hidden"
               name="cmd"
               value="_s-xclick">
        <input type="hidden"
               name="hosted_button_id"
               value="SK827YKEALMT4">
        <input type="image"
               src="https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif"
               name="submit"
               alt="PayPal - The safer, easier way to pay online!">
        <img alt=""
             border="0"
             src="https://www.paypalobjects.com/de_DE/i/scr/pixel.gif"
             width="1"
             height="1">
      </form>
    </li>
    <li class="primary">
      <a href="http://freetype.org/index.html">Home</a>
    </li>
    <li class="primary">
      <a href="http://freetype.org/index.html#news">News</a>
    </li>
    <li class="primary">
      <a href="../index.html">Overview</a>
    </li>
    <li class="primary">
      <a href="../documentation.html">Documentation</a>
    </li>
    <li class="primary">
      <a href="http://freetype.org/developer.html">Development</a>
    </li>
    <li class="primary">
      <a href="http://freetype.org/contact.html"
         class="emphasis">Contact</a>
    </li>

<li class="secondary">
      <a href="index.html">FreeType Design</a>
    </li>
    <li class="tertiary">
      <a href="design-1.html">Introduction</a>
    </li>
    <li class="tertiary">
      <a href="design-2.html">Components and APIs</a>
    </li>
    <li class="tertiary">
      <a href="design-3.html">Public Objects and Classes</a>
    </li>
    <li class="tertiary">
      <a href="design-4.html">Internal Objects and Classes</a>
    </li>
    <li class="tertiary">
      <a href="design-5.html" class="current">Module Classes</a>
    </li>
    <li class="tertiary">
      <a href="design-6.html">Interfaces and Services</a>
    </li>
  </ul>
</div>

</div>

</body>
</html>

MR SKB