2000-10-30 21:46:41 +01:00
|
|
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"
|
|
|
|
|
"http://www.w3.org/TR/REC-html40/loose.dtd">
|
2000-10-26 01:42:02 +02:00
|
|
|
<html>
|
2000-10-30 21:46:41 +01:00
|
|
|
<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>
|
2000-10-26 01:42:02 +02:00
|
|
|
</head>
|
|
|
|
|
|
2000-10-30 21:46:41 +01:00
|
|
|
<body text="#000000"
|
|
|
|
|
bgcolor="#ffffff">
|
|
|
|
|
|
|
|
|
|
<h1 align=center>
|
|
|
|
|
The Design of FreeType 2
|
|
|
|
|
</h1>
|
|
|
|
|
|
|
|
|
|
<center>
|
|
|
|
|
<table width="75%">
|
|
|
|
|
<tr><td>
|
|
|
|
|
|
|
|
|
|
<table width="100%">
|
|
|
|
|
<tr bgcolor="#ccccee"><td>
|
|
|
|
|
<h1>
|
|
|
|
|
II. Public Objects and Classes
|
|
|
|
|
</h1>
|
|
|
|
|
</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
<h2>
|
|
|
|
|
1. Object Orientation in FreeType 2
|
|
|
|
|
</h2>
|
|
|
|
|
|
|
|
|
|
<p>Though written in ANSI C, the library employs a few techniques,
|
2000-10-31 21:42:18 +01:00
|
|
|
inherited from object-oriented programming, to make it easy to extend.
|
2000-10-30 21:46:41 +01:00
|
|
|
Hence, the following conventions apply in the FreeType 2 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
|
|
|
|
|
FreeType 2. We would define the following structure and handle
|
|
|
|
|
types as follows:</p>
|
|
|
|
|
|
|
|
|
|
<font color="blue"><pre>
|
|
|
|
|
typedef struct FT_FooRec_* FT_Foo;
|
|
|
|
|
|
|
|
|
|
typedef struct FT_FooRec_
|
|
|
|
|
{
|
|
|
|
|
// fields for the "foo" class
|
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
} 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>
|
|
|
|
|
|
|
|
|
|
<font color="blue"><pre>
|
|
|
|
|
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;</pre>
|
|
|
|
|
</font>
|
|
|
|
|
|
|
|
|
|
<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 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>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 <tt>FT_Library</tt> 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 <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>
|
|
|
|
|
|
|
|
|
|
<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>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
|
|
|
|
|
<tt>ftinit</tt> 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 <tt>FT_Face</tt> 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>
|
|
|
|
|
|
2000-10-31 21:42:18 +01:00
|
|
|
<p>A face object is normally created through <tt>FT_New_Face()</tt>.
|
2000-10-30 21:46:41 +01:00
|
|
|
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>
|
|
|
|
|
|
|
|
|
|
<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>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>
|
|
|
|
|
|
|
|
|
|
<p>Note that the face object contains several fields used to describe
|
2000-10-31 21:42:18 +01:00
|
|
|
global font data that can be accessed directly by client applications.
|
2000-10-30 21:46:41 +01:00
|
|
|
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>
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
|
|
|
|
|
<h2>
|
|
|
|
|
4. The <tt>FT_Size</tt> 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 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>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>
|
|
|
|
|
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>
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
|
|
|
|
|
<h2>
|
|
|
|
|
5. The <tt>FT_GlyphSlot</tt> 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 explicitly provide
|
|
|
|
|
data to compute a slot's maximum size.</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>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 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>Finally, each face object has a single glyph slot that is directly
|
|
|
|
|
accessible as <tt>face->glyph</tt>.</p>
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
|
|
|
|
|
<h2>
|
|
|
|
|
6. The <tt>FT_CharMap</tt> class
|
|
|
|
|
</h2>
|
|
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
<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>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>
|
2000-10-26 01:42:02 +02:00
|
|
|
|
2000-10-30 21:46:41 +01:00
|
|
|
<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>
|
2000-10-26 01:42:02 +02:00
|
|
|
|
2000-10-30 21:46:41 +01:00
|
|
|
<center>
|
|
|
|
|
<image alt="to be added">
|
|
|
|
|
</center>
|
2000-10-26 01:42:02 +02:00
|
|
|
|
2000-10-30 21:46:41 +01:00
|
|
|
<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>
|
2000-10-26 01:42:02 +02:00
|
|
|
</body>
|
|
|
|
|
</html>
|
