Server : Apache System : Linux server2.corals.io 4.18.0-348.2.1.el8_5.x86_64 #1 SMP Mon Nov 15 09:17:08 EST 2021 x86_64 User : corals ( 1002) PHP Version : 7.4.33 Disable Function : exec,passthru,shell_exec,system Directory : /usr/share/doc/freetype-devel/design/ |
<!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="http://freetype.org/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="http://freetype.org/index.html">Home</a>
</li>
<li class="primary">
<a href="http://freetype.org/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="http://freetype.org/developer.html">Development</a>
</li>
<li class="primary">
<a href="http://freetype.org/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>