ref: 186d231081ef78e19a632cbc4ea85f95cc154251
parent: a14fa3ace894a8f795fc19aa93e87027d8b6da28
author: David Turner <[email protected]>
date: Mon Jan 10 23:09:35 EST 2000
Added a new documentation file that explains how memory management and basic i/o access are performed with FreeType 2. Note that unlike FT 1.x, you don't need to recompile the library if you want to provide your own memory manager or your own i/o streams.
--- /dev/null
+++ b/docs/internals/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>
+© 2000 David Turner (<a href="fichier :///[email protected]">[email protected]</a>)<br>
+© 2000 The FreeType Development Team (<a href="fichier :///[email protected]">[email protected]</a>)</h3></center>
+
+<p><br>
+<hr WIDTH="100%">
+<br>
+<h2>Introduction:</h2>
+<ul>
+ This document explains how the FreeType 2 library performs the low-level and
+ system-specific operations of memory management and i/o access. It is targetted
+ to FreeType hackers, porters and "advanced" developers who want special
+ features like providing their own memory manager or streams.
+ <p>
+ Note that the only system-specific part of the library is a file
+ named "<tt>ftsystem.c</tt>", normally located in the directory
+ "<tt>freetype2/config/<system></tt>" where <tt><system></tt> designates
+ your platform (e.g. "<tt>config/ansi/ftsystem.c</tt>" or
+ "<tt>config/unix/ftsystem.c</tt>").
+ <p>
+</ul>
+
+<p>
+<hr>
+<p>
+
+<h2>I. Memory Management</h2>
+<ul>
+ Memory allocation and releases are performed through a <tt>FT_Memory</tt> object in
+ FreeType. A <tt>FT_Memory</tt> is nothing more than a table of functions plus
+ an arbitrary user data field. It is defined in the file
+ "<tt>freetype2/include/ftsystem.h</tt>" and has the following structure:
+ <p>
+ <ul>
+ <tt>typedef struct</tt><br>
+ <tt>{</tt>+ <ul>
+ <table>
+ <tr><td><tt><b>void* user</b></tt> <td> // a user-defined pointer. This is zero by default
+ <tr><td><tt><b>void* (*alloc)( FT_System, int)</b></tt> <td> // a function used to allocate a new block
+ <tr><td><tt><b>void* (*realloc)( FT_System, int, int, void* )</b></tt><td> // a function used to reallocate a given block
+ <tr><td><tt><b>void (*free)( FT_System, void*)</b></tt> <td> // a function used to release a given block
+ </table>
+ </ul>
+ <tt>} FT_MemoryRec, *FT_Memory;</tt><br>
+ </ul>
+ <p>
+ You'll notice that:<p>
+ <ul>
+ <li>The <tt>FT_Memory</tt> type is really a pointer to a <tt>FT_MemoryRec</tt>.
+ This is a normal convention for the FreeType code.
+ <li>The <tt>realloc</tt> takes two integer arguments. The first one is the
+ current block size, the second one its new size.
+ </ul>
+ <p>
+
+ All current implementations of "<tt>ftsystem.c</tt>" provide a very simple
+ implementation of the <tt>FT_Memory</tt> interface by calling directly the
+ standard C <tt>alloc</tt>, <tt>realloc</tt> and <tt>free</tt>.
+ <p>
+ The FreeType source code never invokes directly the function pointers. Rather,
+ it calls <tt>FT_Alloc</tt>, <tt>FT_Realloc</tt> and <tt>FT_Free</tt> functions
+ which are defined in "<tt>freetype2/src/base/ftobjs.c</tt>". These will not be
+ discussed here.
+ <p>
+ <b>If you want to use your own memory allocator</b> rather than the one provided
+ by your build of FreeType, follow these simple steps:<p>
+ <ol>
+ <li>Create your own <tt>FT_Memory</tt> object, with pointers that map to
+ your own memory management routines (beware function signatures though).
+ <p>
+ <li>Call <tt>FT_Build_Library(memory,&library)</tt>. This will create a new
+ <tt>FT_Library</tt> object that uses your own <tt>FT_Memory</tt> exclusively.
+ Note however that this library has no font drivers loaded in !!
+ <p>
+ <li>Load the default font drivers into the new library, either by
+ calling <tt>FT_Default_Drivers(library)</tt>, or by adding them manually
+ through repeated calls to <tt>FT_Add_Driver(library,&driver_interface)</tt>
+ <p>
+ </ol>
+ This will replace the <tt>FT_Init_FreeType(&library)</tt> call that an application
+ must do to initialise one library instance.
+ <p>
+ Notice that you <em>don't need to recompile FreeType 2 to use your own memory
+ manager !!</em>.
+ <p>
+</ul>
+
+<p>
+<hr>
+<p>
+
+<h2>II. Streams</h2>
+<ul>
+ <h3>1. Basic Stream Structure</h3>
+ <p>
+ A stream models the array of bytes found in a font file. FreeType 2 separates
+ streams into two families :<p>
+ <ul>
+ <li><b>memory-based streams:</b><br>
+ when the stream's content is entirely found in memory. This is the
+ case for ROM font files, or memory-mapped files.
+ <p>
+ <li><b>disk-based streams:</b><br>
+ when the stream isn't directly accessible in memory. This is the
+ case for local or remote files.
+ <p>
+ </ul>
+ <p>
+ Note that a stream's nature only determines how FreeType accesses its content, not
+ the way it is effectively stored. For example, in the case of a compressed font file,
+ one implementation may choose to uncompress the font in memory, then provide a memory
+ based stream to access it. Another one might chose a disk based stream to perform
+ on-the-fly decompression of the font data. Similarly, the font file can be stored
+ on a local disk, or obtained from a network. This will be completely transparent to
+ FreeType.
+ <p>
+ The stream structure is:
+ <p>
+ <ul>
+ <tt>typedef struct</tt><br>
+ <tt>{</tt><br>+ <ul><table>
+ <tr><td><tt><b>char* base</b></tt> <td> for memory-based streams, the address
+ of its first byte.
+
+ <tr><td><tt><b>ulong size</b></tt> <td> the stream's size in bytes.
+
+ <tr><td><tt><b>ulong pos</b></tt> <td> the current stream position in the file
+
+ <tr><td><tt><b>descriptor</b></tt><td> a union field used to hold either an
+ integer file descriptor or pointer.
+ This field is not used by FreeType
+ itself, but is left to implementations
+ of "<tt>ftsystem</tt>"
+ <tr><td><tt><b>pathname</b></tt> <td> a union field that can hold either an
+ integer or pointer. It is not used by
+ FreeType itself, but is left to
+ implementations. These can put the
+ file pathname's during debugging for
+ example.
+
+ <tr><td><tt><b>read</b></tt> <td> a pointer to a function used to seek the
+ stream and/or read a run of bytes from it.
+
+ <tr><td><tt><b>close</b></tt><td> a pointer to a function called when the
+ stream is closed.
+
+ <tr><td><tt><b>memory</b></tt> <td> a <tt>FT_Memory</tt> object, which is used
+ to allocate frames for disk-based streams.
+ This field is set and used by FreeType.
+
+ <tr><td><tt><b>cursor</b></tt> <td> a pointer in memory used when accessing
+ frames. This is set and used by FreeType.
+
+ <tr><td><tt><b>limit</b></tt> <td> a pointer in memory used when accessing
+ frames. This is set and used by FreeType.
+ </table></ul>
+ <tt>} FT_StreamRec, *FT_Stream</tt>
+ </ul>
+ <p>
+
+ The following important things must be noticed here:<p>
+ <ul>
+ <li>The <tt>FT_Stream</tt> type is really a pointer to a <tt>FT_StreamRec</tt>.
+ This is a normal convention for the FreeType source.
+ <p>
+
+ <li>When the <tt>read</tt> field is non NULL, the stream is considered to be
+ disk-based. Otherwise, the stream is memory-based, and the <tt>base</tt>
+ field <em>must</em> be set by "<tt>ftsystem.c</tt>" when the stream is
+ created.
+ <p>
+
+ <li>The <tt>base</tt> field must be set to 0 when a disk-based stream is created.
+ However, this field will later be set and used by the FreeType library when
+ accessing frames of bytes within the font file (of course, this doesn't
+ happen with memory-based streams).
+ </ul>
+
+ <h3>2. Stream lifecyles</h3>
+ <p>
+ Each <tt>FT_Face</tt> needs its own stream to access font data. The most common
+ way to create a new <tt>FT_Stream</tt> object is to call the function
+ <tt>FT_New_Face</tt>. This function takes a <em>file pathname</em> argument that
+ is used to create a new stream object.
+ <p>
+ This is possible because each implementation of "<tt>ftsystem.c</tt>" provides
+ a function called <tt>FT_New_Stream</tt> which takes a file pathname and a
+ <tt>FT_Stream</tt> pointer as an argument. The function simply opens the file
+ and initialises the stream structure accordingly. It is called by <tt>FT_New_Face</tt>
+ to create the face's stream object.
+ <p>
+ A stream is only closed when the face is destroyed through <tt>FT_Done_Face</tt>.
+ Its <tt>close</tt> field function will then be called. Note that the function should
+ <em>never</em> destroy the <tt>FT_Stream</tt>.
+ <p>
+
+
+ <h3>3. Using your own streams</h3>
+ <p>
+ There are cases where it is interesting to provide your own stream to create
+ a new face object, rather than rely on the default implementation. For example,
+ a filepathname, which is a C string, might not be useful on a system where files
+ are named with a UTF-16 string or via an i-node number of memory address (for ROM files).
+ <p>
+ For this purpose, the <tt>FT_Open_Face</tt> is defined. It simply takes a
+ <tt>FT_Stream</tt> pointer as its second argument, instead of a file pathname (the
+ stream must be allocated and initialised by you, so be careful).
+ <p>
+ Actually, the only thing that <tt>FT_New_Face</tt> does is create a new stream
+ through <tt>FT_New_Stream</tt>, then call <tt>FT_Open_Face</tt> to create the
+ face with it.
+ <p>
+ Note also that you can use the function <tt>FT_New_Memory_Face</tt> to create
+ a new font face for a memory-based font file, whose address and size can be passed
+ as arguments. The function automatically creates the corresponding memory-based
+ stream and use it to create the face.
+ <p>
+
+</ul>
+
+
+<p>
+<hr>
+<p>
+
+<h2>III. Thread synchronisation</h2>
+<ul>
+ The FreeType library uses no static data. It can be used concurrently by two
+ thread as long as each one uses its own <tt>FT_Library</tt> instance. Otherwise,
+ one can very simply synchronize access to a single library instance by using a
+ mutex to protect each call to one of FreeType's API functions.
+ <p>
+</ul>
+
+