the design of FT2 has evolved considerably since these documents were written, and it's better not to include them in order to avoid confusion among users of the library..VER-2-0-4-PATCH
David Turner
25 years ago
parent
59266f23c9
commit
43764232b8
12 changed files with 0 additions and 3173 deletions
@ -1,910 +0,0 @@ |
||||
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
||||
<html> |
||||
<head> |
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
||||
<meta name="Author" content="David Turner"> |
||||
<meta name="GENERATOR" content="Mozilla/4.5 [fr] (Win98; I) [Netscape]"> |
||||
<title>FreeType 2 Internals - I/O Frames</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" |
||||
link="#0000EF" |
||||
vlink="#51188E" |
||||
alink="#FF0000"> |
||||
|
||||
<center> |
||||
<h1>FreeType 2.0 Build System</h1></center> |
||||
|
||||
<center> |
||||
<h3> |
||||
© 2000 David Turner (<a href="fichier :///david@freetype.org">david@freetype.org</a>)<br> |
||||
© 2000 The FreeType Development Team |
||||
(<a href="mailto:devel@freetype.org">devel@freetype.org</a>) |
||||
</h3></center> |
||||
|
||||
<center><table width=650><tr><td> |
||||
|
||||
<p><hr WIDTH="100%"></p> |
||||
|
||||
<h2>Table of Content</h2> |
||||
|
||||
<center><table><tr><td> |
||||
<p><font size="+1"><a href="#introduction">Introduction</a></font></p> |
||||
<p><font size="+1"><a href="#features">I. Features & Background</a></font></p> |
||||
<ul> |
||||
<li><a href="#features-1">1. Convenience, not Requirement</a> |
||||
<li><a href="#features-2">2. Compiler and platform independence</a> |
||||
<li><a href="#features-3">3. Uses GNU Make</a> |
||||
<li><a href="#features-4">4. Automatic host platform detection</a> |
||||
<li><a href="#features-5">5. User-selectable builds</a> |
||||
<li><a href="#features-6">6. Robustness</a> |
||||
<li><a href="#features-7">7. Simple modules management</a> |
||||
</ul> |
||||
<p><font size="+1"><a href="#overview">II. Overview of the build process</a></font></p> |
||||
<ul> |
||||
<p><li><a href="#overview-1">1. Build setup</a> |
||||
<ul> |
||||
<li><a href="#overview-1-a">a. Default build setup</a> |
||||
<li><a href="#overview-1-b">b. Selecting another build configuration</a> |
||||
</ul> |
||||
</p> |
||||
|
||||
<li><a href="#overview-2">2. Library compilation</a> |
||||
</ul> |
||||
<p><font size="+1"><a href="#setup">III. Build setup details</a></font></p> |
||||
<p><font size="+1"><a href="#compilation">IV. Library compilation details</a></font></p> |
||||
<ul> |
||||
<li><a href="#compilation-1">a. Compiling the <tt>ftsystem</tt> component</a> |
||||
<li><a href="#compilation-2">b. Compiling the base layer and optional components</a> |
||||
<li><a href="#compilation-3">c. Compiling the modules</a> |
||||
<li><a href="#compilation-4">d. Compiling the <tt>ftinit</tt> component</a> |
||||
</ul> |
||||
</ul> |
||||
</td></tr></table></center> |
||||
|
||||
<hr><a name="introduction"> |
||||
<h2>Introduction:</h2> |
||||
|
||||
<p>This document describes the new build system that was introduced |
||||
with FreeType 2.</p> |
||||
|
||||
<p><hr></p> |
||||
<a name="features"> |
||||
<h2>I. Features and Background:</h2> |
||||
|
||||
<p>The FreeType 2 build system is a set of Makefiles and sub-Makefiles that |
||||
are used to build the library on a very large variety of systems easily. |
||||
One of its main features are the following:</p> |
||||
|
||||
<a name="features-1"> |
||||
<h3>1. Convenience, not Requirement</h3> |
||||
<ul> |
||||
<p>Even though the build system is rather sophisticated, it simply is a |
||||
convenience that was written simply to allow the compilation of the |
||||
FreeType 2 library on as many platforms as possible, as easily as |
||||
possible. However, it is not a requirement and the library can be |
||||
compiled manually or in a graphical IDE without using it, with minimal |
||||
efforts</p> |
||||
|
||||
<p>(for more information on this topic, see the <tt>BUILD</tt> |
||||
document that comes with your release of FreeType, in its <em>Detailed |
||||
Compilation Guide</em> section).</p> |
||||
</ul> |
||||
|
||||
<a name="features-2"> |
||||
<h3>2. Compiler and platform independence</h3> |
||||
<ul> |
||||
<p>The FreeType 2 build system can be used with any compiler, on any platform. |
||||
It is independent of object file suffix, executable file suffix, directory |
||||
separator convention (i.e. "/" or "\"), and compiler flags for path |
||||
inclusion, macro definition, output naming, ansi compliance, etc..</p> |
||||
|
||||
<p>Supporting a new compiler is trivial and only requires writing a minimal |
||||
configuration sub-makefile that contains several Makefile variables |
||||
definitions that are later used by the rest of the build system. This is |
||||
described in details later in the document.</p> |
||||
</ul> |
||||
|
||||
<a name="features-3"> |
||||
<h3>3. Uses GNU Make</h3> |
||||
<ul> |
||||
<p>The build system works <em>exclusively</em> with <b>GNU Make</b>. Reason |
||||
is that it is the only make utility that has all the features required to |
||||
implement the build system as described below. Moreover, it is already |
||||
ported to hundreds of various distinct platforms and is widely and |
||||
freely available.</p> |
||||
|
||||
<p>It also uses the native command line shell. <em>You thus |
||||
don't need a Unix-like shell on your platform</em>. |
||||
For example, FreeType 2 already compiles on Unix, Dos, Windows |
||||
and OS/2 right "out of the box" (assuming you have GNU Make |
||||
installed).</p> |
||||
|
||||
<p>Finally, note that the build system is <em>specifically</em> designed |
||||
for gnu make and will <em>fail</em> with any other make tool. We have |
||||
<em>no plans</em> to support a different tools, as you'll rapidly |
||||
understand by reading this document or looking at the sub-makefiles |
||||
themselves.</p> |
||||
</ul> |
||||
|
||||
<a name="features-4"> |
||||
<h3>4. Automatic host platform detection</h3> |
||||
<ul> |
||||
<p>When you launch the build system for the first time, by simply invoking |
||||
GNU make in the top-level directory, it automatically tries to detect |
||||
your current platform in order to choose the best configuration |
||||
sub-makefile available. It then displays what it found. If everything |
||||
is ok, you can then launch compilation of the library, by invoking make |
||||
a second time.</p> |
||||
|
||||
<p>The following platforms are currently automatically detected:</p> |
||||
<ul> |
||||
<li>Dos (plain-dos, windows in Dos mode, or Dos session under OS/2) |
||||
<li>Windows 95, 98 + Windows NT (a.k.a win32) |
||||
<li>OS/2 |
||||
<li>Unix (uses Autoconf/Automake) |
||||
</ul> |
||||
|
||||
<p>Note that adding support for a new platform requires writing a minimal |
||||
number of very small files, and simply putting them in a new sub-directory |
||||
of <tt>freetype2/config</tt>.</p> |
||||
</ul> |
||||
|
||||
<a name="features-5"> |
||||
<h3>5. User-selectable builds</h3> |
||||
<ul> |
||||
<p>The platform auto-detection rules try to setup the build for a default |
||||
compiler (<em>gcc</em> for most platforms), with default build options |
||||
for the library (which normally is |
||||
<em>"all features enable, no debugging"</em>), as well as the default |
||||
list of modules (which is <em>"all modules in <tt>freetype2/src</tt>"</em>)</p> |
||||
|
||||
<p>There are cases where it is important to specify a different compiler, |
||||
different build options or simply a different module list. The FreeType 2 |
||||
build system is designed in such a way that all of this is easily possible |
||||
from the command line, <em>without having to touch a single file</em>. |
||||
The latter is crucial when dealing with projects that need specific |
||||
builds of the library without modifying a single file from the FreeType |
||||
distribution.</p> |
||||
|
||||
<p>The exact mechanism and implementation to do this is described later in |
||||
this document. It allows, for example, to compile FreeType with any of |
||||
the following compilers on Win32: gcc, Visual C++, Win32-LCC.</p> |
||||
</ul> |
||||
|
||||
<a name="features-6"> |
||||
<h3>6. Robustness</h3> |
||||
<ul> |
||||
<p>The build system uses a single top-level Makefile that includes |
||||
one or more sub-makefiles to build the entire library (base layer |
||||
plus all modules). |
||||
|
||||
<font color="red"> |
||||
To understand why this is important, we <em>strongly</em> recommend |
||||
the following article to all of our readers:</font></p> |
||||
<p> |
||||
<center> |
||||
<font size="+2"><a href="http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html"> |
||||
Recursive Make Considered Dangerous |
||||
</a> |
||||
</font> |
||||
</center> |
||||
</p> |
||||
|
||||
<p>As an example, here's a short list of files that make up the |
||||
build system. Note that each sub-makefile contains rules corresponding |
||||
to a very specific purpose, and that they all use the "<tt>.mk</tt>" |
||||
suffix:</p> |
||||
<ul> |
||||
<li><tt>freetype2/Makefile</tt> |
||||
<li><tt>freetype2/config/detect.mk</tt> |
||||
<li><tt>freetype2/config/freetype.mk</tt> |
||||
<li><tt>freetype2/config/<em><system></em>/detect.mk</tt> |
||||
<li><tt>freetype2/src/<em><module></em>/rules.mk</tt> |
||||
<li><tt>freetype2/src/<em><module></em>/module.mk</tt> |
||||
</ul> |
||||
|
||||
</ul> |
||||
|
||||
<a name="features-7"> |
||||
<h3>7. Simple Module Management</h3> |
||||
<ul> |
||||
<p>FreeType 2 has a very modular design, and is made of a core |
||||
<em>base layer</em> that provides its high-level API as well as |
||||
generic services used by one or more <em>modules</em>. |
||||
|
||||
Most modules are used to support a specific font format (like TrueType |
||||
or Type 1), and they are called <em>font drivers</em>. However, some of |
||||
them do not support font files directly, but rather provide helper |
||||
services to the font drivers.</p> |
||||
|
||||
<p>FreeType 2 is designed so that adding modules at run-time is possible |
||||
and easy. Similarly, we expect many more modules to come in the near |
||||
future and wanted a build system that makes such additions to the |
||||
source package itself dead easy. |
||||
|
||||
Indeed, all source code (base + modules) is located in the |
||||
<tt>freetype2/src</tt> directory hierarchy. And the build system is |
||||
capable of re-generating automatically the list of known modules |
||||
from the contents of this directory. Hence, adding a new font driver |
||||
to the FreeType sources simply requires to:</p> |
||||
|
||||
<ul> |
||||
<li><p>Add a new sub-directory to <tt>freetype2/src</tt> |
||||
<li><p>Re-launch the build system</p> |
||||
</ul> |
||||
|
||||
<p>There is thus no need to edit a source file</p> |
||||
</ul> |
||||
|
||||
<p><hr><p> |
||||
<a name="overview"> |
||||
<h2>II. Overview of the build process(es):</h2> |
||||
|
||||
<p>Before describing in details how the build system works, it is essential |
||||
to give a few examples of how it's used. This section presents |
||||
what's the build process is to the typical developer:</p> |
||||
|
||||
<p>Compiling the library is normally done in two steps: the first one |
||||
configures the build according to the current platform and possible |
||||
additional parameters, while the second simply compiles the library with |
||||
the information gathered in the configuration step.</p> |
||||
|
||||
<a name="overview-1"> |
||||
<h3>1. Build Setup</h3> |
||||
|
||||
<a name="overview-1-a"> |
||||
<h4>a. Default build setup</h4> |
||||
<ul> |
||||
<p>To configure the build, simply invoke gnu make from the top-level FreeType |
||||
directory. This will launch a series of rules that will detect your current |
||||
host platform, and choose a configuration file for you. It will then display |
||||
what it found. For example, here's the output of typing the command "make" |
||||
on a win32 platform (assuming this calls GNU make):</p> |
||||
|
||||
<pre><font color="blue"> |
||||
<font color="purple">C:\FreeType> make</font> |
||||
|
||||
FreeType build system -- automatic system detection |
||||
|
||||
The following settings are used: |
||||
|
||||
platform win32 |
||||
compiler gcc |
||||
configuration directory ./config/win32 |
||||
configuration rules ./config/win32/w32-gcc.mk |
||||
|
||||
If this does not correspond to your system or settings please remove the file |
||||
'config.mk' from this directory then read the INSTALL file for help. |
||||
|
||||
Otherwise, simply type 'make' again to build the library. |
||||
|
||||
<font color="purple">C:\FreeType></font> |
||||
</font></pre> |
||||
|
||||
<p>Note that this step copies the selected configuration file (here |
||||
<tt>./config/win32/w32-gcc.mk</tt>) to <em>the current directory</em>, under |
||||
the name <tt><b>config.mk</b></tt>. This file contains data that is used |
||||
to drive the library compilation of the second step. It correspond to |
||||
the platform and compiler selected by the auto-detection phase.</p> |
||||
|
||||
<p>Note that you can re-generate the <tt><b>config.mk</b></tt> file anytime |
||||
by invoking <tt>make setup</tt> whenever you need it, even when the file is |
||||
already present in the current directory.</p> |
||||
|
||||
<p>Finally, if your platform is not correctly detected, the build system will |
||||
display and use configuration information for the virtual "ansi" platform. |
||||
</p> |
||||
</ul> |
||||
<a name="overview-1-b"> |
||||
<h4>b. Selecting another build configuration</h4> |
||||
<ul> |
||||
<p>You may not be really satisfied by the configuration file selected by the |
||||
auto-detection routines. Typically, you might be using a compiler that is |
||||
not the default one for your platform. It is however possible to re-launch |
||||
the build setup phase with an additional argument, used to specify a |
||||
different compiler/config file. For example, you can type the following |
||||
commands on Win32 systems:</p> |
||||
|
||||
<p align=center><table width="80%" cellpadding=10><tr valign=top><td> |
||||
<p><b><tt>make setup</tt></b></p> |
||||
</td><td> |
||||
<p>re-run the platform detection phase, and select the default compiler for it. |
||||
On Win32, this is <em>gcc</em>.</p> |
||||
</td></tr><tr valign=top><td> |
||||
<p><b><tt>make setup visualc</tt></b></p> |
||||
</td><td> |
||||
<p>re-run the platform detection phase, and select a config file that |
||||
corresponds to the <em>Visual C++</em> compiler</p> |
||||
</td></tr><tr valign=top><td> |
||||
<p><b><tt>make setup lcc</tt></b></p> |
||||
</td><td> |
||||
<p>re-run the platform detection phase, and select a config file that |
||||
corresponds to the <em>Win32-LCC</em> compiler</p> |
||||
</td></tr></table> |
||||
</p> |
||||
|
||||
<p>Note that a specific configuration is selected with a command that |
||||
looks like : <tt><b>make setup <em>compiler</em></b></tt>, |
||||
where the <em><tt>compiler</tt></em> keywords depends on the platform. |
||||
Moreover, each one of them corresponds to a specific configuration |
||||
sub-makefile that is copied as <b><tt>config.mk</tt></b> in the current |
||||
directory.</p> |
||||
</ul> |
||||
|
||||
|
||||
<a name="overview-2"> |
||||
<h3>2. Library compilation</h3> |
||||
|
||||
<p>Once you're satisfied with the version of <b><tt>config.mk</tt></b> that |
||||
has been copied to your current directory, you can simply re-invoke |
||||
gnu make <em>with no arguments</em>. The top-level Makefile will |
||||
automatically detect the config sub-makefile in the current directory, |
||||
and use it to drive the library compilation. The latter can be seen |
||||
as a series of different steps decribed here:</p> |
||||
|
||||
<ul> |
||||
<li><p><b>Compiling the <tt>ftsystem</tt> component</b><br><ul> |
||||
It encapsulates all low-level operations (memory management + |
||||
i/o access) for the library. Its default version, located in |
||||
<tt>./src/base/ftsystem.c</tt> uses the ANSI C library but |
||||
system-specific implementations are also available to |
||||
improve performance (e.g. memory-mapped files on Unix). |
||||
</ul></p> |
||||
|
||||
<li><p><b>Compiling the <em>base layer</em> and optional components</b><br><ul> |
||||
They provide the library's high-level API as well as various useful |
||||
routines for client applications. Many features of the base layer can |
||||
be activated or not depending on a configuration file named |
||||
<tt>ftoption.h</tt> |
||||
</ul></p> |
||||
|
||||
<li><p><b>Compiling the <em>modules</em></b><br><ul> |
||||
Each module is used to support a specific font format (it is then |
||||
called a <em>font driver</em>), or to provide helper services to |
||||
the drivers (e.g. the auto-hinter). They are all located in |
||||
sub-directories of <tt>./src</tt>, like <tt>./src/truetype</tt>, |
||||
<tt>./src/type1</tt>. |
||||
</ul></p> |
||||
|
||||
<li><p><b>Compiling the <tt>ftinit</tt> component</b><br><ul> |
||||
This one is in charge of implementing <tt>FT_Init_FreeType</tt>, |
||||
the library initialisation routine. It also selects what modules |
||||
are activated when a new library instance is created. |
||||
</ul></p> |
||||
</ul> |
||||
<p><hr><p> |
||||
<a name="setup"> |
||||
<h2>II. Details of the build setup.</h2> |
||||
|
||||
<p>When the top-level <tt>Makefile</tt> is invoked, it looks for a |
||||
file named <b><tt>config.mk</tt></b> in the <em>current directory</em>. |
||||
If this file is found, it is used directly to build the library |
||||
(skip to <a href="library">Section III</a> for details then).</p> |
||||
|
||||
<p>Otherwise, the file <b><tt>./config/detect.mk</tt></b> is included |
||||
by the top-level <tt>Makefile</tt> and parsed. Its purpose is to drive the |
||||
platform-detection phase, by:</p> |
||||
|
||||
<ul> |
||||
<li><p>Defining the <tt>PLATFORM</tt> variable, which indicates |
||||
what the currently detected platform is. It is initially |
||||
set to the default value "<tt><b>ansi</b></tt>". |
||||
</p> |
||||
|
||||
<li><p>Searching for a <tt>detect.mk</tt> file in <em>all |
||||
subdirectories</em> of <b><tt>./config</tt></b>. |
||||
Each such file is included and parsed. Each of these files must |
||||
try to detect if the host platform is a system it knows |
||||
about. If so, it changes the value of the <tt>PLATFORM</tt> variable |
||||
accordingly.</p> |
||||
|
||||
<li><p>Copying the selected configuration submakefile to the current directory |
||||
under the name <tt><b>config.mk</b></tt>.</p> |
||||
</ul> |
||||
<p>This is illustrated by the following graphics :</p> |
||||
<p><center> |
||||
<img src="platform-detection.png" border=0> |
||||
</center></p> |
||||
|
||||
<p>Each system-specific <b><tt>detect.mk</tt></b> works as follows:</p> |
||||
<ul> |
||||
<li><p>It checks that the value of <tt>PLATFORM</tt> is currently set |
||||
to <b>ansi</b>, which indicates that no platform was detected |
||||
for now. If this isn't true, it doesn't do anything</p> |
||||
|
||||
<li><p>Otherwise, it runs a series of test to see wether it is on a |
||||
system it knows about. Here are a few examples of tests:</p> |
||||
|
||||
<p><center><table width="80%" cellpadding=5><tr valign=top><td> |
||||
<em><b>Unix</b></em> |
||||
</td><td> |
||||
<p>checks for a file named <tt>/sbin/init</tt>, and runs, when it found |
||||
it, a 'configure' script to generate the relevant config sub-makefile</p> |
||||
</td></tr><tr valign=top><td> |
||||
<em><b>Dos</b></em> |
||||
</td><td> |
||||
<p>checks for the <tt>COMSPEC</tt> environment variable, then tries to |
||||
run the "<tt>ver</tt>" command on the current shell to check that there |
||||
is a "Dos" substring in its output; if not, it tries to find the |
||||
substring "<tt>MDOS\COMMAND</tt>" in <tt>COMSPEC</tt>, which indicates |
||||
a Dos session under OS/2.</p> |
||||
</td></tr><tr valign=top><td> |
||||
<em><b>Win32</b></em> |
||||
</td><td> |
||||
<p>if the environment variable <tt>OS</tt> is defined and has the value |
||||
<tt>Windows_NT</tt>, or if <tt>COMSPEC</tt> is defined and the |
||||
"<tt>ver</tt>" returns a string that contains <tt>Windows</tt> in it, |
||||
we're on a Win32 system.</p> |
||||
</td></tr></table></center> |
||||
</p> |
||||
|
||||
<li><p>It sets the value of <tt>PLATFORM</tt> to a new value corresponding |
||||
to its platform.</p> |
||||
|
||||
<li><p>It then tries to select a configuration |
||||
sub-makefile, depending on the current platform and any optional |
||||
make target (like "visualc" or "devel", etc..). Note that it can |
||||
even generate the file, as on Unix through Autoconf/Automake.</p> |
||||
|
||||
<li><p>It copies the selected configuration sub-makefile to the current |
||||
directory, under the name <tt><b>config.mk</b></tt> |
||||
</ul> |
||||
|
||||
<p>If one wants to support a new platform in the build system, it simply needs |
||||
to provide:</p> |
||||
|
||||
<ul> |
||||
<li>A new subdirectory, in <tt>./config</tt>, with a file named |
||||
<tt>detect.mk</tt> in it, containing relevant checks for the system. |
||||
|
||||
<li>One or more configuration sub-makefiles that will get copied to |
||||
<tt>config.mk</tt> at build setup time. You can use the one in |
||||
<tt>./config/ansi/config.mk</tt> as a template. |
||||
</ul> |
||||
|
||||
<p>Similary, supporting a new compiler on an existing system simply means:</p> |
||||
<ul> |
||||
<li>Writing a new config sub-makefile that contains definitions used to |
||||
specify the compiler and flags for the build. |
||||
|
||||
<li>Change your <tt>./config/<em>system</em>/detect.mk</tt> to recognize |
||||
a new optional build target that will copy your new config sub-makefile |
||||
instead of the default one. |
||||
</ul> |
||||
|
||||
|
||||
<p><hr><p> |
||||
<h2>III. Details of the library compilation.</h2> |
||||
|
||||
<p>When the top-level Makefile is invoked, it looks for a file named |
||||
<tt>config.mk</tt> in the current directory. If one is found, it |
||||
defines the <tt>BUILD_FREETYPE</tt> variable, then includes and parses it. |
||||
The structure of this file is the following: |
||||
</p> |
||||
|
||||
<ul> |
||||
<li><p>First, it defines a series of Make variables that describe |
||||
the host environment, like the compiler, compilation flags, |
||||
object file suffix, the directory where all object files are |
||||
placed, etc..</p> |
||||
|
||||
<li><p>If <tt>BUILD_FREETYPE</tt> is defined, it includes the file |
||||
<tt><b>./config/freetype.mk</b></tt>, which is in charge of |
||||
defining all the rules used to build the library object files. |
||||
(The test is useful to use the <tt>config.mk</tt> file to |
||||
compile other projects that rely on FreeType 2, like its |
||||
demonstration programs).</p> |
||||
|
||||
<li><p>Finally, it defines the rule(s) used to link FreeType 2 object files |
||||
into a library file (e.g. <tt>libfreetype.a</tt>, <tt>freetype.lib</tt>, |
||||
<tt>freetype.dll</tt>, ...). Unfortunately, the command line interface of link tools is |
||||
a <em>lot less</em> standardized than those of compilers, which |
||||
explains why this rule must be defined in the system-specific |
||||
<tt>config.mk</tt>.</p> |
||||
</ul> |
||||
|
||||
<p>The following is an explanation of what <tt><b>./config/freetype.mk</b></tt> |
||||
does to build the library objects: |
||||
</p> |
||||
|
||||
<h4>a. Include paths</h4> |
||||
<ul> |
||||
<p>To avoid namespace pollution, the <tt><em>freetype</em></tt> directory prefix |
||||
is used to include all public header files of the library. This means |
||||
that a client application will typically use lines like:</p> |
||||
|
||||
<pre><font color="blue"> |
||||
#include <freetype/freetype.h> |
||||
#include <freetype/ftglyph.h> |
||||
</font></pre> |
||||
|
||||
<p>to include one the FreeType 2 public header files. <tt>freetype.mk</tt> |
||||
uses a variable named <tt><b>INCLUDES</b></tt> to hold the inclusion |
||||
paths list, and thus starts by adding <tt>./include</tt> to it. However, |
||||
nothing prevents |
||||
|
||||
<p><tt>freetype.mk</tt> uses a variable named <tt><b>INCLUDES</b></tt> |
||||
to hold directory inclusion-path to be used when compiling the library. |
||||
It always add <tt>./include</tt> to this variable, which means |
||||
|
||||
</ul> |
||||
|
||||
<h4>b. Configuration header files:</h4> |
||||
<ul> |
||||
<p>Three header files used to configure the compilation of the |
||||
FreeType 2 library. Their default versions are all located in the |
||||
directory <tt><b>./include/freetype/config/</b></tt>, even though |
||||
project specific versions can be provided on a given build, as |
||||
described later:</p> |
||||
|
||||
<ul> |
||||
<p><b><tt>#include <freetype/config/ftoption.h></tt></b><br><ul> |
||||
This file contains a set of configuration macro definitions that |
||||
can be toggled to activate or deactivate certain features of the |
||||
library. By changing one of these definitions, it is possible to |
||||
compile <em>only the features that are needed</em> for a specific |
||||
project. Note that by default, all options are enabled. |
||||
<br><br> |
||||
You might need to provide an alternative version of <tt>ftoption.h</tt> |
||||
for one of your own projects. |
||||
</ul></p> |
||||
|
||||
<p><b><tt>#include <freetype/config/ftconfig.h></tt></b><br><ul> |
||||
This file includes <tt>ftoption.h</tt> but also contains some automatic |
||||
macro definitions used to indicate some important system-specific |
||||
features (e.g: word size in bytes, DLL export prefix macros, etc..). |
||||
<br><br> |
||||
You shouldn't normally need to change or provide an alternative |
||||
version of this file. |
||||
</ul></p> |
||||
|
||||
|
||||
<p><b><tt>#include <freetype/config/ftmodule.h></tt></b><br><ul> |
||||
This file is very special, as it is normally machine-generated, and |
||||
used by the <tt>ftinit</tt> component that is described below. To |
||||
understand it, one must reminds that FreeType 2 has an extremely |
||||
modular design and that it's possible to change, <em>at run-time</em>, |
||||
the modules it's using. The <tt>ftmodule.h</tt> file simply contains |
||||
the list of modules that are registered with each new instance of |
||||
the library. |
||||
<br><br> |
||||
Note that the file can be re-generated automatically by invoking |
||||
<tt>make setup</tt> from the top-level directory. The re-generated |
||||
list contains all the modules that were found in subdirectories of |
||||
<tt>./src</tt>. |
||||
</ul></p> |
||||
</ul> |
||||
|
||||
<p>Note that we strongly advise you to avoid modifying the config files |
||||
within the FreeType 2 source directory hierarchy. Rather, it's possible |
||||
to specify alternative versions through the help of a build-specific |
||||
include path that is include before <tt>./include</tt> in the inclusion |
||||
path.</p> |
||||
|
||||
<p>For example, imagine that your platform, named <em>foo</em>, needs a |
||||
specific version of <tt>ftoption.h</tt> |
||||
</ul> |
||||
|
||||
<h4>a. Compiling the <b><tt>ftsystem</tt></b> component:</h4> |
||||
<ul> |
||||
<p>FreeType 2 encapsulates all low-level operations (i.e. memory management |
||||
and i/o access) within a single component called <tt><b>ftsystem</b></tt>. |
||||
Its default implementation uses the <em>ANSI C Library</em> and is located |
||||
in <tt>./src/base/ftsystem.c</tt>.</p> |
||||
|
||||
<p>However, some alternate, system-specific, implementations of |
||||
<tt>ftsystem</tt> are provided with the library in order to support more |
||||
efficient and advanced features. As an example, the file |
||||
<tt>./config/unix/ftsystem.c</tt> is an implementation that |
||||
uses memory-mapped files rather than the slow ANSI <tt>fopen</tt>, |
||||
<tt>fread</tt> and <tt>fseek</tt>, boosting performance significantly.</p> |
||||
|
||||
<p>The build system is thus capable of managing alternate implementations |
||||
of <tt>ftsystem</tt></p> |
||||
</ul> |
||||
|
||||
<h4>b. Compiling the base layer and optional components:</h4> |
||||
<ul> |
||||
<p>The high-level API of the library is provided by a component called the |
||||
<em>base layer</em>, whose source is located in <tt>./src/base</tt>. This |
||||
directory also contains one or more components that are optional, i.e. |
||||
that are not required by the library but provide valuable routines to |
||||
client applications.</p> |
||||
|
||||
<p>The features of the base library and other components are selected through |
||||
a single configuration file named |
||||
<tt><b>./include/freetype/config/ftoption.h</b></tt>. It contains a list |
||||
of commented configuration macro definitions, that can be toggled to |
||||
activate or de-activate a certain feature or component at build time.</p> |
||||
|
||||
<p>For example, the code in <tt>./src/base/ftdebug.c</tt> will be compiled |
||||
only if one of these two macros are defined in <tt>ftoption.h</tt>: |
||||
<tt>FT_DEBUG_LEVEL_ERROR</tt> or <tt>FT_DEBUG_LEVEL_TRACE</tt></p> |
||||
</ul> |
||||
|
||||
<h4>c. Compiling the modules:</h4> |
||||
<ul> |
||||
<p>Once the base layer is completed, the build system starts to compile each |
||||
additional module independently. These are simply defined as all source |
||||
code located in a sub-directory of <tt>./src</tt> that contains a file |
||||
named <tt><b>rules.</b></tt>, for example: |
||||
<tt>src/sfnt</tt>, <tt>src/truetype</tt>, <tt>src/type1</tt>, ...</p> |
||||
|
||||
<p>The <tt><b>rules.</b></tt> file simply contains directives used by the |
||||
build system to compile the corresponding module into a single object |
||||
file.</p> |
||||
</ul> |
||||
|
||||
<h4>d. Compiling the <b><tt>ftinit</tt></b> component:</h4> |
||||
<ul> |
||||
<p>The file <tt><b>./src/base/ftinit.c</b></tt> is special because it is used |
||||
to implement the library initialisation function <tt>FT_Init_FreeType</tt>. |
||||
</p> |
||||
</ul> |
||||
|
||||
<p>Typically, you will end up with all object files, as well as the |
||||
corresponding library file, residing in the <tt>freetype2/obj</tt> |
||||
directory.</p> |
||||
|
||||
|
||||
<h3>1. Purpose of the configuration sub-makefile</h3> |
||||
|
||||
<h3>2. Managing module dependencies</h3> |
||||
|
||||
<h3>3. </h3> |
||||
|
||||
<p><hr><p> |
||||
<a name="modules"> |
||||
<h2>IV. Managing the modules list</h2> |
||||
|
||||
<p><hr><p> |
||||
The build system features some important points, which are all detailed |
||||
in the following sections:<p> |
||||
<ul> |
||||
<li><b>Automatic host platform detection</b><br> |
||||
The first time the top <tt>Makefile</tt> is invoked, it will |
||||
run a series of rules to detect your platform. It will then |
||||
create a system-specific configuration sub-Makefile in the |
||||
current directory, called <b><tt>config.mk</tt></b>. You can now |
||||
invoke the top <tt>Makefile</tt> a second time to compile the |
||||
library directly. |
||||
<p> |
||||
The configuration sub-makefile can be regenerated any time |
||||
by invoking "<tt>make setup</tt>", which will re-run the |
||||
detection rules even if a <tt>config.mk</tt> is already present. |
||||
<p> |
||||
|
||||
|
||||
<li><b>User-selectable builds</b><br> |
||||
<p> |
||||
|
||||
|
||||
|
||||
<li><b>Automatic detection of font drivers</b><br> |
||||
FreeType is made of a "base" layer that invokes several |
||||
separately-compiled modules. Each module is a given |
||||
font driver, in charge of supporting a given font format. |
||||
<p> |
||||
The list of font drivers is located in the file |
||||
"<tt>freetype2/config/<em>system</em>/ftmodule.h</tt>", however |
||||
it can be regenerated on-demand. Adding a new module to the |
||||
FreeType source tree is thus as easy as:<p> |
||||
<ul> |
||||
<li>create a new directory in "<tt>freetype2/src</tt>" and |
||||
put the new driver's source code and sub-makefiles there. |
||||
<p> |
||||
|
||||
<li>invoke the top <tt>Makefile</tt> with target |
||||
"<tt>modules</tt>" (as in "<tt>make modules</tt>"), |
||||
as this will automatically regenerate the list of |
||||
available drivers by detecting the new directory and |
||||
its content. |
||||
</ul> |
||||
<p> |
||||
</ul> |
||||
</ul> |
||||
|
||||
<p><hr><p> |
||||
|
||||
<h2>II. Host Platform Detection</h2> |
||||
<ul> |
||||
When the top-level <tt>Makefile</tt> is invoked, it looks for a |
||||
file named <tt>config.mk</tt> in the current directory. If this |
||||
file is found, it is used to build the library |
||||
(see <a href="library">Section III</a>). |
||||
<p> |
||||
Otherwise, the file <tt>freetype2/config/detect.mk</tt> is included |
||||
and parsed. Its purpose is to:<p> |
||||
<ul> |
||||
<li>Define the <tt>PLATFORM</tt> variable, which indicates |
||||
what is the currently detected platform. It is initially |
||||
set to the default value "<tt>ansi</tt>". |
||||
<p> |
||||
|
||||
<li>It searches for a <tt>detect.mk</tt> file in all |
||||
subdirectories of <tt>freetype2/config</tt>. Each such |
||||
file is included and parsed. Each of these files must |
||||
try to detect if the host platform is a system it knows |
||||
about. If so, it changes the value of the <tt>PLATFORM</tt> |
||||
accordingly. |
||||
</ul> |
||||
<p> |
||||
This is illustrated by the following graphics :<p> |
||||
<center> |
||||
<img src="platform-detection.png" border=0> |
||||
</center> |
||||
<p> |
||||
Note that each system-specific <tt>detect.mk</tt> is in charge |
||||
of copying a valid configuration makefile to the current directory |
||||
(i.e. the one where <tt>make</tt> was invoked), depending on the |
||||
current targets. For example, the Win32 <tt>detect.mk</tt> will |
||||
be able to detect a "<tt>visualc</tt>" or "<tt>lcc</tt>" target, |
||||
as described in section I. Similarly, the OS/2 <tt>detect.mk</tt> |
||||
can detect targets like "<tt>borlandc</tt>", "<tt>watcom</tt>" |
||||
or "<tt>visualage</tt>", etc.. |
||||
</ul> |
||||
|
||||
<p><hr><p> |
||||
|
||||
<h2>III. Building the library</h2> |
||||
<ul> |
||||
When the top-level <tt>Makefile</tt> is invoked and that it finds |
||||
a <tt>config.mk</tt> file in the current directory, it defines |
||||
the variable <tt>BUILD_FREETYPE</tt>, then includes and parses the |
||||
configuration sub-makefile. |
||||
<p> |
||||
The latter defines a number of important variables that describe |
||||
the compilation process to the build system. Among other things:<p> |
||||
<ul> |
||||
<li>the extension to be used for object files and library files |
||||
(i.e. <tt>.o</tt> and <tt>.a</tt> on Unix, <tt>.obj</tt> |
||||
and <tt>.lib</tt> on Dos-Windows-OS/2, etc..). |
||||
<p> |
||||
|
||||
<li>the directory where all object files will be stored |
||||
(usually <tt>freetype2/obj</tt>), as well as the one |
||||
containing the library file (usually the same as for |
||||
objects). |
||||
<p> |
||||
|
||||
<li>the command line compiler, and its compilation flags for |
||||
indicating a new include path (usually "<tt>-I</tt>"), |
||||
a new macro declaration (usually "<tt>-D</tt>") or |
||||
the target object file (usually "<tt>-o </tt>") |
||||
</ul> |
||||
<p> |
||||
Once these variable are defined, <tt>config.mk</tt> test for the |
||||
definition of the <tt>BUILD_FREETYPE</tt> variable. If it exists, |
||||
the makefile then includes "<tt>freetype2/config/freetype.mk</tt>" |
||||
which contains the rules required to compile the library. |
||||
<p> |
||||
Note that <tt>freetype.mk</tt> also scans the subdirectories of |
||||
"<tt>freetype2/src</tt>" for a file called "<tt>rules.mk</tt>". |
||||
Each <tt>rules.mk</tt> contains, as it names suggests, the rules |
||||
required to compile a given font driver or module. |
||||
<p> |
||||
Once all this parsing is done, the library can be compiled. Usually, |
||||
each font driver is compiled as a standalone object file (e.g. |
||||
<tt>sfnt.o</tt>, <tt>truetype.o</tt> and <tt>type1.o</tt>). |
||||
<p> |
||||
This process can be illustrated by the following graphics:<p> |
||||
<center> |
||||
<img src="library-compilation.png" border=0> |
||||
</center> |
||||
<p> |
||||
</ul> |
||||
|
||||
<p><hr><p> |
||||
|
||||
<h2>IIV. Managing the list of modules</h2> |
||||
<ul> |
||||
The makefile <tt>freetype.mk</tt> only determines how to compile |
||||
each one of the modules that are located in the sub-directories of |
||||
<tt>freetype2/src</tt>. |
||||
<p> |
||||
However, when the function <tt>FT_Init_FreeType</tt> is invoked at |
||||
the start of an application, it must create a new <tt>FT_Library</tt> |
||||
object, and registers all <em>known</em> font drivers to it by |
||||
repeatly calling <tt>FT_Add_Driver</tt>. |
||||
<p> |
||||
The list of <em>known</em> drivers is located in the file |
||||
"<tt>freetype2/config/<em>system</em>/ftmodule.h</tt>", and is used |
||||
exclusively by the internal function <tt>FT_Default_Drivers</tt>. The |
||||
list in <tt>ftmodule.h</tt> must be re-generated each time you add |
||||
or remove a module from <tt>freetype2/src</tt>. |
||||
<p> |
||||
This is normally performed by invoking the top-level <tt>Makefile</tt> |
||||
with the <tt>modules</tt> target, as in:<p> |
||||
<ul> |
||||
<tt>make modules</tt> |
||||
</ul> |
||||
<p> |
||||
This will trigger a special rule that will re-generate |
||||
<tt>ftmodule.h</tt>. To do so, the Makefile will parse all module |
||||
directories for a file called "<tt>module.mk</tt>". Each |
||||
<tt>module.mk</tt> is a tiny sub-Makefile used to add a single |
||||
module to the driver list. |
||||
<p> |
||||
This is illustrated by the following graphics:<p> |
||||
<center> |
||||
<img src="drivers-list.png" border=0> |
||||
</center> |
||||
<p> |
||||
Note that the new list of modules is displayed in a very human-friendly |
||||
way after a "<tt>make modules</tt>". Here's an example with the current |
||||
source tree (on 11 Jan 2000):<p> |
||||
<ul><pre> |
||||
Regenerating the font drivers list in ./config/unix/ftmodule.h |
||||
* driver: sfnt ( pseudo-driver for TrueType & OpenType formats ) |
||||
* driver: truetype ( Windows/Mac font files with extension *.ttf or *.ttc ) |
||||
* driver: type1 ( Postscript font files with extension *.pfa or *.pfb ) |
||||
-- done -- |
||||
</pre></ul> |
||||
|
||||
</ul> |
||||
|
||||
<p><hr><p> |
||||
|
||||
<h2>V. Building the demonstration programs</h2> |
||||
<ul> |
||||
Several demonstration programs are located in the |
||||
"<tt>freetype2/demos</tt>" directory hierarchy. This directory also |
||||
includes a tiny graphics sub-system that is able to blit glyphs to |
||||
a great variety of surfaces, as well as display these in various |
||||
graphics libraries or windowed environments. |
||||
<p> |
||||
This section describes how the demonstration programs are compiled, |
||||
using the configuration <tt>freetype2/config.mk</tt> and their own |
||||
<tt>freetype2/demos/Makefile</tt>. |
||||
<p> |
||||
To compile the demonstration programs, <em>after the library</em>, |
||||
simply go to <tt>freetype2/demos</tt> then invoke GNU make with no |
||||
arguments. |
||||
<p> |
||||
The top-level Makefile will detect the <tt>config.mk</tt> in the |
||||
<em>upper</em> directory and include it. Because it doesn't define |
||||
the <tt>BUILD_FREETYPE</tt> variable, this will not force the |
||||
inclusion of <tt>freetype2/config/freetype.mk</tt> as described in |
||||
the previous section. |
||||
<p> |
||||
the <tt>Makefile</tt> will then include the makefile called |
||||
"<tt>freetype2/demos/graph/rules.mk</tt>". The graphics <tt>rules.mk</tt> |
||||
defines the rules required to compile the graphics sub-system. |
||||
<p> |
||||
Because the graphics syb-system is also designed modularly, it is able |
||||
to use any number of "modules" to display surfaces on the screen. |
||||
The graphics modules are located in the subdirectories of |
||||
<tt>freetype2/demos/config</tt>. Each such directory contains a file |
||||
named <tt>rules.mk</tt> which is in charge of:<p> |
||||
<ul> |
||||
<li>detecting wether the corresponding graphics library is |
||||
available at the time of compilation. |
||||
<p> |
||||
<li>if it is, alter the compilation rules to include the graphics |
||||
module in the build of the <tt>graph</tt> library. |
||||
</ul> |
||||
<p> |
||||
When the <tt>graph</tt> library is built in <tt>demos/obj</tt>, the |
||||
demonstration programs executables are generated by the top-level |
||||
Makefile. |
||||
<p> |
||||
This is illustrated by the following graphics:<p> |
||||
<center> |
||||
<img src="demo-programs.png" border="0"> |
||||
</center> |
||||
</ul> |
||||
|
||||
<p><hr> |
||||
</td></tr></table></center> |
||||
</body> |
||||
</html> |
||||
|
||||
|
Before Width: | Height: | Size: 2.8 KiB |
|
Before Width: | Height: | Size: 1.8 KiB |
@ -1,791 +0,0 @@ |
||||
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
||||
<html> |
||||
<head> |
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
||||
<meta name="Author" content="David Turner"> |
||||
<meta name="GENERATOR" content="Mozilla/4.5 [fr] (Win98; I) [Netscape]"> |
||||
<title>FreeType 2 Internals</title> |
||||
</head> |
||||
<body> |
||||
|
||||
<body text="#000000" |
||||
bgcolor="#FFFFFF" |
||||
link="#0000EF" |
||||
vlink="#51188E" |
||||
alink="#FF0000"> |
||||
|
||||
<center> |
||||
<h1> |
||||
FreeType 2.0 Internals</h1></center> |
||||
|
||||
<center> |
||||
<h2> |
||||
Version 1.2</h2></center> |
||||
|
||||
<center> |
||||
<h3> |
||||
© 1999-2000 David Turner (<a href="fichier :///david@freetype.org">david@freetype.org</a>)<br> |
||||
© 1999-2000 The FreeType Development Team (<a href="fichier :///devel@freetype.org">devel@freetype.org</a>)</h3></center> |
||||
|
||||
<p><br> |
||||
<hr WIDTH="100%"> |
||||
<br> |
||||
<h2>Introduction:</h2> |
||||
|
||||
<p>This document describes in great deatils the internals of FreeType 2. |
||||
It is a must read for porters and developers alike. Its purpose is to |
||||
|
||||
present the |
||||
<blockquote>This document describes in great details the internals of the |
||||
FreeType 2.0 library. It is a must read for porters and developers alike. |
||||
Its purpose is to present the engine's objects, their roles and interactions. |
||||
It is assumed that the <b><i>FreeType Glyph Conventions</i></b> document |
||||
has been read. |
||||
<p>We advise porters to also read the <b><i>FreeType Porting Guide</i></b> |
||||
after this document. Would-be hackers and maintainers are of course encouraged |
||||
to read the <b><i>FreeType Coding Conventions</i></b> document too. The |
||||
development of a new driver is described in more details in the <b><i>FreeType |
||||
Driver HowTo</i></b> document.</blockquote> |
||||
|
||||
<p><br> |
||||
<hr WIDTH="100%"> |
||||
<h2> |
||||
I. Overview :</h2> |
||||
|
||||
<blockquote> |
||||
<h3> |
||||
1. Features (and what's new) :</h3> |
||||
|
||||
<blockquote>FreeType 2.0 has a number of important new features that were |
||||
not found in the 1.x releases : |
||||
<br> |
||||
<blockquote><b>font-format independent API</b> |
||||
<br>FreeType 2.0 is able to support any kind of font format, be it fixed |
||||
or scalable, through the use of pluggable "font drivers". These drivers |
||||
can be added or replaced at run time, while applications use a new font |
||||
format-independent API. |
||||
<p><b>advanced stream caching</b> |
||||
<br>2.0 is able to control the number of concurrently opened streams when |
||||
using fonts. It is thus possible to open dozens or hundreds of font faces |
||||
without running out of system resources. |
||||
<p><b>real reentrancy support</b> |
||||
<br>It is now possible to use FreeType as a shared library with no static |
||||
data in a multi-threaded environment. The synchronization model has also |
||||
been simplified in order to make font driver writing easier. Of course, |
||||
you can build FreeType with no thread support to get a smaller library. |
||||
<p><b>support for cubic beziers and 17-levels anti-aliasing</b> |
||||
<br>The FreeType scan-line converter (a.k.a. raster) now supports cubic |
||||
bezier arcs seamlessly. It also provides a new anti-aliasing mode which |
||||
uses a palette of 17 levels of grays. |
||||
<br> </blockquote> |
||||
It also features the following : |
||||
<blockquote><b>performance improvements :</b> |
||||
<br>The FreeType raster has been optimized, and the generation of anti-aliased |
||||
pixmaps is now 60% faster than in the 1.x release. Moreover, the TrueType |
||||
bytecode interpreter has been profiled and greatly optimised. |
||||
<p><b>easier portability</b> |
||||
<br>Porting and configuring FreeType is now much easier. A single file |
||||
must be provided for system-specific operations (like memory, i/o, thread |
||||
management), and a single configuration header is used to select the build |
||||
you need. |
||||
<br> </blockquote> |
||||
</blockquote> |
||||
|
||||
<h3> |
||||
2. Architecture :</h3> |
||||
|
||||
<blockquote>The engine is now split in several parts, which are : |
||||
<h4> |
||||
a. The base layer :</h4> |
||||
|
||||
<blockquote>This part contains all the font-format independent features |
||||
of the engine which are : |
||||
<ul> |
||||
<li> |
||||
computations/scaling</li> |
||||
|
||||
<li> |
||||
list processing</li> |
||||
|
||||
<li> |
||||
outline processing</li> |
||||
|
||||
<li> |
||||
scan-line converter</li> |
||||
|
||||
<li> |
||||
stream manager</li> |
||||
|
||||
<li> |
||||
base object classes</li> |
||||
|
||||
<li> |
||||
debugging & traces</li> |
||||
|
||||
<li> |
||||
high-level API functions</li> |
||||
|
||||
<li> |
||||
low-level system object (memory, i/o, threads)</li> |
||||
</ul> |
||||
</blockquote> |
||||
|
||||
<h4> |
||||
b. The font drivers :</h4> |
||||
|
||||
<blockquote>Each font format is managed with the use of a single font driver |
||||
object. The base layer is able to manage several drivers, and these can |
||||
be easily added, removed or upgraded at runtime. Each driver has the following |
||||
features and functions : |
||||
<ul> |
||||
<li> |
||||
auto-check font format when opening a font resource (i.e. file)</li> |
||||
|
||||
<li> |
||||
access, load and/or extract all tables and data from the font file</li> |
||||
|
||||
<li> |
||||
grid-fit/hint the glyph outlines (in the case of scalable formats like |
||||
TrueType or Type1)</li> |
||||
|
||||
<li> |
||||
provide extensions to access font format-specific data and tables from |
||||
the font file</li> |
||||
</ul> |
||||
Note that FreeType 2.0 is a font service. Its purpose is to provide a unified |
||||
API for all kinds of fonts and extract individual glyph images and metrics. |
||||
However, it does not render text itself, as this operation is left to the |
||||
developer, or to higher-level libraries built on top of FreeType. Here |
||||
are a few features that are thus not implemented : |
||||
<blockquote>1) Text string rendering |
||||
<br>2) Glyph bitmap/outline caching for improved performance |
||||
<br>3) Synthetic fonts (i.e. italicising, emboldening, underlining) |
||||
<br>4) Contextual glyph substitution and other advanced layout processes</blockquote> |
||||
Note that features 1 through 3 should be provided by the SemTex library, |
||||
which may soon become part of the standard FreeType distribution.</blockquote> |
||||
</blockquote> |
||||
</blockquote> |
||||
|
||||
<p><br> |
||||
<hr WIDTH="100%"> |
||||
<h2> |
||||
II. Design :</h2> |
||||
|
||||
<blockquote> |
||||
<h3> |
||||
1. Objects :</h3> |
||||
|
||||
<blockquote>They are several kinds of objects in FreeType, which can be |
||||
described as follows : |
||||
<blockquote><b>Base objects</b> |
||||
<br>These objects do not relate directly to font data, but to the way it |
||||
is organised and managed. It is the basic core and provides functions that |
||||
are heavily used by each font driver. Examples are the resource objects, |
||||
used to describe font files, the system object used to manage low-level |
||||
system operations, or the raster object, used to convert vector outlines |
||||
into bitmaps or anti-aliased pixmaps. Most of the base objects are not |
||||
directly visible for client applications of FreeType. |
||||
<p><b>Font objects</b> |
||||
<br>The font objects directly model the data as it is found in font files. |
||||
The root classes implemented in the base layer like <tt>FT_Face</tt>, <tt>FT_Size</tt>, |
||||
<tt>FT_GlyphSlot</tt>, |
||||
must be derived in each font driver.</blockquote> |
||||
Objects are defined in the files "<tt>base/freetype.h</tt>" and "<tt>base/ftobjs.h</tt>". |
||||
The former contains all the public object definitions usable by client |
||||
applications. The latter contains private definitions used by the rest |
||||
of the base layer and each font driver.</blockquote> |
||||
|
||||
<h3> |
||||
2. List management</h3> |
||||
|
||||
<blockquote>The "<tt>base/ftlist.c</tt>" component a very simple doubly-linked |
||||
list facility which is used by the rest of the engine to create and process |
||||
lists, including iteration and finalisation. The definition of the list |
||||
node and functions are placed in the "<tt>base/freetype.h</tt>" to let |
||||
client applications access listed objects as they like. |
||||
<p>The base list type is <tt>FT_List</tt>, which links nodes of type <tt>FT_ListNode</tt> |
||||
together. |
||||
<br> </blockquote> |
||||
|
||||
<h3> |
||||
3. Limited encapsulation</h3> |
||||
|
||||
<blockquote>Unlike what happened in the 1.x releases, the <tt>FT_Face</tt>, |
||||
<tt>FT_Size</tt>, |
||||
<tt>FT_GlyphSlot</tt> and <tt>FT_CharMap</tt> types are no longer blind |
||||
pointers to opaque types. Rather, the corresponding structures are now |
||||
public (and defined in "<tt>base/freetype.h</tt>", see <tt>FT_FaceRec</tt>, |
||||
<tt>FT_SizeRec</tt>, |
||||
etc..) in order to let client applications read directly the various object |
||||
attributes they're interested in. |
||||
<p>This breaks encapsulation of implementation, famed by OOP, but was chosen |
||||
because: |
||||
<br> |
||||
<ul> |
||||
<li> |
||||
it simplifies a lot the work of client applications and libraries which |
||||
don't need to perform a function call everytime they want to read one important |
||||
object attribute (nor does it force them to cache these attributes in their |
||||
own structures).</li> |
||||
</ul> |
||||
|
||||
<ul> |
||||
<li> |
||||
It reduces greatly the API, as many <tt>FT_Get_XXX</tt> functions are avoided.</li> |
||||
</ul> |
||||
|
||||
<ul> |
||||
<li> |
||||
Higher-level libraries are able to access data directly. When it |
||||
is used frequently, they don't need to cache it in their own structures.</li> |
||||
</ul> |
||||
|
||||
<ul> |
||||
<li> |
||||
It is possible to tightly link FreeType objects with higher-level ones, |
||||
in a clearer and more efficient way. This is very important when one wants |
||||
to write a C++ wrapper or a text rendering library on top of FreeType (actually, |
||||
both projects were performed in an earlier version of FreeType 2.0 which |
||||
featured classic encapsulation through get/set methods. The resulting code |
||||
was ugly and slow. Moving to a limited encapsulation approach simplified |
||||
so many things that the compiled code size was reduced by a factor of two |
||||
!).</li> |
||||
</ul> |
||||
|
||||
<ul> |
||||
<li> |
||||
Finally, the API and font object structures were designed after the creation |
||||
of two scalable font drivers and one bitmap font driver. They are now very |
||||
stable and the public (visible) attributes are not going to change.</li> |
||||
</ul> |
||||
</blockquote> |
||||
</blockquote> |
||||
|
||||
<p><br> |
||||
<hr WIDTH="100%"> |
||||
<h2> |
||||
III. Base objects :</h2> |
||||
|
||||
<blockquote>This section describes the FreeType base object classes : |
||||
<br> |
||||
<h3> |
||||
1. System objects :</h3> |
||||
|
||||
<blockquote>The system class is in charge of managing all low-level and |
||||
system-specific operations. This means simply memory management, i/o access |
||||
and thread synchronisation. It is implemented by the "<tt>ftsys.c</tt>" |
||||
component, whose source must be located in the configuration directory |
||||
when building FreeType. (e.g. "<tt>lib/arch/ansi/ftsys.c</tt>" for an ANSI |
||||
build, "<tt>lib/arch/unix/ftsys.c</tt>" for a Unix one, etc..). |
||||
<p>Porting FreeType 2.0 really means providing a new implementation of |
||||
<tt>ftsys</tt> |
||||
(along with a few configuration file changes). Note however that its interface |
||||
is common to all ports, and located in "<tt>base/ftsys.h</tt>".</blockquote> |
||||
|
||||
<h3> |
||||
2. Resources and Streams:</h3> |
||||
|
||||
<blockquote>The concepts of files as storages, and files as streams has |
||||
been separated for FreeType 2.0. The "<b><i>resource</i></b>" concept was |
||||
introduced while the "<b><i>stream</i></b>" one has been redefined. Here |
||||
is how they work together : |
||||
<ul> |
||||
<li> |
||||
a "<b>resource</b>" is an object which models a file, seen as a storage. |
||||
There are several classes of resources, which differ usually in two ways |
||||
: the way their data is accessed by applications, and the way they're named |
||||
within the system.</li> |
||||
</ul> |
||||
|
||||
<ul>For example, when parsing files with the ANSI C library, data has to |
||||
be read (through fseek/fread) into intermediate buffers before it can be |
||||
decoded. This scheme is highly portable, but rather inefficient; when using |
||||
it, we'll describe the file as a disk-based resource. |
||||
<p>As most modern operating systems now provide memory-mapped files, which |
||||
allow direct access while improving performance and reducing memory usage. |
||||
Because data can be read directly in memory, we'll speak of a memory-based |
||||
resource in this case. For embedded systems (like printers, PDAs, etc..), |
||||
ROM-fonts fit into this category as well. |
||||
<p>Regarding naming, most systems use a string to name files in their storage |
||||
hierarchy. Though a typical pathname is an ASCII string (<tt>'c:\windows\fonts\times.ttf'</tt> |
||||
on Windows, <tt>'/home/fonts/times.ttf'</tt> on Unix), some OSes use different |
||||
schemes, varying from Unicode character strings to file i-node numbers. |
||||
These details are platform-specific and must be hidden to the rest of the |
||||
library in resource objects. |
||||
<p>A resource encapsulates the lowest details regarding a file, though |
||||
it should have NO STATE. Note that the nature or type of a resource (i.e. |
||||
disk or memory based) is important to the "stream" component only. The |
||||
rest of the library and font drivers work transparently from their implementation. |
||||
<p>Note also that it is perfectly possible to mix resources of distinct |
||||
natures in a single build</ul> |
||||
|
||||
<ul> |
||||
<li> |
||||
a "<b>stream</b>" is an object which is used to extract bytes from a resource. |
||||
Only resource objects can create streams, through its <i><tt>Open_Stream()</tt></i> |
||||
method. A stream has state, which typically consist of a file "cursor", |
||||
some intermediate buffers, a "current frame" and, of course, methods used |
||||
to extract the data from streams, resolving endianess and alignement issues.</li> |
||||
</ul> |
||||
Data can be extracted from streams through direct reads, or through the |
||||
use of <b>frames</b>. A frame models <i>a run of contiguous bytes</i> starting |
||||
from the current stream position, and of liberal size. |
||||
<p>Methods exist to extract successive integers of any sizes, while resolving |
||||
endianess and alignement issues. Rather than a long rethorical explanation, |
||||
here's how frames are typically used : |
||||
<blockquote><tt>{</tt> |
||||
<br><tt> …</tt> |
||||
<br><tt> FT_Error error;</tt> |
||||
<p><tt> error = FT_Access_Frame( stream, 14 );</tt> |
||||
<br><tt> if (error) goto Fail;</tt> |
||||
<p><tt> val1 = FT_Get_Short(stream);</tt> |
||||
<br><tt> val2 = FT_Get_Long(stream);</tt> |
||||
<br><tt> val3 = FT_Get_Long(stream);</tt> |
||||
<br><tt> val4 = FT_Get_Long(stream);</tt> |
||||
<p><tt> FT_Forget_Frame(stream);</tt> |
||||
<br><tt> …</tt> |
||||
<br><tt>}</tt></blockquote> |
||||
This code does the following : |
||||
<blockquote> |
||||
<ol> |
||||
<li> |
||||
first, it "loads" the next 14 bytes from the current cursor position |
||||
into the stream's frame, using the <tt>FT_Access_Frame</tt> API. An error |
||||
is returned if, for example, less than 14 bytes are left in the stream |
||||
when the call occurs..</li> |
||||
</ol> |
||||
|
||||
<ol> |
||||
<li> |
||||
it extract four integers (one 16-bit short, three 32-bit longs) from |
||||
the frame using <tt>FT_Get_Short</tt> and <tt>FT_Get_Long</tt>. These function |
||||
increment the frame's cursor finally, it "releases" the stream's frame.</li> |
||||
</ol> |
||||
|
||||
<ol> |
||||
<li> |
||||
Each stream has its own frame which can be accessed independently, |
||||
however, nested frame accesses are not allowed. Note also that the bytes |
||||
are effectively read from the stream on the call to <tt>FT_Access_Frame</tt>. |
||||
Any subsequent read will occur after these 14 bytes, even if less are extracted |
||||
through <tt>FT_Get_xxxx</tt> functions.</li> |
||||
</ol> |
||||
</blockquote> |
||||
The implementation of the resource class is located in the system component |
||||
(i.e. "<tt>arch/<i><system></i>/ftsys.c</tt>") and can thus be tailored |
||||
for a specific port of the engine. |
||||
<p>A resource can be created through the <tt>FT_New_Resource</tt> API; |
||||
however this function only accepts an 8-bit pathname to name the target |
||||
font file, which may be inappropriate for systems using a different naming |
||||
scheme (e.g. UTF-16 pathname, i-node number, etc..). It's up to the porter |
||||
then to provide its own resource creation function (like. <tt>FT_New_UTF16_Resource</tt>, |
||||
for example) in its version of "<tt>ftsys.c</tt>". |
||||
<p>Note that <tt>FT_New_Resource</tt> will fail and return an error code |
||||
if the font file cannot be found, or when its font format isn't recognized |
||||
by one of the drivers installed in the library. The list or resources created |
||||
for a given library instance is thus the list of "installed font files". |
||||
<br> </blockquote> |
||||
|
||||
<h3> |
||||
3. Stream Manager :</h3> |
||||
|
||||
<blockquote>As said before, resources do not bear states, while streams |
||||
do. Stream creation is also a very lengthy process, depending on the target |
||||
operating system (e.g. "<tt>fopen</tt>" is usually very slow). |
||||
<p>Because a typical font driver will want to use a new stream on each |
||||
access to individual glyphs, being able to cache the most recently used |
||||
streams is a requirement in order to avoid considerable performance penalties. |
||||
<p>Stream caching is thus implemented in the "<tt>ftstream</tt>" component. |
||||
It maintains a simple LRU list of the least recently used streams. Each |
||||
stream in the cache is still opened and available for immediate processing. |
||||
When a resource is destroyed, the stream cache is parsed to remove all |
||||
related cached streams. |
||||
<p>Stream caching can also be disabled with a configuration macro when |
||||
using only ROM based resources (where stream opening is really quick). |
||||
It is implemented through a Stream Manager object (see <tt>ftstream.c</tt>). |
||||
<br> </blockquote> |
||||
|
||||
<h3> |
||||
4. Raster :</h3> |
||||
|
||||
<blockquote>The raster is the component is charge of generating bitmaps |
||||
and anti-aliased pixmaps from vectorial outline definitions. It is also |
||||
sometimes called the scan-line converter. It has been completely rewritten |
||||
for FreeType 2.0 in order to support third-order bezier arcs, 17-levels |
||||
anti-aliasing (through 4x4 sub-sampling), improved performance, as well |
||||
as stand-alone compilation (in order to include it in other graphics package |
||||
without requiring the rest of the FreeType engine). |
||||
<p>Because it was designed for easy re-use and embedded systems, the raster |
||||
is a rtaher 'unusual' piece of code, because it doesn't perform a single |
||||
memory allocation, nor contain any static or global variable. Rather, it |
||||
is up to client applications to allocate a raster object in their own heap |
||||
or memory space. |
||||
<p>Each raster object also needs a rather large block of memory called |
||||
its render pool. The pool is used during rendering (and only during it) |
||||
in order to perform the scan-line conversion. Because it accesses and manages |
||||
data directly within the pool, the raster yelds impressive performance |
||||
as well as bounded memory consumption. It can also automatically decompose |
||||
large requests into smaller individual sub-tasks. |
||||
<p>Finally, it never creates bitmaps or pixmaps, but simply renders into |
||||
them (providing clipping too). These must be described to the raster with |
||||
the help of a <tt>FT_Raster_Map</tt> structure (a very simple bitmap/pixmap |
||||
descriptor). |
||||
<p>Note that when rendering anti-aliased pixmaps, the raster doesn't use |
||||
an intermediate bitmap buffer, as filtering is part of the scan-line conversion |
||||
process. |
||||
<br> </blockquote> |
||||
|
||||
<h3> |
||||
5. Library objects :</h3> |
||||
|
||||
<blockquote>A library object models a single instance of the FreeType engine. |
||||
This is useful when FreeType is compiled as a shared object (DLL), as it |
||||
can then be used by several applications, each with its own resources and |
||||
objects. |
||||
<p>The <tt>FT_Library</tt> type is an opaque handle to a library object. |
||||
Such an object is created through a call to <tt>FT_Init_FreeType</tt>. |
||||
Once you don't need it anymore, one can destroy a library object through |
||||
<tt>FT_Done_FreeType</tt>. |
||||
<p>Note that in reentrant builds, several threads can access a single library |
||||
object concurrently. Such a build can be chosen by switching one configuration |
||||
macro in the file '<tt>arch/<i><system></i>/ftconfig.h</tt>'</blockquote> |
||||
|
||||
<h3> |
||||
6. Driver objects :</h3> |
||||
|
||||
<blockquote>A driver object models an instance of a given font driver, |
||||
i.e. an element of FreeType code in charge of handling a given font format, |
||||
like TrueType, Type1, FNT, PCF, etc.. |
||||
<p>Each library object contains a given set of driver objects when it is |
||||
created through FT_Init_FreeType, this set being determined at compile |
||||
time (see the file 'base/ftapi.c'). However, removing or adding drivers |
||||
is possible at run-time, in order to make upgrades easy.</blockquote> |
||||
|
||||
<h3> |
||||
7. Diagram</h3> |
||||
|
||||
<blockquote>This diagram show the object relationships for the sole base |
||||
layer. The library object is the root of the object graph : |
||||
<center> |
||||
<p><img SRC="objects_diagram.png" height=300 width=562></center> |
||||
|
||||
<p>It can be read as follows : |
||||
<br> |
||||
<ul> |
||||
<li> |
||||
Each library object has one system, one raster and one stream manager objects. |
||||
These objects can only belong to one given library.</li> |
||||
</ul> |
||||
|
||||
<ul> |
||||
<li> |
||||
Each library contains one list of 0 or more resources, as well as one list |
||||
of 0 or more driver objects.</li> |
||||
</ul> |
||||
|
||||
<ul> |
||||
<li> |
||||
Each stream manager holds a bounded list ("0..n" where 'n' is the stream |
||||
cache's size) of stream objects. Each stream is related to one given resource |
||||
object. Each resource may be related to zero or one stream.</li> |
||||
</ul> |
||||
|
||||
<ul> |
||||
<li> |
||||
Each resource is related to one driver object. A driver is related to 0 |
||||
or more resources.</li> |
||||
</ul> |
||||
</blockquote> |
||||
</blockquote> |
||||
|
||||
<p><br> |
||||
<hr WIDTH="100%"> |
||||
<h2> |
||||
IV. Font objects :</h2> |
||||
|
||||
<blockquote>Font objects are used to directly map the information found |
||||
in font files into several categories : |
||||
<br> |
||||
<h3> |
||||
1. Face objects :</h3> |
||||
|
||||
<blockquote>Face objects are used to model individual font faces. They |
||||
encapsulate data which isn't related to a specific character size, or a |
||||
specific glyph or glyph set. Usually, this means : |
||||
<ul> |
||||
<li> |
||||
the font face's family and style names (e.g. "Palatino" + "Regular")</li> |
||||
|
||||
<li> |
||||
some flags indicating which kind of font this is (scalable or fixed ? fixed-width |
||||
or proportional ? horizontal or vertical ? etc…)</li> |
||||
|
||||
<li> |
||||
the number of glyphs, charmaps and eventually fixed character sizes (for |
||||
bitmap formats) found in the font face.</li> |
||||
|
||||
<li> |
||||
for scalable formats, some important metrics like the ascender, descender, |
||||
global font bounding box, maximum advance width, etc.. expressed in notional |
||||
font/grid units (as well as the number of units on the EM grid).</li> |
||||
</ul> |
||||
A face is created from a resource object, with the <tt>FT_New_Face</tt> |
||||
API. Each driver contains a list of opened face objects for the resources |
||||
it manages. When a driver is removed or destroyed, all its child faces |
||||
are discarded automatically with it.</blockquote> |
||||
|
||||
<h3> |
||||
2. Size objects :</h3> |
||||
|
||||
<blockquote>Size objects are used to model a given character dimension |
||||
for a given device resolution (which really means a given character pixel |
||||
dimensions). |
||||
<p>Each size object is created from a parent face object. The object can |
||||
be reset to new dimensions at any time. Each face object holds a list of |
||||
all its child sizes, these are destroyed automatically when the face object |
||||
is discarded. |
||||
<p>The metrics contains metrics, expressed in pixels, for the ascender, |
||||
descender, maximum advance width, etc.. |
||||
<br> </blockquote> |
||||
|
||||
<h3> |
||||
3. Glyph Slot objects :</h3> |
||||
|
||||
<blockquote>A glyph slot is a container where one can load individual glyphs, |
||||
be they in vector of bitmap format. Each slot also contains metrics for |
||||
the glyph it contains. |
||||
<p>Each face object contains one or more glyph slot object : the first |
||||
glyph slot is created automatically with its parent face, and it is possible |
||||
to add new glyph slots (this is rarely used outside of debugging purposes). |
||||
<br> </blockquote> |
||||
|
||||
<h3> |
||||
4. CharMap objects :</h3> |
||||
|
||||
<blockquote>A charmap object is a sort of dictionary whose task is to translate |
||||
character codes in a given character encoding (like ShiftJIS, Unicode, |
||||
ANSI, etc..) into glyph indexes in a given font face. |
||||
<p>A face object contains one or more charmap objects. All charmap objects |
||||
are created when the parent face is created, though they're not directly |
||||
visible to client applications (rather, they can be enumerated through |
||||
FT_Get_First_CharMap and FT_Get_Next_CharMap, or more simply picked adequately |
||||
with FT_Find_CharMap for a set of given encodings). |
||||
<br> </blockquote> |
||||
|
||||
<h3> |
||||
5. Diagram</h3> |
||||
|
||||
<blockquote>The following diagram illustrates the relationships between |
||||
font objects : |
||||
<center> |
||||
<p><img SRC="objects_diagram2.png" height=327 width=561></center> |
||||
|
||||
<p>Which can be read as : |
||||
<br> |
||||
<ul> |
||||
<li> |
||||
each resource may have zero or more child face objects "opened" for it. |
||||
The number of faces is bounded by the number of font faces within the font |
||||
resource.</li> |
||||
</ul> |
||||
|
||||
<ul> |
||||
<li> |
||||
each driver holds a list of all the faces opened for the resources it manages. |
||||
When the driver is removed, its child faces are discarded automatically.</li> |
||||
</ul> |
||||
|
||||
<ul> |
||||
<li> |
||||
each face object has one single parent resource, and one single driver.</li> |
||||
</ul> |
||||
|
||||
<ul> |
||||
<li> |
||||
each face has one or more charmaps, and one or more glyph slots</li> |
||||
</ul> |
||||
|
||||
<ul> |
||||
<li> |
||||
each face holds a list of zero or more child size objects</li> |
||||
</ul> |
||||
|
||||
<ul> |
||||
<li> |
||||
each charmap, glyph slot and size is related to one given parent face. |
||||
These objects are destroyed automatically when the parent face is discarded.</li> |
||||
</ul> |
||||
</blockquote> |
||||
</blockquote> |
||||
|
||||
<p><br> |
||||
<hr WIDTH="100%"> |
||||
<h2> |
||||
V. Driver Interface :</h2> |
||||
|
||||
<blockquote>A font driver is added to a given library object through the |
||||
<tt>FT_Add_Driver</tt> |
||||
API. This function receives a structure known as a <tt>FT_DriverInterface</tt>, |
||||
which describes the driver's basic properties. |
||||
<p>The <tt>FT_DriverInterface</tt> contains a set of function pointers |
||||
used for the base FreeType functionalities. However, each driver can also |
||||
provide a font-format-specific extended interface to allow client applications |
||||
to use more advanced features. |
||||
<br> |
||||
<h3> |
||||
1. Common Interface</h3> |
||||
|
||||
<blockquote>The structure of <tt>FT_DriverInterface</tt> is rather simple, |
||||
and defined in "<tt>base/ftdriver.h</tt>". It must be well known by any |
||||
developer who wants to write a new driver for the engine. We advise reading |
||||
the <b><i>FreeType Driver HowTo</i></b> as well as the source code of existing |
||||
drivers. Source comments.</blockquote> |
||||
|
||||
<h3> |
||||
2. Driver-specific extensions</h3> |
||||
|
||||
<blockquote>The field of the <tt>FT_DriverInterface</tt> structure is a |
||||
typeless pointer to a format-specific interface. This extended interface |
||||
is usually a structure containing function pointers as well as other kind |
||||
of information related to the driver. |
||||
<p>It is assumed that client applications that wish to use the driver-specific |
||||
extensions are able to <tt>#include</tt> the relevant header files to understand |
||||
the format-specific interface structure.</blockquote> |
||||
</blockquote> |
||||
|
||||
<hr WIDTH="100%"> |
||||
<h2> |
||||
VI. Configuration:</h2> |
||||
|
||||
<blockquote>This section relates to the configuration of the FreeType library. |
||||
By configuration, we mean selection of build options as well as the choice |
||||
of font drivers to be used for each new library object. |
||||
<br> |
||||
<h3> |
||||
1. Configuration files :</h3> |
||||
|
||||
<blockquote>A single file is used to configure the FreeType base engine. |
||||
As it is considered system-specific, it is located in the architecture |
||||
directories of the library, under the name "arch/<system>/ftconfig.h". |
||||
Note that the same directory should also contain a platform-specific implementation |
||||
of "ftsys.c". |
||||
<p>The configuration files is a simple C header which is included by the |
||||
engine's sources during compilation. It is not included in "freetype.h", |
||||
and hence doesn't need to be copied when installing the FreeType headers |
||||
on your system. |
||||
<p>It is made of a series of #define or #undef statements, which are used |
||||
to select or turn off a specific option. Each option is documented with |
||||
heavy comments, and some of them are explained below.</blockquote> |
||||
|
||||
<h3> |
||||
2. Building and Makefiles :</h3> |
||||
|
||||
<blockquote>FreeType 2.0 is more complex than its 1.x release. In order |
||||
to facilitate maintenance, as well as ease considerably the writing of |
||||
new font drivers, <b><i>only GNU Make is supported with FreeType 2.0</i></b>. |
||||
However, it is possible to use any compiler, as well as any object or library |
||||
prefix (<tt>.o, .obj, .a, .lib</tt> etc..) with them. |
||||
<p>To build FreeType 2.0, one has to be in the library directory, then |
||||
invoke its platform-specific makefile. For a Unix system, this would be |
||||
: |
||||
<blockquote> |
||||
<blockquote><tt>% cd freetype2/lib</tt> |
||||
<br><tt>% make -f arch/unix/Makefile</tt> |
||||
<p>where '<tt>make</tt>' is really GNU Make !</blockquote> |
||||
</blockquote> |
||||
The system-specific <tt>Makefile</tt> located in '<tt>arch/<i><system></i></tt>' |
||||
is a tiny file used to define several variables. It then includes the file |
||||
<tt>freetype2/lib/Makefile.lib</tt>, |
||||
which contains all the gory details about library compilation. The system-specific |
||||
<tt>Makefile</tt> can be very easily modified to accomodate a new compiler/platform |
||||
(see the comments within one of these files). |
||||
<p>Each font driver is located in a directory like "<tt>freetype2/lib/drivers/<i><formatdir></i></tt>". |
||||
For example, the TrueType driver is located in "<tt>drivers/truetype</tt>". |
||||
Each driver directory must contain a <tt>Makefile</tt> which will be included |
||||
by <tt>Makefile.lib</tt>. The former is used to define and build driver |
||||
object files. |
||||
<br> |
||||
<p><br> |
||||
<center> |
||||
<p><img SRC="build_diagram.png" height=284 width=559></center> |
||||
</blockquote> |
||||
|
||||
<h3> |
||||
3. Make options :</h3> |
||||
|
||||
<blockquote>The base layer, as well as each font driver, are made up of |
||||
several C sources. Traditionally, one compiles each source (i.e. '<tt>.c</tt>' |
||||
file) into an object ('<tt>.o</tt>' or '<tt>.obj</tt>') file, and all of |
||||
them are grouped into a library file (i.e. '<tt>.a</tt>' or '<tt>.lib</tt>'). |
||||
<p>By default, FreeType takes a slightly different approach when it comes |
||||
to compiling each part of the engine. Usually, a single tiny source is |
||||
compiled, which includes all other component sources. This results in a |
||||
single object files, with the benefits or reduced code size, usually better |
||||
compilation as well as a drastic reduction of the number of symbols exported |
||||
by the library. Of course, it is made possible through the use of specific |
||||
declaration macros in the FreeType source (see the definition of <tt>LOCAL_DEF</tt> |
||||
and <tt>LOCAL_FUNC</tt> in <tt>ftconfig.h</tt> for details). |
||||
<p>For a concrete example, see the source code in "<tt>base/ftbase.c</tt>" |
||||
which generates the whole base layer in a single object file. The same |
||||
build process is applied to font drivers, in order to generate one single |
||||
object file per given font format (e.g. <tt>truetype.o</tt>, <tt>type1.o</tt>, |
||||
etc..). |
||||
<p>Compiling the library and drivers in "normal" mode is possible, through |
||||
the use of the '<tt>multi</tt>' target (which really means « multiple |
||||
objects »). For example, calling : |
||||
<blockquote><tt>% make -f arch/ansi/Makefile multi</tt></blockquote> |
||||
Will build the FreeType library by compiling each source file to an individual |
||||
object, then linking them together. You'll notice that the library is significantly |
||||
bigger in this case. Creating a shared dll from a 'multi' build is certainly |
||||
a very poor idea, as this will export a huge quantity of symbols that aren't |
||||
useful to any client application.</blockquote> |
||||
|
||||
<h3> |
||||
4. Adding a driver at compile time</h3> |
||||
|
||||
<blockquote>A driver can be included very easily in the build process by |
||||
including its <tt>Makefile</tt> in <tt>Makefile.lib</tt>. For example, |
||||
the TrueType driver is simply included with the following lines (see <tt>Makefile.lib</tt>): |
||||
<blockquote><tt># TrueType driver rules</tt> |
||||
<br><tt>#</tt> |
||||
<br><tt>include $(DRIVERS_DIR)/truetype/Makefile</tt></blockquote> |
||||
|
||||
<p><br>Where <tt>DRIVERS_DIR</tt> really is "<tt>freetype2/lib/drivers</tt>", |
||||
though this can be redefined. You can, of course specify a different path |
||||
if you want to place your driver sources in another location. |
||||
<p>Note that this only adds the driver's object files to the generated |
||||
library file. A few more steps are needed to make your <tt>FT_Library</tt> |
||||
objects use the driver. They consist in modifying the file "<tt>base/ftinit.c</tt>", |
||||
whose sole purpose is to define the set of driver objects that are to be |
||||
created with each new library object. |
||||
<br> </blockquote> |
||||
|
||||
<h3> |
||||
5. Adding a driver at run time</h3> |
||||
|
||||
<blockquote>New driver objects can be added at run-time through the <tt>FT_Add_Driver</tt> |
||||
API. This function takes a handle to an existing library object, as well |
||||
as a pointer to a given driver interface. This interface is used to create |
||||
a new driver object and register it within the library. |
||||
<p>Similarly, a single driver can be removed from a library anytime through |
||||
<tt>FT_Remove_Driver</tt>. |
||||
This will automatically discard the resources and face objects managed |
||||
by the driver.</blockquote> |
||||
|
||||
<h3> |
||||
6. Custom library objects :</h3> |
||||
|
||||
<blockquote>Finally, it is possible to build custom library objects. You |
||||
need to pass a handle to a valid <tt>FT_System</tt> object to the <tt>FT_Build_Library</tt> |
||||
API. The function will return a handle to the new fresh library object. |
||||
Note that the library has no registered drivers after the call, developers |
||||
have to add them by hand with <tt>FT_Add_Driver</tt>. |
||||
<p>It is thus possible to create two distinct library objects with distinct |
||||
<tt>FT_System</tt> |
||||
implementations in the same session, which can be useful for debugging |
||||
purpose.</blockquote> |
||||
|
||||
<br> </blockquote> |
||||
|
||||
</body> |
||||
</html> |
||||
@ -1,343 +0,0 @@ |
||||
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
||||
<html> |
||||
<head> |
||||
<meta http-equiv="Content-Type" |
||||
content="text/html; charset=iso-8859-1"> |
||||
<meta name="Author" |
||||
content="David Turner"> |
||||
<title>FreeType 2 Internals - I/O Frames</title> |
||||
</head> |
||||
|
||||
<body text="#000000" |
||||
bgcolor="#FFFFFF" |
||||
link="#0000EF" |
||||
vlink="#51188E" |
||||
alink="#FF0000"> |
||||
|
||||
<h1 align=center> |
||||
FreeType 2.0 I/O Frames |
||||
</h1> |
||||
|
||||
<h3 align=center> |
||||
© 2000 David Turner |
||||
(<a href="mailto:david@freetype.org">david@freetype.org</a>)<br> |
||||
© 2000 The FreeType Development Team |
||||
(<a href="http://www.freetype.org">www.freetype.org</a>) |
||||
</h3> |
||||
|
||||
<center> |
||||
<table width="70%"> |
||||
<tr><td> |
||||
|
||||
<hr> |
||||
|
||||
<h2> |
||||
Introduction |
||||
</h2> |
||||
|
||||
<p>This document explains the concept of I/O <b>frames</b> as used in the |
||||
FreeType 2 source code. It also enumerates the various functions and |
||||
macros that can be used to read them.</p> |
||||
|
||||
<p>It is targeted to FreeType hackers, or more simply to developers who |
||||
would like a better understanding of the library's source code.</p> |
||||
|
||||
<hr> |
||||
|
||||
<h2> |
||||
I. What frames are |
||||
</h2> |
||||
|
||||
<p>Simply speaking, a frame is an array of bytes in a font file that is |
||||
`preloaded' into memory in order to be rapidly parsed. Frames are useful |
||||
to ensure that every `load' is checked against end-of-file overruns, and |
||||
provides nice functions to extract data in a variety of distinct |
||||
formats.</p> |
||||
|
||||
<p>But an example is certainly more meaningful than anything else. The |
||||
following code</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
error = read_short( stream, &str.value1 ); |
||||
if ( error ) goto ... |
||||
|
||||
error = read_ulong( stream, &str.value2 ); |
||||
if ( error ) goto ... |
||||
|
||||
error = read_ulong( stream, &str.value3 ); |
||||
if ( error ) goto ...</pre> |
||||
</font> |
||||
|
||||
<p>can easily be replaced with</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
error = FT_Access_Frame( stream, 2 + 4 + 4 ); |
||||
if ( error ) goto ... |
||||
|
||||
str.value1 = FT_Get_Short( stream ); |
||||
str.value2 = FT_Get_ULong( stream ); |
||||
str.value3 = FT_Get_ULong( stream ); |
||||
|
||||
FT_Forget_Frame( stream );</pre> |
||||
</font> |
||||
|
||||
<p>Here, the call to <code>FT_Access_Frame()</code> will</p> |
||||
|
||||
<ul> |
||||
<li> |
||||
<p>Ensure that there are at least 2+4+4=10 bytes left in the |
||||
stream.</p> |
||||
</li> |
||||
<li> |
||||
<p>`Preload' (for disk-based streams) 10 bytes from the current |
||||
stream position.</p> |
||||
</li> |
||||
<li> |
||||
<p>Set the frame `cursor' to the first byte in the frame.</p> |
||||
</li> |
||||
</ul> |
||||
|
||||
<p>Each <code>FT_Get_Short()</code> or <code>FT_Get_ULong()</code> call |
||||
will read a big-endian integer from the stream (2 bytes for |
||||
<code>FT_Get_Short()</code>, 4 bytes for <code>FT_Get_ULong</code>) |
||||
and advance the frame cursor accordingly.</p> |
||||
|
||||
<p><code>FT_Forget_Frame()</code> `releases' the frame from memory.</p> |
||||
|
||||
<p>There are several advantages to using frames:</p> |
||||
|
||||
<ul> |
||||
<li> |
||||
<p>Single-check when loading tables.</p> |
||||
</li> |
||||
<li> |
||||
<p><em>Making code clearer</em> by providing simple parsing functions |
||||
<em>while keeping code safe</em> from file over-runs and invalid |
||||
offsets.</p> |
||||
</li> |
||||
</ul> |
||||
|
||||
<hr> |
||||
|
||||
<h2> |
||||
II. Accessing and reading a frame with macros |
||||
</h2> |
||||
|
||||
<p>By convention in the FreeType source code, macros are able to use two |
||||
implicit variables named <var>error</var> and <var>stream</var>. This is |
||||
useful because these two variables are extremely often used in the |
||||
library, and doing this only reduces our typing requirements and make the |
||||
source code much clearer.</p> |
||||
|
||||
<p>Note that <var>error</var> must be a local variable of type |
||||
<code>FT_Error</code>, while <var>stream</var> must be a local variable or |
||||
argument of type <code>FT_Stream</code>.</p> |
||||
|
||||
<p>The macro used to access a frame is <font |
||||
color="purple"><code><b>ACCESS_Frame(_size_)</b></code></font>, it will |
||||
translate to</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
( error = FT_Access_Frame( stream, _size_ ) ) |
||||
!= FT_Err_Ok</pre> |
||||
</font> |
||||
|
||||
<p>Similarly, the macro <font |
||||
color="purple"><b><code>FORGET_Frame()</code></b></font> translates to</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
FT_Forget_Frame( stream )</pre> |
||||
</font> |
||||
|
||||
<p>Extracting integers can be performed with the <code>GET_xxx()</code> |
||||
macros, like</p> |
||||
|
||||
<table align=center |
||||
cellpadding=5> |
||||
<tr valign="top"> |
||||
<th> |
||||
Macro name |
||||
</th> |
||||
<th> |
||||
Translation |
||||
</th> |
||||
<th> |
||||
Description |
||||
</th> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<font color="purple"><code><b>GET_Byte()</b></code></font> |
||||
</td> |
||||
<td> |
||||
<font color="blue"><code>FT_Get_Byte(stream)</code></font> |
||||
</td> |
||||
<td> |
||||
<p>Reads an 8-bit unsigned byte.</p> |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<font color="purple"><code><b>GET_Char()</b></code></font> |
||||
</td> |
||||
<td> |
||||
<font color="blue"><code>(FT_Char)<br> |
||||
FT_Get_Byte(stream)</code></font> |
||||
</td> |
||||
<td> |
||||
<p>Reads an 8-bit <em>signed</em> byte.</p> |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<font color="purple"><code><b>GET_Short()</b></code></font> |
||||
</td> |
||||
<td> |
||||
<font color="blue"><code>FT_Get_Short(stream)</code></font> |
||||
</td> |
||||
<td> |
||||
Reads a 16-bit signed big-endian integer. |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<font color="purple"><code><b>GET_UShort()</b></code></font> |
||||
</td> |
||||
<td> |
||||
<font color="blue"><code>(FT_UShort)<br> |
||||
FT_Get_Short(stream)</code></font> |
||||
</td> |
||||
<td> |
||||
Reads a 16-bit unsigned big-endian integer. |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<font color="purple"><code><b>GET_Offset()</b></code></font> |
||||
</td> |
||||
<td> |
||||
<font color="blue"><code>FT_Get_Offset(stream)</code></font> |
||||
</td> |
||||
<td> |
||||
Reads a 24-bit signed big-endian integer. |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<font color="purple"><code><b>GET_UOffset()</b></code></font> |
||||
</td> |
||||
<td> |
||||
<font color="blue"><code>(FT_UOffset)<br> |
||||
FT_Get_Offset(stream)</code></font> |
||||
</td> |
||||
<td> |
||||
Reads a 24-bit unsigned big-endian integer. |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<font color="purple"><code><b>GET_Long()</b></code></font> |
||||
</td> |
||||
<td> |
||||
<font color="blue"><code>FT_Get_Long(stream)</code></font> |
||||
</td> |
||||
<td> |
||||
Reads a 32-bit signed big-endian integer. |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<font color="purple"><code><b>GET_ULong()</b></code></font> |
||||
</td> |
||||
<td> |
||||
<font color="blue"><code>(FT_ULong)<br> |
||||
FT_Get_Long(stream)</code></font> |
||||
</td> |
||||
<td> |
||||
Reads a 32-bit unsigned big-endian integer. |
||||
</td> |
||||
</tr> |
||||
</table> |
||||
|
||||
<p>(Note that an <b>Offset</b> is an integer stored with 3 bytes on |
||||
the file.)</p> |
||||
|
||||
<p>All this means that the following code</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
error = FT_Access_Frame( stream, 2 + 4 + 4 ); |
||||
if ( error ) goto ... |
||||
|
||||
str.value1 = FT_Get_Short( stream ); |
||||
str.value2 = FT_Get_ULong( stream ); |
||||
str.value3 = FT_Get_ULong( stream ); |
||||
|
||||
FT_Forget_Frame( stream );</pre> |
||||
</font> |
||||
|
||||
<p>can be simplified with macros:</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
if ( ACCESS_Frame( 2 +4 + 4 ) ) goto ... |
||||
|
||||
str.value1 = GET_Short(); |
||||
str.value2 = GET_ULong(); |
||||
str.value3 = GET_ULong(); |
||||
|
||||
FORGET_Frame();</pre> |
||||
</font> |
||||
|
||||
<p>Which is clearer. Notice that <var>error</var> and <var>stream</var> |
||||
must be defined locally though for this code to work!</p> |
||||
|
||||
<hr> |
||||
|
||||
<h2> |
||||
III. Alternatives |
||||
</h2> |
||||
|
||||
<p>It is sometimes useful to read small integers from a font file without |
||||
using a frame. Some functions have been introduced in FreeType 2 to |
||||
do just that, and they are of the form <font |
||||
color="blue"><code>FT_Read_xxxx</code></font>.</p> |
||||
|
||||
<p>For example, <font color="blue"><code>FT_Read_Short(stream, |
||||
&error)</code></font> reads and returns a 2-byte big-endian integer from a |
||||
<var>stream</var>, and places an error code in the <var>error</var> |
||||
variable.</p> |
||||
|
||||
<p>Thus, reading a single big-endian integer is shorter than using a frame |
||||
for it.</p> |
||||
|
||||
<p>Note that there are also macros <font |
||||
color="purple"><code>READ_xxx()</code></font> which translate to</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
FT_Read_xxx( stream, &error ), error != FT_Err_Ok</pre> |
||||
</font> |
||||
|
||||
<p>and can be used as in</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
if ( READ_UShort( variable1 ) || |
||||
READ_ULong ( variable2 ) ) |
||||
goto Fail;</pre> |
||||
</font> |
||||
|
||||
<p>if <var>error</var> and <var>stream</var> are already defined |
||||
locally.</p> |
||||
|
||||
</td></tr> |
||||
</table> |
||||
</center> |
||||
|
||||
</body> |
||||
</html> |
||||
|
Before Width: | Height: | Size: 1.7 KiB |
|
Before Width: | Height: | Size: 870 B |
|
Before Width: | Height: | Size: 3.8 KiB |
|
Before Width: | Height: | Size: 3.1 KiB |
|
Before Width: | Height: | Size: 1.7 KiB |
@ -1,258 +0,0 @@ |
||||
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
||||
<html> |
||||
<head> |
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
||||
<meta name="Author" content="David Turner"> |
||||
<meta name="GENERATOR" content="Mozilla/4.5 [fr] (Win98; I) [Netscape]"> |
||||
<title>FreeType 2 Internals</title> |
||||
</head> |
||||
<body> |
||||
|
||||
<body text="#000000" |
||||
bgcolor="#FFFFFF" |
||||
link="#0000EF" |
||||
vlink="#51188E" |
||||
alink="#FF0000"> |
||||
|
||||
<center> |
||||
<h1> |
||||
FreeType 2.0 System Interface</h1></center> |
||||
|
||||
<center> |
||||
<h3> |
||||
© 2000 David Turner (<a href="fichier :///david@freetype.org">david@freetype.org</a>)<br> |
||||
© 2000 The FreeType Development Team (<a href="fichier :///devel@freetype.org">devel@freetype.org</a>)</h3></center> |
||||
|
||||
<p><br> |
||||
<hr WIDTH="100%"> |
||||
<br> |
||||
<h2>Introduction:</h2> |
||||
<ul> |
||||
This document explains how the FreeType 2 library performs the low-level and |
||||
system-specific operations of memory management and i/o access. It is targetted |
||||
to FreeType hackers, porters and "advanced" developers who want special |
||||
features like providing their own memory manager or streams. |
||||
<p> |
||||
Note that the only system-specific part of the library is a file |
||||
named "<tt>ftsystem.c</tt>", normally located in the directory |
||||
"<tt>freetype2/config/<system></tt>" where <tt><system></tt> designates |
||||
your platform (e.g. "<tt>config/ansi/ftsystem.c</tt>" or |
||||
"<tt>config/unix/ftsystem.c</tt>"). |
||||
<p> |
||||
</ul> |
||||
|
||||
<p> |
||||
<hr> |
||||
<p> |
||||
|
||||
<h2>I. Memory Management</h2> |
||||
<ul> |
||||
Memory allocation and releases are performed through a <tt>FT_Memory</tt> object in |
||||
FreeType. A <tt>FT_Memory</tt> is nothing more than a table of functions plus |
||||
an arbitrary user data field. It is defined in the file |
||||
"<tt>freetype2/include/ftsystem.h</tt>" and has the following structure: |
||||
<p> |
||||
<ul> |
||||
<tt>typedef struct</tt><br> |
||||
<tt>{</tt> |
||||
<ul> |
||||
<table> |
||||
<tr><td><tt><b>void* user</b></tt> <td> // a user-defined pointer. This is zero by default |
||||
<tr><td><tt><b>void* (*alloc)( FT_System, int)</b></tt> <td> // a function used to allocate a new block |
||||
<tr><td><tt><b>void* (*realloc)( FT_System, int, int, void* )</b></tt><td> // a function used to reallocate a given block |
||||
<tr><td><tt><b>void (*free)( FT_System, void*)</b></tt> <td> // a function used to release a given block |
||||
</table> |
||||
</ul> |
||||
<tt>} FT_MemoryRec, *FT_Memory;</tt><br> |
||||
</ul> |
||||
<p> |
||||
You'll notice that:<p> |
||||
<ul> |
||||
<li>The <tt>FT_Memory</tt> type is really a pointer to a <tt>FT_MemoryRec</tt>. |
||||
This is a normal convention for the FreeType code. |
||||
<li>The <tt>realloc</tt> takes two integer arguments. The first one is the |
||||
current block size, the second one its new size. |
||||
</ul> |
||||
<p> |
||||
|
||||
All current implementations of "<tt>ftsystem.c</tt>" provide a very simple |
||||
implementation of the <tt>FT_Memory</tt> interface by calling directly the |
||||
standard C <tt>alloc</tt>, <tt>realloc</tt> and <tt>free</tt>. |
||||
<p> |
||||
The FreeType source code never invokes directly the function pointers. Rather, |
||||
it calls <tt>FT_Alloc</tt>, <tt>FT_Realloc</tt> and <tt>FT_Free</tt> functions |
||||
which are defined in "<tt>freetype2/src/base/ftobjs.c</tt>". These will not be |
||||
discussed here. |
||||
<p> |
||||
<b>If you want to use your own memory allocator</b> rather than the one provided |
||||
by your build of FreeType, follow these simple steps:<p> |
||||
<ol> |
||||
<li>Create your own <tt>FT_Memory</tt> object, with pointers that map to |
||||
your own memory management routines (beware function signatures though). |
||||
<p> |
||||
<li>Call <tt>FT_Build_Library(memory,&library)</tt>. This will create a new |
||||
<tt>FT_Library</tt> object that uses your own <tt>FT_Memory</tt> exclusively. |
||||
Note however that this library has no font drivers loaded in !! |
||||
<p> |
||||
<li>Load the default font drivers into the new library, either by |
||||
calling <tt>FT_Default_Drivers(library)</tt>, or by adding them manually |
||||
through repeated calls to <tt>FT_Add_Driver(library,&driver_interface)</tt> |
||||
<p> |
||||
</ol> |
||||
This will replace the <tt>FT_Init_FreeType(&library)</tt> call that an application |
||||
must do to initialise one library instance. |
||||
<p> |
||||
Notice that you <em>don't need to recompile FreeType 2 to use your own memory |
||||
manager !!</em>. |
||||
<p> |
||||
</ul> |
||||
|
||||
<p> |
||||
<hr> |
||||
<p> |
||||
|
||||
<h2>II. Streams</h2> |
||||
<ul> |
||||
<h3>1. Basic Stream Structure</h3> |
||||
<p> |
||||
A stream models the array of bytes found in a font file. FreeType 2 separates |
||||
streams into two families :<p> |
||||
<ul> |
||||
<li><b>memory-based streams:</b><br> |
||||
when the stream's content is entirely found in memory. This is the |
||||
case for ROM font files, or memory-mapped files. |
||||
<p> |
||||
<li><b>disk-based streams:</b><br> |
||||
when the stream isn't directly accessible in memory. This is the |
||||
case for local or remote files. |
||||
<p> |
||||
</ul> |
||||
<p> |
||||
Note that a stream's nature only determines how FreeType accesses its content, not |
||||
the way it is effectively stored. For example, in the case of a compressed font file, |
||||
one implementation may choose to uncompress the font in memory, then provide a memory |
||||
based stream to access it. Another one might chose a disk based stream to perform |
||||
on-the-fly decompression of the font data. Similarly, the font file can be stored |
||||
on a local disk, or obtained from a network. This will be completely transparent to |
||||
FreeType. |
||||
<p> |
||||
The stream structure is: |
||||
<p> |
||||
<ul> |
||||
<tt>typedef struct</tt><br> |
||||
<tt>{</tt><br> |
||||
<ul><table> |
||||
<tr><td><tt><b>char* base</b></tt> <td> for memory-based streams, the address |
||||
of its first byte. |
||||
|
||||
<tr><td><tt><b>ulong size</b></tt> <td> the stream's size in bytes. |
||||
|
||||
<tr><td><tt><b>ulong pos</b></tt> <td> the current stream position in the file |
||||
|
||||
<tr><td><tt><b>descriptor</b></tt><td> a union field used to hold either an |
||||
integer file descriptor or pointer. |
||||
This field is not used by FreeType |
||||
itself, but is left to implementations |
||||
of "<tt>ftsystem</tt>" |
||||
<tr><td><tt><b>pathname</b></tt> <td> a union field that can hold either an |
||||
integer or pointer. It is not used by |
||||
FreeType itself, but is left to |
||||
implementations. These can put the |
||||
file pathname's during debugging for |
||||
example. |
||||
|
||||
<tr><td><tt><b>read</b></tt> <td> a pointer to a function used to seek the |
||||
stream and/or read a run of bytes from it. |
||||
|
||||
<tr><td><tt><b>close</b></tt><td> a pointer to a function called when the |
||||
stream is closed. |
||||
|
||||
<tr><td><tt><b>memory</b></tt> <td> a <tt>FT_Memory</tt> object, which is used |
||||
to allocate frames for disk-based streams. |
||||
This field is set and used by FreeType. |
||||
|
||||
<tr><td><tt><b>cursor</b></tt> <td> a pointer in memory used when accessing |
||||
frames. This is set and used by FreeType. |
||||
|
||||
<tr><td><tt><b>limit</b></tt> <td> a pointer in memory used when accessing |
||||
frames. This is set and used by FreeType. |
||||
</table></ul> |
||||
<tt>} FT_StreamRec, *FT_Stream</tt> |
||||
</ul> |
||||
<p> |
||||
|
||||
The following important things must be noticed here:<p> |
||||
<ul> |
||||
<li>The <tt>FT_Stream</tt> type is really a pointer to a <tt>FT_StreamRec</tt>. |
||||
This is a normal convention for the FreeType source. |
||||
<p> |
||||
|
||||
<li>When the <tt>read</tt> field is non NULL, the stream is considered to be |
||||
disk-based. Otherwise, the stream is memory-based, and the <tt>base</tt> |
||||
field <em>must</em> be set by "<tt>ftsystem.c</tt>" when the stream is |
||||
created. |
||||
<p> |
||||
|
||||
<li>The <tt>base</tt> field must be set to 0 when a disk-based stream is created. |
||||
However, this field will later be set and used by the FreeType library when |
||||
accessing frames of bytes within the font file (of course, this doesn't |
||||
happen with memory-based streams). |
||||
</ul> |
||||
|
||||
<h3>2. Stream lifecyles</h3> |
||||
<p> |
||||
Each <tt>FT_Face</tt> needs its own stream to access font data. The most common |
||||
way to create a new <tt>FT_Stream</tt> object is to call the function |
||||
<tt>FT_New_Face</tt>. This function takes a <em>file pathname</em> argument that |
||||
is used to create a new stream object. |
||||
<p> |
||||
This is possible because each implementation of "<tt>ftsystem.c</tt>" provides |
||||
a function called <tt>FT_New_Stream</tt> which takes a file pathname and a |
||||
<tt>FT_Stream</tt> pointer as an argument. The function simply opens the file |
||||
and initialises the stream structure accordingly. It is called by <tt>FT_New_Face</tt> |
||||
to create the face's stream object. |
||||
<p> |
||||
A stream is only closed when the face is destroyed through <tt>FT_Done_Face</tt>. |
||||
Its <tt>close</tt> field function will then be called. Note that the function should |
||||
<em>never</em> destroy the <tt>FT_Stream</tt>. |
||||
<p> |
||||
|
||||
|
||||
<h3>3. Using your own streams</h3> |
||||
<p> |
||||
There are cases where it is interesting to provide your own stream to create |
||||
a new face object, rather than rely on the default implementation. For example, |
||||
a filepathname, which is a C string, might not be useful on a system where files |
||||
are named with a UTF-16 string or via an i-node number of memory address (for ROM files). |
||||
<p> |
||||
For this purpose, the <tt>FT_Open_Face</tt> is defined. It simply takes a |
||||
<tt>FT_Stream</tt> pointer as its second argument, instead of a file pathname (the |
||||
stream must be allocated and initialised by you, so be careful). |
||||
<p> |
||||
Actually, the only thing that <tt>FT_New_Face</tt> does is create a new stream |
||||
through <tt>FT_New_Stream</tt>, then call <tt>FT_Open_Face</tt> to create the |
||||
face with it. |
||||
<p> |
||||
Note also that you can use the function <tt>FT_New_Memory_Face</tt> to create |
||||
a new font face for a memory-based font file, whose address and size can be passed |
||||
as arguments. The function automatically creates the corresponding memory-based |
||||
stream and use it to create the face. |
||||
<p> |
||||
|
||||
</ul> |
||||
|
||||
|
||||
<p> |
||||
<hr> |
||||
<p> |
||||
|
||||
<h2>III. Thread synchronisation</h2> |
||||
<ul> |
||||
The FreeType library uses no static data. It can be used concurrently by two |
||||
thread as long as each one uses its own <tt>FT_Library</tt> instance. Otherwise, |
||||
one can very simply synchronize access to a single library instance by using a |
||||
mutex to protect each call to one of FreeType's API functions. |
||||
<p> |
||||
</ul> |
||||
|
||||
|
||||
@ -1,871 +0,0 @@ |
||||
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> |
||||
<html> |
||||
<head> |
||||
<meta http-equiv="Content-Type" |
||||
content="text/html; charset=iso-8859-1"> |
||||
<meta name="Author" |
||||
content="David Turner"> |
||||
<title>FreeType 2 Tutorial</title> |
||||
</head> |
||||
|
||||
<body text="#000000" |
||||
bgcolor="#FFFFFF" |
||||
link="#0000EF" |
||||
vlink="#51188E" |
||||
alink="#FF0000"> |
||||
|
||||
<h1 align=center> |
||||
FreeType 2.0 Tutorial |
||||
</h1> |
||||
|
||||
<h3 align=center> |
||||
© 2000 David Turner |
||||
(<a href="mailto:david@freetype.org">david@freetype.org</a>)<br> |
||||
© 2000 The FreeType Development Team |
||||
(<a href="http://www.freetype.org">www.freetype.org</a>) |
||||
</h3> |
||||
|
||||
<center> |
||||
<table width="70%"> |
||||
<tr><td> |
||||
|
||||
<hr> |
||||
|
||||
<h2> |
||||
Introduction |
||||
</h2> |
||||
|
||||
<p>This short tutorial will teach you how to use the FreeType 2 |
||||
library in your own applications.</p> |
||||
|
||||
<hr> |
||||
|
||||
<h3> |
||||
1. Header files |
||||
</h3> |
||||
|
||||
<p>To include the main FreeType header file, simply say</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
#include <freetype/freetype.h></pre> |
||||
</font> |
||||
|
||||
<p>in your application code. Note that other files are available in the |
||||
FreeType include directory, most of them being included by |
||||
<tt>"freetype.h"</tt>. They will be described later in this |
||||
tutorial.</p> |
||||
|
||||
<hr> |
||||
|
||||
<h3> |
||||
2. Initialize the library |
||||
</h3> |
||||
|
||||
<p>Simply create a variable of type <tt>FT_Library</tt> named, for |
||||
example, <tt>library</tt>, and call the function |
||||
<tt>FT_Init_FreeType()</tt> as in</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
#include <freetype/freetype.h> |
||||
|
||||
FT_Library library; |
||||
|
||||
... |
||||
|
||||
{ |
||||
... |
||||
error = FT_Init_FreeType( &library ); |
||||
if ( error ) |
||||
{ |
||||
... an error occurred during library initialization ... |
||||
} |
||||
}</pre> |
||||
</font> |
||||
|
||||
<p>This function is in charge of the following:</p> |
||||
|
||||
<ul> |
||||
<li> |
||||
<p>Creating a new instance of the FreeType 2 library, and set |
||||
the handle <tt>library</tt> to it.</p> |
||||
</li> |
||||
<li> |
||||
<p>Load each modules that FreeType knows about in the library. |
||||
This means that by default, your new <tt>library</tt> object is able |
||||
to handle TrueType, Type 1, CID-keyed & OpenType/CFF fonts |
||||
gracefully.</p> |
||||
</li> |
||||
</ul> |
||||
|
||||
<p>As you can see, the function returns an error code, like most others |
||||
in the FreeType API. An error code of 0 <em>always</em> means that |
||||
the operation was successful; otherwise, the value describes the error, |
||||
and <tt>library</tt> is set to NULL.</p> |
||||
|
||||
<hr> |
||||
|
||||
<h3> |
||||
3. Load a font face |
||||
</h3> |
||||
|
||||
<h4> |
||||
a. From a font file |
||||
</h4> |
||||
|
||||
<p>Create a new <em>face</em> object by calling <tt>FT_New_Face</tt>. |
||||
A <em>face</em> describes a given typeface and style. For example, |
||||
"Times New Roman Regular" and "Times New Roman Italic" correspond to |
||||
two different faces.</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
FT_Library library; /* handle to library */ |
||||
FT_Face face; /* handle to face object */ |
||||
|
||||
error = FT_Init_FreeType( &library ); |
||||
if ( error ) { ... } |
||||
|
||||
error = FT_New_Face( library, |
||||
"/usr/share/fonts/truetype/arial.ttf", |
||||
0, |
||||
&face ); |
||||
if ( error == FT_Err_Unknown_File_Format ) |
||||
{ |
||||
... the font file could be opened and read, but it appears |
||||
... that its font format is unsupported |
||||
} |
||||
else if ( error ) |
||||
{ |
||||
... another error code means that the font file could not |
||||
... be opened or read, or simply that it is broken... |
||||
}</pre> |
||||
</font> |
||||
|
||||
<p>As you can certainly imagine, <tt>FT_New_Face</tt> opens a font |
||||
file, then tries to extract one face from it. Its parameters are</p> |
||||
|
||||
<table cellpadding=5> |
||||
<tr valign="top"> |
||||
<td> |
||||
<tt><b>library</b></tt> |
||||
</td> |
||||
<td> |
||||
<p>handle to the FreeType library instance where the face object |
||||
is created</p> |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<tt><b>filepathname</b></tt> |
||||
</td> |
||||
<td> |
||||
<p>the font file pathname (standard C string).</p> |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<tt><b>face_index</b></tt> |
||||
</td> |
||||
<td> |
||||
<p>Certain font formats allow several font faces to be embedded |
||||
in a single file.</p> |
||||
|
||||
<p>This index tells which face you want to load. An error will |
||||
be returned if its value is too large.</p> |
||||
|
||||
<p>Index 0 always work though.</p> |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<tt><b>face</b></tt> |
||||
</td> |
||||
<td> |
||||
<p>A <em>pointer</em> to the handle that will be set to describe |
||||
the new face object.</p> |
||||
|
||||
<p>It is set to NULL in case of error.</p> |
||||
</td> |
||||
</tr> |
||||
</table> |
||||
|
||||
<p>To know how many faces a given font file contains, simply load its |
||||
first face (use <tt>face_index</tt>=0), then see the value of |
||||
<tt>face->num_faces</tt> which indicates how many faces are embedded |
||||
in the font file.</p> |
||||
|
||||
<h4> |
||||
b. From memory |
||||
</h4> |
||||
|
||||
<p>In the case where you have already loaded the font file in memory, |
||||
you can similarly create a new face object for it by calling |
||||
<tt>FT_New_Memory_Face</tt> as in</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
FT_Library library; /* handle to library */ |
||||
FT_Face face; /* handle to face object */ |
||||
|
||||
error = FT_Init_FreeType( &library ); |
||||
if ( error ) { ... } |
||||
|
||||
error = FT_New_Memory_Face( library, |
||||
buffer, /* first byte in memory */ |
||||
size, /* size in bytes */ |
||||
0, /* face_index */ |
||||
&face ); |
||||
if ( error ) { ... }</pre> |
||||
</font> |
||||
|
||||
<p>As you can see, <tt>FT_New_Memory_Face()</tt> simply takes a |
||||
pointer to the font file buffer and its size in bytes instead of a |
||||
file pathname. Other than that, it has exactly the same semantics as |
||||
<tt>FT_New_Face()</tt>.</p> |
||||
|
||||
<h4> |
||||
c. From other sources (compressed files, network, etc.) |
||||
</h4> |
||||
|
||||
<p>There are cases where using a file pathname or preloading the file |
||||
in memory is simply not enough. With FreeType 2, it is possible |
||||
to provide your own implementation of i/o routines.</p> |
||||
|
||||
<p>This is done through the <tt>FT_Open_Face()</tt> function, which |
||||
can be used to open a new font face with a custom input stream, select |
||||
a specific driver for opening, or even pass extra parameters to the |
||||
font driver when creating the object. We advise you to refer to the |
||||
FreeType 2 reference manual in order to learn how to use it.</p> |
||||
|
||||
<p>Note that providing a custom stream might also be used to access a |
||||
TrueType font embedded in a Postscript Type 42 wrapper.</p> |
||||
|
||||
<hr> |
||||
|
||||
<h3> |
||||
4. Accessing face content |
||||
</h3> |
||||
|
||||
<p>A <em>face object</em> models all information that globally describes |
||||
the face. Usually, this data can be accessed directly by dereferencing |
||||
a handle, like</p> |
||||
|
||||
<table cellpadding=5> |
||||
<tr valign="top"> |
||||
<td> |
||||
<tt><b>face->num_glyphs</b></tt> |
||||
</td> |
||||
<td> |
||||
<p>Gives the number of <em>glyphs</em> available in the font face. |
||||
A glyph is simply a character image. It doesn't necessarily |
||||
correspond to a <em>character code</em> though.</p> |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<tt><b>face->flags</b></tt> |
||||
</td> |
||||
<td> |
||||
<p>A 32-bit integer containing bit flags used to describe some |
||||
face properties. For example, the flag |
||||
<tt>FT_FACE_FLAG_SCALABLE</tt> is used to indicate that the face's |
||||
font format is scalable and that glyph images can be rendered for |
||||
all character pixel sizes. For more information on face flags, |
||||
please read the <a href="#">FreeType 2 API Reference</a>.</p> |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<tt><b>face->units_per_EM</b></tt> |
||||
</td> |
||||
<td> |
||||
<p>This field is only valid for scalable formats (it is set to 0 |
||||
otherwise). It indicates the number of font units covered by the |
||||
EM.</p> |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<tt><b>face->num_fixed_sizes</b></tt> |
||||
</td> |
||||
<td> |
||||
<p>This field gives the number of embedded bitmap <em>strikes</em> |
||||
in the current face. A <em>strike</em> is simply a series of |
||||
glyph images for a given character pixel size. For example, a |
||||
font face could include strikes for pixel sizes 10, 12 |
||||
and 14. Note that even scalable font formats can have |
||||
embedded bitmap strikes!</p> |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<tt><b>face->fixed_sizes</b></tt> |
||||
</td> |
||||
<td> |
||||
<p>this is a pointer to an array of <tt>FT_Bitmap_Size</tt> |
||||
elements. Each <tt>FT_Bitmap_Size</tt> indicates the horizontal |
||||
and vertical <em>pixel sizes</em> for each of the strikes that are |
||||
present in the face.</p> |
||||
</td> |
||||
</tr> |
||||
</table> |
||||
|
||||
<p>For a complete listing of all face properties and fields, please read |
||||
the <a href="#">FreeType 2 API Reference</a>.<p> |
||||
|
||||
<hr> |
||||
|
||||
<h3> |
||||
5. Setting the current pixel size |
||||
</h3> |
||||
|
||||
<p>FreeType 2 uses "<em>size objects</em>" to model all |
||||
information related to a given character size for a given face. |
||||
For example, a size object will hold the value of certain metrics |
||||
like the ascender or text height, expressed in 1/64th of a pixel, |
||||
for a character size of 12 points.</p> |
||||
|
||||
<p>When the <tt>FT_New_Face</tt> function is called (or one of its |
||||
cousins), it <b>automatically</b> creates a new size object for |
||||
the returned face. This size object is directly accessible as |
||||
<b><tt>face->size</tt></b>.</p> |
||||
|
||||
<p><em>NOTA BENE: a single face object can deal with one or more size |
||||
objects at a time, however, this is something that few programmers |
||||
really need to do. We have thus have decided to simplify the API for |
||||
the most common use (i.e. one size per face), while keeping this |
||||
feature available through additional fuctions.</em></p> |
||||
|
||||
<p>When a new face object is created, its size object defaults to the |
||||
character size of 10 pixels (both horizontally and vertically) for |
||||
scalable formats. For fixed-sizes formats, the size is more or less |
||||
undefined, which is why you must set it before trying to load a |
||||
glyph.</p> |
||||
|
||||
<p>To do that, simply call <tt>FT_Set_Char_Size()</tt>. Here is an |
||||
example where the character size is set to 16pt for a 300x300 dpi |
||||
device:</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
error = FT_Set_Char_Size( |
||||
face, /* handle to face object */ |
||||
0, /* char_width in 1/64th of points */ |
||||
16*64, /* char_height in 1/64th of points */ |
||||
300, /* horizontal device resolution */ |
||||
300 ); /* vertical device resolution */</pre> |
||||
</font> |
||||
|
||||
<p>You will notice that:</p> |
||||
|
||||
<ul> |
||||
<li> |
||||
<p>The character width and heights are specified in 1/64th of |
||||
points. A point is a <em>physical</em> distance, equaling 1/72th |
||||
of an inch, it's not a pixel..<p> |
||||
</li> |
||||
<li> |
||||
<p>The horizontal and vertical device resolutions are expressed in |
||||
<em>dots-per-inch</em>, or <em>dpi</em>. You can use 72 or |
||||
96 dpi for display devices like the screen. The resolution |
||||
is used to compute the character pixel size from the character |
||||
point size.</p> |
||||
</li> |
||||
<li> |
||||
<p>A value of 0 for the character width means "<em>same as |
||||
character height</em>", a value of 0 for the character height |
||||
means "<em>same as character width</em>". Otherwise, it is possible |
||||
to specify different char widths and heights.</p> |
||||
</li> |
||||
<li> |
||||
<p>Using a value of 0 for the horizontal or vertical resolution means |
||||
72 dpi, which is the default.</p> |
||||
</li> |
||||
<li> |
||||
<p>The first argument is a handle to a face object, not a size |
||||
object. That's normal, and must be seen as a convenience.</p> |
||||
</li> |
||||
</ul> |
||||
|
||||
<p>This function computes the character pixel size that corresponds to |
||||
the character width and height and device resolutions. However, if you |
||||
want to specify the pixel sizes yourself, you can simply call |
||||
<tt>FT_Set_Pixel_Sizes()</tt>, as in</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
error = FT_Set_Pixel_Sizes( |
||||
face, /* handle to face object */ |
||||
0, /* pixel_width */ |
||||
16 ); /* pixel_height */</pre> |
||||
</font> |
||||
|
||||
<p>This example will set the character pixel sizes to 16x16 pixels. |
||||
As previously, a value of 0 for one of the dimensions means |
||||
"<em>same as the other</em>".</p> |
||||
|
||||
<p>Note that both functions return an error code. Usually, an error |
||||
occurs with a fixed-size font format (like FNT or PCF) when trying to |
||||
set the pixel size to a value that is not listed in the |
||||
<tt><b>face->fixed_sizes</b></tt> array.</p> |
||||
|
||||
<hr> |
||||
|
||||
<h3> |
||||
6. Loading a glyph image |
||||
</h3> |
||||
|
||||
<h4> |
||||
a. Converting a character code into a glyph index |
||||
</h4> |
||||
|
||||
<p>Usually, an application wants to load a glyph image based on its |
||||
<em>character code</em>, which is a unique value that defines the |
||||
character for a given <em>encoding</em>. For example, the character |
||||
code 65 represents the `A' in ASCII encoding.</p> |
||||
|
||||
<p>A face object contains one or more tables, called |
||||
<em>charmaps</em>, that are used to convert character codes to glyph |
||||
indices. For example, most TrueType fonts contain two charmaps. One |
||||
is used to convert Unicode character codes to glyph indices, the other |
||||
is used to convert Apple Roman encoding into glyph indices. Such |
||||
fonts can then be used either on Windows (which uses Unicode) and |
||||
Macintosh (which uses Apple Roman, bwerk). Note also that a given |
||||
charmap might not map to all the glyphs present in the font.</p> |
||||
|
||||
<p>By default, when a new face object is created, it lists all the |
||||
charmaps contained in the font face and selects the one that supports |
||||
Unicode character codes if it finds one. Otherwise, it tries to find |
||||
support for Latin-1, then ASCII.</p> |
||||
|
||||
<p>We will describe later how to look for specific charmaps in a face. |
||||
For now, we will assume that the face contains at least a Unicode |
||||
charmap that was selected during <tt>FT_New_Face()</tt>. To convert a |
||||
Unicode character code to a font glyph index, we use |
||||
<tt>FT_Get_Char_Index()</tt> as in</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
glyph_index = FT_Get_Char_Index( face, charcode );</pre> |
||||
</font> |
||||
|
||||
<p>This will look the glyph index corresponding to the given |
||||
<tt>charcode</tt> in the charmap that is currently selected for the |
||||
face. If charmap is selected, the function simply returns the |
||||
charcode.</p> |
||||
|
||||
<p>Note that this is one of the rare FreeType functions that do not |
||||
return an error code. However, when a given character code has no |
||||
glyph image in the face, the value 0 is returned. By convention, |
||||
it always correspond to a special glyph image called the <b>missing |
||||
glyph</b>, which usually is represented as a box or a space.</p> |
||||
|
||||
<h4> |
||||
b. Loading a glyph from the face |
||||
</h4> |
||||
|
||||
<p>Once you have a glyph index, you can load the corresponding glyph |
||||
image. Note that the glyph image can be in several formats. For |
||||
example, it will be a bitmap for fixed-size formats like FNT, FON, or |
||||
PCF. It will also be a scalable vector outline for formats like |
||||
TrueType or Type 1. The glyph image can also be stored in an |
||||
alternate way that is not known at the time of writing this |
||||
documentation.</p> |
||||
|
||||
<p>The glyph image is always stored in a special object called a |
||||
<em>glyph slot</em>. As its name suggests, a glyph slot is simply a |
||||
container that is able to hold one glyph image at a time, be it a |
||||
bitmap, an outline, or something else. Each face object has a single |
||||
glyph slot object that can be accessed as |
||||
<b><tt>face->glyph</tt></b>.</p> |
||||
|
||||
<p>Loading a glyph image into the slot is performed by calling |
||||
<tt>FT_Load_Glyph()</tt> as in</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
error = FT_Load_Glyph( |
||||
face, /* handle to face object */ |
||||
glyph_index, /* glyph index */ |
||||
load_flags ); /* load flags, see below */</pre> |
||||
</font> |
||||
|
||||
<p>The <tt>load_flags</tt> value is a set of bit flags used to |
||||
indicate some special operations. The default value |
||||
<tt>FT_LOAD_DEFAULT</tt> is 0.</p> |
||||
|
||||
<p>This function will try to load the corresponding glyph image |
||||
from the face. Basically, this means that:</p> |
||||
|
||||
<ul> |
||||
<li> |
||||
<p>If a bitmap is found for the corresponding glyph and pixel |
||||
size, it will in the slot (embedded bitmaps are always |
||||
favored over native image formats, because we assume that |
||||
they are higher-quality versions of the same image. This |
||||
can be ignored by using the FT_LOAD_NO_BITMAP flag)</p> |
||||
</li> |
||||
|
||||
<li> |
||||
<p>Otherwise, a native image for the glyph will be loaded. |
||||
It will also be scaled to the current pixel size, as |
||||
well as hinted for certain formats like TrueType and |
||||
Type1.</p> |
||||
</li> |
||||
</ul> |
||||
|
||||
<p>The field <tt><b>glyph->format</b></tt> describe the format |
||||
used to store the glyph image in the slot. If it is not |
||||
<tt>ft_glyph_format_bitmap</tt>, one can immediately |
||||
convert it to a bitmap through <tt>FT_Render_Glyph</tt>, |
||||
as in:</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
error = FT_Render_Glyph( |
||||
face->glyph, /* glyph slot */ |
||||
render_mode ); /* render mode */ |
||||
</pre> |
||||
</font> |
||||
|
||||
<p>The parameter <tt>render_mode</tt> is a set of bit flags used |
||||
to specify how to render the glyph image. Set it to 0 to render |
||||
a monochrome bitmap, or to <tt>ft_render_mode_antialias</tt> to |
||||
generate a high-quality (256 gray levels) anti-aliased bitmap |
||||
from the glyph image.</p> |
||||
|
||||
<p>Once you have a bitmap glyph image, you can access it directly |
||||
through <tt><b>glyph->bitmap</b></tt> (a simple bitmap descriptor), |
||||
and position it through <tt><b>glyph->bitmap_left</b></tt> and |
||||
<tt><b>glyph->bitmap_top</b></tt>.</p> |
||||
|
||||
<p>Note that <tt>bitmap_left</tt> is the horizontal distance from the |
||||
current pen position to the left-most border of the glyph bitmap, |
||||
while <tt>bitmap_top</tt> is the vertical distance from the |
||||
pen position (on the baseline) to the top-most border of the |
||||
glyph bitmap. <em>It is positive to indicate an upwards |
||||
distance</em>.</p> |
||||
|
||||
<p>The next section will detail the content of a glyph slot and |
||||
how to access specific glyph information (including metrics).</p> |
||||
|
||||
<h4> |
||||
c. Using other charmaps |
||||
</h4> |
||||
|
||||
<p>As said before, when a new face object is created, it will look for |
||||
a Unicode, Latin-1, or ASCII charmap and select it. The currently |
||||
selected charmap is accessed via <b><tt>face->charmap</tt></b>. This |
||||
field is NULL when no charmap is selected, which typically happens |
||||
when you create a new <tt>FT_Face</tt> object from a font file that |
||||
doesn't contain an ASCII, Latin-1, or Unicode charmap (rare |
||||
stuff).</p> |
||||
|
||||
<p>There are two ways to select a different charmap with FreeType 2. |
||||
The easiest is when the encoding you need already has a corresponding |
||||
enumeration defined in <tt><freetype/freetype.h></tt>, as |
||||
<tt>ft_encoding_big5</tt>. In this case, you can simply call |
||||
<tt>FT_Select_CharMap</tt> as in:</p> |
||||
|
||||
<font color="blue"><pre> |
||||
error = FT_Select_CharMap( |
||||
face, /* target face object */ |
||||
ft_encoding_big5 ); /* encoding.. */ |
||||
</pre></font> |
||||
|
||||
<p>Another way is to manually parse the list of charmaps for the |
||||
face, this is accessible through the fields |
||||
<tt><b>num_charmaps</b></tt> and <tt><b>charmaps</b></tt> |
||||
(notice the 's') of the face object. As you could expect, |
||||
the first is the number of charmaps in the face, while the |
||||
second is <em>a table of pointers to the charmaps</em> |
||||
embedded in the face.</p> |
||||
|
||||
<p>Each charmap has a few visible fields used to describe it more |
||||
precisely. Mainly, one will look at |
||||
<tt><b>charmap->platform_id</b></tt> and |
||||
<tt><b>charmap->encoding_id</b></tt> that define a pair of |
||||
values that can be used to describe the charmap in a rather |
||||
generic way.</p> |
||||
|
||||
<p>Each value pair corresponds to a given encoding. For example, |
||||
the pair (3,1) corresponds to Unicode. Their list is |
||||
defined in the TrueType specification but you can also use the |
||||
file <tt><freetype/ftnameid.h></tt> which defines several |
||||
helpful constants to deal with them..</p> |
||||
|
||||
<p>To look for a specific encoding, you need to find a corresponding |
||||
value pair in the specification, then look for it in the charmaps |
||||
list. Don't forget that some encoding correspond to several |
||||
values pair (yes it's a real mess, but blame Apple and Microsoft |
||||
on such stupidity..). Here's some code to do it:</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
FT_CharMap found = 0; |
||||
FT_CharMap charmap; |
||||
int n; |
||||
|
||||
for ( n = 0; n < face->num_charmaps; n++ ) |
||||
{ |
||||
charmap = face->charmaps[n]; |
||||
if ( charmap->platform_id == my_platform_id && |
||||
charmap->encoding_id == my_encoding_id ) |
||||
{ |
||||
found = charmap; |
||||
break; |
||||
} |
||||
} |
||||
|
||||
if ( !found ) { ... } |
||||
|
||||
/* now, select the charmap for the face object */ |
||||
error = FT_Set_CharMap( face, found ); |
||||
if ( error ) { ... }</pre> |
||||
</font> |
||||
|
||||
<p>Once a charmap has been selected, either through |
||||
<tt>FT_Select_CharMap</tt> or <tt>FT_Set_CharMap</tt>, |
||||
it is used by all subsequent calls to |
||||
<tt>FT_Get_Char_Index()</tt>.</p> |
||||
|
||||
|
||||
<h4> |
||||
d. Glyph Transforms: |
||||
</h4> |
||||
|
||||
<p>It is possible to specify an affine transformation to be applied |
||||
to glyph images when they're loaded. Of course, this will only |
||||
work for scalable (vectorial) font formats.</p> |
||||
|
||||
<p>To do that, simply call <tt>FT_Set_Transform</tt>, as in:</p> |
||||
|
||||
<font color="blue"><pre> |
||||
error = FT_Set_Transform( |
||||
face, /* target face object */ |
||||
&matrix, /* pointer to 2x2 matrix */ |
||||
&delta ); /* pointer to 2d vector */ |
||||
</pre></font> |
||||
|
||||
<p>This function will set the current transform for a given face |
||||
object. Its second parameter is a pointer to a simple |
||||
<tt>FT_Matrix</tt> structure that describes a 2x2 affine matrix. |
||||
The third parameter is a pointer to a <tt>FT_Vector</tt> structure |
||||
that describe a simple 2d vector.</p> |
||||
|
||||
<p>Note that the matrix pointer can be set to NULL, (in which case |
||||
the identity transform will be used). Coefficients of the matrix |
||||
are in 16.16 fixed float units.</p> |
||||
|
||||
<p>The vector pointer can also be set to NULL (in which case a delta |
||||
of (0,0) will be used). The vector coordinates are expressed in |
||||
1/64th of a pixel (also known as 26.6 fixed floats).</p> |
||||
|
||||
<p><em>NOTA BENE: The transform is applied every glyph that is loaded |
||||
through <tt>FT_Load_Glyph</tt>. Note that loading a glyph bitmap |
||||
with a non-trivial transform will produce an error..</em></p> |
||||
|
||||
<hr> |
||||
|
||||
<h3> |
||||
7. Accessing glyph image data |
||||
</h3> |
||||
|
||||
<p>Glyph image data is accessible through <tt><b>face->glyph</b></tt>. |
||||
See the definition of the <tt>FT_GlyphSlot</tt> type for more details. |
||||
As stated previously, each face has a single glyph slot, where |
||||
<em>one</em> glyph image <em>at a time</em> can be loaded. Each time |
||||
you call <tt>FT_Load_Glyph()</tt>, you erase the content of the glyph |
||||
slot with a new glyph image.</p> |
||||
|
||||
<p>Note however that the glyph slot object itself doesn't change, only |
||||
its content, which means that you can perfectly create a "shortcut" to |
||||
access it as in</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
{ |
||||
/* shortcut to glyph slot */ |
||||
FT_GlyphSlot glyph = face->glyph; |
||||
|
||||
for ( n = 0; n < face->num_glyphs; n++ ) |
||||
{ |
||||
... load glyph n ... |
||||
... access glyph data as glyph->xxxx |
||||
} |
||||
}</pre> |
||||
</font> |
||||
|
||||
<p>The <tt>glyph</tt> variable will be valid until its parent |
||||
<tt>face</tt> is destroyed. Here are a few important fields of the |
||||
glyph slot:<p> |
||||
|
||||
<table cellpadding=5> |
||||
<tr valign="top"> |
||||
<td> |
||||
<tt><b>glyph->format</b></tt> |
||||
</td> |
||||
<td> |
||||
<p>Indicates the type of the loaded glyph image. Can be either |
||||
<tt>ft_glyph_format_bitmap</tt>, <tt>ft_glyph_format_outline</tt>, |
||||
or other values.</p> |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<tt><b>glyph->metrics</b></tt> |
||||
</td> |
||||
<td> |
||||
<p>A simple structure used to hold the glyph image's metrics. |
||||
Note that <em>most distances are expressed in 1/64th of |
||||
pixels!</em> See the API reference or the user guide for a |
||||
description of the <tt>FT_Glyph_Metrics</tt> structure.</p> |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<tt><b>glyph->bitmap</b></tt> |
||||
</td> |
||||
<td> |
||||
<p>If the glyph slot contains a bitmap, a simple |
||||
<tt>FT_Bitmap</tt> that describes it. See the API reference or |
||||
user guide for a description of the <tt>FT_Bitmap</tt> |
||||
structure.</p> |
||||
</td> |
||||
</tr> |
||||
<tr valign="top"> |
||||
<td> |
||||
<tt><b>glyph->outline</b></tt> |
||||
</td> |
||||
<td> |
||||
<p>When the glyph slot contains a scalable outline, this structure |
||||
describes it. See the definition of the <tt>FT_Outline</tt> |
||||
structure.</p> |
||||
</td> |
||||
</tr> |
||||
</table> |
||||
|
||||
<h3> |
||||
8. Rendering glyph outlines into bitmaps |
||||
</h3> |
||||
|
||||
<p>You can easily test the format of the glyph image by inspecting the |
||||
<tt>face->glyph->format</tt> variable. If its value is |
||||
<tt>ft_glyph_format_bitmap</tt>, the glyph image that was loaded is a |
||||
bitmap that can be directly blit to your own surfaces through your |
||||
favorite graphics library (FreeType 2 doesn't provide bitmap |
||||
blitting routines, as you may imagine :-)</p> |
||||
|
||||
<p>If the format is <tt>ft_glyph_format_outline</tt> or something else, |
||||
the library provides a means to convert such glyph images to bitmaps |
||||
through what are called <b>rasters</b>.</p> |
||||
|
||||
<p>On the other hand, if the image is a scalable outline or something |
||||
else, FreeType provides a function to convert the glyph image into a |
||||
pre-existing bitmap that you will handle to it, named |
||||
<tt>FT_Get_Glyph_Bitmap</tt>. Here's a <em>simple</em> example code |
||||
that renders an outline into a <b>monochrome</b> bitmap:</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
{ |
||||
FT_GlyphSlot glyph; |
||||
|
||||
... load glyph ... |
||||
|
||||
glyph = face->glyph; /* shortcut to glyph data */ |
||||
if ( glyph->format == ft_glyph_format_outline ) |
||||
{ |
||||
FT_Bitmap bit; |
||||
|
||||
/* set-up a bitmap descriptor for our target bitmap */ |
||||
bit.rows = bitmap_height; |
||||
bit.width = bitmap_width; |
||||
bit.pitch = bitmap_row_bytes; |
||||
/* render into a mono bitmap */ |
||||
bit.pixel_mode = ft_pixel_mode_mono; |
||||
bit.buffer = bitmap_buffer; |
||||
|
||||
/* render the outline directly into the bitmap */ |
||||
error = FT_Get_Glyph_Bitmap( face, &bit ); |
||||
if ( error ) { ... } |
||||
} |
||||
}</pre> |
||||
</font> |
||||
|
||||
<p>You should note that <b><em><tt>FT_Get_Glyph_Bitmap()</tt> doesn't |
||||
create the bitmap</em></b>. It only needs a descriptor, of type |
||||
<tt>FT_Bitmap</tt>, and writes directly into it.</p> |
||||
|
||||
<p>Note that the FreeType scan-converter for outlines can also generate |
||||
anti-aliased glyph bitmaps with 128 level of grays. For now, it is |
||||
restricted to rendering to 8-bit gray-level bitmaps, though this may |
||||
change in the future. Here is some code to do just that:</p> |
||||
|
||||
<font color="blue"> |
||||
<pre> |
||||
{ |
||||
FT_GlyphSlot glyph; |
||||
|
||||
... load glyph ... |
||||
|
||||
glyph = face->glyph; /* shortcut to glyph data */ |
||||
if ( glyph->format == ft_glyph_format_outline ) |
||||
{ |
||||
FT_Bitmap bit; |
||||
|
||||
/* set-up a bitmap descriptor for our target bitmap */ |
||||
bit.rows = bitmap_height; |
||||
bit.width = bitmap_width; |
||||
bit.pitch = bitmap_row_bytes; |
||||
/* 8-bit gray-level bitmap */ |
||||
bit.pixel_mode = ft_pixel_mode_gray; |
||||
/* MUST be 128 for now */ |
||||
bit.grays = 128; |
||||
bit.buffer = bitmap_buffer; |
||||
|
||||
/* clean the bitmap - IMPORTANT */ |
||||
memset( bit.buffer, 0, bit.rows*bit.pitch ); |
||||
|
||||
/* render the outline directly into the bitmap */ |
||||
error = FT_Get_Glyph_Bitmap( face, &bit ); |
||||
if ( error ) { ... } |
||||
} |
||||
}</pre> |
||||
</font> |
||||
|
||||
<p>You will notice that</p> |
||||
|
||||
<ul> |
||||
<li> |
||||
<p>As previously, <tt>FT_Get_Glyph_Bitmap()</tt> doesn't generate |
||||
the bitmap, it simply renders to it.</p> |
||||
</li> |
||||
<li> |
||||
<p>The target bitmap must be cleaned before calling the function. |
||||
This is a limitation of our current anti-aliasing algorithm and is |
||||
EXTREMELY important.</p> |
||||
</li> |
||||
<li> |
||||
<p>The anti-aliaser uses 128 levels of grays exclusively for |
||||
now (this will probably change in a near future). This means that |
||||
you <b>must</b> set <tt>bit.grays</tt> to 128. The generated |
||||
image uses values from 0 (back color) to 127 (foreground color).</p> |
||||
</li> |
||||
<li> |
||||
<p>It is <b>not</b> possible to render directly an anti-aliased |
||||
outline into a pre-existing gray-level bitmap, or even any |
||||
colored-format one (like RGB16 or paletted 8-bits). We will not |
||||
discuss this issue in great details here, but the reason is that we |
||||
do not want to deal with graphics composition (or alpha-blending) |
||||
within FreeType.<p/> |
||||
</li> |
||||
</ul> |
||||
</td></tr> |
||||
</table> |
||||
</center> |
||||
|
||||
</body> |
||||
</html> |
||||
Loading…
Reference in new issue