Formatting/correcting the first three parts of the design docs.
This commit is contained in:
Werner Lemberg
parent
cf4398a6f5
commit
60784a2200
@ -1,82 +1,102 @@
|
||||
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
|
||||
"http://www.w3.org/TR/REC-html40/loose.dtd">
|
||||
<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>
|
||||
<meta http-equiv="Content-Type"
|
||||
content="text/html; charset=iso-8859-1">
|
||||
<meta name="Author"
|
||||
content="David Turner">
|
||||
<title>The Design of FreeType 2 - Introduction</title>
|
||||
</head>
|
||||
<body text=#000000 bgcolor=#ffffff>
|
||||
|
||||
<center><table width="500"><tr><td>
|
||||
<body text="#000000"
|
||||
bgcolor="#ffffff">
|
||||
|
||||
<center><h1>The Design of FreeType 2</h1></center>
|
||||
<h1 align=center>
|
||||
The Design of FreeType 2
|
||||
</h1>
|
||||
|
||||
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
|
||||
<h1>Introduction</h1>
|
||||
</td></tr></table>
|
||||
<center>
|
||||
<table width="75%">
|
||||
<tr><td>
|
||||
|
||||
<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>
|
||||
<table width="100%">
|
||||
<tr bgcolor="#ccccee"><td>
|
||||
<h1>
|
||||
Introduction
|
||||
</h1>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
<p>Before anything else, it is important to understand the <em>purpose</em>
|
||||
of this library, i.e. why it has been written:</p>
|
||||
<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 how FreeType 2 is organized, in order to let them
|
||||
extend, customize, and debug it.</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>
|
||||
<p>Before anything else, it is important to understand the
|
||||
<em>purpose</em> of this library, i.e., why it has been written:</p>
|
||||
|
||||
<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>
|
||||
<ul>
|
||||
<li>
|
||||
<p>It allows client applications to <em>access font files easily</em>,
|
||||
wherever they could be stored, and as independently of the font format
|
||||
as possible.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>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>It allows easy <em>retrieval of individual glyph data</em>
|
||||
(metrics, images, name, anything else).</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><em>Access to font format-specific "features"</em> whenever
|
||||
possible (e.g. SFNT tables, Multiple Masters, OpenType Layout tables,
|
||||
etc.).</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<li><p>to allow easy <em>retrieval of individual glyph data</em>
|
||||
(metrics, images, name, anything else)</p></li>
|
||||
<p>Its design has also severely been influenced by the following
|
||||
requirements:</p>
|
||||
|
||||
<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>
|
||||
<ul>
|
||||
<li>
|
||||
<p><em>High portability</em>. 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><em>Extendability</em>. New features should be added with the
|
||||
least modifications in the library's code base. This requirement
|
||||
induces an extremely simple design where nearly all operations are
|
||||
provided by modules.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p><em>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><em>Compactness</em> and <em>efficiency</em>. The primary target
|
||||
for this library are embedded systems with low cpu and memory
|
||||
resources.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>its design has also severely been influenced by the following
|
||||
requirements:</p>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<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 initialization & compilation to your needs.</p>
|
||||
|
||||
<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>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@ -1,112 +1,129 @@
|
||||
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
|
||||
"http://www.w3.org/TR/REC-html40/loose.dtd">
|
||||
<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>
|
||||
<meta http-equiv="Content-Type"
|
||||
content="text/html; charset=iso-8859-1">
|
||||
<meta name="Author"
|
||||
content="David Turner">
|
||||
<title>The Design of FreeType 2 - Basic Design</title>
|
||||
</head>
|
||||
<body text=#000000 bgcolor=#ffffff>
|
||||
|
||||
<center><table width="500"><tr><td>
|
||||
<body text="#000000"
|
||||
bgcolor="#ffffff">
|
||||
|
||||
<center><h1>The Design of FreeType 2</h1></center>
|
||||
<h1 align=center>
|
||||
The Design of FreeType 2
|
||||
</h1>
|
||||
|
||||
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
|
||||
<h1>I. Components and APIs</h1>
|
||||
</td></tr></table>
|
||||
<center>
|
||||
<table width="75%">
|
||||
<tr><td>
|
||||
|
||||
<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>
|
||||
<table width="100%">
|
||||
<tr bgcolor="#ccccee"><td>
|
||||
<h1>
|
||||
I. Components and APIs
|
||||
</h1>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<p>A first brief description of this system of components could be:</p>
|
||||
|
||||
<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>
|
||||
<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 which 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>
|
||||
<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>
|
||||
<center>
|
||||
<img src="basic-design.png"
|
||||
width="394" height="313"
|
||||
alt="Basic FreeType design">
|
||||
</center>
|
||||
|
||||
<p>Now, a few additional things must be added to complete this picture:</p>
|
||||
<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>
|
||||
<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 <tt>ftsystem</tt> component, which is in
|
||||
charge of implementing memory management & input stream access, as
|
||||
well as <tt>ftinit</tt>, which is in charge of library initialization
|
||||
(i.e. implementing the <tt>FT_Init_FreeType()</tt> function).</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 <tt>ftglyph</tt> 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
|
||||
<tt>ftmm</tt> 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> modules both use the routines provided by the
|
||||
<tt>sfnt</tt> module).</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<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>
|
||||
<p>Hence, a more complete picture would be:</p>
|
||||
|
||||
<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>
|
||||
<center>
|
||||
<img src="detailed-design.png"
|
||||
width="390" height="429"
|
||||
alt="Detailed FreeType design">
|
||||
</center>
|
||||
|
||||
<p>Hence, a more complete picture would be:</p>
|
||||
<p>Please take note of the following important points:</p>
|
||||
|
||||
<center><img src="detailed-design.png" width="390" height="429"></center>
|
||||
<ul>
|
||||
<li>
|
||||
<p>An optional component can use either the high-level or base API.
|
||||
This is the case of <tt>ftglyph</tt> in the above picture.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Some optional components can use module-specific interfaces ignored
|
||||
by the base layer. In the above example, <tt>ftmm</tt> 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, <tt>ftinit</tt> provides
|
||||
<tt>FT_Init_FreeType()</tt> to client applications.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<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>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@ -1,263 +1,293 @@
|
||||
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
|
||||
"http://www.w3.org/TR/REC-html40/loose.dtd">
|
||||
<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>
|
||||
<meta http-equiv="Content-Type"
|
||||
content="text/html; charset=iso-8859-1">
|
||||
<meta name="Author"
|
||||
content="David Turner">
|
||||
<title>The Design of FreeType 2 - Public Objects</title>
|
||||
</head>
|
||||
<body text=#000000 bgcolor=#ffffff>
|
||||
|
||||
<center><table width="500"><tr><td>
|
||||
<body text="#000000"
|
||||
bgcolor="#ffffff">
|
||||
|
||||
<center><h1>The Design of FreeType 2</h1></center>
|
||||
<h1 align=center>
|
||||
The Design of FreeType 2
|
||||
</h1>
|
||||
|
||||
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td>
|
||||
<h1>II. Public Objects and Classes</h1>
|
||||
</td></tr></table>
|
||||
<center>
|
||||
<table width="75%">
|
||||
<tr><td>
|
||||
|
||||
<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>
|
||||
<table width="100%">
|
||||
<tr bgcolor="#ccccee"><td>
|
||||
<h1>
|
||||
II. Public Objects and Classes
|
||||
</h1>
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
<h2>1. Object Orientation in FreeType 2:</h2>
|
||||
<p>We will now explain 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>
|
||||
|
||||
<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>
|
||||
<h2>
|
||||
1. Object Orientation in FreeType 2
|
||||
</h2>
|
||||
|
||||
<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>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 FreeType 2 source
|
||||
code:</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>
|
||||
<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>
|
||||
|
||||
<pre><font color="blue">
|
||||
typedef struct FT_FooRec_* FT_Foo;
|
||||
<p>Consider that we need to manage objects of type "foo" in
|
||||
FreeType 2. We would define the following structure and handle
|
||||
types as follows:</p>
|
||||
|
||||
typedef struct FT_FooRec_
|
||||
{
|
||||
// fields for the "foo" class
|
||||
...
|
||||
<font color="blue"><pre>
|
||||
typedef struct FT_FooRec_* FT_Foo;
|
||||
|
||||
} FT_FooRec;
|
||||
</font></pre>
|
||||
typedef struct FT_FooRec_
|
||||
{
|
||||
// fields for the "foo" class
|
||||
...
|
||||
|
||||
<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>
|
||||
} FT_FooRec;</pre>
|
||||
</font>
|
||||
|
||||
<p>As a convention, handle types use simple but meaningful
|
||||
identifiers beginning with <tt>FT_</tt>, as in <tt>FT_Foo</tt>,
|
||||
while structures use the same name with a <tt>Rec</tt> suffix
|
||||
appended to it ("Rec" is short for "record"). <em>Note that each
|
||||
class type has a corresponding handle type</em>.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Class derivation is achieved internally by wrapping base class
|
||||
structures into new ones. As an example, we define a "foobar" class
|
||||
that is derived from "foo". We would do something like:</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>
|
||||
<font color="blue"><pre>
|
||||
typedef struct FT_FooBarRec_* FT_FooBar;
|
||||
|
||||
<pre><font color="blue">
|
||||
typedef struct FT_FooBarRec_* FT_FooBar;
|
||||
typedef struct FT_FooBarRec_
|
||||
{
|
||||
// the base "foo" class fields
|
||||
FT_FooRec root;
|
||||
|
||||
typedef struct FT_FooBarRec_
|
||||
{
|
||||
// the base "foo" class fields
|
||||
FT_FooRec root;
|
||||
// fields proper to the "foobar" class
|
||||
...
|
||||
} FT_FooBarRec;</pre>
|
||||
</font>
|
||||
|
||||
// fields proper to the "foobar" class
|
||||
...
|
||||
<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>
|
||||
|
||||
} FT_FooBarRec;
|
||||
</font></pre>
|
||||
<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 returns 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>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
<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>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>
|
||||
|
||||
<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>
|
||||
<hr>
|
||||
|
||||
</p></li>
|
||||
</ul>
|
||||
<h2>
|
||||
2. The <tt>FT_Library</tt> class
|
||||
</h2>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<hr>
|
||||
<p>The library object is the <em>parent</em> 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>
|
||||
|
||||
<h2>2. The <em><b>FT_Library</b></em> class:</h2>
|
||||
<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
|
||||
actions.</p>
|
||||
|
||||
<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>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>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>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
|
||||
<tt>ftinit</tt> component. This process is explained in details later
|
||||
in this document.</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>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>
|
||||
|
||||
<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>
|
||||
<hr>
|
||||
|
||||
<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>
|
||||
<h2>
|
||||
3. The <tt>FT_Face</tt> class
|
||||
</h2>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<h2>3. The <em><b>FT_Face</b></em> class:</h2>
|
||||
<p>A face object is normally created through <tt>FT_New_Face()</tt>.
|
||||
This function takes the following parameters: an <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), and the address of a
|
||||
<tt>FT_Face</tt> handle. It returns an error code:</p>
|
||||
|
||||
<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>
|
||||
<font color="blue"><pre>
|
||||
FT_Error FT_New_Face( FT_Library library,
|
||||
const char* filepathname,
|
||||
FT_Long face_index,
|
||||
FT_Face* face );</pre>
|
||||
</font>
|
||||
|
||||
<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>
|
||||
<p>In case of success, the function will return 0, and the handle
|
||||
pointed to by the <tt>face</tt> parameter will be set to a non-NULL
|
||||
value.</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>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
|
||||
FreeType 2 API Reference.</p>
|
||||
|
||||
<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>
|
||||
<hr>
|
||||
|
||||
<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>
|
||||
<h2>
|
||||
4. The <tt>FT_Size</tt> class
|
||||
</h2>
|
||||
|
||||
<hr>
|
||||
<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>
|
||||
|
||||
<h2>4. The <em><b>FT_Size</b></em> class:</h2>
|
||||
<p>The contents 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>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>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 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>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>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>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>
|
||||
structure, 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>
|
||||
|
||||
<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>
|
||||
<hr>
|
||||
|
||||
<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>
|
||||
<h2>
|
||||
5. The <tt>FT_GlyphSlot</tt> class
|
||||
</h2>
|
||||
|
||||
<hr>
|
||||
<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>
|
||||
|
||||
<h2>5. The <em><b>FT_GlyphSlot</b></em> class:</h2>
|
||||
<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 explicitly provide
|
||||
data to compute a slot's maximum size.</p>
|
||||
|
||||
<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>Another reason for glyph slots is that they are also used to hold
|
||||
format-specific hints for a given glyphs as well as all other data
|
||||
necessary to correctly load the glyph.</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>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>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>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.
|
||||
|
||||
<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>
|
||||
The Type 1-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 Type 1 hinter is used.</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.
|
||||
<p>Finally, each face object has a single glyph slot that is directly
|
||||
accessible as <tt>face->glyph</tt>.</p>
|
||||
|
||||
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>
|
||||
<hr>
|
||||
|
||||
<p>Finally, each face object has a single glyph slot, that is directly
|
||||
accessible as <tt>face->glyph</tt>.</p>
|
||||
<h2>
|
||||
6. The <tt>FT_CharMap</tt> class
|
||||
</h2>
|
||||
|
||||
<hr>
|
||||
<p>The <tt>FT_CharMap</tt> type is used as a handle to character map
|
||||
objects, or <em>charmaps</em>. 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>
|
||||
|
||||
<h2>6. The <em><b>FT_CharMap</b></em> class:</h2>
|
||||
<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 encodings.</p>
|
||||
|
||||
<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>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>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 font format provides its own derivative of
|
||||
<tt>FT_CharMapRec</tt> and thus needs to implement these objects.</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>
|
||||
<hr>
|
||||
|
||||
<p>Each font format provides its own derivative of <tt>FT_CharMapRec</tt>
|
||||
and thus needs to implement these objects.</p>
|
||||
<h2>
|
||||
7. Objects relationships
|
||||
</h2>
|
||||
|
||||
<hr>
|
||||
<h2>7. Objects relationships:</h2>
|
||||
<p>The following diagram summarizes what we have just said regarding the
|
||||
public objects managed by the library, as well as explicitely describes
|
||||
their relationships</p>
|
||||
|
||||
<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>
|
||||
<center>
|
||||
<image alt="to be added">
|
||||
</center>
|
||||
|
||||
<p>Note that this picture will be updated at the end of the next
|
||||
chapter, related to <em>internal objects</em>.</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>
|
||||
</td></tr>
|
||||
</table>
|
||||
</center>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@ -119,7 +119,8 @@
|
||||
<table width="100%">
|
||||
<tr bgcolor="#CCCCEE"><td>
|
||||
<h2 align=center>
|
||||
<a name="general">General questions & answers</h2>
|
||||
<a name="general">General questions & answers
|
||||
</h2>
|
||||
</td></tr>
|
||||
<tr><td>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user