ref: 4cd68a09c52289fd27ca556e7d83055b51c3f295
parent: 6a4253388bee1f9be9ab6787a74b2217f1869712
author: David Turner <[email protected]>
date: Wed Oct 25 19:42:02 EDT 2000
updating the FT2 design documentation - note that the "modules.html" will soon disappear, it is now replaced by a more general and more detailed series of pages named "design-??.html" - the images have been seriously reworked, more will come tomorrow
binary files a/docs/design/basic-design.png b/docs/design/basic-design.png differ
--- /dev/null
+++ b/docs/design/design-1.html
@@ -1,0 +1,82 @@
+<html>
+<head><title>The Design of FreeType 2 - Introduction</title>
+<basefont face="Georgia, Arial, Helvetica, Geneva">
+<style content="text/css">
+ P { text-align=justify }+ H1 { text-align=center }+ H2 { text-align=center }+ LI { text-align=justify }+</style>
+</head>
+<body text=#000000 bgcolor=#ffffff>
+
+<center><table width="500"><tr><td>
+
+<center><h1>The Design of FreeType 2</h1></center>
+
+<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
+<h1>Introduction</h1>
+</td></tr></table>
+
+<p>This document provides details on the design and implementation
+ of the FreeType 2 library. Its goal is to allow developers to
+ better understand the way FT2 is organized, in order to let them
+ extend, customize and debug it.</p>
+
+<p>Before anything else, it is important to understand the <em>purpose</em>
+ of this library, i.e. why it has been written:</p>
+
+<ul>
+ <li><p>first of all, to allow client applications to <em>access font files
+ easily</em>, wherever they could be stored, and as independently
+ of font format as possible.</p></li>
+
+ <li><p>to allow easy <em>retrieval of global font data</em> most commonly
+ found in normal font formats (i.e. global metrics,
+ encoding/charmaps, etc..)</p></li>
+
+ <li><p>to allow easy <em>retrieval of individual glyph data</em>
+ (metrics, images, name, anything else)</p></li>
+
+ <li><p>to allow <em>access to font format-specific "features"</em>
+ whenever possible (e.g. SFNT tables, Multiple Masters,
+ OpenType Layout tables, etc..)</p></li>
+</ul>
+
+<p>its design has also severely been influenced by the following
+ requirements:</p>
+
+<ul>
+ <li><p><b>high portability</b>, as the library must be able to run
+ on any kind of environment. this requirement introduces a few
+ drastic choices that are part of FreeType 2's low-level system
+ interface.</p></li>
+
+ <li><p><b>extendibility</b>, as new features should be added with
+ the least modifications in the library's code base. this
+ requirements induces an extremely simple design where nearly
+ all operations are provided by modules.
+ </p></li>
+
+ <li><p><b>customization</b>, it should be easy to build a version
+ of the library that only contains the features needed by a
+ specific project. This really is important when you need to
+ integrate it in a font server for embedded graphics libraries.</p></li>
+
+ <li><p><b>compactness</b> and <b>efficiency</b>, given that the
+ primary target for this library is embedded systems with low
+ cpu and memory resources.</p></li>
+</ul>
+
+<p>The rest of this document is divided in several sections. First, a
+ few chapters will present the library's basic design as well as the
+ objects/data managed internally by FreeType 2.</p>
+
+<p>A later section is then dedicated to library customization, relating
+ such topics as system-specific interfaces, how to write your own
+ module and how to tailor library initialisation & compilation
+ to your needs.</p>
+
+</td></tr></table></center>
+</body>
+</html>
--- /dev/null
+++ b/docs/design/design-2.html
@@ -1,0 +1,112 @@
+<html>
+<head><title>The Design of FreeType 2 - Basic Design</title>
+<basefont face="Georgia, Arial, Helvetica, Geneva">
+<style content="text/css">
+ P { text-align=justify }+ H1 { text-align=center }+ H2 { text-align=center }+ LI { text-align=justify }+</style>
+</head>
+<body text=#000000 bgcolor=#ffffff>
+
+<center><table width="500"><tr><td>
+
+<center><h1>The Design of FreeType 2</h1></center>
+
+<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
+<h1>I. Components and APIs</h1>
+</td></tr></table>
+
+<p>It's better to describe FreeType 2 as a collection of
+ <em>components</em>. Each one of them is a more or less abstract
+ part of the library that is in charge of one specific task. We will
+ now explicit the connections and relationships between them.</p>
+
+<p>A first brief description of this system of components could be:</p>
+<ul>
+ <li><p>
+ client applications typically call the FreeType 2 <b>high-level
+ API</b>, whose functions are implemented in a single component
+ called the <em>Base Layer</em>.
+ </p></li>
+
+ <li><p>
+ depending on the context or the task, the base
+ layer then calls one or more <em>module</em> components to
+ perform the work. In most cases, the client application doesn't
+ need to know what module was called.
+ </p></li>
+
+ <li><p>
+ the base layer also contains a set of routines that are
+ used for generic things like memory allocation, list
+ processing, i/o stream parsing, fixed point computation,
+ etc.. these functions can also be called by a module
+ at any time, and they form what is called the <b>low-level
+ base API</b>.
+ </p></li>
+</ul>
+
+<p>This is illustrated by the following graphics (note that component
+ entry points are represented as colored triangles):</p>
+
+<center><img src="basic-design.png" width="394" height="313"></center>
+
+<p>Now, a few additional things must be added to complete this picture:</p>
+
+<ul>
+ <li><p>some parts of the base layer can be replaced for specific builds
+ of the library, and can thus be considered as components themselves.
+ this is the case for the <b>ftsystem</b> component, which is in
+ charge of implementing memory management & input stream access,
+ as well as the <b>ftinit</b>, which is in charge of library
+ initialisation (i.e. implementing <tt>FT_Init_FreeType</tt>).
+ </p></li>
+
+ <li><p>
+ FreeType 2 comes also with a set of <em>optional components</em>,
+ which can be used either as a convenience for client applications
+ (e.g. the <b>ftglyph</b> component, used to provide a simple API
+ to manage glyph images independently of their internal representation),
+ or to access format-specific features (e.g. the <b>ftmm</b> component
+ used to access and manage Multiple Masters data in Type 1 fonts)
+ </p></li>
+
+ <li><p>
+ Finally, a module is capable of calling functions provided by
+ another module. This is very useful to share code and tables
+ between several font driver modules (for example, the <tt>truetype</tt>
+ and <tt>cff</tt> both use the routines provided by the <tt>sfnt</tt>
+ module).
+ </p></li>
+</ul>
+
+<p>Hence, a more complete picture would be:</p>
+
+<center><img src="detailed-design.png" width="390" height="429"></center>
+
+<p>Please take note of the following important points:</p>
+
+<ul>
+ <li><p>
+ an optional component can use either the high-level or base
+ API. This is the case of <b>ftglyph</b> in the above picture.
+ </p></li>
+
+ <li><p>
+ some optional component can use module-specific interfaces
+ ignored by the base layer. In the above example, <b>ftmm</b>
+ directly accesses the Type 1 module to set/query data
+ </p></li>
+
+ <li><p>
+ a replacable component can provide a function of the high-level
+ API. For example, <b>ftinit</b> provides <tt>FT_Init_FreeType</tt>
+ to client applications.
+ </p></li>
+</ul>
+
+</td></tr></table></center>
+</body>
+</html>
--- /dev/null
+++ b/docs/design/design-3.html
@@ -1,0 +1,263 @@
+<html>
+<head><title>The Design of FreeType 2 - Public Objects</title>
+<basefont face="Georgia, Arial, Helvetica, Geneva">
+<style content="text/css">
+ P { text-align=justify }+ H1 { text-align=center }+ H2 { text-align=center }+ LI { text-align=justify }+</style>
+</head>
+<body text=#000000 bgcolor=#ffffff>
+
+<center><table width="500"><tr><td>
+
+<center><h1>The Design of FreeType 2</h1></center>
+
+<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
+<h1>II. Public Objects and Classes</h1>
+</td></tr></table>
+
+<p>We will now detail the abstractions provided by FreeType 2 to
+ client applications to manage font files and data. As you would
+ normally expect, these are implemented through objects/classes.</p>
+
+<h2>1. Object Orientation in FreeType 2:</h2>
+
+<p>Though written in ANSI 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 FT2 source code:</p>
+
+<ol>
+ <li><p>
+ each object type/class has 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/class.</p>
+
+ <p>Consider that we need to manage objects of type "foo" in FT2.
+ We would define the following structure and handle types as
+ follow:</p>
+
+ <pre><font color="blue">
+ typedef struct FT_FooRec_* FT_Foo;
+
+ typedef struct FT_FooRec_
+ {+ // fields for the "foo" class
+ ...
+
+ } FT_FooRec;
+ </font></pre>
+
+ <p>As a convention, handle types use simple but meaningful identifiers
+ beginning with "FT_", as in "FT_Foo", while structures use the same
+ name with a "Rec" suffix appended to it ('Rec' is short for "record").+ <em>Note that each class type has a corresponding handle type</em>.
+ </p>
+
+
+ <li><p>
+ class derivation is achieved internally by wrapping base class
+ structures into new ones. As an example, let's define a "foobar"
+ class that is derived from "foo". We would do something like:</p>
+
+ <pre><font color="blue">
+ 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;
+ </font></pre>
+
+ <p>As you can see, we ensure that a "foobar" object is also a "foo"
+ 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 a <tt>FT_FooBar</tt> handle also points to a "foo" object
+ and can be typecasted to <tt>FT_Foo</tt>. Similarly, when the
+ library handles a <tt>FT_Foo</tt> handle to client applications,
+ the object can be really implemented as a <tt>FT_FooBar</tt> or any
+ derived class from "foo".</p>
+
+ </p></li>
+</ul>
+
+<p>Note that in the following sections of this chapter, we will refer
+ to "the <tt>FT_Foo</tt> class" to indicate the type of objects
+ handled through <tt>FT_Foo</tt> pointers, be they implemented as
+ "foo" or "foobar".</p>
+
+<hr>
+
+<h2>2. The <em><b>FT_Library</b></em> class:</h2>
+
+<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 "parent" of all other objects in FreeType 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 <tt>FT_Init_FreeType</tt>,
+ in order to create a new library object, ready to be used for
+ further action.</p>
+
+<p>Another alternative is to create a fresh new library instance
+ by calling the function <tt>FT_New_Library</tt>, defined in the
+ <tt><freetype/ftmodule.h></tt> public header file. This
+ function will however return an "empty" library instance with
+ no module registered in it. You can "install" modules in the
+ instance by calling <tt>FT_Add_Module</tt> 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 and/or
+ computed is determined at build time, and depends on the content
+ of the <b>ftinit</b> 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 <tt>FT_Done_FreeType</tt>.</p>
+<hr>
+
+<h2>3. The <em><b>FT_Face</b></em> class:</h2>
+
+<p>A face object corresponds to a single <em>font face</em>, i.e.
+ a specific typeface with a specific style. For example, "Arial"
+ and "Arial Italic" correspond to two distinct faces.</p>
+
+<p>A face object is normally created through <tt>FT_New_Face</tt>.
+ This function takes the following parameters: a <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),
+ as well as the address of a <tt>FT_Face</tt> handle. It returns
+ an error code:</p>
+
+<pre><font color="blue">
+ FT_Error FT_New_Face( FT_Library library,
+ const char* filepathname,
+ FT_Long face_index,
+ FT_Face *face );
+</font></pre>
+
+<p>in case of success, the function will return 0, and the handle
+ pointed to by the "face" parameter will be 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
+ <tt>FT_FaceRec</tt> definition in the FT2 API Reference.</p>
+
+<hr>
+
+<h2>4. The <em><b>FT_Size</b></em> class:</h2>
+
+<p>Each <tt>FT_Face</tt> object <em>has</em> one or more <tt>FT_Size</tt>
+ objects. A <em>size object</em> is used to store data specific to a
+ given character width and height. Each newly created face object
+ has one size, which is directly accessible as <tt>face->size</tt>.</p>
+
+<p>The content of a size object can be changed by calling either
+ <tt>FT_Set_Pixel_Sizes</tt> or <tt>FT_Set_Char_Size</tt>.</p>
+
+<p>A new size object can be created with <tt>FT_New_Size</tt>, and
+ destroyed manually with </tt>FT_Done_Size</tt>. Note that typical
+ applications don't need to do this normally: they tend 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 <tt>FT_SizeRec</tt>. 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 table that
+ results from the execution of the "cvt" program in a <tt>TT_Size</tt>,
+ while the Type 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 :-)</p>
+
+<hr>
+
+<h2>5. The <em><b>FT_GlyphSlot</b></em> class:</h2>
+
+<p>The purpose of a glyph slot 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
+ explicitely provide data to compute a slot's maximum size.</p>
+
+<p>Another reason for glyph slots is that they're also used to hold
+ format-specific hints for a given glyphs has well as all other
+ data necessary to correctly load the glyph.</p>
+
+<p>The base <tt>FT_GlyphSlotRec</tt> structure only presents glyph
+ metrics and images to client applications, while 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 Type1-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 T1 hinter is used.</p>
+
+<p>Finally, each face object has a single glyph slot, that is directly
+ accessible as <tt>face->glyph</tt>.</p>
+
+<hr>
+
+<h2>6. The <em><b>FT_CharMap</b></em> class:</h2>
+
+<p>Finally, the <tt>FT_CharMap</tt> type is used as a handle to
+ character map objects, or "charmaps" to be brief. A charmap is
+ simply some sort of table or dictionary which is used 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 ugly "standards".</p>
+
+<p>Each <tt>FT_CharMap</tt> object contains a "platform" and an "encoding"
+ field used to identify precisely the character repertoire corresponding
+ to it.</p>
+
+<p>Each font format provides its own derivative of <tt>FT_CharMapRec</tt>
+ and thus needs to implement these objects.</p>
+
+<hr>
+<h2>7. Objects relationships:</h2>
+
+<p>The following diagram summarizes what we just said regarding the
+ public objects managed by the library, as well as explicitely
+ describes their relationships:</p>
+
+<p>Note that this picture will be updated at the end of the next
+ chapter, related to <em>internal objects</em>.</p>
+
+</td></tr></table></center>
+</body>
+</html>
--- /dev/null
+++ b/docs/design/design-4.html
@@ -1,0 +1,289 @@
+<html>
+<head><title>The Design of FreeType 2 - Internal Objects</title>
+<basefont face="Georgia, Arial, Helvetica, Geneva">
+<style content="text/css">
+ P { text-align=justify }+ H1 { text-align=center }+ H2 { text-align=center }+ LI { text-align=justify }+</style>
+</head>
+<body text=#000000 bgcolor=#ffffff>
+
+<center><table width="500"><tr><td>
+
+<center><h1>The Design of FreeType 2</h1></center>
+
+<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
+<h1>III. Internal Objects and Classes</h1>
+</td></tr></table>
+
+<p>Let's have a look now at the <em>internal</em> objects that FreeType 2
+ uses, i.e. those not directly available to client applications, and
+ let's see how they fit in the picture.</p>
+
+<h2>1. Memory management:</h2>
+
+<p>All memory management operations are performed through three specific
+ routines of the base layer, namely: <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.</p>
+
+<p>The latter is a pointer to a simple object used to describe the current
+ memory pool/manager to use. It contains a simple table of
+ alloc/realloc/free functions. A memory manager is created at
+ library initialisation time by <tt>FT_Init_FreeType</tt> by calling
+ the function <tt>FT_New_Memory</tt> provided by the <b>ftsystem</b>
+ component.</p>
+
+<p>By default, this manager uses the ANSI <tt>malloc</tt>, <tt>realloc</tt>
+ and <tt>free</tt> functions. However, as <b>ftsystem</b> 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
+ <tt>FT_MemoryRec</tt> is located in the public file
+ <tt><freetype/ftsystem.h></tt>.
+ </p></li>
+
+ <li><p>
+ call <tt>FT_New_Library</tt> to create a new library instance using
+ your custom memory manager. This new library is "virgin" and doesn't
+ contain any registered modules.
+ </p></li>
+
+ <li><p>
+ Register the set of default modules by calling the function
+ <tt>FT_Add_Default_Modules</tt> provided by the <b>ftinit</b>
+ component, or manually register your drivers by repeatedly
+ calling <tt>FT_Add_Module</tt>.
+ </p></li>
+</ol>
+
+
+<hr>
+<h2>2. Input streams:</h2>
+
+<p>Font files are always read through <tt>FT_Stream</tt> objects. The
+ definition of <tt>FT_StreamRec</tt> is located in the public file
+ <tt><freetype/ftsystem.h></tt>, which allows client developers
+ to provide their own implementation of streams if they wish so.</p>
+
+<p>The function <tt>FT_New_Face</tt> will always automatically create a
+ new stream object from the C pathname given as its second argument.
+ This is achieved by calling the function <tt>FT_New_Stream</tt> provided
+ by the <b>ftsystem</b> 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 <tt>fopen</tt>,
+ <tt>fseek</tt>, <tt>fread</tt> calls. However, the Unix build of
+ FreeType 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 "frames", and temorarily buffered adequately through typical
+ seek/read operations.</p>
+
+<p>The FreeType stream sub-system also implements extremely efficient
+ algorithms to very quickly load structures from font files while
+ ensure complete safety in the case of "broken file".</p>
+
+<p>The function <tt>FT_New_Memory_Face</tt> can be used
+ to directly create/open a <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 <tt>FT_Open_Face</tt>, 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 <tt>FT_Done_Face</tt>. Generally speaking, it's certainly
+ <em>not a good idea</em> to keep numerous <tt>FT_Face</tt> objects
+ opened.</p>
+
+<hr>
+<h2>3. Modules:</h2>
+
+<p>A FreeType 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 and public structure named <tt>FT_Module_Class</tt>,
+ defined in <tt><freetype/ftmodule.h></tt>, and is detailed
+ heavily later in this document:</p>
+
+<p>You need a pointer to a <tt>FT_Module_Class</tt> structure when
+ calling <tt>FT_Add_Module</tt>, whose declaration is:</p>
+
+<pre><font color="blue">
+ FT_Error FT_Add_Module( FT_Library library,
+ const FT_Module_Class* clazz );
+</font></pre>
+
+<p>Calling this function will do the following:</p>
+
+<ul>
+ <li><p>
+ it will check if the library already holds a module object corresponding
+ to the same module name as the one found in the <tt>FT_Module_Class</tt>.
+ </p></li>
+
+ <li><p>
+ it this is the case, it will compare the module version number to see
+ if 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, the function returns immediately. Similarly, it checks
+ that the version of FreeType 2 that is running is correct compared
+ to the one required by the module.
+ </p></li>
+
+ <li><p>
+ it creates 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>
+ when a module initializer is present in the module class, it will
+ be called to complete the module object's initialisation.
+ </p></li>
+
+ <li><p>
+ the new module is added to the library's list of "registered"
+ modules. In case of an upgrade, the previous module object is
+ simply destroyed.
+ </p></li>
+
+</ul>
+
+<p>Note that this function doesn't return a <tt>FT_Module</tt> handle,
+ given that module objects are completely internal to the library
+ (and client applications shouldn't normally mess with them :-)</p>
+
+<p>Finally, it's important to understand that FreeType 2 recognizes
+ and manages several kinds of modules. These will be explained in
+ more details later in this document, but we'll list for now the
+ following types:</p>
+
+<ul>
+ <li><p>
+ <b>renderer</b> modules are used to convert native glyph images to
+ bitmaps/pixmaps. FT2 comes with two renderer modules
+ by default: one to generate monochrome bitmaps, the other to generate
+ high-quality anti-aliased pixmaps.
+ </p></li>
+
+ <li><p>
+ <b>font driver</b> modules are used to support one or more specific
+ font format. Typically, each font driver provides a specific
+ implementation/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>
+ <b>helper</b> modules are used to contain code that is shared
+ by several font drivers. For example, the <b>sfnt</b> module is
+ used to parse and manage tables found in SFNT-based font formats;
+ it is then used by both the TrueType and OpenType font drivers.
+ </p></li>
+
+ <li><p>
+ finally, the <b>auto-hinter</b> 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 (that depends on the original font file's
+ format). This means that all face objects are destroyed when a module
+ is removed/unregistered from a library instance (typically by calling
+ <tt>FT_Remove_Module</tt>).</p>
+
+<font color="red">
+<p>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>
+</font>
+
+<hr>
+<h2>4. Libraries:</h2>
+
+<p>And we now come back to our well-known <tt>FT_Library</tt> objects.
+ From what have been said here, we already know that a library
+ instance owns at least the following:</p>
+
+<ul>
+ <li><p>
+ a memory manager object (<tt>FT_Memory</tt>), used for all
+ allocation/releases within the instance.
+ </p></li>
+
+ <li><p>
+ a list of <tt>FT_Module</tt> objects, corresponding to the
+ "installed" or "registered" modules of the instance. This
+ list can be changed at any time through <tt>FT_Add_Module</tt>
+ and <tt>FT_Remove_Module</tt>.
+ </p></li>
+
+ <li><p>
+ finally, remember that face objects are owner by font drivers
+ that are themselves modules owned by the library.
+ </p></li>
+</ul>
+
+<p>There is however another object owned by the library instance that
+ hasn't been described until now, and it's the <em>raster pool</em>.</p>
+
+<p>The <b>raster pool</b> is simply a block of memory of fixed size
+ that is used internally as a "scratch area" for various memory-hungry
+ transient operations. For example, it is used by each renderer when
+ converting a vectorial glyph outline into a bitmap (actually,
+ that's where its name comes from :-).</p>
+
+<p>The advantage of using a raster pool comes from the fact that it
+ allows us to completely avoid memory allocation during certain
+ memory-intensive though common transient operations (like
+ glyph bitmap generation), speeding up the overall process.</p>
+
+<p>The size of the raster pool is fixed at initialisation time
+ (it defaults to 16 Kb) and cannot be changed at run-time
+ (though we could fix this if there's a real need for that).</p>
+
+<p>When a transient operation needs more memory than the pool's
+ size, it can decide to either allocate a heap block as an
+ exceptional condition, or sub-divide recursively the task to
+ perform in order to never exceed the pool's threshold..</p>
+
+<p>This extremely memory-conservative behaviour is certainly one of
+ the keys to FreeType's performance in certain areas (most importantly
+ in glyph rendering / scanline-conversion ).</p>
+
+<hr>
+<h2>5. Summary</h2>
+
+<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 2's base design:</p>
+
+<center><img src="to-be-done.png" width="100" height="100"></center>
+
+</td></tr></table></center>
+</body>
+</html>
binary files a/docs/design/detailed-design.png b/docs/design/detailed-design.png differ