shithub: freetype+ttf2subf

git/fs: mount .git/fs: mount/attach disallowed

--- /dev/null

+++ b/docs/design/build-system.html

@@ -1,0 +1,359 @@

+<!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>

+</head>

+<body>

+<body text="#000000"

+      bgcolor="#FFFFFF"

+      link="#0000EF"

+      vlink="#51188E"

+      alink="#FF0000">

+<center>

+<h1>

+FreeType 2.0 Build System</h1></center>

+<center>

+<h3>

+&copy; 2000 David Turner (<a href="fichier :///[email protected]">[email protected]</a>)<br>

+&copy; 2000 The FreeType Development Team

+(<a href="mailto:[email protected]">[email protected]</a>)

+</h3></center>

+<p><br>

+<hr WIDTH="100%">

+<br>&nbsp;

+<h2>Introduction:</h2>

+<ul>

+	This document describes the new build system that was introduced

+    with FreeType 2.

+</ul>

+<p><hr><p>

+<h2>I. Features and Background:</h2>

+<ul>

+	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. To

+	understand it properly, it must be noticed that:<p>

+	<ul>

+		<li>The build system is made of a <em>single Makefile</em>,

+			dispatched over several directories with the help of the

+			<tt>include</tt> directive. Technically speaking, it is

+			composed of the top-level "<tt>freetype2/Makefile</tt>"

+			which includes several other sub-Makefiles, whose extension

+			is always "<tt>.mk</tt>". Examples are:<p>

+			<ul>

+				<tt>freetype2/config/freetype.mk</tt><br>

+				<tt>freetype2/config/<em>system</em>/detect.mk</tt><br>

+				<tt>freetype2/src/<em>module</em>/rules.mk</tt><br>

+				etc..

+			</ul>

+			<p>

+			<font size="+2" color="red">

+			We <em>strongly</em> recommend the following article:<p>

+			<center>

+			  <a href="http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html">

+			  Recursive Make Considered Dangerous

+			  </a>

+			</center>

+			</font>

+			<p>

+			To understand why such a layout was chosen.

+			<p>

+		<li>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>

+			<em>You 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>

+			Note that we have <em>no plans</em> to support a different

+			make tool, as you'll rapidly understand by reading this

+			document or looking at the Makefiles themselves.

+			<p>

+	</ul>

+	<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>

+			The system-specific <b><tt>config.mk</tt></b> created when

+			running <tt>make</tt> for the first time contains various

+			definitions, including compiler, compiler flags, object files

+			directories, etc.. However, a given platform has often several

+			compilers available, each with a different name and flags to be

+			used. Rather than trying to detect the compiler in the build

+			system, users can also specify which compiler they use when

+			running <tt>make</tt>.

+			<p>

+			For example, on Win32 platforms:<p>

+			<ul>

+				<table>

+					<tr valign="top">

+					<td><b><tt>make&nbsp;setup</tt></b>

+					<td>Will generate a <tt>config.mk</tt> that

+					    can be used to compile the library with

+						<b><tt>gcc</tt></b> (<em>which is the default

+						compiler for most supported platforms</em>).

+					<tr valign="top">

+					<td><b><tt>make&nbsp;setup&nbsp;visualc</tt></b>

+					<td>Will generate a different <tt>config.mk</tt>

+					    that can be used to compile the library

+						with the Visual C++ command-line compiler.

+					<tr valign="top">

+					<td><b><tt>make&nbsp;setup&nbsp;lcc</tt></b>

+					<td>Will generate a different <tt>config.mk</tt>

+						that can be used to compile the library

+						with the Win32-LCC compiler.

+				</table>

+			</ul>

+			<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&nbsp;</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>

binary files /dev/null b/docs/design/demo-programs.png differ

binary files /dev/null b/docs/design/drivers-list.png differ

--- /dev/null

+++ b/docs/design/index.html

@@ -1,0 +1,788 @@

+<!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.0</h2></center>

+<center>

+<h3>

+&copy; 1999 David Turner (<a href="fichier :///[email protected]">[email protected]</a>)<br>

+&copy; 1999 The FreeType Development Team (<a href="fichier :///[email protected]">[email protected]</a>)</h3></center>

+<p><br>

+<hr WIDTH="100%">

+<br>&nbsp;

+<h2>

+Introduction:</h2>

+<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>&nbsp;

+<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>&nbsp;</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>&nbsp;</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 &amp; 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>&nbsp;</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>&nbsp;

+<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&nbsp; 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>&nbsp;

+<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>&nbsp; �</tt>

+<br><tt>&nbsp; FT_Error&nbsp; error;</tt>

+<p><tt>&nbsp; error = FT_Access_Frame( stream, 14 );</tt>

+<br><tt>&nbsp; if (error) goto Fail;</tt>

+<p><tt>&nbsp; val1 = FT_Get_Short(stream);</tt>

+<br><tt>&nbsp; val2 = FT_Get_Long(stream);</tt>

+<br><tt>&nbsp; val3 = FT_Get_Long(stream);</tt>

+<br><tt>&nbsp; val4 = FT_Get_Long(stream);</tt>

+<p><tt>&nbsp; FT_Forget_Frame(stream);</tt>

+<br><tt>&nbsp; �</tt>

+<br><tt>}</tt></blockquote>

+This code does the following :

+<blockquote>

+<ol>

+<li>

+&nbsp;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>

+&nbsp;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>

+&nbsp;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>&lt;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>&nbsp;</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>&nbsp;</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>&nbsp;</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&nbsp; 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>&lt;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>&nbsp;

+<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>&nbsp;

+<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>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;

+<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>&nbsp;

+<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>&nbsp;

+<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/&lt;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>&lt;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>&lt;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>&nbsp;

+<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 &laquo; multiple

+objects &raquo;). 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>&nbsp;</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>&nbsp;</blockquote>

+</body>

+</html>

--- /dev/null

+++ b/docs/design/io-frames.html

@@ -1,0 +1,247 @@

+<!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>

+</head>

+<body>

+<body text="#000000"

+      bgcolor="#FFFFFF"

+      link="#0000EF"

+      vlink="#51188E"

+      alink="#FF0000">

+<center>

+<h1>

+FreeType 2.0 I/O Frames</h1></center>

+<center>

+<h3>

+&copy; 2000 David Turner (<a href="mailto:[email protected]">[email protected]</a>)<br>

+&copy; 2000 The FreeType Development Team (<a href="http://www.freetype.org">www.freetype.org</a>)</h3></center>

+<p><br>

+<hr WIDTH="100%">

+<br>&nbsp;

+<h2>Introduction:</h2>

+<ul>

+  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>

+  It is targetted to FreeType hackers, or more simply to developers who would

+  like a better understanding of the library's source code.

+</ul>

+<p><hr><p>

+<h2>I. What frames are:</h2>

+<ul>

+  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>

+  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>

+  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 <tt>FT_Access_Frame</tt> will:<p>

+  <ul>

+	  <li>Ensure that there are at least 2+4+4=10 bytes left in the stream.

+	  <li>"Preload" (for disk-based streams) 10 bytes from the current

+          stream position.

+	  <li>Set the frame "cursor" to the first byte in the frame;

+  </ul>

+  <p>

+  Each <tt>FT_Get_Short</tt> or <tt>FT_Get_ULong</tt> call will read a

+  big-endian integer from the stream (2 bytes for <tt>FT_Get_Short</tt>,

+  4 bytes for <tt>FT_Get_ULong</tt>) and advance the frame cursor accordingly.

+  <p>

+  <tt>FT_Forget_Frame</tt> "releases" the frame from memory

+  <p>

+  There are several advantages to using frames :<p>

+  <ul>

+	  <li>single-check when loading tables

+	  <li><em>making code clearer</em> by providing simple parsing functions

+             <em>while keeping code safe</em> from file over-runs and invalid

+             offsets.

+  </ul>

+  <p>

+</ul>

+<p><hr><p>

+<h2>II. Accessing and reading a frame with macros:</h2>

+<ul>

+	By convention in the FreeType source code, macros are able to use two implicit

+	variables named "<tt>error</tt>" and "<tt>stream</tt>". This is useful because

+	these two variables are extremely used in the library, and doing this only

+	reduces our typing requirements and make the source code much clearer.

+	<p>

+	Note that <tt>error</tt> must be a local variable of type <tt>FT_Error</tt>,<br>

+	while <tt>stream</tt> must be a local variable or argument of type <tt>FT_Stream</tt>;

+	<p>

+	The macro used to access a frame is

+    <font color="purple"><tt><b>ACCESS_Frame(_size_)</b></tt></font>, it will

+	translate to:<p>

+	<ul><font color="blue">

+		<tt>(error=FT_Access_Frame(stream,_size_)) != FT_Err_Ok</tt>.

+	</font></ul>

+	<p>

+	Similarly, the macro

+    <font color="purple"><b><tt>FORGET_Frame()</tt></b></font>

+    translates to:<p>

+	<ul><font color="blue">

+		<tt>FT_Forget_Frame(stream)</tt>

+	</font></ul>

+	<p>

+	Extracting integers can be performed with the <tt>GET_xxx</tt> macros, like:<p>

+	<ul>

+		<table>

+			<tr>

+                <td><b>Macro name</b>    <td>Translation  <td>Description

+            <tr><td><font color="purple"><tt><b>

+                GET_Byte()

+                </b></tt></font><td><font color="blue"><tt>

+                (FT_Get_Byte(stream))

+                </tt></font><td>

+                reads an 8-bit unsigned byte

+            <tr><td><font color="purple"><tt><b>

+                GET_Char()

+                </b></tt></font><td><font color="blue"><tt>

+                ((FT_Char)FT_Get_Byte(stream))

+                </tt></font><td>

+                reads an 8-bit <em>signed</em> byte

+            <tr><td><font color="purple"><tt><b>

+                GET_Short()

+                </b></tt></font><td><font color="blue"><tt>

+                (FT_Get_Short(stream))

+                </tt></font><td>

+                reads a 16-bit signed big-endian integer

+            <tr><td><font color="purple"><tt><b>

+                GET_UShort()

+                </b></tt></font><td><font color="blue"><tt>

+                ((FT_UShort)FT_Get_Short(stream))

+                </tt></font><td>

+                reads a 16-bit unsigned big-endian integer

+            <tr><td><font color="purple"><tt><b>

+                GET_Offset()

+                </b></tt></font><td><font color="blue"><tt>

+                (FT_Get_Offset(stream))

+                </tt></font><td>

+                reads a 24-bit signed big-endian integer

+            <tr><td><font color="purple"><tt><b>

+                GET_UOffset()

+                </b></tt></font><td><font color="blue"><tt>

+                ((FT_UOffset)FT_Get_Offset(stream))

+                </tt></font><td>

+                reads a 24-bit unsigned big-endian integer

+            <tr><td><font color="purple"><tt><b>

+                GET_Long()

+                </b></tt></font><td><font color="blue"><tt>

+                (FT_Get_Long(stream))

+                </tt></font><td>

+                reads a 32-bit signed big-endian integer

+            <tr><td><font color="purple"><tt><b>

+                GET_ULong()

+                </b></tt></font><td><font color="blue"><tt>

+                ((FT_ULong)FT_Get_Long(stream))

+                </tt></font><td>

+                reads a 32-bit unsigned big-endian integer

+		</table>

+	</ul>

+	<p>

+	(Note that an <b>Offset</b> is an integer stored with 3 bytes on the file).

+    <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);<br>

+	</pre></font>

+	<p>

+	Can be replaced with macros by:<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 <b>error</b> and <b>stream</b> must be defined

+	locally though for this code to work.. !!

+</ul>

+<p><hr><p>

+<h2>III. Alternatives:</h2>

+<ul>

+  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"><tt>FT_Read_xxxx</tt></font>.

+  <p>

+  For example,

+  <font color="blue"><tt>FT_Read_Short( stream, &error )</tt></font> reads and

+  returns a 2-byte big-endian integer from a <tt>stream</tt>, and place an

+  error code in the <tt>error</tt> variable.

+  <p>

+  Thus, reading a single big-endian integer is shorter than using a frame

+  for it.

+  <p>

+  Note that there is also the macros

+  <font color="purple"><tt>READ_xxx()</tt></font> which translate to:<p>

+  <font color="blue"><pre>

+    <tt>( 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>

+  when <b>error</b> and <b>stream</b> are already defined locally..

+</ul>

binary files /dev/null b/docs/design/library-compilation.png differ

binary files /dev/null b/docs/design/logo1.png differ

binary files /dev/null b/docs/design/objects_diagram.png differ

binary files /dev/null b/docs/design/objects_diagram2.png differ

binary files /dev/null b/docs/design/platform-detection.png differ

--- /dev/null

+++ b/docs/design/system-interface.html

@@ -1,0 +1,258 @@

+<!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>

+&copy; 2000 David Turner (<a href="fichier :///[email protected]">[email protected]</a>)<br>

+&copy; 2000 The FreeType Development Team (<a href="fichier :///[email protected]">[email protected]</a>)</h3></center>

+<p><br>

+<hr WIDTH="100%">

+<br>&nbsp;

+<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/&lt;system&gt;</tt>" where <tt>&lt;system&gt;</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>

--- a/docs/internals/build-system.html

+++ /dev/null

@@ -1,359 +1,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>

-</head>

-<body>

-<body text="#000000"

-      bgcolor="#FFFFFF"

-      link="#0000EF"

-      vlink="#51188E"

-      alink="#FF0000">

-<center>

-<h1>

-FreeType 2.0 Build System</h1></center>

-<center>

-<h3>

-&copy; 2000 David Turner (<a href="fichier :///[email protected]">[email protected]</a>)<br>

-&copy; 2000 The FreeType Development Team

-(<a href="mailto:[email protected]">[email protected]</a>)

-</h3></center>

-<p><br>

-<hr WIDTH="100%">

-<br>&nbsp;

-<h2>Introduction:</h2>

-<ul>

-	This document describes the new build system that was introduced

-    with FreeType 2.

-</ul>

-<p><hr><p>

-<h2>I. Features and Background:</h2>

-<ul>

-	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. To

-	understand it properly, it must be noticed that:<p>

-	<ul>

-		<li>The build system is made of a <em>single Makefile</em>,

-			dispatched over several directories with the help of the

-			<tt>include</tt> directive. Technically speaking, it is

-			composed of the top-level "<tt>freetype2/Makefile</tt>"

-			which includes several other sub-Makefiles, whose extension

-			is always "<tt>.mk</tt>". Examples are:<p>

-			<ul>

-				<tt>freetype2/config/freetype.mk</tt><br>

-				<tt>freetype2/config/<em>system</em>/detect.mk</tt><br>

-				<tt>freetype2/src/<em>module</em>/rules.mk</tt><br>

-				etc..

-			</ul>

-			<p>

-			<font size="+2" color="red">

-			We <em>strongly</em> recommend the following article:<p>

-			<center>

-			  <a href="http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html">

-			  Recursive Make Considered Dangerous

-			  </a>

-			</center>

-			</font>

-			<p>

-			To understand why such a layout was chosen.

-			<p>

-		<li>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>

-			<em>You 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>

-			Note that we have <em>no plans</em> to support a different

-			make tool, as you'll rapidly understand by reading this

-			document or looking at the Makefiles themselves.

-			<p>

-	</ul>

-	<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>

-			The system-specific <b><tt>config.mk</tt></b> created when

-			running <tt>make</tt> for the first time contains various

-			definitions, including compiler, compiler flags, object files

-			directories, etc.. However, a given platform has often several

-			compilers available, each with a different name and flags to be

-			used. Rather than trying to detect the compiler in the build

-			system, users can also specify which compiler they use when

-			running <tt>make</tt>.

-			<p>

-			For example, on Win32 platforms:<p>

-			<ul>

-				<table>

-					<tr valign="top">

-					<td><b><tt>make&nbsp;setup</tt></b>

-					<td>Will generate a <tt>config.mk</tt> that

-					    can be used to compile the library with

-						<b><tt>gcc</tt></b> (<em>which is the default

-						compiler for most supported platforms</em>).

-					<tr valign="top">

-					<td><b><tt>make&nbsp;setup&nbsp;visualc</tt></b>

-					<td>Will generate a different <tt>config.mk</tt>

-					    that can be used to compile the library

-						with the Visual C++ command-line compiler.

-					<tr valign="top">

-					<td><b><tt>make&nbsp;setup&nbsp;lcc</tt></b>

-					<td>Will generate a different <tt>config.mk</tt>

-						that can be used to compile the library

-						with the Win32-LCC compiler.

-				</table>

-			</ul>

-			<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&nbsp;</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>

binary files a/docs/internals/demo-programs.png /dev/null differ

binary files a/docs/internals/drivers-list.png /dev/null differ

--- a/docs/internals/index.html

+++ /dev/null

@@ -1,788 +1,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.0</h2></center>

-<center>

-<h3>

-&copy; 1999 David Turner (<a href="fichier :///[email protected]">[email protected]</a>)<br>

-&copy; 1999 The FreeType Development Team (<a href="fichier :///[email protected]">[email protected]</a>)</h3></center>

-<p><br>

-<hr WIDTH="100%">

-<br>&nbsp;

-<h2>

-Introduction:</h2>

-<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>&nbsp;

-<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>&nbsp;</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>&nbsp;</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 &amp; 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>&nbsp;</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>&nbsp;

-<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&nbsp; 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>&nbsp;

-<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>&nbsp; �</tt>

-<br><tt>&nbsp; FT_Error&nbsp; error;</tt>

-<p><tt>&nbsp; error = FT_Access_Frame( stream, 14 );</tt>

-<br><tt>&nbsp; if (error) goto Fail;</tt>

-<p><tt>&nbsp; val1 = FT_Get_Short(stream);</tt>

-<br><tt>&nbsp; val2 = FT_Get_Long(stream);</tt>

-<br><tt>&nbsp; val3 = FT_Get_Long(stream);</tt>

-<br><tt>&nbsp; val4 = FT_Get_Long(stream);</tt>

-<p><tt>&nbsp; FT_Forget_Frame(stream);</tt>

-<br><tt>&nbsp; �</tt>

-<br><tt>}</tt></blockquote>

-This code does the following :

-<blockquote>

-<ol>

-<li>

-&nbsp;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>

-&nbsp;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>

-&nbsp;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>&lt;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>&nbsp;</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>&nbsp;</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>&nbsp;</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&nbsp; 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>&lt;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>&nbsp;

-<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>&nbsp;

-<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>&nbsp;</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>&nbsp;</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>&nbsp;</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>&nbsp;

-<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>&nbsp;

-<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>&nbsp;

-<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/&lt;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>&lt;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>&lt;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>&nbsp;

-<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 &laquo; multiple

-objects &raquo;). 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>&nbsp;</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>&nbsp;</blockquote>

-</body>

-</html>

--- a/docs/internals/io-frames.html

+++ /dev/null

@@ -1,247 +1,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>

-</head>

-<body>

-<body text="#000000"

-      bgcolor="#FFFFFF"

-      link="#0000EF"

-      vlink="#51188E"

-      alink="#FF0000">

-<center>

-<h1>

-FreeType 2.0 I/O Frames</h1></center>

-<center>

-<h3>

-&copy; 2000 David Turner (<a href="mailto:[email protected]">[email protected]</a>)<br>

-&copy; 2000 The FreeType Development Team (<a href="http://www.freetype.org">www.freetype.org</a>)</h3></center>

-<p><br>

-<hr WIDTH="100%">

-<br>&nbsp;

-<h2>Introduction:</h2>

-<ul>

-  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>

-  It is targetted to FreeType hackers, or more simply to developers who would

-  like a better understanding of the library's source code.

-</ul>

-<p><hr><p>

-<h2>I. What frames are:</h2>

-<ul>

-  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>

-  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>

-  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 <tt>FT_Access_Frame</tt> will:<p>

-  <ul>

-	  <li>Ensure that there are at least 2+4+4=10 bytes left in the stream.

-	  <li>"Preload" (for disk-based streams) 10 bytes from the current

-          stream position.

-	  <li>Set the frame "cursor" to the first byte in the frame;

-  </ul>

-  <p>

-  Each <tt>FT_Get_Short</tt> or <tt>FT_Get_ULong</tt> call will read a

-  big-endian integer from the stream (2 bytes for <tt>FT_Get_Short</tt>,

-  4 bytes for <tt>FT_Get_ULong</tt>) and advance the frame cursor accordingly.

-  <p>

-  <tt>FT_Forget_Frame</tt> "releases" the frame from memory

-  <p>

-  There are several advantages to using frames :<p>

-  <ul>

-	  <li>single-check when loading tables

-	  <li><em>making code clearer</em> by providing simple parsing functions

-             <em>while keeping code safe</em> from file over-runs and invalid

-             offsets.

-  </ul>

-  <p>

-</ul>

-<p><hr><p>

-<h2>II. Accessing and reading a frame with macros:</h2>

-<ul>

-	By convention in the FreeType source code, macros are able to use two implicit

-	variables named "<tt>error</tt>" and "<tt>stream</tt>". This is useful because

-	these two variables are extremely used in the library, and doing this only

-	reduces our typing requirements and make the source code much clearer.

-	<p>

-	Note that <tt>error</tt> must be a local variable of type <tt>FT_Error</tt>,<br>

-	while <tt>stream</tt> must be a local variable or argument of type <tt>FT_Stream</tt>;

-	<p>

-	The macro used to access a frame is

-    <font color="purple"><tt><b>ACCESS_Frame(_size_)</b></tt></font>, it will

-	translate to:<p>

-	<ul><font color="blue">

-		<tt>(error=FT_Access_Frame(stream,_size_)) != FT_Err_Ok</tt>.

-	</font></ul>

-	<p>

-	Similarly, the macro

-    <font color="purple"><b><tt>FORGET_Frame()</tt></b></font>

-    translates to:<p>

-	<ul><font color="blue">

-		<tt>FT_Forget_Frame(stream)</tt>

-	</font></ul>

-	<p>

-	Extracting integers can be performed with the <tt>GET_xxx</tt> macros, like:<p>

-	<ul>

-		<table>

-			<tr>

-                <td><b>Macro name</b>    <td>Translation  <td>Description

-            <tr><td><font color="purple"><tt><b>

-                GET_Byte()

-                </b></tt></font><td><font color="blue"><tt>

-                (FT_Get_Byte(stream))

-                </tt></font><td>

-                reads an 8-bit unsigned byte

-            <tr><td><font color="purple"><tt><b>

-                GET_Char()

-                </b></tt></font><td><font color="blue"><tt>

-                ((FT_Char)FT_Get_Byte(stream))

-                </tt></font><td>

-                reads an 8-bit <em>signed</em> byte

-            <tr><td><font color="purple"><tt><b>

-                GET_Short()

-                </b></tt></font><td><font color="blue"><tt>

-                (FT_Get_Short(stream))

-                </tt></font><td>

-                reads a 16-bit signed big-endian integer

-            <tr><td><font color="purple"><tt><b>

-                GET_UShort()

-                </b></tt></font><td><font color="blue"><tt>

-                ((FT_UShort)FT_Get_Short(stream))

-                </tt></font><td>

-                reads a 16-bit unsigned big-endian integer

-            <tr><td><font color="purple"><tt><b>

-                GET_Offset()

-                </b></tt></font><td><font color="blue"><tt>

-                (FT_Get_Offset(stream))

-                </tt></font><td>

-                reads a 24-bit signed big-endian integer

-            <tr><td><font color="purple"><tt><b>

-                GET_UOffset()

-                </b></tt></font><td><font color="blue"><tt>

-                ((FT_UOffset)FT_Get_Offset(stream))

-                </tt></font><td>

-                reads a 24-bit unsigned big-endian integer

-            <tr><td><font color="purple"><tt><b>

-                GET_Long()

-                </b></tt></font><td><font color="blue"><tt>

-                (FT_Get_Long(stream))

-                </tt></font><td>

-                reads a 32-bit signed big-endian integer

-            <tr><td><font color="purple"><tt><b>

-                GET_ULong()

-                </b></tt></font><td><font color="blue"><tt>

-                ((FT_ULong)FT_Get_Long(stream))

-                </tt></font><td>

-                reads a 32-bit unsigned big-endian integer

-		</table>

-	</ul>

-	<p>

-	(Note that an <b>Offset</b> is an integer stored with 3 bytes on the file).

-    <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);<br>

-	</pre></font>

-	<p>

-	Can be replaced with macros by:<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 <b>error</b> and <b>stream</b> must be defined

-	locally though for this code to work.. !!

-</ul>

-<p><hr><p>

-<h2>III. Alternatives:</h2>

-<ul>

-  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"><tt>FT_Read_xxxx</tt></font>.

-  <p>

-  For example,

-  <font color="blue"><tt>FT_Read_Short( stream, &error )</tt></font> reads and

-  returns a 2-byte big-endian integer from a <tt>stream</tt>, and place an

-  error code in the <tt>error</tt> variable.

-  <p>

-  Thus, reading a single big-endian integer is shorter than using a frame

-  for it.

-  <p>

-  Note that there is also the macros

-  <font color="purple"><tt>READ_xxx()</tt></font> which translate to:<p>

-  <font color="blue"><pre>

-    <tt>( 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>

-  when <b>error</b> and <b>stream</b> are already defined locally..

-</ul>

binary files a/docs/internals/library-compilation.png /dev/null differ

binary files a/docs/internals/logo1.png /dev/null differ

binary files a/docs/internals/objects_diagram.png /dev/null differ

binary files a/docs/internals/objects_diagram2.png /dev/null differ

binary files a/docs/internals/platform-detection.png /dev/null differ

--- a/docs/internals/system-interface.html

+++ /dev/null

@@ -1,258 +1,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>

-&copy; 2000 David Turner (<a href="fichier :///[email protected]">[email protected]</a>)<br>

-&copy; 2000 The FreeType Development Team (<a href="fichier :///[email protected]">[email protected]</a>)</h3></center>

-<p><br>

-<hr WIDTH="100%">

-<br>&nbsp;

-<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/&lt;system&gt;</tt>" where <tt>&lt;system&gt;</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>