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
author: David Turner <david@freetype.org> 2000-10-25 23:42:02 +0000
committer: David Turner <david@freetype.org> 2000-10-25 23:42:02 +0000
commit: 4cd68a09c52289fd27ca556e7d83055b51c3f295 (patch)
tree: 9766a91f26f0d2c615616248f1c2cabf90187412 /docs
parent: 6a4253388bee1f9be9ab6787a74b2217f1869712 (diff)
download: freetype2-4cd68a09c52289fd27ca556e7d83055b51c3f295.tar.gz
6 files changed, 746 insertions, 0 deletions
diff --git a/docs/design/basic-design.png b/docs/design/basic-design.png
index 881e1a8de..5acdccc54 100644
--- a/docs/design/basic-design.png
+++ b/docs/design/basic-design.png
diff --git a/docs/design/design-1.html b/docs/design/design-1.html
new file mode 100644
index 000000000..604fbc873
--- /dev/null
+++ b/docs/design/design-1.html
@@ -0,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>
diff --git a/docs/design/design-2.html b/docs/design/design-2.html
new file mode 100644
index 000000000..fba5c9887
--- /dev/null
+++ b/docs/design/design-2.html
@@ -0,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>
diff --git a/docs/design/design-3.html b/docs/design/design-3.html
new file mode 100644
index 000000000..83900f278
--- /dev/null
+++ b/docs/design/design-3.html
@@ -0,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>&lt;freetype/ftmodule.h&gt;</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-&gt;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-&gt;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>
diff --git a/docs/design/design-4.html b/docs/design/design-4.html
new file mode 100644
index 000000000..0a0c63338
--- /dev/null
+++ b/docs/design/design-4.html
@@ -0,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>&lt;freetype/ftsystem.h&gt;</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>&lt;freetype/ftsystem.h&gt;</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>&lt;freetype/ftmodule.h&gt;</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>
diff --git a/docs/design/detailed-design.png b/docs/design/detailed-design.png
index 174c1a967..d27f761a1 100644
--- a/docs/design/detailed-design.png
+++ b/docs/design/detailed-design.png
author	David Turner <david@freetype.org>	2000-10-25 23:42:02 +0000
committer	David Turner <david@freetype.org>	2000-10-25 23:42:02 +0000
commit	4cd68a09c52289fd27ca556e7d83055b51c3f295 (patch)
tree	9766a91f26f0d2c615616248f1c2cabf90187412 /docs
parent	6a4253388bee1f9be9ab6787a74b2217f1869712 (diff)
download	freetype2-4cd68a09c52289fd27ca556e7d83055b51c3f295.tar.gz