ref: 60784a2200ad63293db4309ae5d8c72e826084dc
parent: cf4398a6f5b71230abb395a540a6db38a2296476
author: Werner Lemberg <wl@gnu.org>
date: Mon Oct 30 15:46:41 EST 2000
Formatting/correcting the first three parts of the design docs.
--- a/docs/design/design-1.html
+++ b/docs/design/design-1.html
@@ -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>
--- a/docs/design/design-2.html
+++ b/docs/design/design-2.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>
--- a/docs/design/design-3.html
+++ b/docs/design/design-3.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>
--- a/docs/ft2faq.html
+++ b/docs/ft2faq.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>