subsys/win32k/freetype/docs/design/system-interface.html

   1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5    <meta name="Author" content="David Turner">
   6    <meta name="GENERATOR" content="Mozilla/4.5 [fr] (Win98; I) [Netscape]">
   7    <title>FreeType 2 Internals</title>
   8 </head>
   9 <body>
  10
  11 <body text="#000000"
  12       bgcolor="#FFFFFF"
  13       link="#0000EF"
  14       vlink="#51188E"
  15       alink="#FF0000">
  16
  17 <center>
  18 <h1>
  19 FreeType 2.0 System Interface</h1></center>
  20
  21 <center>
  22 <h3>
  23 &copy; 2000 David Turner (<a href="fichier :///david@freetype.org">david@freetype.org</a>)<br>
  24 &copy; 2000 The FreeType Development Team (<a href="fichier :///devel@freetype.org">devel@freetype.org</a>)</h3></center>
  25
  26 <p><br>
  27 <hr WIDTH="100%">
  28 <br>&nbsp;
  29 <h2>Introduction:</h2>
  30 <ul>
  31         This document explains how the FreeType 2 library performs the low-level and
  32         system-specific operations of memory management and i/o access. It is targetted
  33         to FreeType hackers, porters and "advanced" developers who want special
  34         features like providing their own memory manager or streams.
  35         <p>
  36         Note that the only system-specific part of the library is a file
  37         named "<tt>ftsystem.c</tt>", normally located in the directory
  38     "<tt>freetype2/config/&lt;system&gt;</tt>" where <tt>&lt;system&gt;</tt> designates
  39         your platform (e.g. "<tt>config/ansi/ftsystem.c</tt>"  or
  40         "<tt>config/unix/ftsystem.c</tt>").
  41         <p>
  42 </ul>
  43
  44 <p>
  45 <hr>
  46 <p>
  47
  48 <h2>I. Memory Management</h2>
  49 <ul>
  50         Memory allocation and releases are performed through a <tt>FT_Memory</tt> object in
  51     FreeType. A <tt>FT_Memory</tt> is nothing more than a table of functions plus
  52         an arbitrary user data field. It is defined in the file
  53     "<tt>freetype2/include/ftsystem.h</tt>" and has the following structure:
  54         <p>
  55         <ul>
  56                 <tt>typedef struct</tt><br>
  57                 <tt>{</tt>
  58                 <ul>
  59                 <table>
  60                         <tr><td><tt><b>void*   user</b></tt>   <td> // a user-defined pointer. This is zero by default
  61                         <tr><td><tt><b>void* (*alloc)( FT_System, int)</b></tt>  <td> // a function used to allocate a new block
  62                         <tr><td><tt><b>void* (*realloc)( FT_System, int, int, void* )</b></tt><td> // a function used to reallocate a given block
  63                         <tr><td><tt><b>void  (*free)( FT_System, void*)</b></tt>   <td> // a function used to release a given block
  64                 </table>
  65                 </ul>
  66                 <tt>} FT_MemoryRec, *FT_Memory;</tt><br>
  67         </ul>
  68         <p>
  69         You'll notice that:<p>
  70         <ul>
  71                 <li>The <tt>FT_Memory</tt> type is really a pointer to a <tt>FT_MemoryRec</tt>.
  72                         This is a normal convention for the FreeType code.
  73                 <li>The <tt>realloc</tt> takes two integer arguments. The first one is the
  74                         current block size, the second one its new size.
  75         </ul>
  76         <p>
  77
  78         All current implementations of "<tt>ftsystem.c</tt>" provide a very simple
  79     implementation of the <tt>FT_Memory</tt> interface by calling directly the
  80         standard C <tt>alloc</tt>, <tt>realloc</tt> and <tt>free</tt>.
  81         <p>
  82         The FreeType source code never invokes directly the function pointers. Rather,
  83         it calls <tt>FT_Alloc</tt>, <tt>FT_Realloc</tt> and <tt>FT_Free</tt> functions
  84         which are defined in "<tt>freetype2/src/base/ftobjs.c</tt>". These will not be
  85     discussed here.
  86     <p>
  87         <b>If you want to use your own memory allocator</b> rather than the one provided
  88         by your build of FreeType, follow these simple steps:<p>
  89         <ol>
  90                 <li>Create your own <tt>FT_Memory</tt> object, with pointers that map to
  91             your own memory management routines (beware function signatures though).
  92                 <p>
  93                 <li>Call <tt>FT_Build_Library(memory,&library)</tt>. This will create a new
  94                         <tt>FT_Library</tt> object that uses your own <tt>FT_Memory</tt> exclusively.
  95                         Note however that this library has no font drivers loaded in !!
  96                 <p>
  97                 <li>Load the default font drivers into the new library, either by
  98                         calling <tt>FT_Default_Drivers(library)</tt>, or by adding them manually
  99             through repeated calls to <tt>FT_Add_Driver(library,&driver_interface)</tt>
 100                 <p>
 101         </ol>
 102         This will replace the <tt>FT_Init_FreeType(&library)</tt> call that an application
 103         must do to initialise one library instance.
 104         <p>
 105         Notice that you <em>don't need to recompile FreeType 2 to use your own memory
 106         manager !!</em>.
 107         <p>
 108 </ul>
 109
 110 <p>
 111 <hr>
 112 <p>
 113
 114 <h2>II. Streams</h2>
 115 <ul>
 116         <h3>1. Basic Stream Structure</h3>
 117         <p>
 118         A stream models the array of bytes found in a font file. FreeType 2 separates
 119         streams into two families :<p>
 120         <ul>
 121                 <li><b>memory-based streams:</b><br>
 122                         when the stream's content is entirely found in memory. This is the
 123                         case for ROM font files, or memory-mapped files.
 124                         <p>
 125                 <li><b>disk-based streams:</b><br>
 126                         when the stream isn't directly accessible in memory. This is the
 127                         case for local or remote files.
 128                         <p>
 129         </ul>
 130         <p>
 131         Note that a stream's nature only determines how FreeType accesses its content, not
 132         the way it is effectively stored. For example, in the case of a compressed font file,
 133         one implementation may choose to uncompress the font in memory, then provide a memory
 134     based stream to access it. Another one might chose a disk based stream to perform
 135         on-the-fly decompression of the font data. Similarly, the font file can be stored
 136     on a local disk, or obtained from a network. This will be completely transparent to
 137     FreeType.
 138         <p>
 139         The stream structure is:
 140         <p>
 141         <ul>
 142                 <tt>typedef struct</tt><br>
 143                 <tt>{</tt><br>
 144                 <ul><table>
 145                         <tr><td><tt><b>char*  base</b></tt>   <td> for memory-based streams, the address
 146                                                                                                    of its first byte.
 147
 148                         <tr><td><tt><b>ulong  size</b></tt>   <td> the stream's size in bytes.
 149
 150                         <tr><td><tt><b>ulong  pos</b></tt>    <td> the current stream position in the file
 151
 152                         <tr><td><tt><b>descriptor</b></tt><td> a union field used to hold either an
 153                                                                                                integer file descriptor or pointer.
 154                                                                                                    This field is not used by FreeType
 155                                                                                                    itself, but is left to implementations
 156                                                                                                    of "<tt>ftsystem</tt>"
 157                         <tr><td><tt><b>pathname</b></tt>  <td> a union field that can hold either an
 158                                                                                                    integer or pointer. It is not used by
 159                                                                                                    FreeType itself, but is left to
 160                                                                                                    implementations. These can put the
 161                                                                                                    file pathname's during debugging for
 162                                                                                                    example.
 163
 164                         <tr><td><tt><b>read</b></tt>   <td> a pointer to a function used to seek the
 165                                                                                           stream and/or read a run of bytes from it.
 166
 167                         <tr><td><tt><b>close</b></tt><td> a pointer to a function called when the
 168                                                                                           stream is closed.
 169
 170                         <tr><td><tt><b>memory</b></tt> <td> a <tt>FT_Memory</tt> object, which is used
 171                                                                                                 to allocate frames for disk-based streams.
 172                                                                                                 This field is set and used by FreeType.
 173
 174                         <tr><td><tt><b>cursor</b></tt> <td> a pointer in memory used when accessing
 175                                                                                                 frames. This is set and used by FreeType.
 176
 177                         <tr><td><tt><b>limit</b></tt>  <td> a pointer in memory used when accessing
 178                                                                                                 frames. This is set and used by FreeType.
 179                 </table></ul>
 180                 <tt>} FT_StreamRec, *FT_Stream</tt>
 181         </ul>
 182         <p>
 183
 184         The following important things must be noticed here:<p>
 185         <ul>
 186                 <li>The <tt>FT_Stream</tt> type is really a pointer to a <tt>FT_StreamRec</tt>.
 187             This is a normal convention for the FreeType source.
 188                         <p>
 189
 190                 <li>When the <tt>read</tt> field is non NULL, the stream is considered to be
 191                         disk-based. Otherwise, the stream is memory-based, and the <tt>base</tt>
 192                         field <em>must</em> be set by "<tt>ftsystem.c</tt>" when the stream is
 193                         created.
 194                         <p>
 195
 196                 <li>The <tt>base</tt> field must be set to 0 when a disk-based stream is created.
 197                         However, this field will later be set and used by the FreeType library when
 198             accessing frames of bytes within the font file (of course, this doesn't
 199             happen with memory-based streams).
 200         </ul>
 201
 202         <h3>2. Stream lifecyles</h3>
 203         <p>
 204         Each <tt>FT_Face</tt> needs its own stream to access font data. The most common
 205         way to create a new <tt>FT_Stream</tt> object is to call the function
 206         <tt>FT_New_Face</tt>. This function takes a <em>file pathname</em> argument that
 207         is used to create a new stream object.
 208         <p>
 209         This is possible because each implementation of "<tt>ftsystem.c</tt>" provides
 210         a function called <tt>FT_New_Stream</tt> which takes a file pathname and a
 211     <tt>FT_Stream</tt> pointer as an argument. The function simply opens the file
 212         and initialises the stream structure accordingly. It is called by <tt>FT_New_Face</tt>
 213         to create the face's stream object.
 214         <p>
 215         A stream is only closed when the face is destroyed through <tt>FT_Done_Face</tt>.
 216         Its <tt>close</tt> field function will then be called. Note that the function should
 217         <em>never</em> destroy the <tt>FT_Stream</tt>.
 218         <p>
 219
 220
 221         <h3>3. Using your own streams</h3>
 222         <p>
 223         There are cases where it is interesting to provide your own stream to create
 224         a new face object, rather than rely on the default implementation. For example,
 225     a filepathname, which is a C string, might not be useful on a system where files
 226         are named with a UTF-16 string or via an i-node number of memory address (for ROM files).
 227         <p>
 228         For this purpose, the <tt>FT_Open_Face</tt> is defined. It simply takes a
 229         <tt>FT_Stream</tt> pointer as its second argument, instead of a file pathname (the
 230         stream must be allocated and initialised by you, so be careful).
 231         <p>
 232         Actually, the only thing that <tt>FT_New_Face</tt> does is create a new stream
 233         through <tt>FT_New_Stream</tt>, then call <tt>FT_Open_Face</tt> to create the
 234         face with it.
 235         <p>
 236         Note also that you can use the function <tt>FT_New_Memory_Face</tt> to create
 237         a new font face for a memory-based font file, whose address and size can be passed
 238         as arguments. The function automatically creates the corresponding memory-based
 239         stream and use it to create the face.
 240         <p>
 241
 242 </ul>
 243
 244
 245 <p>
 246 <hr>
 247 <p>
 248
 249 <h2>III. Thread synchronisation</h2>
 250 <ul>
 251         The FreeType library uses no static data. It can be used concurrently by two
 252         thread as long as each one uses its own <tt>FT_Library</tt> instance. Otherwise,
 253         one can very simply synchronize access to a single library instance by using a
 254         mutex to protect each call to one of FreeType's API functions.
 255         <p>
 256 </ul>
 257
 258