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
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=utf-8">
<meta http-equiv="Content-Style-Type"
content="text/css">
<meta http-equiv="Content-Script-Type"
content="text/javascript">
<meta name="description"
content="FreeType Documentation">
<meta name="Author"
content="David Turner">
<link rel="icon"
href="../../../image/favicon_-90.ico">
<link rel="shortcut icon"
href="../../../image/favicon_-90.ico">
<link rel="stylesheet"
type="text/css"
href="../../../css/freetype2_-90.css">
<script type="text/javascript"
src="../../../js/jquery-1.11.0.min.js">
</script>
<script type="text/javascript"
src="../../../js/jquery.ba-resize.min.js">
</script>
<script type="text/javascript"
src="../../../js/freetype2.js">
</script>
<title>FreeType Design / III</title>
</head>
<body>
<div id="top"
class="bar">
<h1><a href="../../../index.html">FreeType</a>
Design / III</h1>
</div>
<div id="wrapper">
<div class="colmask leftmenu">
<div class="colright">
<div class="col1wrap">
<div class="col1">
<!-- ************************************************** -->
<div id="internal-objects">
<h2>III. Internal Objects and Classes</h2>
<p>Let us have a look now at the <em>internal</em> objects
that FreeType 2 uses, i.e., those not directly
available to client applications, and see how they fit
into the picture.</p>
<h3 id="section-1">1. Memory Management</h3>
<p>Most memory management operations are performed through
three specific routines of the base
layer: <tt>FT_Alloc</tt>, <tt>FT_Realloc</tt>,
and <tt>FT_Free</tt>. Each one of these functions expects
a <tt>FT_Memory</tt> handle as its first parameter. Note,
however, that there exist more, similar variants for
specific purposes which we skip here for simplicity.</p>
<p><tt>FT_Memory</tt> is a pointer to a simple object that
describes the current memory pool or manager. It contains
a small table of alloc, realloc, and free functions. A
memory manager is created at library initialization time
by <tt>FT_Init_FreeType</tt>, calling the (internal)
function <tt>FT_New_Memory</tt> provided by
the <tt>ftsystem</tt> component.</p>
<p>By default, this manager uses the ANSI functions <tt>malloc</tt>,
<tt>realloc</tt>, and <tt>free</tt>. However,
as <tt>ftsystem</tt> is a replaceable part of the base
layer, a specific build of the library could provide a
different default memory manager.</p>
<p>Even with a default build, client applications are still
able to provide their own memory manager by not calling
<tt>FT_Init_FreeType</tt> but follow these simple
steps.</p>
<ol>
<li>
<p>Create a new <tt>FT_Memory</tt> object by hand. The
definition
of <a href="../reference/ft2-system_interface.html#ft_memoryrec"><code>FT_MemoryRec</code></a>
is located in the public header
file <tt>ftsystem.h</tt>.</p>
</li>
<li>
<p>Call <a href="../reference/ft2-module_management.html#ft_new_library"><code>FT_New_Library</code></a>
to create a new library instance using your custom
memory manager. This new library doesn't yet contain
any registered modules.</p>
</li>
<li>
<p>Register the set of default modules by calling the
function <a href="../reference/ft2-module_management.html#ft_add_default_modules"><code>FT_Add_Default_Modules</code></a>
provided by the <tt>ftinit</tt> component, or manually
register your drivers by repeatedly
calling <a href="../reference/ft2-module_management.html#ft_add_module"><code>FT_Add_Module</code></a>.</p>
</li>
</ol>
<h3 id="section-2">2. Input Streams</h3>
<p>Font files are always read through <tt>FT_Stream</tt>
objects. The definition
of <a href="../reference/ft2-system_interface.html#ft_streamrec"><code>FT_StreamRec</code></a>
is located in the public header file <tt>ftsystem.h</tt>,
which allows client developers to provide their own
implementation of streams if they wish so.</p>
<p>The
function <a href="../reference/ft2-base_interface.html#ft_new_face"><code>FT_New_Face</code></a>
always automatically creates a new stream object from the
C pathname given as its second argument. This is
achieved by calling the (internal) function
<tt>FT_New_Stream</tt> provided by the <tt>ftsystem</tt>
component. As the latter is replaceable, the
implementation of streams may vary greatly between
platforms.</p>
<p>As an example, the default implementation of streams is
located in the file <tt>src/base/ftsystem.c</tt> and uses
the ANSI functions <tt>fopen</tt>, <tt>fseek</tt>,
and <tt>fread</tt>. However, the Unix build of
FreeType 2 provides an alternative implementation
that uses memory-mapped files, when available on the host
platform, resulting in a significant access speed-up.</p>
<p>FreeType distinguishes between memory-based and
disk-based streams. In the first case, all data is
directly accessed in memory (e.g., ROM-based, write-only
static data, and memory-mapped files), while in the
second, portions of the font files are read in chunks
called <em>frames</em>, and temporarily buffered similarly
through typical seek and read operations.</p>
<p>The FreeType stream sub-system also implements extremely
efficient algorithms to very quickly load structures from
font files while ensuring complete safety in the case of a
‘broken file’.</p>
<p>The
function <a href="../reference/ft2-base_interface.html#ft_new_memory_face"><code>FT_New_Memory_Face</code></a>
can be used to directly create and open
an <tt>FT_Face</tt> object from data that is readily
available in memory (including ROM-based fonts).</p>
<p>Finally, in the case where a custom input stream is
needed, client applications can use the
function <a href="../reference/ft2-base_interface.html#ft_open_face"><code>FT_Open_Face</code></a>,
which can accept custom input streams. This may be useful
in the case of compressed or remote font files, or even
embedded font files that need to be extracted from certain
documents.</p>
<p>Note that each face owns a single stream, which is also
destroyed
by <a href="../reference/ft2-base_interface.html#ft_done_face"><code>FT_Done_Face</code></a>.</p>
<h3 id="section-3">3. Modules</h3>
<p>A FreeType 2 module is itself a piece of code.
However, the library creates a single <tt>FT_Module</tt>
object for each module that is registered
when <tt>FT_Add_Module</tt> is called.</p>
<p>The definition of <tt>FT_ModuleRec</tt> is not publicly
available to client applications. However,
each <em>module type</em> is described by a simple public
structure
named <a href="../reference/ft2-module_management.html#ft_module_class"><code>FT_Module_Class</code></a>,
defined in header file
<tt>ftmodule.h</tt>, and is described later in this
document.</p>
<p>You need a pointer to an <tt>FT_Module_Class</tt>
structure when
calling <a href="../reference/ft2-module_management.html#ft_add_module"><code>FT_Add_Module</code></a>.</p>
<pre>
FT_Error
FT_Add_Module( FT_Library library,
const FT_Module_Class* clazz );</pre>
<p>This function does the following tasks.</p>
<ul>
<li>
<p>Check whether the library already holds a module
object corresponding to the same module name as the
one found in <tt>FT_Module_Class</tt>.</p>
</li>
<li>
<p>If this is the case, compare the module version
number to see whether it is possible
to <em>upgrade</em> the module to a new version. If
the module class's version number is smaller than the
already installed one, return immediately. Similarly,
check that the version of FreeType 2 that is
running is correct compared to the one required by the
module.</p>
</li>
<li>
<p>Create a new <tt>FT_Module</tt> object, using data
and flags of the module class to determine its byte
size and how to properly initialize it.</p>
</li>
<li>
<p>If a module initializer is present in the module
class, call it to complete the module object's
initialization.</p>
</li>
<li>
<p>Add the new module to the library's list of
‘registered’ modules. In case of an
upgrade, destroy the previous module object.</p>
</li>
</ul>
<p>Note that this function doesn't return
an <tt>FT_Module</tt> handle, given that module objects
are completely internal to the library (and client
applications shouldn't normally mess with
them :-)</p>
<p>Finally, it is important to understand that
FreeType 2 recognizes and manages several kinds of
modules. These will be explained later on in this
document.</p>
<ul>
<li>
<p><em>Renderer</em> modules are used to convert native
glyph images to bitmaps or pixmaps. FreeType 2
comes with two renderer modules by default: one to
generate monochrome bitmaps, the other to generate
anti-aliased pixmaps.</p>
</li>
<li>
<p><em>Font driver</em> modules are used to support one
or more font formats. Typically, each font driver
provides a specific implementation or derivative
of <tt>FT_Face</tt>, <tt>FT_Size</tt>,
<tt>FT_GlyphSlot</tt>, as well
as <tt>FT_CharMap</tt>.</p>
</li>
<li>
<p><em>Helper</em> modules are shared by several font
drivers. For example, the <tt>sfnt</tt> module parses
and manages tables found in SFNT-based font formats;
it is then used by both the TrueType font and CFF
drivers.</p>
</li>
<li>
<p>Finally, the <em>auto-hinter</em> module has a
specific place in the library's design, as its role is
to process vectorial glyph outlines, independently of
their native font format, to produce optimal results
at small pixel sizes.</p>
</li>
</ul>
<p>Note that every <tt>FT_Face</tt> object is <em>owned</em>
by the corresponding font driver, depending on the
original font file's format. This means that all face
objects are destroyed when a module is removed or
unregistered from a library instance (typically by calling
the <a href="../reference/ft2-module_management.html#ft_remove_module"><code>FT_Remove_Module</code></a>
function). Because of this, you should always take care
that no <tt>FT_Face</tt> object is opened when you upgrade
or remove a module from a library, as this could cause
unexpected object deletion!</p>
<h3 id="section-4">4. Summary</h3>
<p>Finally, the following picture illustrates what has been
said in this section, as well as the previous, by
presenting the complete object graph of FreeType 2's
base design.</p>
<center>
<img src="library-model.png"
width="411"
height="405"
alt="Complete library model">
</center>
</div>
<!-- ************************************************** -->
<div class="updated">
<p>Last update: 13-Feb-2018</p>
</div>
</div>
</div>
<!-- ************************************************** -->
<div class="col2">
</div>
</div>
</div>
<!-- ************************************************** -->
<div id="TOC">
<ul>
<li class="funding">
<form action="https://www.paypal.com/cgi-bin/webscr"
method="post"
target="_top">
<input type="hidden"
name="cmd"
value="_s-xclick">
<input type="hidden"
name="hosted_button_id"
value="SK827YKEALMT4">
<input type="image"
src="https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif"
name="submit"
alt="PayPal - The safer, easier way to pay online!">
<img alt=""
border="0"
src="https://www.paypalobjects.com/de_DE/i/scr/pixel.gif"
width="1"
height="1">
</form>
</li>
<li class="primary">
<a href="../../../index.html">Home</a>
</li>
<li class="primary">
<a href="../../../index.html#news">News</a>
</li>
<li class="primary">
<a href="../index.html">Overview</a>
</li>
<li class="primary">
<a href="../documentation.html">Documentation</a>
</li>
<li class="primary">
<a href="../../../developer.html">Development</a>
</li>
<li class="primary">
<a href="../../../contact.html"
class="emphasis">Contact</a>
</li>
<li>
<!-- separate primary from secondary entries -->
</li>
<li class="secondary">
<a href="index.html">FreeType Design</a>
</li>
<li class="tertiary">
<a href="design-1.html">Introduction</a>
</li>
<li class="tertiary">
<a href="design-2.html">Components and APIs</a>
</li>
<li class="tertiary">
<a href="design-3.html">Public Objects and Classes</a>
</li>
<li class="tertiary">
<a href="design-4.html" class="current">Internal Objects and Classes</a>
</li>
<li class="tertiary">
<a href="design-5.html">Module Classes</a>
</li>
<li class="tertiary">
<a href="design-6.html">Interfaces and Services</a>
</li>
</ul>
</div>
</div> <!-- id="wrapper" -->
<div id="TOC-bottom">
</div>
</body>
</html>
|
