kmx git

Commit 883df43fec1bbd2e8658693c964045072ec3044d

2000-05-29T07:30:17
Completely checked and fully formatted.
diff --git a/docs/design/io-frames.html b/docs/design/io-frames.html
index 6bd515a..2b249b6 100644
--- a/docs/design/io-frames.html
+++ b/docs/design/io-frames.html
@@ -1,12 +1,12 @@
 <!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>
+  <meta http-equiv="Content-Type"
+        content="text/html; charset=iso-8859-1">
+  <meta name="Author"
+        content="David Turner">
+  <title>FreeType 2 Internals - I/O Frames</title>
 </head>
-<body>
 
 <body text="#000000"
       bgcolor="#FFFFFF"
@@ -14,234 +14,328 @@
       vlink="#51188E"
       alink="#FF0000">
 
-<center>
-<h1>
-FreeType 2.0 I/O Frames</h1></center>
+<h1 align=center>
+  FreeType 2.0 I/O Frames
+</h1>
+
+<h3 align=center>
+  &copy; 2000 David Turner
+    (<a href="mailto:david@freetype.org">david@freetype.org</a>)<br>
+  &copy; 2000 The FreeType Development Team
+    (<a href="http://www.freetype.org">www.freetype.org</a>)
+</h3>
 
 <center>
-<h3>
-&copy; 2000 David Turner (<a href="mailto:david@freetype.org">david@freetype.org</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>
+<table width="70%">
+<tr><td>
+
+  <hr>
+
+  <h2>
+    Introduction
+  </h2>
+
+  <p>This document explains the concept of I/O <b>frames</b> as used in the
+  FreeType&nbsp;2 source code.  It also enumerates the various functions and
+  macros that can be used to read them.</p>
+
+  <p>It is targeted to FreeType hackers, or more simply to developers who
+  would like a better understanding of the library's source code.</p>
+
+  <hr>
+
+  <h2>
+    I. What frames are
+  </h2>
+
+  <p>Simply speaking, a frame is an array of bytes in a font file that is
+  "preloaded" into memory in order to be rapidly parsed.  Frames are useful
+  to ensure that every "load" is checked against end-of-file overruns, and
+  provides nice functions to extract data in a variety of distinct
+  formats.</p>
+
+  <p>But an example is certainly more meaningful than anything else.  The
+  following code</p>
+
+  <font color="blue">
+  <pre>
+    error = read_short( stream, &str.value1 );
+    if ( error ) goto ...
+
+    error = read_ulong( stream, &str.value2 );
+    if ( error ) goto ...
+
+    error = read_ulong( stream, &str.value3 );
+    if ( error ) goto ...</pre>
+  </font>
+
+  <p>can easily be replaced with</p>
+
+  <font color="blue">
+  <pre>
+    error = FT_Access_Frame( stream, 2 + 4 + 4 );
+    if ( error ) goto ...
+
+    str.value1 = FT_Get_Short( stream );
+    str.value2 = FT_Get_ULong( stream );
+    str.value3 = FT_Get_ULong( stream );
+
+    FT_Forget_Frame( stream );</pre>
+  </font>
+
+  <p>Here, the call to <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;
+    <li>
+      <p>Ensure that there are at least 2+4+4=10 bytes left in the
+      stream.</p>
+    </li>
+    <li>
+      <p>"Preload" (for disk-based streams) 10&nbsp;bytes from the current
+      stream position.</p>
+    </li>
+    <li>
+      <p>Set the frame "cursor" to the first byte in the frame.</p>
+    </li>
   </ul>
-  <p>
-  Each <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>
+
+  <p>Each <tt>FT_Get_Short()</tt> or <tt>FT_Get_ULong()</tt> call will read
+  a big-endian integer from the stream (2&nbsp;bytes for
+  <tt>FT_Get_Short()</tt>, 4&nbsp;bytes for <tt>FT_Get_ULong</tt>) and
+  advance the frame cursor accordingly.</p>
+
+  <p><tt>FT_Forget_Frame()</tt> "releases" the frame from memory.</p>
+
+  <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.
+    <li>
+      <p>Single-check when loading tables.</p>
+    </li>
+    <li>
+      <p><em>Making code clearer</em> by providing simple parsing functions
+      <em>while keeping code safe</em> from file over-runs and invalid
+      offsets.</p>
+    </li>
   </ul>
-  <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>
 
+  <hr>
+
+  <h2>
+    II. Accessing and reading a frame with macros
+  </h2>
+
+  <p>By convention in the FreeType source code, macros are able to use two
+  implicit variables named <tt>error</tt> and <tt>stream</tt>.  This is
+  useful because these two variables are extremely often used in the
+  library, and doing this only reduces our typing requirements and make the
+  source code much clearer.</p>
+
+  <p>Note that <tt>error</tt> must be a local variable of type
+  <tt>FT_Error</tt>, while <tt>stream</tt> must be a local variable or
+  argument of type <tt>FT_Stream</tt>.</p>
+
+  <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>
+
+  <font color="blue">
+  <pre>
+    ( error = FT_Access_Frame( stream, _size_ ) )
+        != FT_Err_Ok</tt></pre>
+  </font>
+
+  <p>Similarly, the macro <font
+  color="purple"><b><tt>FORGET_Frame()</tt></b></font> translates to</p>
+
+  <font color="blue">
+  <pre>
+    <tt>FT_Forget_Frame( stream )</tt></pre>
+  </font>
+
+  <p>Extracting integers can be performed with the <tt>GET_xxx()</tt>
+  macros, like</p>
+
+  <table align=center>
+    <tr valign="top">
+      <td>
+        <b>Macro name</b>
+      </td>
+      <td>
+        Translation
+      </td>
+      <td>
+        Description
+      </td>
+    </tr>
+    <tr valign="top">
+      <td>
+        <font color="purple"><tt><b>GET_Byte()</b></tt></font>
+      </td>
+      <td>
+        <font color="blue"><tt>FT_Get_Byte(stream)</tt></font>
+      </td>
+      <td>
+        <p>Reads an 8-bit unsigned byte.</p>
+      </td>
+    </tr>
+    <tr valign="top">
+      <td>
+        <font color="purple"><tt><b>GET_Char()</b></tt></font>
+      </td>
+      <td>
+        <font color="blue"><tt>(FT_Char)<br>
+        FT_Get_Byte(stream)</tt></font>
+      </td>
+      <td>
+        <p>Reads an 8-bit <em>signed</em> byte.</p>
+      </td>
+    </tr>
+    <tr valign="top">
+      <td>
+        <font color="purple"><tt><b>GET_Short()</b></tt></font>
+      </td>
+      <td>
+        <font color="blue"><tt>FT_Get_Short(stream)</tt></font>
+      </td>
+      <td>
+        Reads a 16-bit signed big-endian integer.
+      </td>
+    </tr>
+    <tr valign="top">
+      <td>
+        <font color="purple"><tt><b>GET_UShort()</b></tt></font>
+      </td>
+      <td>
+        <font color="blue"><tt>(FT_UShort)<br>
+        FT_Get_Short(stream)</tt></font>
+      </td>
+      <td>
+        Reads a 16-bit unsigned big-endian integer.
+      </td>
+    </tr>
+    <tr valign="top">
+      <td>
+        <font color="purple"><tt><b>GET_Offset()</b></tt></font>
+      </td>
+      <td>
+        <font color="blue"><tt>FT_Get_Offset(stream)</tt></font>
+      </td>
+      <td>
+        Reads a 24-bit signed big-endian integer.
+      </td>
+    </tr>
+    <tr valign="top">
+      <td>
+        <font color="purple"><tt><b>GET_UOffset()</b></tt></font>
+      </td>
+      <td>
+        <font color="blue"><tt>(FT_UOffset)<br>
+        FT_Get_Offset(stream)</tt></font>
+      </td>
+      <td>
+        Reads a 24-bit unsigned big-endian integer.
+      </td>
+    </tr>
+    <tr valign="top">
+      <td>
+        <font color="purple"><tt><b>GET_Long()</b></tt></font>
+      </td>
+      <td>
+        <font color="blue"><tt>FT_Get_Long(stream)</tt></font>
+      </td>
+      <td>
+        Reads a 32-bit signed big-endian integer.
+      </td>
+    </tr>
+    <tr valign="top">
+      <td>
+        <font color="purple"><tt><b>GET_ULong()</b></tt></font>
+      </td>
+      <td>
+        <font color="blue"><tt>(FT_ULong)<br>
+        FT_Get_Long(stream)</tt></font>
+      </td>
+      <td>
+        Reads a 32-bit unsigned big-endian integer.
+      </td>
+    </tr>
+  </table>
+
+  <p>(Note that an <b>Offset</b> is an integer stored with 3&nbsp;bytes on
+  the file.)</p>
+
+  <p>All this means that the following code</p>
+
+  <font color="blue">
+  <pre>
+    error = FT_Access_Frame( stream, 2 + 4 + 4 );
+    if ( error ) goto ...
+
+    str.value1 = FT_Get_Short( stream );
+    str.value2 = FT_Get_ULong( stream );
+    str.value3 = FT_Get_ULong( stream );
+
+    FT_Forget_Frame( stream );</pre>
+    </font>
+
+    <p>can be simplified with macros:</p>
+
+    <font color="blue">
+    <pre>
+    if ( ACCESS_Frame( 2 +4 + 4 ) ) goto ...
+
+    str.value1 = GET_Short();
+    str.value2 = GET_ULong();
+    str.value3 = GET_ULong();
+
+    FORGET_Frame();</pre>
+    </font>
+
+    <p>Which is clearer.  Notice that <tt>error</tt> and <tt>stream</tt>
+    must be defined locally though for this code to work!</p>
+
+    <hr>
+
+  <h2>
+    III. Alternatives
+  </h2>
+
+  <p>It is sometimes useful to read small integers from a font file without
+  using a frame.  Some functions have been introduced in FreeType&nbsp;2 to
+  do just that, and they are of the form <font
+  color="blue"><tt>FT_Read_xxxx</tt></font>.</p>
+
+  <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 places an error code in the <tt>error</tt>
+  variable.</p>
+
+  <p>Thus, reading a single big-endian integer is shorter than using a frame
+  for it.</p>
+
+  <p>Note that there are also macros <font
+  color="purple"><tt>READ_xxx()</tt></font> which translate to</p>
+
+  <font color="blue">
+  <pre>
+    FT_Read_xxx( stream, &error ), error != FT_Err_Ok</pre>
+  </font>
+
+  <p>and can be used as in</p>
+
+  <font color="blue">
+  <pre>
+    if ( READ_UShort( variable1 ) ||
+         READ_ULong ( variable2 ) )
+      goto Fail;</pre>
+  </font>
+
+  <p>if <tt>error</tt> and <tt>stream</tt> are already defined locally.</p>
+
+</td></tr>
+</table>
+</center>
+
+</body>
+</html>
diff --git a/docs/tutorial/index.html b/docs/tutorial/index.html
index 0f4c74c..cbba6ec 100644
--- a/docs/tutorial/index.html
+++ b/docs/tutorial/index.html
@@ -1,12 +1,12 @@
 <!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 Tutorial</title>
+  <meta http-equiv="Content-Type"
+        content="text/html; charset=iso-8859-1">
+  <meta name="Author"
+        content="David Turner">
+  <title>FreeType 2 Tutorial</title>
 </head>
-<body>
 
 <body text="#000000"
       bgcolor="#FFFFFF"
@@ -14,632 +14,746 @@
       vlink="#51188E"
       alink="#FF0000">
 
-<center>
-<h1>
-FreeType 2.0 Tutorial</h1></center>
+<h1 align=center>
+  FreeType 2.0 Tutorial
+</h1>
 
-<center>
-<h3>
-&copy; 2000 David Turner (<a href="mailto:david@freetype.org">david@freetype.org</a>)<br>
-&copy; 2000 The FreeType Development Team
-(<a href="http://www.freetype.org">www.freetype.org</a>)
-</h3></center>
+<h3 align=center>
+  &copy; 2000 David Turner
+    (<a href="mailto:david@freetype.org">david@freetype.org</a>)<br>
+  &copy; 2000 The FreeType Development Team
+    (<a href="http://www.freetype.org">www.freetype.org</a>)
+</h3>
 
 <center>
-<table width=650><tr><td>
-
-<p><br>
-<hr WIDTH="100%">
-<br>&nbsp;
-<h2>Introduction:</h2>
-<ul>
-    This simple tutorial will teach you how to use the FreeType 2 library
-    in your own applications.
-</ul>
-
-<p><hr><p>
-
-<h3>1. Header files :</h3>
-<ul>
-  To include the main FreeType header file, simply use:<p>
-  <ul><font color="blue"><tt>
-      #include &lt;freetype/freetype.h&gt;<p>
-  </tt></font></ul>
-  in your application code. Note that other files are available in the
-  FreeType include directory, most of them being included by
-  <tt>"freetype.h"</tt>. They will be described later in this tutorial.
-</ul>
-
-<p><hr><p>
-
-<h3>2. Initialise the library:</h3>
-<ul>
-  Simply create a variable of type <tt>FT_Library</tt> named, for example,
-  <tt>library</tt>, and call the function <tt>FT_Init_FreeType</tt> as in:
-
-  <font color="blue"><pre>
-       #include &lt;freetype/freetype.h&gt;
-
-       FT_Library  library;
-
-       ....
-
-       {
-         ..
-         error = FT_Init_FreeType( &library );
-         if (error) { .. an error occured during library initialisation .. }
-       }
-  </pre></font>
-  <p>
-  This function is in charge of the following:<p>
-  <ul>
-      <li>Creating a new instance of the FreeType 2 library, and set
-          the handle <tt>library</tt> to it.
-          <p>
-
-      <li>Load each font driver that FreeType knows about in the library.
-          This means that by default, your new <tt>library</tt> object is
-          able to handle TrueType and Type 1 fonts gracefully.
-          <p>
-  </ul>
-  <p>
-  As you can see, the function returns an error code, like most others in the
-  FreeType API. An error code of 0 <em>always</em> means that the operation
-  was succesful; otherwise, the value describes the error, and <tt>library</tt>
-  is set to NULL.
-</ul>
-
-<p><hr><p>
-
-<h3>3. Load a font face:</h3>
-<ul>
-  <h4>a. From a font file:</h4>
-  <ul>
-    Create a new <em>face</em> object by calling <tt>FT_New_Face</tt>. A
-    <em>face</em> describes a given typeface and style. For example,
-    "Times New Roman Regular" and "Times New Roman Italic" correspond to
-    two different faces.
-    <p>
-    <font color="blue"><pre>
-
-      FT_Library   library;   /* handle to library     */
-      FT_Face      face;      /* handle to face object */
+<table width="70%">
+<tr><td>
+
+  <hr>
+
+  <h2>
+    Introduction
+  </h2>
+
+  <p>This short tutorial will teach you how to use the FreeType&nbsp;2
+  library in your own applications.</p>
+
+  <hr>
+
+    <h3>
+      1. Header files
+    </h3>
+
+    <p>To include the main FreeType header file, simply say</p>
+
+    <font color="blue">
+    <pre>
+    #include &lt;freetype/freetype.h&gt;</pre>
+    </font>
 
+    <p>in your application code.  Note that other files are available in the
+    FreeType include directory, most of them being included by
+    <tt>"freetype.h"</tt>.  They will be described later in this
+    tutorial.</p>
+
+    <hr>
+
+    <h3>
+      2. Initialize the library
+    </h3>
+
+    <p>Simply create a variable of type <tt>FT_Library</tt> named, for
+    example, <tt>library</tt>, and call the function
+    <tt>FT_Init_FreeType()</tt> as in</p>
+
+    <font color="blue">
+    <pre>
+    #include &lt;freetype/freetype.h&gt;
+
+    FT_Library  library;
+
+    ...
+
+    {
+      ...
       error = FT_Init_FreeType( &library );
-      if (error) { ..... }
+      if ( error )
+      {
+        ... an error occurred during library initialization ...
+      }
+    }</pre>
+    </font>
+
+    <p>This function is in charge of the following:</p>
+
+    <ul>
+      <li>
+         <p>Creating a new instance of the FreeType&nbsp;2 library, and set
+         the handle <tt>library</tt> to it.</p>
+      </li>
+      <li>
+        <p>Load each font driver that FreeType knows about in the library. 
+        This means that by default, your new <tt>library</tt> object is able
+        to handle TrueType and Type&nbsp;1 fonts gracefully.</p>
+      </li>
+    </ul>
+
+    <p>As you can see, the function returns an error code, like most others
+    in the FreeType API.  An error code of&nbsp;0 <em>always</em> means that
+    the operation was successful; otherwise, the value describes the error,
+    and <tt>library</tt> is set to NULL.</p>
+
+    <hr>
+
+    <h3>
+      3. Load a font face
+    </h3>
+
+      <h4>
+        a. From a font file
+      </h4>
+
+      <p>Create a new <em>face</em> object by calling <tt>FT_New_Face</tt>. 
+      A <em>face</em> describes a given typeface and style.  For example,
+      "Times New Roman Regular" and "Times New Roman Italic" correspond to
+      two different faces.</p>
+
+      <font color="blue">
+      <pre>
+    FT_Library   library;   /* handle to library     */
+    FT_Face      face;      /* handle to face object */
+
+    error = FT_Init_FreeType( &library );
+    if ( error ) { ... }
+
+    error = FT_New_Face( library,
+                         "/usr/share/fonts/truetype/arial.ttf",
+                         0,
+                         &face );
+    if ( error == FT_Err_Unknown_File_Format )
+    {
+      ... the font file could be opened and read, but it appears
+      ... that its font format is unsupported
+    }
+    else if ( error )
+    {
+      ... another error code means that the font file could not
+      ... be opened or read, or simply that it is broken...
+    }</pre>
+      </font>
+
+      <p>As you can certainly imagine, <tt>FT_New_Face</tt> opens a font
+      file, then tries to extract one face from it.  Its parameters are</p>
+
+      <table cellpadding=5>
+        <tr valign="top">
+          <td>
+            <tt><b>library</b></tt>
+          </td>
+          <td>
+            <p>handle to the FreeType library instance where the face object
+            is created</p>
+          </td>
+        </tr>
+        <tr valign="top">
+          <td>
+            <tt><b>filepathname</b></tt>
+          </td>
+          <td>
+            <p>the font file pathname (standard C string).</p>
+          </td>
+        </tr>
+        <tr valign="top">
+          <td>
+            <tt><b>face_index</b></tt>
+          </td>
+          <td>
+            <p>Certain font formats allow several font faces to be embedded
+            in a single file.</p>
+
+            <p>This index tells which face you want to load.  An error will
+            be returned if its value is too large.</p>
+
+            <p>Index 0 always work though.</p>
+          </td>
+        </tr>
+        <tr valign="top">
+          <td>
+            <tt><b>face</b></tt>
+          </td>
+          <td>
+            <p>A <em>pointer</em> to the handle that will be set to describe
+            the new face object.</p>
+
+            <p>It is set to NULL in case of error.</p>
+          </td>
+        </tr>
+      </table>
+
+      <p>To know how many faces a given font file contains, simply load its
+      first face (use <tt>face_index</tt>=0), then see the value of
+      <tt>face->num_faces</tt> which indicates how many faces are embedded
+      in the font file.</p>
+
+      <h4>
+        b. From memory
+      </h4>
+
+      <p>In the case where you have already loaded the font file in memory,
+      you can similarly create a new face object for it by calling
+      <tt>FT_New_Memory_Face</tt> as in</p>
+
+      <font color="blue">
+      <pre>
+    FT_Library   library;   /* handle to library     */
+    FT_Face      face;      /* handle to face object */
+
+    error = FT_Init_FreeType( &library );
+    if ( error ) { ... }
+
+    error = FT_New_Memory_Face( library,
+                                buffer,    /* first byte in memory */
+                                size,      /* size in bytes        */
+                                0,         /* face_index           */
+                                &face );
+    if ( error ) { ... }</pre>
+      </font>
+
+      <p>As you can see, <tt>FT_New_Memory_Face()</tt> simply takes a
+      pointer to the font file buffer and its size in bytes instead of a
+      file pathname.  Other than that, it has exactly the same semantics as
+      <tt>FT_New_Face()</tt>.</p>
+
+      <h4>
+        c. From other sources (compressed files, network, etc.)
+      </h4>
+
+      <p>There are cases where using a file pathname or preloading the file
+      in memory is simply not enough.  With FreeType&nbsp;2, it is possible
+      to provide your own implementation of i/o routines.</p>
+
+      <p>This is done through the <tt>FT_Open_Face()</tt> function, which
+      can be used to open a new font face with a custom input stream, select
+      a specific driver for opening, or even pass extra parameters to the
+      font driver when creating the object.  We advise you to refer to the
+      FreeType&nbsp;2 reference manual in order to learn how to use it.</p>
+
+      <hr>
+
+    <h3>
+      4. Accessing face content
+    </h3>
+
+    <p>A <em>face object</em> models all information that globally describes
+    the face.  Usually, this data can be accessed directly by dereferencing
+    a handle, like</p>
+
+    <table cellpadding=5>
+      <tr valign="top">
+        <td>
+          <tt><b>face->num_glyphs</b></tt>
+        </td>
+        <td>
+          <p>Gives the number of <em>glyphs</em> available in the font face.
+          A glyph is simply a character image.  It doesn't necessarily
+          correspond to a <em>character code</em> though.</p>
+        </td>
+      </tr>
+      <tr valign="top">
+        <td>
+          <tt><b>face->flags</b></tt>
+        </td>
+        <td>
+          <p>A 32-bit integer containing bit flags used to describe some
+          face properties.  For example, the flag
+          <tt>FT_FACE_FLAG_SCALABLE</tt> is used to indicate that the face's
+          font format is scalable and that glyph images can be rendered for
+          all character pixel sizes.  For more information on face flags,
+          please read the <a href="#">FreeType&nbsp;2 API Reference</a>.</p>
+        </td>
+      </tr>
+      <tr valign="top">
+        <td>
+          <tt><b>face->units_per_EM</b></tt>
+        </td>
+        <td>
+          <p>This field is only valid for scalable formats (it is set to 0
+          otherwise).  It indicates the number of font units covered by the
+          EM.</p>
+        </td>
+      </tr>
+      <tr valign="top">
+        <td>
+          <tt><b>face->num_fixed_sizes</b></tt>
+        </td>
+        <td>
+          <p>This field gives the number of embedded bitmap <em>strikes</em>
+          in the current face.  A <em>strike</em> is simply a series of
+          glyph images for a given character pixel size.  For example, a
+          font face could include strikes for pixel sizes 10, 12
+          and&nbsp;14.  Note that even scalable font formats can have
+          embedded bitmap strikes!</p>
+        </td>
+      </tr>
+      <tr valign="top">
+        <td>
+          <tt><b>face->fixed_sizes</b></tt>
+        </td>
+        <td>
+          <p>this is a pointer to an array of <tt>FT_Bitmap_Size</tt>
+          elements.  Each <tt>FT_Bitmap_Size</tt> indicates the horizontal
+          and vertical <em>pixel sizes</em> for each of the strikes that are
+          present in the face.</p>
+        </td>
+      </tr>
+    </table>
+
+    <p>For a complete listing of all face properties and fields, please read
+    the <a href="#">FreeType&nbsp;2 API Reference</a>.<p>
+
+    <hr>
+
+    <h3>
+      5. Setting the current pixel size
+    </h3>
+
+    <p>A face object also holds a handle to a <em>size object</em> in its
+    <tt>face->size</tt> field.  The <em>size</em> object is used to model
+    all information for the face that is relative to a given character
+    size.</p>
+
+    <p>When a new face object is created, its size object defaults to the
+    character size of 10&nbsp;pixels (both horizontall and vertically) for
+    scalable formats.  For fixed-sizes formats, the size is more or less
+    undefined, which is why you must set it before trying to load a
+    glyph.</p>
+
+    <p>To do that, simply call <tt>FT_Set_Char_Size()</tt>.  Here is an
+    example where the character size is set to 16pt for a 300x300&nbsp;dpi
+    device:</p>
+
+    <font color="blue">
+    <pre>
+    error = FT_Set_Char_Size(
+              face,    /* handle to face object           */
+              0,       /* char_width in 1/64th of points  */
+              16*64,   /* char_height in 1/64th of points */
+              300,     /* horizontal device resolution    */
+              300 );   /* vertical device resolution      */</pre>
+    </font>
+
+    <p>You will notice that:</p>
+
+    <ul>
+      <li>
+        <p>The character width and heights are specified in 1/64th of
+        points.<p>
+      </li>
+      <li>
+        <p>The horizontal and vertical device resolutions are expressed in
+        <em>dots-per-inch</em>, or <em>dpi</em>. You can use 72 or
+        96&nbsp;dpi for display devices like the screen.</p>
+      </li>
+      <li>
+        <p>A value of&nbsp;0 for the character width means "<em>same as
+        character height</em>", a value of&nbsp;0 for the character height
+        means "<em>same as character width</em>".  Otherwise, it is possible
+        to specify different char widths and heights.</p>
+      </li>
+      <li>
+        <p>Using a value of 0 for the horizontal or vertical resolution means
+        72&nbsp;dpi, which is the default.</p>
+      </li>
+    </ul>
 
-      error = FT_New_Face( library,
-                           "/usr/share/fonts/truetype/arial.ttf",
-                           0,
-                           &face );
-      if (error == FT_Err_Unknown_File_Format)
+    <p>This function computes the character pixel size that corresponds to
+    the character width and height and device resolutions.  However, if you
+    want to specify the pixel sizes yourself, you can simply call
+    <tt>FT_Set_Pixel_Sizes()</tt>, as in</p>
+
+    <font color="blue">
+    <pre>
+    error = FT_Set_Pixel_Sizes(
+              face,   /* handle to face object            */
+              0,      /* pixel_width                      */
+              16 );   /* pixel_height                     */</pre>
+    </font>
+
+    <p>This example will set the character pixel sizes to 16x16&nbsp;pixels. 
+    As previously, a value of&nbsp;0 for one of the dimensions means
+    "<em>same as the other</em>".</p>
+
+    <p>Note that both functions return an error code.  Usually, an error
+    occurs with a fixed-size font format (like FNT or PCF) when trying to
+    set the pixel size to a value that is not listed in the
+    <tt><b>face->fixed_sizes</b></tt> array.</p>
+
+    <hr>
+
+    <h3>
+      6. Loading a glyph image
+    </h3>
+
+      <h4>
+        a. Converting a character code into a glyph index
+      </h4>
+
+      <p>Usually, an application wants to load a glyph image based on its
+      <em>character code</em>, which is a unique value that defines the
+      character for a given <em>encoding</em>.  For example, the character
+      code&nbsp;65 represents the `A' in ASCII encoding.</p>
+
+      <p>A face object contains one or more tables, called
+      <em>charmaps</em>, that are used to convert character codes to glyph
+      indices.  For example, most TrueType fonts contain two charmaps.  One
+      is used to convert Unicode character codes to glyph indices, the other
+      is used to convert Apple Roman encoding into glyph indices.  Such
+      fonts can then be used either on Windows (which uses Unicode) and
+      Macintosh (which uses Apple Roman, bwerk).  Note also that a given
+      charmap might not map to all the glyphs present in the font.</p>
+
+      <p>By default, when a new face object is created, it lists all the
+      charmaps contained in the font face and selects the one that supports
+      Unicode character codes if it finds one.  Otherwise, it tries to find
+      support for Latin-1, then ASCII.</p>
+
+      <p>We will describe later how to look for specific charmaps in a face. 
+      For now, we will assume that the face contains at least a Unicode
+      charmap that was selected during <tt>FT_New_Face()</tt>.  To convert a
+      Unicode character code to a font glyph index, we use
+      <tt>FT_Get_Char_Index()</tt> as in</p>
+
+      <font color="blue">
+      <pre>
+    glyph_index = FT_Get_Char_Index( face, charcode );</pre>
+      </font>
+
+      <p>This will look the glyph index corresponding to the given
+      <tt>charcode</tt> in the charmap that is currently selected for the
+      face.  If charmap is selected, the function simply returns the
+      charcode.</p>
+
+      <p>Note that this is one of the rare FreeType functions that do not
+      return an error code.  However, when a given character code has no
+      glyph image in the face, the value&nbso;0 is returned.  By convention,
+      it always correspond to a special glyph image called the <b>missing
+      glyph</b>, which usually is represented as a box or a space.</p>
+
+      <h4>
+        b. Loading a glyph from the face
+      </h4>
+
+      <p>Once you have a glyph index, you can load the corresponding glyph
+      image.  Note that the glyph image can be in several formats.  For
+      example, it will be a bitmap for fixed-size formats like FNT, FON, or
+      PCF.  It will also be a scalable vector outline for formats like
+      TrueType or Type&nbsp;1.  The glyph image can also be stored in an
+      alternate way that is not known at the time of writing this
+      documentation.</p>
+
+      <p>The glyph image is always stored in a special object called a
+      <em>glyph slot</em>.  As its name suggests, a glyph slot is simply a
+      container that is able to hold one glyph image at a time, be it a
+      bitmap, an outline, or something else.  Each face object has a single
+      glyph slot object that can be accessed as
+      <b><tt>face->glyph</tt></b>.</p>
+
+      <p>Loading a glyph image into the slot is performed by calling
+      <tt>FT_Load_Glyph()</tt> as in</p>
+
+      <font color="blue">
+      <pre>
+    error = FT_Load_Glyph( 
+              face,          /* handle to face object */
+              glyph_index,   /* glyph index           */
+              load_flags );  /* load flags, see below */</pre>
+      </font>
+
+      <p>The <tt>load_flags</tt> value is a set of bit flags used to
+      indicate some special operations.  The default value
+      <tt>FT_LOAD_DEFAULT</tt> is&nbsp;0.  The function performs the
+      following:</p>
+
+      <ul>
+        <li>
+          <p>If there is a bitmap for the corresponding glyph and size, load
+          it in the glyph slot, unless the <tt>FT_LOAD_NO_BITMAP</tt> flag
+          is set.  This is even <em>true</em> for scalable formats (embedded
+          bitmaps are favored over outlines as they usually correspond to
+          higher-quality images of the same glyph).</p>
+        </li>
+        <li>
+          <p>If there is an outline for the corresponding glyph, load it
+          unless <tt>FT_LOAD_NO_OUTLINE</tt> is set.  Otherwise, scale it to
+          the current size, unless the <tt>FT_LOAD_NO_SCALE</tt> flag is
+          set.</p>
+        </li>
+        <li>
+          <p>If the outline was loaded and scaled, try to grid-fit it (which
+          dramatically improves its quality) unless the flag
+          <tt>FT_LOAD_NO_HINTING</tt> is set.</p>
+        </li>
+      </ul>
+
+      <p>There are a few others <tt>FT_LOAD_xxx</tt> flags defined.  For
+      more details see the <a href="#">FreeType&nbsp;2 API
+      Reference</a>.</p>
+
+      <h4>
+        c. Using other charmaps
+      </h4>
+
+      <p>As said before, when a new face object is created, it will look for
+      a Unicode, Latin-1, or ASCII charmap and select it.  The currently
+      selected charmap is accessed via <b><tt>face->charmap</tt></b>.  This
+      field is NULL when no charmap is selected, which typically happens
+      when you create a new <tt>FT_Face</tt> object from a font file that
+      doesn't contain an ASCII, Latin-1, or Unicode charmap (rare
+      stuff).</p>
+    
+      <p>The fields <b><tt>face->num_charmaps</tt></b> and
+      <b><tt>face->charmaps</tt></b> (notice the `s') can be used by client
+      applications to check which charmaps are available in a given
+      face.</p>
+
+      <p><b><tt>face->charmaps</tt></b> is an array of <em>pointers</em> to
+      the <tt><b>face->num_charmaps</b></tt> charmaps contained in the font
+      face.</p>
+
+      <p>Each charmap has a few visible fields used to describe it in more
+      detail.  For example, <tt><b>charmap->encoding</b></tt> is an
+      enumeration type that describes the charmap with FreeType codes.  One
+      can also look at <tt><b>charmap->platform_id</b></tt> and
+      <tt><b>charmap->encoding_id</b></tt> for more exotic needs.</p>
+
+      <p>Here's an example code that looks for a Chinese Big&nbsp;5 charmap,
+      then selects it via <tt>FT_Set_CharMap()</tt>:</p>
+
+      <font color="blue">
+      <pre>
+    FT_CharMap  found = 0;
+    FT_CharMap  charmap;
+    int         n;
+
+    for ( n = 0; n &lt; face->num_charmaps; n++ )
+    {
+      charmap = face->charmaps[n];
+      if ( charmap->encoding == ft_encoding_big5 )
       {
-         .... the font file could be opened and read, but it appears
-         .... that its font format is unsupported
+        found = charmap;
+        break;
       }
-      else if (error)
+    }
+
+    if ( !found ) { ... }
+
+    /* now, select the charmap for the face object */
+    error = FT_Set_CharMap( face, found );
+    if ( error ) { ... }</pre>
+      </font>
+
+      <p>One might now call <tt>FT_Get_Char_Index()</tt> with Big&nbsp;5
+      character codes to retrieve glyph indices.</p>
+
+      <hr>
+
+    <h3>
+      7. Accessing glyph image data
+    </h3>
+
+    <p>Glyph image data is accessible through <tt><b>face->glyph</b></tt>. 
+    See the definition of the <tt>FT_GlyphSlot</tt> type for more details. 
+    As stated previously, each face has a single glyph slot, where
+    <em>one</em> glyph image <em>at a time</em> can be loaded.  Each time
+    you call <tt>FT_Load_Glyph()</tt>, you erase the content of the glyph
+    slot with a new glyph image.</p>
+
+    <p>Note however that the glyph slot object itself doesn't change, only
+    its content, which means that you can perfectly create a "shortcut" to
+    access it as in</p>
+
+    <font color="blue">
+    <pre>
+    {
+      /* shortcut to glyph slot */
+      FT_GlyphSlot  glyph = face->glyph;
+
+      for ( n = 0; n &lt; face->num_glyphs; n++ )
       {
-         .... another error code means that the font file could not
-         .... be opened, read or simply that it is broken..
+        ... load glyph n ...
+        ... access glyph data as glyph->xxxx
       }
-    </pre></font>
-    <p>
-    As you certainly imagine, <tt>FT_New_Face</tt> opens a font file then
-    tries to extract one face from it. Its parameters are :<p>
-    <ul>
+    }</pre>
+    </font>
+
+    <p>The <tt>glyph</tt> variable will be valid until its parent
+    <tt>face</tt> is destroyed.  Here are a few important fields of the
+    glyph slot:<p>
+
     <table cellpadding=5>
-    <tr valign="top"><td><tt><b>library</b></tt>
-        <td>handle to the FreeType library instance where the face object is
-            created
-
-    <tr valign="top"><td><tt><b>filepathname</b></tt>
-        <td>the font file pathname (standard C string).
-
-    <tr valign="top"><td><tt><b>face_index</b></tt>
-        <td>Certain font formats allow several font faces to be embedded in
-            a single file.<br>
-            This index tells which face you want to load. An
-            error will be returned if its value is too large.<br>
-            Index 0 always work though.
-
-    <tr><td><tt><b>face</b></tt>
-        <td>A <em>pointer</em> to the handle that will be set to
-            describe the new face object.<br>
-            It is set to NULL in case of error.
+      <tr valign="top">
+        <td>
+          <tt><b>glyph->format</b></tt>
+        </td>
+        <td>
+          <p>Indicates the type of the loaded glyph image.  Can be either
+          <tt>ft_glyph_format_bitmap</tt>, <tt>ft_glyph_format_outline</tt>,
+          or other values.</p>
+        </td>
+      </tr>
+      <tr valign="top">
+        <td>
+          <tt><b>glyph->metrics</b></tt>
+        </td>
+        <td>
+          <p>A simple structure used to hold the glyph image's metrics. 
+          Note that <em>most distances are expressed in 1/64th of
+          pixels!</em> See the API reference or the user guide for a
+          description of the <tt>FT_Glyph_Metrics</tt> structure.</p>
+        </td>
+      </tr>
+      <tr valign="top">
+        <td>
+          <tt><b>glyph->bitmap</b></tt>
+        </td>
+        <td>
+          <p>If the glyph slot contains a bitmap, a simple
+          <tt>FT_Bitmap</tt> that describes it.  See the API reference or
+          user guide for a description of the <tt>FT_Bitmap</tt>
+          structure.</p>
+        </td>
+      </tr>
+      <tr valign="top">
+        <td>
+          <tt><b>glyph->outline</b></tt>
+        </td>
+        <td>
+          <p>When the glyph slot contains a scalable outline, this structure
+          describes it. See the definition of the <tt>FT_Outline</tt>
+          structure.</p>
+        </td>
+      </tr>
     </table>
-    </ul>
-    <p>
-    To known how many faces a given font file contains, simply load its
-    first face (use <tt>face_index</tt>=0), then see the value of
-    <tt>face->num_faces</tt> which indicates how many faces are embedded in
-    the font file.
-  </ul>
-  <p>
-
-  <h4>b. From memory:</h4>
-  <ul>
-    In the case where you have already loaded the font file in memory, you
-    can similarly create a new face object for it by calling
-    <tt>FT_New_Memory_Face</tt> as in:
-    <p>
-    <font color="blue"><pre>
-
-      FT_Library   library;   /* handle to library     */
-      FT_Face      face;      /* handle to face object */
 
-      error = FT_Init_FreeType( &library );
-      if (error) { ..... }
-
-      error = FT_New_Memory_Face( library,
-                                  buffer,    /* first byte in memory */
-                                  size,      /* size in bytes        */
-                                  0,         /* face_index           */
-                                  &face );
-      if (error) { ... }
-    </pre></font>
-    <p>
-    As you can see, <tt>FT_New_Memory_Face</tt> simply takes a pointer to
-    the font file buffer and its size in bytes instead of a file pathname.
-    Other than that, it has exactly the same semantics than
-    <tt>FT_New_Face</tt>.
-  </ul>
-  <p>
-
-  <h4>c. From other sources: (compressed files, network, etc..)</h4>
-  <ul>
-    There are cases where using a filepathname or preloading the file in
-    memory is simply not enough. With FreeType 2, it is possible to provide
-    your own implementation of i/o routines.
-    <p>
-    This is done through the <tt>FT_Open_Face</tt> function, which can be
-    used to open a new font face with a custom input stream, select a specific
-    driver for opening, or even pass extra parameters to the font driver
-    when creating the object. We advise you to refer to the FreeType 2
-    Reference in order to learn how to use it.
-    <p>
-  </ul>
-  <p>
-</ul>
-
-<p><hr><p>
-
-<h3>4. Accessing face content:</h3>
-<ul>
-  A <em>face object</em> models all information that globally describes
-  the face. Usually, this data can be accessed directly by dereferencing
-  a handle, like :
-  <p>
-  <table cellpadding=5>
-  <tr valign="top">
-     <td><tt><b>face&minus;>num_glyphs</b></tt>
-     <td>gives the number of <em>glyphs</em> available in the font face. A glyph
-         is simply a character image. It doesn't necessarily correspond to
-         a <em>character code</em> though.
-
-  <tr valign="top">
-     <td><tt><b>face&minus;>flags</b></tt>
-     <td>a 32-bit integer containing bit flags used to describe some face
-         properties. For example, the flag <tt>FT_FACE_FLAG_SCALABLE</tt> is
-         used to indicate that the face's font format is scalable and that
-         glyph images can be rendered for all character pixel sizes. For more
-         information on face flags, please read the <a href="#">FreeType API
-         Reference</a>
-
-  <tr valign="top">
-     <td><tt><b>face&minus;>units_per_EM</b></tt>
-     <td>This field is only valid for scalable formats (it is set to 0
-         otherwise). It indicates the number of font units covered by the
-         EM.
-
-  <tr valign="top">
-     <td><tt><b>face&minus;>num_fixed_sizes</b></tt>
-     <td>this field gives the number of embedded bitmap <em>strikes</em> in
-         the current face. A <em>strike</em> is simply a series of glyph
-         images for a given character pixel size. For example, a font face
-         could include strikes for pixel sizes 10, 12 and 14. Note that even
-         scalable font formats can embedded bitmap strikes !
-
-  <tr valign="top">
-     <td><tt><b>face&minus;>fixed_sizes</b></tt>
-     <td>this is a pointer to an array of <tt>FT_Bitmap_Size</tt> element.
-         each <tt>FT_Bitmap_Size</tt> indicates the horizontal and vertical
-         <em>pixel sizes</em> for each of the strikes that are present in the face.
-
-  </table>
-  <p>
-  For a complete listing of all face properties and fields, please read
-  the <a href="#">FreeType 2 API Reference</a>.
-  <p>
-</ul>
-
-<p><hr><p>
-<h3>5. Setting the current pixel size:</h3>
-<ul>
-  A face object also holds a handle to a <em>size object</em> in its
-  <tt>face->size</tt> field. The <em>size</em> object is used to model
-  all information for the face that is relative to a given character
-  size.
-  <p>
-  When a new face object is created, its size object defaults to the
-  character size of 10 pixels (both horizontall and vertically) for
-  scalable formats. For fixed-sizes formats, the size is more or less
-  undefined, which is why you must set it before trying to load a
-  glyph.
-  <p>
-  To do that, simply call <tt>FT_Set_Char_Size</tt>. Here's an example
-  where the character size is set to 16 pts for a 300x300 dpi device:
-  <p>
-  <font color="blue"><pre>
-        error = FT_Set_Char_Size( face,    /* handle to face object           */
-                                  0,       /* char_width in 1/64th of points  */
-                                  16*64,   /* char_height in 1/64th of points */
-                                  300,     /* horizontal device resolution    */
-                                  300 );   /* vertical device resolution      */
-  </pre></font>
-  <p>
-  You'll notice that:<p>
-  <ul>
-     <li>The character width and heights are specified in 1/64th of points.<p>
-
-     <li>The horizontal and vertical device resolutions are expressed in
-         <em>dots-per-inch</em>, or <em>dpi</em>. You can use 72 or 96 dpi
-         for display devices like the screen.<p>
-
-     <li>A value of 0 for the character width means "<em>same as character
-         height</em>", a value of 0 for the character height means
-         "<em>same as character width</em>". Otherwise, it is possible to
-         specify different char width and height.<p>
-
-     <li>Using a value of 0 for the horizontal or vertical resolution means
-         72 dpi, which is the default.
-	 <p>
-  </ul>
-  <p>
-  This function computes the character pixel size that corresponds to the
-  character width and height and device resolutions. However, if you want
-  to specify the pixel sizes yourself, you can simply call
-  <tt>FT_Set_Pixel_Sizes</tt>, as in:
-  <p>
-  <font color="blue"><pre>
-     error = FT_Set_Pixel_Sizes( face,   /* handle to face object            */
-                                 0,      /* pixel_width                      */
-                                 16 );   /* pixel_height                     */
-  </pre></font>
-  <p>
-  This example will set the character pixel sizes to 16x16 pixels. As
-  previously, a value of 0 for one of the dimensions means "<em>same as
-  the other</em>".
-  <p>
-  Note that both functions return an error code. Usually, an error occurs
-  with a fixed-size font format (like FNT or PCF) when trying to set the
-  pixel size to a value that is not listed in the
-  <tt><b>face->fixed_sizes</b></tt> array.
-</ul>
-
-<p><hr><p>
-
-<h3>6. Loading a glyph image:</h3>
-<ul>
-  <h4>a. Converting a character code into a glyph index:</h4>
-  <ul>
-     Usually, an application wants to load a glyph image based on its
-     <em>character code</em>, which is a unique value that defines the
-     character for a given <em>encoding</em>. For example, the character
-     code 65 represents the 'A' in the ASCII encoding.
-     <p>
-     A face object contains one or more tables, called <em>charmaps</em>,
-     that are used to convert character codes to glyph indices. For example,
-     most TrueType fonts contain two charmaps. One is used to convert Unicode
-     character codes to glyph indices, the other is used to convert
-     Apple Roman encoding into glyph indices. Such fonts can then be used
-     either on Windows (which uses Unicode) and Macintosh (which uses
-     Apple Roman, bwerk..). Note also that a given charmap might not map to all
-     the glyphs present in the font.
-     <p>
-     By default, when a new face object is created, it lists all the charmaps
-     contained in the font face and selects the one that supports Unicode
-     character codes if it finds one. Otherwise, it tries to find support for
-     Latin-1, then ASCII.
-     <p>
-     We'll describe later how to look for specific charmaps in a face. For
-     now, we'll assume that the face contains at least a Unicode charmap that
-     was selected during <tt>FT_New_Face</tt>. To convert a Unicode character
-     code to a font glyph index, we use <tt>FT_Get_Char_Index</tt> as in:
-     <p>
-     <font color="blue"><pre>
-         glyph_index = FT_Get_Char_Index( face, charcode );
-     </pre></font>
-     <p>
-     This will look the glyph index corresponding to the given <tt>charcode</tt>
-     in the charmap that is currently selected for the face. If charmap is
-     selected, the function simply returns the charcode.
-     <p>
-     Note that this is one of the rare FreeType functions that do not return
-     an error code. However, when a given character code has no glyph image in
-     the face, the value 0 is returned. By convention, it always correspond to
-     a special glyph image called the <b>missing glyph</b>, which usually is
-     represented as a box or a space.
-     <p>
-  </ul>
-  <p>
-
-  <h4>b. Loading a glyph from the face:</h4>
-  <ul>
-     Once you have a glyph index, you can load the corresponding glyph image.
-     Note that the glyph image can be in several formats. For example, it will
-     be a bitmap for fixed-size formats like FNT, FON or PCF. It will also
-     be a scalable vector outline for formats like TrueType or Type 1. The
-     glyph image can also be stored in an alternate way that is not known
-     at the time of writing this documentation.
-     <p>
-     The glyph image is always stored in a special object called a
-     <em>glyph slot</em>. As it names suggests, a glyph slot is simply a
-     container that is able to hold one glyph image at a time, be it a bitmap,
-     an outline, or something else. Each face object has a single glyph slot
-     object that can be accessed as <b><tt>face&minus;&gt;glyph</tt></b>.
-     <p>
-     Loading a glyph image into the slot is performed by calling
-     <tt>FT_Load_Glyph</tt> as in:
-     <p>
-     <font color="blue"><pre>
-        error = FT_Load_Glyph( face,          /* handle to face object */
-                               glyph_index,   /* glyph index           */
-                               load_flags );  /* load flags, see below */
-     </pre></font>
-     <p>
-     The <tt>load_flags</tt> value is a set of bit flags used to indicate
-     some special operations. The default value <tt>FT_LOAD_DEFAULT</tt> is
-     0. The function performs the following :<p>
-     <ul>
-         <li>if there is a bitmap for the corresponding glyph and size, load
-             it in the glyph slot, unless the <tt>FT_LOAD_NO_BITMAP</tt> flag
-             is set. This is even <em>true</em> for scalable formats (embedded
-             bitmaps are favored over outlines as they usually correspond to
-             higher-quality images of the same glyph).
-             <p>
-
-         <li>if there is an outline for the corresponding glyph, load it
-             unless <tt>FT_LOAD_NO_OUTLINE</tt> is set. Otherwise, scale it
-             to the current size, unless the <tt>FT_LOAD_NO_SCALE</tt> flag
-             is set.
-             <p>
-
-         <li>if the outline was loaded and scaled, try to grid-fit it (which
-             dramatically improves its quality) unless the flag
-             <tt>FT_LOAD_NO_HINTING</tt> is set.
-     </ul>
-     <p>
-     There are a few others <tt>FT_LOAD_xxx</tt> flags defined. For more
-     details see the <a href="#">FreeType 2 API Reference</a>.
-  </ul>
-  <p>
-
-  <h4>c. Using other charmaps:</h4>
-  <ul>
-    As said before, when a new face object is created, it will look for
-    a Unicode, Latin-1 or ASCII charmap and select it. The currently
-    selected charmap is accessed via <b><tt>face&minus;&gt;charmap</tt></b>. This
-    field is NULL when no charmap is selected, which typically happen when you
-    create a new <tt>FT_Face</tt> object from a font file that doesn't contain
-    an ASCII, Latin-1 or Unicode charmap (rare stuff).
-    <p>
-    The fields <b><tt>face&minus;&gt;num_charmaps</tt></b> and
-    <b><tt>face&minus;&gt;charmaps</tt></b> (notice the 's') can be used by
-    client applications to look at what charmaps are available in a given
-    face.
-    <p>
-    <b><tt>face&minus;&gt;charmaps</tt></b> is an array of <em>pointers</em>
-    to the <tt><b>face&minus;&gt;num_charmaps</b></tt> charmaps contained in the
-    font face.
-    <p>
-    Each charmap has a few visible fields used to describe it in more details.
-    For example, <tt><b>charmap->encoding</b></tt> is an enumeration type
-    that describes the charmap with FreeType codes. One can also look at
-    <tt><b>charmap->platform_id</b></tt> and
-    <tt><b>charmap->encoding_id</b></tt> for more exotic needs.
-    <p>
-    Here's an example code that looks for a chinese Big5 charmap then
-    selects it via <tt>FT_Set_CharMap</tt>:
-    <p>
-    <font color="blue"><pre>
-        FT_CharMap  found = 0;
-        FT_CharMap  charmap;
-        int         n;
-
-        for ( n = 0; n &lt; face-&gt;num_charmaps; n++ )
-        {
-          charmap = face&gt;charmaps[n];
-          if (charmap->encoding == ft_encoding_big5)
-          {
-            found = charmap;
-            break;
-          }
-        }
-
-        if (!found) { ... }
-
-        /* now, select the charmap for the face object */
-        error = FT_Set_CharMap( face, found );
-        if (error) { .... }
-    </pre></font>
-    <p>
-    One might now call <tt>FT_Get_Char_Index</tt> with Big5 character codes
-    to retrieve glyph indices.
-    <p>
-  </ul>
-  <p>
-</ul>
-
-<p><hr><p>
-
-<h3>7. Accessing glyph image data:</h3>
-<ul>
-  Glyph image data is accessible through <tt><b>face&minus;&gt;glyph</b></tt>.
-  See the definition of the <tt>FT_GlyphSlot</tt> type for more details. As
-  stated previously, each face has a single glyph slot, where <em>one</em> glyph
-  image <em>at a time</em> can be loaded. Each time you call
-  <tt>FT_Load_Glyph</tt>, you erase the content of the glyph slot with a new
-  glyph image.
-  <p>
-  Note however that the glyph slot object itself doesn't change, only its
-  content, which means that you can perfectly create a "shortcut" to access
-  it as in:
-  <p>
-  <font color="blue"><pre>
-     {
-       FT_GlyphSlot  glyph = face->glyph;  /* shortcut to glyph slot */
-
-       for ( n = 0; n &lt; face->num_glyphs; n++ )
-       {
-         .... load glyph n...
-         .... access glyph data as glyph-&gt;xxxx
-       }
-     }
-  </pre></font>
-  <p>
-  The <tt>glyph</tt> variable will be valid until its parent <tt>face</tt>
-  is destroyed. Here are a few important fields of the glyph slot:
-  <p>
-  <table cellpadding=10>
-    <tr valign="top">
-       <td><tt><b>glyph&minus;&gt;format</b></tt>
-       <td>Indicates the type of the loaded glyph image. Can be either
-           <tt>ft_glyph_format_bitmap</tt>, <tt>ft_glyph_format_outline</tt>
-           or other values.
-
-    <tr valign="top">
-       <td><tt><b>glyph&minus;&gt;metrics</b></tt>
-       <td>A simple structure used to hold the glyph image's metrics. Note
-           that <em>most distances are expressed in 1/64th of pixels !</em>
-           See the API reference or User Guide for a description of the
-           <tt>FT_Glyph_Metrics</tt> structure.
-
-    <tr valign="top">
-       <td><tt><b>glyph&minus;&gt;bitmap</b></tt>
-       <td>When the glyph slot contains a bitmap, a simple <tt>FT_Bitmap</tt>
-           that describes it. See the API reference or user guide for a
-           description of the <tt>FT_Bitmap</tt> structure.
-
-    <tr valign="top">
-       <td><tt><b>glyph&minus;&gt;outline</b></tt>
-       <td>When the glyph slot contains a scalable outline, this structure
-           describes it. See the definition of the <tt>FT_Outline</tt>
-           structure.
-  </table>
-  <p>
-</ul>
-
-<h3>8. Rendering glyph outlines into bitmaps:</h3>
-<ul>
-  You can easily test the format of the glyph image by inspecting the
-  <tt>face->glyph->format</tt> variable. If its value is
-  <tt>ft_glyph_format_bitmap</tt>, the glyph image that was loaded is
-  a bitmap that can be directly blit to your own surfaces through your
-  favorite graphics library (FreeType 2 doesn't provide bitmap blitting
-  routines, as you may imagine :-)
-  <p>
-  On the other hand, when the format if <tt>ft_glyph_format_outline</tt>
-  or something else, the library provides a means to convert such glyph
-  images to bitmaps through what are called <b>rasters</b>.
-  <p>
-
-
-
-  On the other hand, when the image is a scalable outline, or something else,
-  FreeType provides a function to convert the glyph image into a
-  pre-existing bitmap that you'll handle to it, named
-  <tt>FT_Get_Glyph_Bitmap</tt>. Here's a <em>simple</em> example code
-  that renders an outline into a <b>monochrome</b> bitmap :
-  <p>
-  <font color="blue"><pre>
-     {
-       FT_GlyphSlot  glyph;
-
-       .... load glyph ...
-
-       glyph = face-&gt;glyph;   /* shortcut to glyph data */
-       if (glyph->format == ft_glyph_format_outline )
-       {
-         FT_Bitmap  bit;
-
-         /* set-up a bitmap descriptor for our target bitmap */
-         bit.rows       = bitmap_height;
-         bit.width      = bitmap_width;
-         bit.pitch      = bitmap_row_bytes;
-         bit.pixel_mode = ft_pixel_mode_mono;  /* render into a mono bitmap */
-         bit.buffer     = bitmap_buffer;
-
-         /* render the outline directly into the bitmap */
-         error = FT_Get_Glyph_Bitmap( face, &bit );
-         if (error) { ... }
-       }
-     }
-  </pre></font>
-  <p>
-  You should note that <b><em><tt>FT_Get_Glyph_Bitmap</tt> doesn't create the
-  bitmap.</em></b> It only needs a descriptor, of type <tt>FT_Bitmap</tt>,
-  and writes directly into it.
-  <p>
-  Note that the FreeType scan-converter for outlines can also generate
-  anti-aliased glyph bitmaps with 128 level of grays. For now, it is
-  restricted to rendering to 8-bit gray-level bitmaps, though this may
-  change in the future. Here's some code to do just that:
-  <p>
-  <font color="blue"><pre>
-     {
-       FT_GlyphSlot  glyph;
-
-       .... load glyph ...
-
-       glyph = face-&gt;glyph;   /* shortcut to glyph data */
-       if (glyph->format == ft_glyph_format_outline )
-       {
-         FT_Bitmap  bit;
-
-         /* set-up a bitmap descriptor for our target bitmap */
-         bit.rows       = bitmap_height;
-         bit.width      = bitmap_width;
-         bit.pitch      = bitmap_row_bytes;
-         bit.pixel_mode = ft_pixel_mode_gray;  /* 8-bit gray-level bitmap */
-         bit.grays      = 128;                 /* MUST be 128 for now     */
-         bit.buffer     = bitmap_buffer;
-
-         /* clean the bitmap - IMPORTANT */
-         memset( bit.buffer, 0, bit.rows*bit.pitch );
-
-         /* render the outline directly into the bitmap */
-         error = FT_Get_Glyph_Bitmap( face, &bit );
-         if (error) { ... }
-       }
-     }
-  </pre></font>
-  <p>
-  You'll notice that :<p>
-  <ul>
-     <li>As previously, <tt>FT_Get_Glyph_Bitmap</tt> doesn't generate the
-         bitmap, it simply renders to it.<p>
-
-     <li>The target bitmap must be cleaned before calling the function. This
-         is a limitation of our current anti-aliasing algorithm and is
-         EXTREMELY important.<p>
-
-     <li>The anti-aliaser uses 128 levels of grays exclusively for now (this
-         will probably change in a near future). This means that you <b>must</b>
-         set <tt>bit.grays</tt> to 128. The generated image uses values from
-         0 (back color) to 127 (foreground color).
-         <p>
-
-     <li>It is <b>not</b> possible to render directly an anti-aliased outline into
-         a pre-existing gray-level bitmap, or even any colored-format one
-         (like RGB16 or paletted 8-bits). We will not discuss this issue in
-         great details here, but the reason is that we do not want to deal
-         with graphics composition (or alpha-blending) within FreeType.
-  </ul>
-  <p>
-  </ul>
-</ul>
-
-</td></tr></table>
+    <h3>
+      8. Rendering glyph outlines into bitmaps
+    </h3>
+
+    <p>You can easily test the format of the glyph image by inspecting the
+    <tt>face->glyph->format</tt> variable.  If its value is
+    <tt>ft_glyph_format_bitmap</tt>, the glyph image that was loaded is a
+    bitmap that can be directly blit to your own surfaces through your
+    favorite graphics library (FreeType&nbsp;2 doesn't provide bitmap
+    blitting routines, as you may imagine&nbsp;:-)</p>
+
+    <p>If the format is <tt>ft_glyph_format_outline</tt> or something else,
+    the library provides a means to convert such glyph images to bitmaps
+    through what are called <b>rasters</b>.</p>
+
+    <p>On the other hand, if the image is a scalable outline or something
+    else, FreeType provides a function to convert the glyph image into a
+    pre-existing bitmap that you will handle to it, named
+    <tt>FT_Get_Glyph_Bitmap</tt>.  Here's a <em>simple</em> example code
+    that renders an outline into a <b>monochrome</b> bitmap:</p>
+
+    <font color="blue">
+    <pre>
+    {
+      FT_GlyphSlot  glyph;
+
+      ... load glyph ...
+
+      glyph = face-&gt;glyph;   /* shortcut to glyph data */
+      if ( glyph->format == ft_glyph_format_outline )
+      {
+        FT_Bitmap  bit;
+
+        /* set-up a bitmap descriptor for our target bitmap */
+        bit.rows       = bitmap_height;
+        bit.width      = bitmap_width;
+        bit.pitch      = bitmap_row_bytes;
+        /* render into a mono bitmap */
+        bit.pixel_mode = ft_pixel_mode_mono;
+        bit.buffer     = bitmap_buffer;
+
+        /* render the outline directly into the bitmap */
+        error = FT_Get_Glyph_Bitmap( face, &bit );
+        if ( error ) { ... }
+      }
+    }</pre>
+    </font>
+
+    <p>You should note that <b><em><tt>FT_Get_Glyph_Bitmap()</tt> doesn't
+    create the bitmap</em></b>.  It only needs a descriptor, of type
+    <tt>FT_Bitmap</tt>, and writes directly into it.</p>
+
+    <p>Note that the FreeType scan-converter for outlines can also generate
+    anti-aliased glyph bitmaps with 128 level of grays.  For now, it is
+    restricted to rendering to 8-bit gray-level bitmaps, though this may
+    change in the future.  Here is some code to do just that:</p>
+
+    <font color="blue">
+    <pre>
+    {
+      FT_GlyphSlot  glyph;
+
+      ... load glyph ...
+
+      glyph = face->glyph;   /* shortcut to glyph data */
+      if ( glyph->format == ft_glyph_format_outline )
+      {
+        FT_Bitmap  bit;
+
+        /* set-up a bitmap descriptor for our target bitmap */
+        bit.rows       = bitmap_height;
+        bit.width      = bitmap_width;
+        bit.pitch      = bitmap_row_bytes;
+        /* 8-bit gray-level bitmap */
+        bit.pixel_mode = ft_pixel_mode_gray;
+        /* MUST be 128 for now     */
+        bit.grays      = 128;
+        bit.buffer     = bitmap_buffer;
+
+        /* clean the bitmap - IMPORTANT */
+        memset( bit.buffer, 0, bit.rows*bit.pitch );
+
+        /* render the outline directly into the bitmap */
+        error = FT_Get_Glyph_Bitmap( face, &bit );
+        if ( error ) { ... }
+      }
+    }</pre>
+    </font>
+
+    <p>You will notice that</p>
+
+    <ul>
+      <li>
+        <p>As previously, <tt>FT_Get_Glyph_Bitmap()</tt> doesn't generate
+        the bitmap, it simply renders to it.</p>
+      </li>
+      <li>
+        <p>The target bitmap must be cleaned before calling the function. 
+        This is a limitation of our current anti-aliasing algorithm and is
+        EXTREMELY important.</p>
+      </li>
+      <li>
+        <p>The anti-aliaser uses 128&nbsp;levels of grays exclusively for
+        now (this will probably change in a near future).  This means that
+        you <b>must</b> set <tt>bit.grays</tt> to&nbsp;128.  The generated
+        image uses values from 0 (back color) to 127 (foreground color).</p>
+      </li>
+      <li>
+        <p>It is <b>not</b> possible to render directly an anti-aliased
+        outline into a pre-existing gray-level bitmap, or even any
+        colored-format one (like RGB16 or paletted 8-bits).  We will not
+        discuss this issue in great details here, but the reason is that we
+        do not want to deal with graphics composition (or alpha-blending)
+        within FreeType.<p/>
+      </li>
+    </ul>
+</td></tr>
+</table>
 </center>
-<p><hr>
 
+</body>
+</html>
kc3-lang/freetype

Commit 883df43fec1bbd2e8658693c964045072ec3044d
