/usr/share/doc/libfreetype6/design/design-4.html is in libfreetype6-dev 2.4.8-1ubuntu2.
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 354 355 356 357 358 359 360 361 | <!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 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-3.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-5.html">Next</a>
</td>
</tr>
</table>
</center>
<p><hr></p>
<table width="100%">
<tr bgcolor="#ccccee"><td>
<h1>
III. Internal Objects and Classes
</h1>
</td></tr>
</table>
<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>
<h2>
1. Memory management
</h2>
<p>All memory management operations are performed through three specific
routines of the base layer, namely: <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.</p>
<p>The latter is a pointer to a simple object used to describe the
current memory pool/manager. It contains a simple table of
alloc/realloc/free functions. A memory manager is created at library
initialization time by <tt>FT_Init_FreeType()</tt>, calling the function
<tt>FT_New_Memory()</tt> provided by the <tt>ftsystem</tt>
component.</p>
<p>By default, this manager uses the ANSI <tt>malloc()</tt>,
<tt>realloc()</tt>, and <tt>free()</tt> functions. 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 <tt>FT_MemoryRec</tt> is located in the public file
<tt><freetype/ftsystem.h></tt>.</p>
</li>
<li>
<p>Call <tt>FT_New_Library()</tt> 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
<tt>FT_Add_Default_Modules()</tt> provided by the <tt>ftinit</tt>
component, or manually register your drivers by repeatedly
calling <tt>FT_Add_Module()</tt>.</p>
</li>
</ol>
<hr>
<h2>
2. Input streams
</h2>
<p>Font files are always read through <tt>FT_Stream</tt> objects. The
definition of <tt>FT_StreamRec</tt> is located in the public file
<tt><freetype/ftsystem.h></tt>, which allows client developers to
provide their own implementation of streams if they wish so.</p>
<p>The function <tt>FT_New_Face()</tt> will always automatically create
a new stream object from the C pathname given as its second
argument. This is achieved by calling the 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
<tt>fopen()</tt>, <tt>fseek()</tt>, and <tt>fread()</tt> calls.
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/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 <tt>FT_New_Memory_Face()</tt> can be used to directly
create/open a <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 <tt>FT_Open_Face()</tt>, 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
<tt>FT_Done_Face()</tt>. Generally speaking, it is certainly
<em>not</em> a good idea to keep numerous <tt>FT_Face</tt> objects
opened.</p>
<hr>
<h2>
3. Modules
</h2>
<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 <tt>FT_Module_Class</tt>, defined in
<tt><freetype/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 <tt>FT_Add_Module()</tt>, whose declaration is:</p>
<font color="blue"><pre>
FT_Error FT_Add_Module( FT_Library library,
const FT_Module_Class* clazz );</pre>
</font>
<p>Calling this function will do the following:</p>
<ul>
<li>
<p>It will 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, it will 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, the function returns immediately. Similarly,
it checks that the version of FreeType 2 that is running is
correct compared to the one required by the module.</p>
</li>
<li>
<p>It creates 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, it will
be called to complete the module object's initialization.</p>
</li>
<li>
<p>The new module is added to the library's list of "registered"
modules. In case of an upgrade, the previous module object is
simply destroyed.</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 in more details later in this document, but we will list for
now the following types:</p>
<ul>
<li>
<p><em>Renderer</em> modules are used to convert native glyph images
to bitmaps/pixmaps. FreeType 2 comes with two renderer modules
by default: one to generate monochrome bitmaps, the other to
generate high-quality 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/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 and
OpenType font 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/unregistered from a library instance (typically by calling the
<tt>FT_Remove_Module()</tt> function).</p>
<p><em>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!</em></p>
<hr>
<h2>
4. Libraries
</h2>
<p>We now come back to our well-known <tt>FT_Library</tt> object. From
what have been said before, we already know that a library instance owns
at least the following:</p>
<ul>
<li>
<p>A memory manager object (<tt>FT_Memory</tt>), used for all
allocation/releases within the instance.</p>
</li>
<li>
<p>A list of <tt>FT_Module</tt> objects, corresponding to the
"installed" or "registered" modules of the instance. This list can
be changed at any time through <tt>FT_Add_Module()</tt> and
<tt>FT_Remove_Module()</tt>.</p>
</li>
<li>
<p>Remember that face objects are owner by font drivers that are
themselves modules owned by the library.</p>
</li>
</ul>
<p>There is however another object owned by the library instance that
hasn't been described yet: the <em>raster pool</em>.</p>
<p>The <em>raster pool</em> is simply a block of memory of fixed size
that is used internally as a "scratch area" for various memory-hungry
transient operations, avoiding memory allocation. For example, it is
used by each renderer when converting a vectorial glyph outline into a
bitmap (actually, that's where its name comes from :-).</p>
<p>The size of the raster pool is fixed at initialisation time (it
defaults to 16kByte) and cannot be changed at run-time (though we could
fix this if there is a real need for that).</p>
<p>When a transient operation needs more memory than the pool's size, it
can decide to either allocate a heap block as an exceptional condition,
or sub-divide recursively the task to perform in order to never exceed
the pool's threshold.</p>
<p>This extremely memory-conservative behaviour is certainly one of the
keys to FreeType's performance in certain areas (most importantly in
glyph rendering/scanline-conversion).</p>
<hr>
<h2>
5. Summary
</h2>
<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>
<p><hr></p>
<center>
<table width="100%"
border=0
cellpadding=5>
<tr bgcolor="#CCFFCC" valign=center>
<td align=center
width="30%">
<a href="design-3.html">Previous</a>
</td>
<td align=center
width="30%">
<a href="index.html">Contents</a>
</td>
<td align=center
width="30%">
<a href="design-5.html">Next</a>
</td>
</tr>
</table>
</center>
</td></tr>
</table>
</center>
</body>
</html>
|