kmx git

<!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.png" 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.png" 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.png" 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>
kc3-lang/freetype/docs/design/index.html

Commit

docs/design/index.html
