22

✏️ Editing: design-3.html

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

<title>FreeType Design / II</title>
</head>

<body>

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

<div id="public-objects">
          <h2>II. Public Objects and Classes</h2>

<p>We will now explain the abstractions provided by
            FreeType&nbsp;2 to client applications to manage font
            files and data.  As you would normally expect, these are
            implemented through objects and classes.</p>

<h3 id="section-1">1. Object Orientation in
            FreeType&nbsp;2</h3>

<p>Though written in ANSI&nbsp;C, the library employs a few
            techniques, inherited from object-oriented programming, to
            make it easy to extend.  Hence, the following conventions
            apply in the FreeType&nbsp;2 source code.</p>

<ol>
            <li>
              <p>Almost all object types or classes have a
                corresponding <em>structure type</em> <b>and</b> a
                corresponding <em>structure pointer type</em>.  The
                latter is called the <em>handle type</em> for the type
                or class.</p>

<p>Consider that we need to manage objects of type
                &lsquo;foo&rsquo; in FreeType&nbsp;2.  We would define
                the following structure and handle types as
                follows.</p>

<pre>
typedef struct FT_FooRec_*  FT_Foo;

typedef struct  FT_FooRec_
{
  /* fields for the 'foo' class */
  ...

} FT_FooRec;</pre>

<p>As a convention, handle types use simple but
                meaningful identifiers beginning with <tt>FT_</tt>, as
                in <tt>FT_Foo</tt>, while structures use the same name
                with a <tt>Rec</tt> suffix appended to it
                (&lsquo;Rec&rsquo; is short for
                &lsquo;record&rsquo;).</p>
            </li>
            <li>
              <p>Class derivation is achieved internally by wrapping
                base class structures into new ones.  As an example,
                we define a &lsquo;foobar&rsquo; class that is derived
                from &lsquo;foo&rsquo;.  We would do something
                like this.</p>

<pre>
typedef struct FT_FooBarRec_*  FT_FooBar;

typedef struct  FT_FooBarRec_
{
  /* the base 'foo' class fields */
  FT_FooRec  root;

/* fields proper to the 'foobar' class */
  ...
} FT_FooBarRec;</pre>

<p>As you can see, we ensure that a &lsquo;foobar&rsquo;
                object is also a &lsquo;foo&rsquo; object by placing
                a <tt>FT_FooRec</tt> at the start of the
                <tt>FT_FooBarRec</tt> definition.  It is
                called <b>root</b> by convention.</p>

<p>Note that an <tt>FT_FooBar</tt> handle also points to
                a &lsquo;foo&rsquo; object and can be typecast
                to <tt>FT_Foo</tt>.  Similarly, when the library
                returns an <tt>FT_Foo</tt> handle to client
                applications, the object can be really implemented as
                <tt>FT_FooBar</tt> or any derived class from
                &lsquo;foo&rsquo;.</p>
            </li>
          </ol>

<p>In the following sections of this chapter, we will refer
            to &lsquo;the <tt>FT_Foo</tt> class&rsquo; to indicate the
            type of objects handled through <tt>FT_Foo</tt> pointers,
            be they implemented as &lsquo;foo&rsquo; or
            &lsquo;foobar&rsquo;.</p>

<h3 id="section-2">2. The <tt>FT_Library</tt> class</h3>

<p>This type corresponds to a handle to a single instance of
            the library.  Note that the corresponding
            structure <tt>FT_LibraryRec</tt> is not defined in public
            header files, making client applications unable to access
            its internal fields.</p>

<p>The library object is the <em>parent</em> of all other
            objects in FreeType&nbsp;2.  You need to create a new
            library instance before doing anything else with the
            library.  Similarly, destroying it will automatically
            destroy all its children (i.e., faces and modules).</p>

<p>Typical client applications should
            call <a href="../reference/ft2-base_interface.html#FT_Init_FreeType"><code>FT_Init_FreeType</code></a>
            in order to create a new library object, ready to be used
            for further actions.</p>

<p>Another alternative is to create a fresh new library
            instance by calling the function
            <a href="../reference/ft2-module_management.html#FT_New_Library"><code>FT_New_Library</code></a>,
            defined in the
            <tt>ftmodule.h</tt> public header file.  This function
            will however return an &lsquo;empty&rsquo; library
            instance with no module registered in it.  You can
            &lsquo;install&rsquo; modules in the instance by calling
            <a href="../reference/ft2-module_management.html#FT_Add_Module"><code>FT_Add_Module</code></a>
            manually.</p>

<p>Calling <tt>FT_Init_FreeType</tt> is a lot more
            convenient, because this function basically registers a
            set of default modules into each new library instance.
            The way this list is accessed or computed is determined at
            build time, and depends on the content of
            the <tt>ftinit</tt> component.  This process is explained
            in details later in this document.</p>

<p>For now, one should consider that library objects are
            created with <tt>FT_Init_FreeType</tt>, and destroyed
            along with all children
            with <a href="../reference/ft2-base_interface.html#FT_Done_FreeType"><code>FT_Done_FreeType</code></a>.</p>

<h3 id="section-3">3. The <tt>FT_Face</tt> class</h3>

<p>A face object corresponds to a single <em>font face</em>,
            i.e., a specific typeface with a specific style.  For
            example, &lsquo;Arial&rsquo; and &lsquo;Arial
            Italic&rsquo; correspond to two distinct faces.</p>

<p>A face object is normally created
            through <a href="../reference/ft2-base_interface.html#FT_New_Face"><code>FT_New_Face</code></a>.
            This function takes the following parameters:
            an <tt>FT_Library</tt> handle, a C file pathname used to
            indicate which font file to open, an index used to decide
            which face to load from the file (a single file may
            contain several faces in certain cases), and the address
            of an <tt>FT_Face</tt> handle.  It returns an error
            code.</p>

<pre>
FT_Error  FT_New_Face( FT_Library   library,
                       const char*  filepathname,
                       FT_Long      face_index,
                       FT_Face*     face );</pre>

<p>In case of success, the function
            returns <tt>FT_Err_Ok</tt> (which is value&nbsp;0), and
            the handle pointed to by the <tt>face</tt> parameter is
            set to a non-NULL value.</p>

<p>Note that the face object contains several fields used to
            describe global font data that can be accessed directly by
            client applications, for example, the total number of
            glyphs in the face, the face's family name, style name,
            the EM size for scalable formats, etc.  For more details,
            look at
            the <a href="../reference/ft2-base_interface.html#FT_FaceRec"><code>FT_FaceRec</code></a>
            definition in the FreeType&nbsp;2 API Reference.</p>

<h3 id="section-4">4. The <tt>FT_Size</tt> class</h3>

<p>Each <tt>FT_Face</tt> object has one or more
            <tt>FT_Size</tt> objects.  A <em>size object</em> stores
            data specific to a given character width and height.  Each
            newly created face object has one size, which is directly
            accessible as <tt>face-&gt;size</tt>.</p>

<p>The contents of a size object can be changed by calling
            <a href="../reference/ft2-base_interface.html#FT_Request_Size"><code>FT_Request_Size</code></a>, <a href="../reference/ft2-base_interface.html#FT_Set_Pixel_Sizes"><code>FT_Set_Pixel_Sizes</code></a>,
            or <a href="../reference/ft2-base_interface.html#FT_Set_Char_Size"><code>FT_Set_Char_Size</code></a>.</p>

<p>A new size object can be created
            with <a href="../reference/ft2-sizes_management.html#FT_New_Size"><code>FT_New_Size</code></a>,
            and destroyed manually
            with <a href="../reference/ft2-sizes_management.html#FT_Done_Size"><code>FT_Done_Size</code></a>.
            Note that typical applications don't need to do this
            normally: usually it is fully sufficient to use the
            default size object provided with
            each <tt>FT_Face</tt>.</p>

<p>The public fields of <tt>FT_Size</tt> objects are defined
            in a very small structure
            named <a href="../reference/ft2-base_interface.html#FT_SizeRec"><code>FT_SizeRec</code></a>.
            However, it is important to understand that some font
            drivers define their own derivatives of <tt>FT_Size</tt>
            to store important internal data that is re-computed each
            time the character size changes.  Most of the time, these
            are size-specific <em>font hints</em>.</p>

<p>For example, the TrueType driver stores the scaled CVT
            (Control Value Table) data that results from the execution
            of the &lsquo;prep&rsquo; program in a <tt>TT_Size</tt>
            structure, while the Type&nbsp;1 driver stores scaled
            global metrics (like blue zones) in a <tt>T1_Size</tt>
            object.  Don't worry if you don't understand the current
            paragraph; most of this stuff is highly font format
            specific and doesn't need to be explained to client
            developers&nbsp;:-)</p>

<h3 id="section-5">5. The <tt>FT_GlyphSlot</tt> class</h3>

<p>The purpose of a <em>glyph slot</em> is to provide a
            place where glyph images can be loaded one by one easily,
            independently of the glyph image format (bitmap, vector
            outline, or anything else).</p>

<p>Ideally, once a glyph slot is created, any glyph image
            can be loaded into it without additional memory
            allocation.  In practice, this is only possible with
            certain formats like TrueType which explicitly provide
            data to compute a slot's maximum size.</p>

<p>Another reason for glyph slots is that they are also used
            to hold format-specific hints for a given glyphs as well
            as all other data necessary to correctly load the
            glyph.</p>

<p>The
            base <a href="../reference/ft2-base_interface.html#FT_GlyphSlotRec"><code>FT_GlyphSlotRec</code></a>
            structure only presents glyph metrics and images to client
            applications, while the actual implementation may contain
            more sophisticated data.</p>

<p>As an example, the
            TrueType-specific <tt>TT_GlyphSlotRec</tt> structure
            contains additional fields to hold glyph-specific
            bytecode, transient outlines used during the hinting
            process, and a few other things.  The
            Type&nbsp;1-specific <tt>T1_GlyphSlotRec</tt> structure
            holds glyph hints during glyph loading, as well as
            additional logic used to properly hint the glyphs when a
            native Type&nbsp;1 hinter is used.</p>

<p>Each face object has a single glyph slot that is directly
            accessible as <tt>face-&gt;glyph</tt>.</p>

<h3 id="section-6">6. The <tt>FT_CharMap</tt> class</h3>

<p>The <tt>FT_CharMap</tt> type is a handle to character map
            objects, or <em>charmaps</em>.  A charmap is simply some
            sort of table or dictionary to translate character codes
            in a given encoding into glyph indices for the font.</p>

<p>A single face may contain several charmaps.  Each one of
            them corresponds to a given character repertoire, like
            Unicode, Apple Roman, Windows codepages, and other
            encodings.</p>

<p>Each <tt>FT_CharMap</tt> object contains a
            &lsquo;platform&rsquo; and an &lsquo;encoding&rsquo; field
            to precisely identify the character repertoire
            corresponding to it.</p>

<p>Each font format provides its own derivative of
            <a href="../reference/ft2-base_interface.html#FT_CharMapRec"><code>FT_CharMapRec</code></a>
            and thus needs to implement these objects.</p>

<h3 id="section-7">7. Objects Relationship</h3>

<p>The following diagram summarizes what we have just said
            regarding the public objects managed by the library; it
            also describes their relationship.</p>

<p>Note that this picture will be updated at the end of the
            next chapter, related to <em>internal objects</em>.</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" class="current">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">Module Classes</a>
    </li>
    <li class="tertiary">
      <a href="design-6.html">Interfaces and Services</a>
    </li>
  </ul>
</div>

</div>

</body>
</html>

MR SKB