- minor formatting / testing in docmaker.pydavid-pic-changes
David Turner
25 years ago
parent
3c7c5da3bb
commit
6fbb95beb1
4 changed files with 669 additions and 3 deletions
|
After Width: | Height: | Size: 990 B |
|
After Width: | Height: | Size: 1.8 KiB |
@ -0,0 +1,639 @@ |
||||
<html> |
||||
<head><title>FreeType 2 - Modules</title> |
||||
<basefont face="Georgia, Arial, Helvetica, Geneva"> |
||||
<style content="text/css"> |
||||
P { text-align=justify } |
||||
H1 { text-align=center } |
||||
H2 { text-align=center } |
||||
LI { text-align=justify } |
||||
</style> |
||||
</head> |
||||
<body text=#000000 bgcolor=#ffffff> |
||||
|
||||
<center><table width="500"><tr><td> |
||||
|
||||
<center><h1>FreeType 2 Modules</h1></center> |
||||
|
||||
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
||||
<h1>Introduction</h1> |
||||
</td></tr></table> |
||||
|
||||
<p> |
||||
The purpose of this document is to present in great details the way |
||||
FreeType 2 uses and manages modules. Among other things, it answers |
||||
the following questions:</p> |
||||
|
||||
<ul> |
||||
<li><p> |
||||
what is a module, and what kind of modules are recognized |
||||
by the library? |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
how are modules registered and managed by the library? |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
how to write a new module, especially new font drivers? |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
how to select specific modules for a given build of the |
||||
library ? |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
how to compile modules as stand-alone DLLs / shared objects? |
||||
</p></li> |
||||
|
||||
</ul> |
||||
|
||||
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
||||
<h1>Overview</h1> |
||||
</td></tr></table> |
||||
|
||||
|
||||
<h3>1. Library design:</h3> |
||||
|
||||
<p>The design of the library is pretty basic:</p> |
||||
<ul> |
||||
<li><p> |
||||
client applications typically call the FreeType 2 high-level |
||||
API, whose functions are implemented in a single component |
||||
called the <em>Base Layer</em>. |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
depending on the context or the task, the base |
||||
layer then calls one or more modules to perform the |
||||
work. In most cases, the client application doesn't |
||||
need to know what module was called. |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
the base layer also contains a set of routines that are |
||||
used for generic things like memory allocation, list |
||||
processing, i/o stream parsing, fixed point computation, |
||||
etc.. these functions can also be called by a module |
||||
at any, and they form what is called the "low-level |
||||
base API". |
||||
</p></li> |
||||
</ul> |
||||
|
||||
<p>This is illustrated by the following graphics:</p> |
||||
|
||||
<center><img src="basic-design.png" width="312" height="312"></center> |
||||
|
||||
<p>Note that, however, FT2 comes with a set of <em>optional</em> |
||||
components that can be ommited from certain builds, and whose |
||||
purpose vary between two situations:</p> |
||||
|
||||
<ul> |
||||
<li><p> |
||||
some are located on top of the high-level API and provide |
||||
convenience functions that make certain things easier |
||||
for typical applications. They typically do not call |
||||
modules directly, though they can use the low level |
||||
base API for certain tasks.</p> |
||||
|
||||
<p>As an example, see the the <tt>ftglyph</tt> component |
||||
that is used to manipulate glyph images more conveniently |
||||
than the default API.</p> |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
some other components complement the base layer, by providing |
||||
additional routines. Most of them allow client applications |
||||
to access format-specific data.</p> |
||||
|
||||
<p>For example, the <tt>ftmm</tt> component provides high-level |
||||
functions to specify Multiple Master coordinates for MM Type 1 |
||||
fonts.</p> |
||||
</p></li> |
||||
</ul> |
||||
|
||||
<p>This is illustrated by the following graphics:</p> |
||||
|
||||
<center><img src="detailed-design.png" width="365" height="392"></center> |
||||
|
||||
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
||||
<h1>Module Classes</h1> |
||||
</td></tr></table> |
||||
|
||||
<p> |
||||
The library is capable of managing and using several kinds of |
||||
modules:</p> |
||||
|
||||
<ul> |
||||
<li><p> |
||||
<b>renderer</b> modules are used to convert scalable glyph images |
||||
to bitmaps. FreeType 2 comes by default with two of them:</p> |
||||
|
||||
<center><table cellpadding=5><tr valign=top><td> |
||||
<p><b><tt>raster1</tt></b></p> |
||||
</td><td> |
||||
<p>supports the conversion of vectorial outlines (described by a |
||||
<tt>FT_Outline</tt> object) to <em>monochrome</em> bitmaps. |
||||
</td></tr><tr valign=top><td></p> |
||||
|
||||
<p><b><tt>smooth</tt></b></p> |
||||
</td><td> |
||||
<p>supports the conversion of the same outlines to high-quality |
||||
<em>anti-aliased</em> pixmaps.</p> |
||||
</td></tr></table></center> |
||||
|
||||
|
||||
<p>The specification and interface of renderers is described in |
||||
details within this document.</p> |
||||
|
||||
<p>Note that most font formats use <tt>FT_Outline</tt> objects |
||||
to describe scalable glyph images. However, FT2 is flexible |
||||
and allows specific modules to register and support other |
||||
formats. As an example, it's (at least theorically :-) perfectly |
||||
possible to write a renderer module that is capable of directly |
||||
converting MetaFont glyph definitions to bitmaps or pixmaps ! |
||||
(of course, this assumes that you also write a MetaFont font |
||||
driver to load the definitions :-). |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
<b>font driver</b> modules are used to support one or more specific |
||||
font format. By default, FT2 comes with the following modules:</p> |
||||
|
||||
<center><table cellpadding=5><tr valign=top><td> |
||||
<p><tt><b>truetype</b></tt></p> |
||||
</td><td> |
||||
<p>supports TrueType font files</p> |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
<p><tt><b>type1</b></tt></p> |
||||
</td><td> |
||||
<p>supports Postscript Type 1 fonts, both in binary (.pfb) or ASCII |
||||
(.pfa) formats, including Multiple Master fonts.</p> |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
<p><tt><b>cid</b></tt></p> |
||||
</td><td> |
||||
<p>supports Postscript CID-keyed fonts</p> |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
<p><tt><b>cff</b></tt></p> |
||||
</td><td> |
||||
<p>supports OpenType, CFF as well as CEF fonts (CEF is a derivative |
||||
of CFF used by Adobe in its SVG viewer).</p> |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
<p><tt><b>winfonts</b></tt></p> |
||||
</td><td> |
||||
<p>supports Windows bitmap fonts (i.e. ".FON" and ".FNT").</p> |
||||
</td></tr> |
||||
|
||||
</td></tr></table></center> |
||||
|
||||
<p>Note that font drivers can support bitmapped or scalable glyph |
||||
images. A given font driver that supports bezier outlines through |
||||
the <tt>FT_Outline</tt> can also provide its own hinter, or rely |
||||
on FreeType's <b>autohinter</b> module. |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
<b>helper</b> modules are used to hold shared code that is |
||||
often used by several font drivers, or even other modules. |
||||
Here are a few examples of helper modules that come with |
||||
FreeType 2:</p> |
||||
|
||||
<table cellpadding=5><tr valign=top><td> |
||||
<b><tt>sfnt</tt></b> |
||||
</td><td> |
||||
used to support font formats based on the "<tt>SFNT</tt>" |
||||
storage scheme. This means TrueType & OpenType fonts as |
||||
well as other variants (like TrueType fonts that only |
||||
contain embedded bitmaps). |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
<b><tt>psnames</tt></b> |
||||
</td><td> |
||||
used to provide various useful function related to glyph |
||||
names ordering and Postscript encodings/charsets. For example, |
||||
this module is capable of automatically synthetizing a Unicode |
||||
charmap from a Type 1 glyph name dictionary. |
||||
</td></tr></table></center> |
||||
</p></li> |
||||
|
||||
|
||||
<li><p> |
||||
finally, the <b>autohinter</b> module has a specific role in |
||||
FreeType 2, as it can be used automatically during glyph loading |
||||
to process individual glyph outlines when a font driver doesn't |
||||
provide it's own hinting engine. |
||||
</p></li> |
||||
</ul> |
||||
|
||||
<p>We will now study how modules are described, then managed by |
||||
the library.</p> |
||||
|
||||
<h3>1. The <tt>FT_Module_Class</tt> structure:</h3> |
||||
|
||||
<p>As described later in this document, library initialisation is |
||||
performed by calling the <tt>FT_Init_FreeType</tt> function. The |
||||
latter is in charge of creating a new "empty" <tt>FT_Library</tt> |
||||
object, then register each "default" module by repeatedly calling |
||||
the <tt>FT_Add_Module</tt> function.</p> |
||||
|
||||
<p>Similarly, client applications can call <tt>FT_Add_Module</tt> |
||||
any time they wish in order to register a new module in the library. |
||||
Let's take a look at this function's declaration:</p> |
||||
|
||||
<pre><font color="blue"> |
||||
extern FT_Error FT_Add_Module( FT_Library library, |
||||
const FT_Module_Class* clazz ); |
||||
</font></pre> |
||||
|
||||
<p>As one can see, this function expects a handle to a library object, |
||||
as well as a pointer to a <tt>FT_Module_Class</tt> structure. It |
||||
returns an error code. In case of success, a new module object is |
||||
created and added to the library. Note by the way that the module |
||||
isn't returned directly by the call !.</p> |
||||
|
||||
<p>Let's study the definition of <tt>FT_Module_Class</tt>, and explain it |
||||
a bit. The following code is taken from |
||||
<tt><freetype/ftmodule.h></tt>:</p> |
||||
|
||||
<pre><font color="blue"> |
||||
typedef struct FT_Module_Class_ |
||||
{ |
||||
FT_ULong module_flags; |
||||
FT_Int module_size; |
||||
const FT_String* module_name; |
||||
FT_Fixed module_version; |
||||
FT_Fixed module_requires; |
||||
|
||||
const void* module_interface; |
||||
|
||||
FT_Module_Constructor module_init; |
||||
FT_Module_Destructor module_done; |
||||
FT_Module_Requester get_interface; |
||||
|
||||
} FT_Module_Class; |
||||
</font></pre> |
||||
|
||||
<p>here's a description of its fields:</p> |
||||
|
||||
<center><table cellpadding=5><tr valign=top><td> |
||||
<p><b>module_flags</b></p> |
||||
</td><td> |
||||
<p>this is a set of bit flags used to describe the module's |
||||
category. Valid values are:</p> |
||||
<ul> |
||||
<li><p> |
||||
<b>ft_module_font_driver</b> if the module is a font driver |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
<b>ft_module_renderer</b> if the module is a renderer |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
<b>ft_module_hinter</b> if the module is an auto-hinter |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
<b>ft_module_driver_scalable</b> if the module is a font |
||||
driver supporting scalable glyph formats. |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
<b>ft_module_driver_no_outlines</b> if the module is a |
||||
font driver supporting scalable glyph formats that <em>cannot</em> |
||||
be described by a <tt>FT_Outline</tt> object |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
<b>ft_module_driver_has_hinter</b> if the module is a font |
||||
driver that provides its own hinting scheme/algorithm |
||||
</p></li> |
||||
</ul> |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
<p><b>module_size</b></p> |
||||
</td><td> |
||||
<p>an integer that gives the size in <em>bytes</em> of a given module |
||||
object. This should <em>never</em> be less than |
||||
<tt>sizeof(FT_ModuleRec)</tt>, but can be more when the module |
||||
needs to sub-class the base <tt>FT_ModuleRec</tt> class.</p> |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
<p><b>module_name</b></p> |
||||
</td><td> |
||||
<p>this is the module's internal name, coded as a simple ASCII C |
||||
string. There can't be two modules with the same name registered |
||||
in a given <tt>FT_Library</tt> object. However, <tt>FT_Add_Module</tt> |
||||
uses the <b>module_version</b> field to detect module upgrades |
||||
and perform them cleanly, even at run-time.</p> |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
<p><b>module_version</b></p> |
||||
</td><td> |
||||
<p>a 16.16 fixed float number giving the module's major and minor |
||||
version numbers. It is used to determine wether a module needs |
||||
to be upgraded when calling <tt>FT_Add_Module</tt>.</p> |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
<p><b>module_requires</b></p> |
||||
</td><td> |
||||
<p>a 16.16 fixed float number giving the version of FreeType 2 that |
||||
is required to install this module. By default, should be 0x20000 |
||||
for FreeType 2.0</p> |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
<p><b>module_requires</b></p> |
||||
</td><td> |
||||
<p>most modules support one or more "interfaces", i.e. tables of function |
||||
pointers. This field is used to point to the module's main interface, |
||||
where there is one. It's a short-cut that prevents users of the module |
||||
to call "get_interface" each time they need to access one of the object's |
||||
common entry points.</p> |
||||
|
||||
<p>Note that is is optional, and can be set to NULL. Other interfaces |
||||
can also be accessed through the <b>get_interface</b> field.</p> |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
<p><b>module_init</b></p> |
||||
</td><td> |
||||
<p>this is a pointer to a function used to initialise the fields of |
||||
a fresh new <tt>FT_Module</tt> object. It is called <em>after</em> the module's |
||||
base fields have been set by the library, and is generally used to |
||||
initialise the fields of <tt>FT_ModuleRec</tt> subclasses.</p> |
||||
|
||||
<p>Most module classes set it to NULL to indicate that no extra |
||||
initialisation is necessary</p> |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
<p><b>module_done</b></p> |
||||
</td><td> |
||||
<p>this is a pointer to a function used to finalise the fields of |
||||
a given <tt>FT_Module</tt> object. Note that it is called <em>before</em> the |
||||
library unsets the module's base fields, and is generally used to |
||||
finalize the fields of <tt>FT_ModuleRec</tt> subclasses.</p> |
||||
|
||||
<p>Most module classes set it to NULL to indicate that no extra |
||||
finalisation is necessary</p> |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
<p><b>get_interface</b></p> |
||||
</td><td> |
||||
<p>this is a pointer to a function used to request the address of |
||||
a given module interface. Set it to NULL if you don't need to support |
||||
additional interfaces but the main one.</p> |
||||
</td></tr><tr valign=top><td> |
||||
|
||||
</td></tr></table></center> |
||||
|
||||
|
||||
<h3>2. The <tt>FT_Module</tt> type:</h3> |
||||
|
||||
<p>the <tt>FT_Module</tt> type is a handle (i.e. a pointer) to a given |
||||
module object / instance, whose base structure is given by the |
||||
internal <tt>FT_ModuleRec</tt> type (we will not detail its |
||||
structure here).</p> |
||||
|
||||
<p>When <tt>FT_Add_Module</tt> is called, it first allocate a new |
||||
module instance, using the <tt><b>module_size</b></tt> class |
||||
field to determine its byte size. The function initializes |
||||
a the root <tt>FT_ModuleRec</tt> fields, then calls |
||||
the class-specific initializer <tt><b>module_init</b></tt> |
||||
when this field is not set to NULL.</p> |
||||
|
||||
|
||||
|
||||
|
||||
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
||||
<h1>Renderer Modules</h1> |
||||
</td></tr></table> |
||||
|
||||
<p>As said previously, <b>renderers</b> are used to convert scalable |
||||
glyph images to bitmaps or pixmaps. Each renderer module is defined |
||||
through a <b>renderer class</b>, whose definition is found in the |
||||
file <tt><freetype/ftrender.h></tt>. However, a few concepts |
||||
need to be explained before having a detailed look at this structure. |
||||
</p> |
||||
|
||||
<h3>1. Glyph formats:</h3> |
||||
|
||||
<p>Each glyph image that is loaded by FreeType (either through |
||||
<tt>FT_Load_Glyph</tt> or <tt>FT_Load_Char</tt>), has a given |
||||
<em>image format</em>, described by the field |
||||
<tt>face->glyph->format</tt>. It is a 32-byte integer that |
||||
can take any value. However, the file <tt><freetype/ftimage.h></tt> |
||||
defines at least the following values:</p> |
||||
|
||||
<center><table cellpadding=5> |
||||
<tr valign=top><td> |
||||
<tt><b>ft_glyph_format_bitmap</b></tt> |
||||
</td><td> |
||||
this value is used to indicate that the glyph image is a bitmap or pixmap. |
||||
Its content can then be accessed directly from |
||||
<tt>face->glyph->bitmap</tt> after the glyph was loaded. |
||||
</td></tr> |
||||
|
||||
<tr valign=top><td> |
||||
<tt><b>ft_glyph_format_outline</b></tt> |
||||
</td><td> |
||||
this value is used to indicate that the glyph image is a scalable vectorial |
||||
outline, that can be described by a <tt>FT_Outline</tt> object. Its content |
||||
can be accessed directly from |
||||
<tt>face->glyph->outline</tt> after the glyph was loaded. |
||||
this is the format that is commonly returned by TrueType, Type1 and |
||||
OpenType / CFF fonts. |
||||
</td></tr> |
||||
|
||||
<tr valign=top><td> |
||||
<tt><b>ft_glyph_format_plotter</b></tt> |
||||
</td><td> |
||||
this value is equivalent to <tt><b>ft_glyph_format_outline</b></tt> except |
||||
that the outline stored corresponds to path strokes, instead of filled |
||||
outlines. It can be returned from certain Type 1 fonts (notably the Hershey |
||||
collection of free fonts). |
||||
</td></tr> |
||||
|
||||
<tr valign=top><td> |
||||
<tt><b>ft_glyph_format_composite</b></tt> |
||||
</td><td> |
||||
this value is used to indicate that the glyph image is really a "compound" |
||||
of several other "sub-glyphs". This value is only returned when a glyph |
||||
is loaded with the <tt><b>FT_LOAD_NO_RECURSE</b></tt> flag. The list of |
||||
subglyphs that make up the composite can be accessed directly as |
||||
<tt>face->glyph->subglyphs</tt> after the glyph was loaded. |
||||
</td></tr> |
||||
|
||||
</table></center> |
||||
|
||||
<p>Note that this is only a list of pre-defined formats supported by |
||||
FreeType. Nothing prevents an application to install a new font |
||||
driver that creates other kinds of glyph images. For example, one |
||||
could imagine a MetaFont font driver, that would be capable to |
||||
parse font definition files and create in-memory "glyph programs", |
||||
that could be returned in <tt>face->glyph->other</tt>.</p> |
||||
|
||||
<h3>2. The <tt>FT_Outline</tt> type:</h3> |
||||
|
||||
<p>This structure, which is also defined, and heavily commented, in |
||||
the file <tt><freetype/ftimage.h></tt>, is used to hold |
||||
a scalable glyph image that is made of one or more contours, each |
||||
contour being described by line segments or bezier arcs (either |
||||
quadratic or cubic). The outline itself is stored in a compact |
||||
way that makes processing it easy.</p> |
||||
|
||||
<p>Points are placed in a 2D plane that uses the y-upwards convention, |
||||
and their coordinates are stored in 1/64th of pixels (also known |
||||
as the 26.6 fixed point format). Pixels correspond to single squares |
||||
whose borders are on integer coordinates (i.e. mutiples of 64). |
||||
In other words, pixel centers are located on half pixel coordinates.</p> |
||||
|
||||
<p>Outlines can be very easily transformed (translated, rotated, etc..) |
||||
before being converted to bitmap, which allows for sophisticated |
||||
use of text. FreeType 2 comes by default with two "outline renderer" |
||||
modules:</p> |
||||
|
||||
<p><ul> |
||||
<li><b>raster1</b>, used to convert them to monochrome bitmaps</li> |
||||
<li><b>smooth</b>, used to convert them to high-quality anti-aliased |
||||
pixmaps</li> |
||||
</ul></p> |
||||
|
||||
<h3>3. Bitmaps and scan-conversion:</h3> |
||||
|
||||
<p>Bitmaps and pixmaps are described through a <tt>FT_Bitmap</tt> |
||||
structure, which is defined and heavily commented in |
||||
<tt><freetype/ftimage.h></tt> |
||||
|
||||
|
||||
<pre><font color="blue"> |
||||
typedef struct FT_Renderer_Class_ |
||||
{ |
||||
FT_Module_Class root; |
||||
|
||||
FT_Glyph_Format glyph_format; |
||||
|
||||
FTRenderer_render render_glyph; |
||||
FTRenderer_transform transform_glyph; |
||||
FTRenderer_getCBox get_glyph_cbox; |
||||
FTRenderer_setMode set_mode; |
||||
|
||||
FT_Raster_Funcs* raster_class; |
||||
|
||||
} FT_Renderer_Class; |
||||
</font></pre> |
||||
|
||||
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
||||
<h1>Font Driver Modules</h1> |
||||
</td></tr></table> |
||||
|
||||
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
||||
<h1>Library Initialisation & Dynamic Builds</h1> |
||||
</td></tr></table> |
||||
|
||||
<p>By default, all components of FreeType 2 are compiled independently, |
||||
then grouped into a single static library file that can be installed |
||||
or used directly to compile client applications</p> |
||||
|
||||
<p>Such applications must normally call the <tt>FT_Init_FreeType</tt> |
||||
function before using the library. This function is in charge of |
||||
two things:</p> |
||||
|
||||
<ul> |
||||
<li><p> |
||||
First, it creates a <tt>FT_Library</tt> object (by calling |
||||
the public function <tt>FT_New_Library</tt>). This new |
||||
object is "empty" and has no module registered in it. |
||||
</p></li> |
||||
|
||||
<li><p> |
||||
Then, it registers all "default modules" by repeatedly calling |
||||
<tt>FT_Add_Module</tt>. |
||||
</p></li> |
||||
</ul> |
||||
|
||||
<p>It is important to notice that the default implementation of |
||||
<tt>FT_Init_FreeType</tt>, which is located in the source |
||||
file <tt>"src/base/ftinit.c"</tt> always uses a <em>static</em> |
||||
list of modules that is generated at compile time from the |
||||
configuration file <tt><freetype/config/ftmodule.h></tt>. |
||||
</p> |
||||
|
||||
<p>There are cases where this may be inadequate. For example, one |
||||
might want to compile modules as independent DLLs in a specific |
||||
location (like <tt>"/usr/lib/freetype/module/"</tt>), and have |
||||
the library initialisation function load the modules dynamically |
||||
by parsing the directory's content</p> |
||||
|
||||
<p>This is possible, and we're going to explain how to do it.</p> |
||||
|
||||
|
||||
<h4>a. Building the library as a DLL (i.e. "shared object" on Unix)</h4> |
||||
|
||||
<p>But first of all, let's explain how to build FreeType 2 as a single |
||||
DLL or shared object, i.e. one that includes the base layer, all |
||||
default modules and optional components into a single file.</p> |
||||
|
||||
<p>When building dynamic libraries, certain compilers require specific |
||||
directives to <em>declare</em> exported DLL entry points. For example, the |
||||
"<tt>__cdecl</tt>" directive is required by Win32 compilers, as it forces |
||||
the use of the "C" parameter passing convention (instead of "smarter" |
||||
schemes, which usually use registers and the stack to pass parameters).</p> |
||||
|
||||
<p>To make matter worse, some of these compilers require the directive |
||||
before the function's return type, while some others want it between |
||||
the return type and the function's identifier.</p> |
||||
|
||||
<p>To allow such compilations, the <tt>FT_EXPORT_DEF()</tt> macro is |
||||
used in all public header files in order to declare each high-level |
||||
API function of FreeType 2, as in the following example, taken from |
||||
<tt><freetype/freetype.h></tt>:</p> |
||||
|
||||
<pre><font color="blue"> |
||||
FT_EXPORT_DEF(FT_Error) FT_Init_FreeType( void ); |
||||
</font></pre> |
||||
|
||||
<p>the definition of <tt>FT_EXPORT_DEF(x)</tt> defaults to <tt>"extern x"</tt>, |
||||
except when a specific definition is given in the library's system-specific |
||||
configuration file <tt><freetype/config/ftconfig.h></tt>. This |
||||
allows project builders to specify the exact compilation directive |
||||
they need.</p> |
||||
|
||||
<p>Similarly, the <tt>FT_EXPORT_FUNC(x)</tt> macro is defined and used to |
||||
<em>define</em> exported functions within the FreeType 2 source code. |
||||
However, it is only used at compilation time.</p> |
||||
|
||||
|
||||
<p>Note that on Unix, there is no need for specific exportation directives. |
||||
However, the code must be compiled in a special way, named Position |
||||
Independent Code ("PIC"), which is normally selected through specific |
||||
compiler flags (like "-PIC" with gcc).</p> |
||||
|
||||
|
||||
<h4>b. Building modules as DLLs</h4> |
||||
|
||||
<p>In order to build modules as dynamic libraries, we first need to compile |
||||
the base layer (and optional components) as a single DLL. This is very |
||||
similar to the case we just described, except that we also need to |
||||
export all functions that are part of the "low level base API", |
||||
as these will get called by the modules in various cases.</p> |
||||
|
||||
<p>Similarly to the high-level API, all functions of the low-level base |
||||
API are declared in the internal header files of FreeType 2 with the |
||||
<tt>BASE_DEF(x)</tt> macro. The latter is similar to |
||||
<tt>FT_EXPORT_DEF</tt> and defaults to <tt>"extern x"</tt> unless |
||||
you specify a specific definition in |
||||
<tt><freetype/config/ftconfig.h></tt>.</p> |
||||
<p> |
||||
|
||||
<hr> |
||||
|
||||
<table width="100%" cellpadding=5><tr bgcolor="#ccccee"><td> |
||||
<h1>Conclusion</h1> |
||||
</td></tr></table> |
||||
|
||||
</td></tr></table></center> |
||||
</body> |
||||
</html> |
||||
Loading…
Reference in new issue