forked from minhngoc25a/freetype2
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
This commit is contained in:
David Turner
parent
7b028719d8
commit
691a9571dd
Binary file not shown.
|
Before Width: | Height: | Size: 990 B After Width: | Height: | Size: 2.0 KiB |
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
|
|
@ -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><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>
|
||||
|
|
@ -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><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 file not shown.
|
Before Width: | Height: | Size: 1.8 KiB After Width: | Height: | Size: 2.4 KiB |
Loading…
Reference in New Issue