22

✏️ Editing: design-4.html

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

<title>FreeType Design / III</title>
</head>

<body>

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

<div id="internal-objects">
          <h2>III. Internal Objects and Classes</h2>

<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>

<h3 id="section-1">1. Memory Management</h3>

<p>Most memory management operations are performed through
            three specific routines of the base
            layer: <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.  Note,
            however, that there exist more, similar variants for
            specific purposes which we skip here for simplicity.</p>

<p><tt>FT_Memory</tt> is a pointer to a simple object that
            describes the current memory pool or manager.  It contains
            a small table of alloc, realloc, and free functions.  A
            memory manager is created at library initialization time
            by <tt>FT_Init_FreeType</tt>, calling the (internal)
            function <tt>FT_New_Memory</tt> provided by
            the <tt>ftsystem</tt> component.</p>

<p>By default, this manager uses the ANSI functions <tt>malloc</tt>,
            <tt>realloc</tt>, and <tt>free</tt>.  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 <a href="../reference/ft2-system_interface.html#FT_MemoryRec"><code>FT_MemoryRec</code></a>
                is located in the public header
                file <tt>ftsystem.h</tt>.</p>
            </li>
            <li>
              <p>Call <a href="../reference/ft2-module_management.html#FT_New_Library"><code>FT_New_Library</code></a>
                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 <a href="../reference/ft2-module_management.html#FT_Add_Default_Modules"><code>FT_Add_Default_Modules</code></a>
                provided by the <tt>ftinit</tt> component, or manually
                register your drivers by repeatedly
                calling <a href="../reference/ft2-module_management.html#FT_Add_Module"><code>FT_Add_Module</code></a>.</p>
            </li>
          </ol>

<h3 id="section-2">2. Input Streams</h3>

<p>Font files are always read through <tt>FT_Stream</tt>
            objects.  The definition
            of <a href="../reference/ft2-system_interface.html#FT_StreamRec"><code>FT_StreamRec</code></a>
            is located in the public header file <tt>ftsystem.h</tt>,
            which allows client developers to provide their own
            implementation of streams if they wish so.</p>

<p>The
            function <a href="../reference/ft2-base_interface.html#FT_New_Face"><code>FT_New_Face</code></a>
            always automatically creates a new stream object from the
            C&nbsp;pathname given as its second argument.  This is
            achieved by calling the (internal) 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 functions <tt>fopen</tt>, <tt>fseek</tt>,
            and <tt>fread</tt>.  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 and 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
            &lsquo;broken file&rsquo;.</p>

<p>The
            function <a href="../reference/ft2-base_interface.html#FT_New_Memory_Face"><code>FT_New_Memory_Face</code></a>
            can be used to directly create and open
            an <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 <a href="../reference/ft2-base_interface.html#FT_Open_Face"><code>FT_Open_Face</code></a>,
            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 <a href="../reference/ft2-base_interface.html#FT_Done_Face"><code>FT_Done_Face</code></a>.</p>

<h3 id="section-3">3. Modules</h3>

<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 <a href="../reference/ft2-module_management.html#FT_Module_Class"><code>FT_Module_Class</code></a>,
            defined in header file
            <tt>ftmodule.h</tt>, and is described later in this
            document.</p>

<p>You need a pointer to an <tt>FT_Module_Class</tt>
            structure when
            calling <a href="../reference/ft2-module_management.html#FT_Add_Module"><code>FT_Add_Module</code></a>.</p>

<pre>
FT_Error
FT_Add_Module( FT_Library              library,
               const FT_Module_Class*  clazz );</pre>

<p>This function does the following tasks.</p>

<ul>
            <li>
              <p>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, 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, return immediately.  Similarly,
                check that the version of FreeType&nbsp;2 that is
                running is correct compared to the one required by the
                module.</p>
            </li>
            <li>
              <p>Create 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, call it to complete the module object's
                initialization.</p>
            </li>
            <li>
              <p>Add the new module to the library's list of
                &lsquo;registered&rsquo; modules.  In case of an
                upgrade, destroy the previous module object.</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 later on in this
            document.</p>

<ul>
            <li>
              <p><em>Renderer</em> modules are used to convert native
                glyph images to bitmaps or pixmaps.  FreeType&nbsp;2
                comes with two renderer modules by default: one to
                generate monochrome bitmaps, the other to generate
                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 or 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 font and CFF
                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 or
            unregistered from a library instance (typically by calling
            the <a href="../reference/ft2-module_management.html#FT_Remove_Module"><code>FT_Remove_Module</code></a>
            function).  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>

<h3 id="section-4">4. Summary</h3>

<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>

<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" class="current">Internal Objects and Classes</a>
    </li>
    <li class="tertiary">
      <a href="design-5.html">Module Classes</a>
    </li>
    <li class="tertiary">
      <a href="design-6.html">Interfaces and Services</a>
    </li>
  </ul>
</div>

</div>

</body>
</html>

MR SKB