/usr/share/doc/libfreetype6/design/design-3.html is in libfreetype6-dev 2.5.2-1ubuntu2.8.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 | <!doctype html public "-//w3c//dtd html 4.0 transitional//en"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<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</title>
</head>
<body text="#000000"
bgcolor="#FFFFFF"
link="#0000EF"
vlink="#51188E"
alink="#FF0000">
<h1 align=center>
The design of FreeType 2
</h1>
<h3 align=center>
Copyright 1998-2000 David Turner (<a
href="mailto:david@freetype.org">david@freetype.org</a>)<br>
Copyright 2000, 2007 The FreeType Development Team (<a
href="mailto:devel@freetype.org">devel@freetype.org</a>)
</h3>
<center>
<table width="65%">
<tr><td>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC"
valign=center>
<td align=center
width="30%">
<a href="design-2.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-4.html">Next</a>
</td>
</tr>
</table>
</center>
<p><hr></p>
<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,
inherited from object-oriented programming, to make it easy to extend.
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>
<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>
<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
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>
<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>
<p>The following diagram summarizes what we have just said regarding the
public objects managed by the library, as well as explicitly describes
their relationships</p>
<center>
<img src="simple-model.png"
width=453 height=378
alt="Simple library model">
</center>
<p>Note that this picture will be updated at the end of the next
chapter, related to <em>internal objects</em>.</p>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC" valign=center>
<td align=center
width="30%">
<a href="design-2.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-4.html">Next</a>
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>
|