docs/internals/freetype_internals.html - third_party/freetype2 - Git at Google

 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
 <html>
 <head>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <meta name="Author" content="David Turner">
    <meta name="GENERATOR" content="Mozilla/4.5 [fr] (Win98; I) [Netscape]">
    <title>FreeType 2 Internals</title>
 </head>
 <body>

 <body text="#000000"
       bgcolor="#FFFFFF"
       link="#0000EF"
       vlink="#51188E"
       alink="#FF0000">

 <center>
 <h1>
 FreeType 2.0 Internals</h1></center>

 <center>
 <h2>
 Version 1.0</h2></center>

 <center>
 <h3>
 &copy; 1999 David Turner (<a href="fichier :///david@freetype.org">david@freetype.org</a>)<br>
 &copy; 1999 The FreeType Development Team (<a href="fichier :///devel@freetype.org">devel@freetype.org</a>)</h3></center>

 <p><br>
 <hr WIDTH="100%">
 <br>&nbsp;
 <h2>
 Introduction:</h2>

 <blockquote>This document describes in great details the internals of the
 FreeType 2.0 library. It is a must read for porters and developers alike.
 Its purpose is to present the engine's objects, their roles and interactions.
 It is assumed that the <b><i>FreeType Glyph Conventions</i></b> document
 has been read.
 <p>We advise porters to also read the <b><i>FreeType Porting Guide</i></b>
 after this document. Would-be hackers and maintainers are of course encouraged
 to read the <b><i>FreeType Coding Conventions</i></b> document too. The
 development of a new driver is described in more details in the <b><i>FreeType
 Driver HowTo</i></b> document.</blockquote>

 <p><br>
 <hr WIDTH="100%">
 <h2>
 I. Overview :</h2>

 <blockquote>
 <h3>
 1. Features (and what's new) :</h3>

 <blockquote>FreeType 2.0 has a number of important new features that were
 not found in the 1.x releases :
 <br>&nbsp;
 <blockquote><b>font-format independent API</b>
 <br>FreeType 2.0 is able to support any kind of font format, be it fixed
 or scalable, through the use of pluggable "font drivers". These drivers
 can be added or replaced at run time, while applications use a new font
 format-independent API.
 <p><b>advanced stream caching</b>
 <br>2.0 is able to control the number of concurrently opened streams when
 using fonts. It is thus possible to open dozens or hundreds of font faces
 without running out of system resources.
 <p><b>real reentrancy support</b>
 <br>It is now possible to use FreeType as a shared library with no static
 data in a multi-threaded environment. The synchronization model has also
 been simplified in order to make font driver writing easier. Of course,
 you can build FreeType with no thread support to get a smaller library.
 <p><b>support for cubic beziers and 17-levels anti-aliasing</b>
 <br>The FreeType scan-line converter (a.k.a. raster) now supports cubic
 bezier arcs seamlessly. It also provides a new anti-aliasing mode which
 uses a palette of 17 levels of grays.
 <br>&nbsp;</blockquote>
 It also features the following :
 <blockquote><b>performance improvements :</b>
 <br>The FreeType raster has been optimized, and the generation of anti-aliased
 pixmaps is now 60% faster than in the 1.x release. Moreover, the TrueType
 bytecode interpreter has been profiled and greatly optimised.
 <p><b>easier portability</b>
 <br>Porting and configuring FreeType is now much easier. A single file
 must be provided for system-specific operations (like memory, i/o, thread
 management), and a single configuration header is used to select the build
 you need.
 <br>&nbsp;</blockquote>
 </blockquote>

 <h3>
 2. Architecture :</h3>

 <blockquote>The engine is now split in several parts, which are :
 <h4>
 a. The base layer :</h4>

 <blockquote>This part contains all the font-format independent features
 of the engine which are :
 <ul>
 <li>
 computations/scaling</li>

 <li>
 list processing</li>

 <li>
 outline processing</li>

 <li>
 scan-line converter</li>

 <li>
 stream manager</li>

 <li>
 base object classes</li>

 <li>
 debugging &amp; traces</li>

 <li>
 high-level API functions</li>

 <li>
 low-level system object (memory, i/o, threads)</li>
 </ul>
 </blockquote>

 <h4>
 b. The font drivers :</h4>

 <blockquote>Each font format is managed with the use of a single font driver
 object. The base layer is able to manage several drivers, and these can
 be easily added, removed or upgraded at runtime. Each driver has the following
 features and functions :
 <ul>
 <li>
 auto-check font format when opening a font resource (i.e. file)</li>

 <li>
 access, load and/or extract all tables and data from the font file</li>

 <li>
 grid-fit/hint the glyph outlines (in the case of scalable formats like
 TrueType or Type1)</li>

 <li>
 provide extensions to access font format-specific data and tables from
 the font file</li>
 </ul>
 Note that FreeType 2.0 is a font service. Its purpose is to provide a unified
 API for all kinds of fonts and extract individual glyph images and metrics.
 However, it does not render text itself, as this operation is left to the
 developer, or to higher-level libraries built on top of FreeType. Here
 are a few features that are thus not implemented :
 <blockquote>1) Text string rendering
 <br>2) Glyph bitmap/outline caching for improved performance
 <br>3) Synthetic fonts (i.e. italicising, emboldening, underlining)
 <br>4) Contextual glyph substitution and other advanced layout processes</blockquote>
 Note that features 1 through 3 should be provided by the SemTex library,
 which may soon become part of the standard FreeType distribution.</blockquote>
 </blockquote>
 </blockquote>

 <p><br>
 <hr WIDTH="100%">
 <h2>
 II. Design :</h2>

 <blockquote>
 <h3>
 1. Objects :</h3>

 <blockquote>They are several kinds of objects in FreeType, which can be
 described as follows :
 <blockquote><b>Base objects</b>
 <br>These objects do not relate directly to font data, but to the way it
 is organised and managed. It is the basic core and provides functions that
 are heavily used by each font driver. Examples are the resource objects,
 used to describe font files, the system object used to manage low-level
 system operations, or the raster object, used to convert vector outlines
 into bitmaps or anti-aliased pixmaps. Most of the base objects are not
 directly visible for client applications of FreeType.
 <p><b>Font objects</b>
 <br>The font objects directly model the data as it is found in font files.
 The root classes implemented in the base layer like <tt>FT_Face</tt>, <tt>FT_Size</tt>,
 <tt>FT_GlyphSlot</tt>,
 must be derived in each font driver.</blockquote>
 Objects are defined in the files "<tt>base/freetype.h</tt>" and "<tt>base/ftobjs.h</tt>".
 The former contains all the public object definitions usable by client
 applications. The latter contains private definitions used by the rest
 of the base layer and each font driver.</blockquote>

 <h3>
 2. List management</h3>

 <blockquote>The "<tt>base/ftlist.c</tt>" component a very simple doubly-linked
 list facility which is used by the rest of the engine to create and process
 lists, including iteration and finalisation. The definition of the list
 node and functions are placed in the "<tt>base/freetype.h</tt>" to let
 client applications access listed objects as they like.
 <p>The base list type is <tt>FT_List</tt>, which links nodes of type <tt>FT_ListNode</tt>
 together.
 <br>&nbsp;</blockquote>

 <h3>
 3. Limited encapsulation</h3>

 <blockquote>Unlike what happened in the 1.x releases, the <tt>FT_Face</tt>,
 <tt>FT_Size</tt>,
 <tt>FT_GlyphSlot</tt> and <tt>FT_CharMap</tt> types are no longer blind
 pointers to opaque types. Rather, the corresponding structures are now
 public (and defined in "<tt>base/freetype.h</tt>", see <tt>FT_FaceRec</tt>,
 <tt>FT_SizeRec</tt>,
 etc..) in order to let client applications read directly the various object
 attributes they're interested in.
 <p>This breaks encapsulation of implementation, famed by OOP, but was chosen
 because:
 <br>&nbsp;
 <ul>
 <li>
 it simplifies a lot the work of client applications and libraries which
 don't need to perform a function call everytime they want to read one important
 object attribute (nor does it force them to cache these attributes in their
 own structures).</li>
 </ul>

 <ul>
 <li>
 It reduces greatly the API, as many <tt>FT_Get_XXX</tt> functions are avoided.</li>
 </ul>

 <ul>
 <li>
 Higher-level libraries are able to&nbsp; access data directly. When it
 is used frequently, they don't need to cache it in their own structures.</li>
 </ul>

 <ul>
 <li>
 It is possible to tightly link FreeType objects with higher-level ones,
 in a clearer and more efficient way. This is very important when one wants
 to write a C++ wrapper or a text rendering library on top of FreeType (actually,
 both projects were performed in an earlier version of FreeType 2.0 which
 featured classic encapsulation through get/set methods. The resulting code
 was ugly and slow. Moving to a limited encapsulation approach simplified
 so many things that the compiled code size was reduced by a factor of two
 !).</li>
 </ul>

 <ul>
 <li>
 Finally, the API and font object structures were designed after the creation
 of two scalable font drivers and one bitmap font driver. They are now very
 stable and the public (visible) attributes are not going to change.</li>
 </ul>
 </blockquote>
 </blockquote>

 <p><br>
 <hr WIDTH="100%">
 <h2>
 III. Base objects :</h2>

 <blockquote>This section describes the FreeType base object classes :
 <br>&nbsp;
 <h3>
 1. System objects :</h3>

 <blockquote>The system class is in charge of managing all low-level and
 system-specific operations. This means simply memory management, i/o access
 and thread synchronisation. It is implemented by the "<tt>ftsys.c</tt>"
 component, whose source must be located in the configuration directory
 when building FreeType. (e.g. "<tt>lib/arch/ansi/ftsys.c</tt>" for an ANSI
 build, "<tt>lib/arch/unix/ftsys.c</tt>" for a Unix one, etc..).
 <p>Porting FreeType 2.0 really means providing a new implementation of
 <tt>ftsys</tt>
 (along with a few configuration file changes). Note however that its interface
 is common to all ports, and located in "<tt>base/ftsys.h</tt>".</blockquote>

 <h3>
 2. Resources and Streams:</h3>

 <blockquote>The concepts of files as storages, and files as streams has
 been separated for FreeType 2.0. The "<b><i>resource</i></b>" concept was
 introduced while the "<b><i>stream</i></b>" one has been redefined. Here
 is how they work together :
 <ul>
 <li>
 a "<b>resource</b>" is an object which models a file, seen as a storage.
 There are several classes of resources, which differ usually in two ways
 : the way their data is accessed by applications, and the way they're named
 within the system.</li>
 </ul>

 <ul>For example, when parsing files with the ANSI C library, data has to
 be read (through fseek/fread) into intermediate buffers before it can be
 decoded. This scheme is highly portable, but rather inefficient; when using
 it, we'll describe the file as a disk-based resource.
 <p>As most modern operating systems now provide memory-mapped files, which
 allow direct access while improving performance and reducing memory usage.
 Because data can be read directly in memory, we'll speak of a memory-based
 resource in this case. For embedded systems (like printers, PDAs, etc..),
 ROM-fonts fit into this category as well.
 <p>Regarding naming, most systems use a string to name files in their storage
 hierarchy. Though a typical pathname is an ASCII string (<tt>'c:\windows\fonts\times.ttf'</tt>
 on Windows, <tt>'/home/fonts/times.ttf'</tt> on Unix), some OSes use different
 schemes, varying from Unicode character strings to file i-node numbers.
 These details are platform-specific and must be hidden to the rest of the
 library in resource objects.
 <p>A resource encapsulates the lowest details regarding a file, though
 it should have NO STATE. Note that the nature or type of a resource (i.e.
 disk or memory based) is important to the "stream" component only. The
 rest of the library and font drivers work transparently from their implementation.
 <p>Note also that it is perfectly possible to mix resources of distinct
 natures in a single build</ul>

 <ul>
 <li>
 a "<b>stream</b>" is an object which is used to extract bytes from a resource.
 Only resource objects can create streams, through its <i><tt>Open_Stream()</tt></i>
 method. A stream has state, which typically consist of a file "cursor",
 some intermediate buffers, a "current frame" and, of course, methods used
 to extract the data from streams, resolving endianess and alignement issues.</li>
 </ul>
 Data can be extracted from streams through direct reads, or through the
 use of <b>frames</b>. A frame models <i>a run of contiguous bytes</i> starting
 from the current stream position, and of liberal size.
 <p>Methods exist to extract successive integers of any sizes, while resolving
 endianess and alignement issues. Rather than a long rethorical explanation,
 here's how frames are typically used :
 <blockquote><tt>{</tt>
 <br><tt>&nbsp; </tt>
 <br><tt>&nbsp; FT_Error&nbsp; error;</tt>
 <p><tt>&nbsp; error = FT_Access_Frame( stream, 14 );</tt>
 <br><tt>&nbsp; if (error) goto Fail;</tt>
 <p><tt>&nbsp; val1 = FT_Get_Short(stream);</tt>
 <br><tt>&nbsp; val2 = FT_Get_Long(stream);</tt>
 <br><tt>&nbsp; val3 = FT_Get_Long(stream);</tt>
 <br><tt>&nbsp; val4 = FT_Get_Long(stream);</tt>
 <p><tt>&nbsp; FT_Forget_Frame(stream);</tt>
 <br><tt>&nbsp; </tt>
 <br><tt>}</tt></blockquote>
 This code does the following :
 <blockquote>
 <ol>
 <li>
 &nbsp;first, it "loads" the next 14 bytes from the current cursor position
 into the stream's frame, using the <tt>FT_Access_Frame</tt> API. An error
 is returned if, for example, less than 14 bytes are left in the stream
 when the call occurs..</li>
 </ol>

 <ol>
 <li>
 &nbsp;it extract four integers (one 16-bit short, three 32-bit longs) from
 the frame using <tt>FT_Get_Short</tt> and <tt>FT_Get_Long</tt>. These function
 increment the frame's cursor finally, it "releases" the stream's frame.</li>
 </ol>

 <ol>
 <li>
 &nbsp;Each stream has its own frame which can be accessed independently,
 however, nested frame accesses are not allowed. Note also that the bytes
 are effectively read from the stream on the call to <tt>FT_Access_Frame</tt>.
 Any subsequent read will occur after these 14 bytes, even if less are extracted
 through <tt>FT_Get_xxxx</tt> functions.</li>
 </ol>
 </blockquote>
 The implementation of the resource class is located in the system component
 (i.e. "<tt>arch/<i>&lt;system></i>/ftsys.c</tt>") and can thus be tailored
 for a specific port of the engine.
 <p>A resource can be created through the <tt>FT_New_Resource</tt> API;
 however this function only accepts an 8-bit pathname to name the target
 font file, which may be inappropriate for systems using a different naming
 scheme (e.g. UTF-16 pathname, i-node number, etc..). It's up to the porter
 then to provide its own resource creation function (like. <tt>FT_New_UTF16_Resource</tt>,
 for example) in its version of "<tt>ftsys.c</tt>".
 <p>Note that <tt>FT_New_Resource</tt> will fail and return an error code
 if the font file cannot be found, or when its font format isn't recognized
 by one of the drivers installed in the library. The list or resources created
 for a given library instance is thus the list of "installed font files".
 <br>&nbsp;</blockquote>

 <h3>
 3. Stream Manager :</h3>

 <blockquote>As said before, resources do not bear states, while streams
 do. Stream creation is also a very lengthy process, depending on the target
 operating system (e.g. "<tt>fopen</tt>" is usually very slow).
 <p>Because a typical font driver will want to use a new stream on each
 access to individual glyphs, being able to cache the most recently used
 streams is a requirement in order to avoid considerable performance penalties.
 <p>Stream caching is thus implemented in the "<tt>ftstream</tt>" component.
 It maintains a simple LRU list of the least recently used streams. Each
 stream in the cache is still opened and available for immediate processing.
 When a resource is destroyed, the stream cache is parsed to remove all
 related cached streams.
 <p>Stream caching can also be disabled with a configuration macro when
 using only ROM based resources (where stream opening is really quick).
 It is implemented through a Stream Manager object (see <tt>ftstream.c</tt>).
 <br>&nbsp;</blockquote>

 <h3>
 4. Raster :</h3>

 <blockquote>The raster is the component is charge of generating bitmaps
 and anti-aliased pixmaps from vectorial outline definitions. It is also
 sometimes called the scan-line converter. It has been completely rewritten
 for FreeType 2.0 in order to support third-order bezier arcs, 17-levels
 anti-aliasing (through 4x4 sub-sampling), improved performance, as well
 as stand-alone compilation (in order to include it in other graphics package
 without requiring the rest of the FreeType engine).
 <p>Because it was designed for easy re-use and embedded systems, the raster
 is a rtaher 'unusual' piece of code, because it doesn't perform a single
 memory allocation, nor contain any static or global variable. Rather, it
 is up to client applications to allocate a raster object in their own heap
 or memory space.
 <p>Each raster object also needs a rather large block of memory called
 its render pool. The pool is used during rendering (and only during it)
 in order to perform the scan-line conversion. Because it accesses and manages
 data directly within the pool, the raster yelds impressive performance
 as well as bounded memory consumption. It can also automatically decompose
 large requests into smaller individual sub-tasks.
 <p>Finally, it never creates bitmaps or pixmaps, but simply renders into
 them (providing clipping too). These must be described to the raster with
 the help of a <tt>FT_Raster_Map</tt> structure (a very simple bitmap/pixmap
 descriptor).
 <p>Note that when rendering anti-aliased pixmaps, the raster doesn't use
 an intermediate bitmap buffer, as filtering is part of the scan-line conversion
 process.
 <br>&nbsp;</blockquote>

 <h3>
 5. Library objects :</h3>

 <blockquote>A library object models a single instance of the FreeType engine.
 This is useful when FreeType is compiled as a shared object (DLL), as it
 can then be used by several applications, each with its own resources and
 objects.
 <p>The <tt>FT_Library</tt> type is an opaque handle to a library object.
 Such an object is created through a call&nbsp; to <tt>FT_Init_FreeType</tt>.
 Once you don't need it anymore, one can destroy a library object through
 <tt>FT_Done_FreeType</tt>.
 <p>Note that in reentrant builds, several threads can access a single library
 object concurrently. Such a build can be chosen by switching one configuration
 macro in the file '<tt>arch/<i>&lt;system></i>/ftconfig.h</tt>'</blockquote>

 <h3>
 6. Driver objects :</h3>

 <blockquote>A driver object models an instance of a given font driver,
 i.e. an element of FreeType code in charge of handling a given font format,
 like TrueType, Type1, FNT, PCF, etc..
 <p>Each library object contains a given set of driver objects when it is
 created through FT_Init_FreeType, this set being determined at compile
 time (see the file 'base/ftapi.c'). However, removing or adding drivers
 is possible at run-time, in order to make upgrades easy.</blockquote>

 <h3>
 7. Diagram</h3>

 <blockquote>This diagram show the object relationships for the sole base
 layer. The library object is the root of the object graph :
 <center>
 <p><img SRC="objects_diagram.gif" height=300 width=562></center>

 <p>It can be read as follows :
 <br>&nbsp;
 <ul>
 <li>
 Each library object has one system, one raster and one stream manager objects.
 These objects can only belong to one given library.</li>
 </ul>

 <ul>
 <li>
 Each library contains one list of 0 or more resources, as well as one list
 of 0 or more driver objects.</li>
 </ul>

 <ul>
 <li>
 Each stream manager holds a bounded list ("0..n" where 'n' is the stream
 cache's size) of stream objects. Each stream is related to one given resource
 object. Each resource may be related to zero or one stream.</li>
 </ul>

 <ul>
 <li>
 Each resource is related to one driver object. A driver is related to 0
 or more resources.</li>
 </ul>
 </blockquote>
 </blockquote>

 <p><br>
 <hr WIDTH="100%">
 <h2>
 IV. Font objects :</h2>

 <blockquote>Font objects are used to directly map the information found
 in font files into several categories :
 <br>&nbsp;
 <h3>
 1. Face objects :</h3>

 <blockquote>Face objects are used to model individual font faces. They
 encapsulate data which isn't related to a specific character size, or a
 specific glyph or glyph set. Usually, this means :
 <ul>
 <li>
 the font face's family and style names (e.g. "Palatino" + "Regular")</li>

 <li>
 some flags indicating which kind of font this is (scalable or fixed ? fixed-width
 or proportional ? horizontal or vertical ? etc)</li>

 <li>
 the number of glyphs, charmaps and eventually fixed character sizes (for
 bitmap formats) found in the font face.</li>

 <li>
 for scalable formats, some important metrics like the ascender, descender,
 global font bounding box, maximum advance width, etc.. expressed in notional
 font/grid units (as well as the number of units on the EM grid).</li>
 </ul>
 A face is created from a resource object, with the <tt>FT_New_Face</tt>
 API. Each driver contains a list of opened face objects for the resources
 it manages. When a driver is removed or destroyed, all its child faces
 are discarded automatically with it.</blockquote>

 <h3>
 2. Size objects :</h3>

 <blockquote>Size objects are used to model a given character dimension
 for a given device resolution (which really means a given character pixel
 dimensions).
 <p>Each size object is created from a parent face object. The object can
 be reset to new dimensions at any time. Each face object holds a list of
 all its child sizes, these are destroyed automatically when the face object
 is discarded.
 <p>The metrics contains metrics, expressed in pixels, for the ascender,
 descender, maximum advance width, etc..
 <br>&nbsp;</blockquote>

 <h3>
 3. Glyph Slot objects :</h3>

 <blockquote>A glyph slot is a container where one can load individual glyphs,
 be they in vector of bitmap format. Each slot also contains metrics for
 the glyph it contains.
 <p>Each face object contains one or more glyph slot object : the first
 glyph slot is created automatically with its parent face, and it is possible
 to add new glyph slots (this is rarely used outside of debugging purposes).
 <br>&nbsp;</blockquote>

 <h3>
 4. CharMap objects :</h3>

 <blockquote>A charmap object is a sort of dictionary whose task is to translate
 character codes in a given character encoding (like ShiftJIS, Unicode,
 ANSI, etc..) into glyph indexes in a given font face.
 <p>A face object contains one or more charmap objects. All charmap objects
 are created when the parent face is created, though they're not directly
 visible to client applications (rather, they can be enumerated through
 FT_Get_First_CharMap and FT_Get_Next_CharMap, or more simply picked adequately
 with FT_Find_CharMap for a set of given encodings).
 <br>&nbsp;</blockquote>

 <h3>
 5. Diagram</h3>

 <blockquote>The following diagram illustrates the relationships between
 font objects :
 <center>
 <p><img SRC="objects_diagram2.gif" height=327 width=561></center>

 <p>Which can be read as :
 <br>&nbsp;
 <ul>
 <li>
 each resource may have zero or more child face objects "opened" for it.
 The number of faces is bounded by the number of font faces within the font
 resource.</li>
 </ul>

 <ul>
 <li>
 each driver holds a list of all the faces opened for the resources it manages.
 When the driver is removed, its child faces are discarded automatically.</li>
 </ul>

 <ul>
 <li>
 each face object has one single parent resource, and one single driver.</li>
 </ul>

 <ul>
 <li>
 each face has one or more charmaps, and one or more glyph slots</li>
 </ul>

 <ul>
 <li>
 each face holds a list of zero or more child size objects</li>
 </ul>

 <ul>
 <li>
 each charmap, glyph slot and size is related to one given parent face.
 These objects are destroyed automatically when the parent face is discarded.</li>
 </ul>
 </blockquote>
 </blockquote>

 <p><br>
 <hr WIDTH="100%">
 <h2>
 V. Driver Interface :</h2>

 <blockquote>A font driver is added to a given library object through the
 <tt>FT_Add_Driver</tt>
 API. This function receives a structure known as a <tt>FT_DriverInterface</tt>,
 which describes the driver's basic properties.
 <p>The <tt>FT_DriverInterface</tt> contains a set of function pointers
 used for the base FreeType functionalities. However, each driver can also
 provide a font-format-specific extended interface to allow client applications
 to use more advanced features.
 <br>&nbsp;
 <h3>
 1. Common Interface</h3>

 <blockquote>The structure of <tt>FT_DriverInterface</tt> is rather simple,
 and defined in "<tt>base/ftdriver.h</tt>". It must be well known by any
 developer who wants to write a new driver for the engine. We advise reading
 the <b><i>FreeType Driver HowTo</i></b> as well as the source code of existing
 drivers. Source comments.</blockquote>

 <h3>
 2. Driver-specific extensions</h3>

 <blockquote>The field of the <tt>FT_DriverInterface</tt> structure is a
 typeless pointer to a format-specific interface. This extended interface
 is usually a structure containing function pointers as well as other kind
 of information related to the driver.
 <p>It is assumed that client applications that wish to use the driver-specific
 extensions are able to <tt>#include</tt> the relevant header files to understand
 the format-specific interface structure.</blockquote>
 </blockquote>

 <hr WIDTH="100%">
 <h2>
 VI. Configuration:</h2>

 <blockquote>This section relates to the configuration of the FreeType library.
 By configuration, we mean selection of build options as well as the choice
 of font drivers to be used for each new library object.
 <br>&nbsp;
 <h3>
 1. Configuration files :</h3>

 <blockquote>A single file is used to configure the FreeType base engine.
 As it is considered system-specific, it is located in the architecture
 directories of the library, under the name "arch/&lt;system>/ftconfig.h".
 Note that the same directory should also contain a platform-specific implementation
 of "ftsys.c".
 <p>The configuration files is a simple C header which is included by the
 engine's sources during compilation. It is not included in "freetype.h",
 and hence doesn't need to be copied when installing the FreeType headers
 on your system.
 <p>It is made of a series of #define or #undef statements, which are used
 to select or turn off a specific option. Each option is documented with
 heavy comments, and some of them are explained below.</blockquote>

 <h3>
 2. Building and Makefiles :</h3>

 <blockquote>FreeType 2.0 is more complex than its 1.x release. In order
 to facilitate maintenance, as well as ease considerably the writing of
 new font drivers, <b><i>only GNU Make is supported with FreeType 2.0</i></b>.
 However, it is possible to use any compiler, as well as any object or library
 prefix (<tt>.o, .obj, .a, .lib</tt> etc..) with them.
 <p>To build FreeType 2.0, one has to be in the library directory, then
 invoke its platform-specific makefile. For a Unix system, this would be
 :
 <blockquote>
 <blockquote><tt>% cd freetype2/lib</tt>
 <br><tt>% make -f arch/unix/Makefile</tt>
 <p>where '<tt>make</tt>' is really GNU Make !</blockquote>
 </blockquote>
 The system-specific <tt>Makefile</tt> located in '<tt>arch/<i>&lt;system></i></tt>'
 is a tiny file used to define several variables. It then includes the file
 <tt>freetype2/lib/Makefile.lib</tt>,
 which contains all the gory details about library compilation. The system-specific
 <tt>Makefile</tt> can be very easily modified to accomodate a new compiler/platform
 (see the comments within one of these files).
 <p>Each font driver is located in a directory like "<tt>freetype2/lib/drivers/<i>&lt;formatdir></i></tt>".
 For example, the TrueType driver is located in "<tt>drivers/truetype</tt>".
 Each driver directory must contain a <tt>Makefile</tt> which will be included
 by <tt>Makefile.lib</tt>. The former is used to define and build driver
 object files.
 <br>&nbsp;
 <p><br>
 <center>
 <p><img SRC="build_diagram.gif" height=284 width=559></center>
 </blockquote>

 <h3>
 3. Make options :</h3>

 <blockquote>The base layer, as well as each font driver, are made up of
 several C sources. Traditionally, one compiles each source (i.e. '<tt>.c</tt>'
 file) into an object ('<tt>.o</tt>' or '<tt>.obj</tt>') file, and all of
 them are grouped into a library file (i.e. '<tt>.a</tt>' or '<tt>.lib</tt>').
 <p>By default, FreeType takes a slightly different approach when it comes
 to compiling each part of the engine. Usually, a single tiny source is
 compiled, which includes all other component sources. This results in a
 single object files, with the benefits or reduced code size, usually better
 compilation as well as a drastic reduction of the number of symbols exported
 by the library. Of course, it is made possible through the use of specific
 declaration macros in the FreeType source (see the definition of <tt>LOCAL_DEF</tt>
 and <tt>LOCAL_FUNC</tt> in <tt>ftconfig.h</tt> for details).
 <p>For a concrete example, see the source code in "<tt>base/ftbase.c</tt>"
 which generates the whole base layer in a single object file. The same
 build process is applied to font drivers, in order to generate one single
 object file per given font format (e.g. <tt>truetype.o</tt>, <tt>type1.o</tt>,
 etc..).
 <p>Compiling the library and drivers in "normal" mode is possible, through
 the use of the '<tt>multi</tt>' target (which really means &laquo; multiple
 objects &raquo;). For example, calling :
 <blockquote><tt>% make -f arch/ansi/Makefile multi</tt></blockquote>
 Will build the FreeType library by compiling each source file to an individual
 object, then linking them together. You'll notice that the library is significantly
 bigger in this case. Creating a shared dll from a 'multi' build is certainly
 a very poor idea, as this will export a huge quantity of symbols that aren't
 useful to any client application.</blockquote>

 <h3>
 4. Adding a driver at compile time</h3>

 <blockquote>A driver can be included very easily in the build process by
 including its <tt>Makefile</tt> in <tt>Makefile.lib</tt>. For example,
 the TrueType driver is simply included with the following lines (see <tt>Makefile.lib</tt>):
 <blockquote><tt># TrueType driver rules</tt>
 <br><tt>#</tt>
 <br><tt>include $(DRIVERS_DIR)/truetype/Makefile</tt></blockquote>

 <p><br>Where <tt>DRIVERS_DIR</tt> really is "<tt>freetype2/lib/drivers</tt>",
 though this can be redefined. You can, of course specify a different path
 if you want to place your driver sources in another location.
 <p>Note that this only adds the driver's object files to the generated
 library file. A few more steps are needed to make your <tt>FT_Library</tt>
 objects use the driver. They consist in modifying the file "<tt>base/ftinit.c</tt>",
 whose sole purpose is to define the set of driver objects that are to be
 created with each new library object.
 <br>&nbsp;</blockquote>

 <h3>
 5. Adding a driver at run time</h3>

 <blockquote>New driver objects can be added at run-time through the <tt>FT_Add_Driver</tt>
 API. This function takes a handle to an existing library object, as well
 as a pointer to a given driver interface. This interface is used to create
 a new driver object and register it within the library.
 <p>Similarly, a single driver can be removed from a library anytime through
 <tt>FT_Remove_Driver</tt>.
 This will automatically discard the resources and face objects managed
 by the driver.</blockquote>

 <h3>
 6. Custom library objects :</h3>

 <blockquote>Finally, it is possible to build custom library objects. You
 need to pass a handle to a valid <tt>FT_System</tt> object to the <tt>FT_Build_Library</tt>
 API. The function will return a handle to the new fresh library object.
 Note that the library has no registered drivers after the call, developers
 have to add them by hand with <tt>FT_Add_Driver</tt>.
 <p>It is thus possible to create two distinct library objects with distinct
 <tt>FT_System</tt>
 implementations in the same session, which can be useful for debugging
 purpose.</blockquote>

 <br>&nbsp;</blockquote>

 </body>
 </html>