From b94713e9c58fa6655d69b6919c057acc465a4a89 Mon Sep 17 00:00:00 2001
From: David Turner <david@freetype.org>
Date: Mon, 17 Jan 2000 18:56:49 +0000
Subject: [PATCH] Added a FreeType 2 Tutorial !!

---
 docs/tutorial/index.html | 645 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 645 insertions(+)
 create mode 100644 docs/tutorial/index.html
diff --git a/docs/tutorial/index.html b/docs/tutorial/index.html
new file mode 100644
index 000000000..9dc1cd63b
--- /dev/null
+++ b/docs/tutorial/index.html
@@ -0,0 +1,645 @@
+<!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>
+</head>
+<body>
+
+<body text="#000000"
+      bgcolor="#FFFFFF"
+      link="#0000EF"
+      vlink="#51188E"
+      alink="#FF0000">
+
+<center>
+<h1>
+FreeType 2.0 Tutorial</h1></center>
+
+<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 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>
+  You only need to include the public header file named <tt>freetype.h</tt>
+  in your source code. Depending on how the library was installed on your
+  system, you might need to use :<p>
+  <ul><font color="blue"><tt>
+      #include &lt;freetype.h&gt;<p>
+  </tt></font></ul>
+  or
+  <ul><font color="blue"><tt>
+      #include &lt;freetype2/freetype.h&gt;<p>
+  </tt></font></ul>
+  in your application to include the public interface to FreeType.<p>
+</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.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 */
+    
+          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, read or simply that it is broken..
+          }
+    </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>
+    <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.
+    </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:</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 through the <tt>FT_Stream</tt>
+    type.
+    <p>
+    Basically, one has to set up a <tt>FT_Stream</tt> object, according to
+    the rules defined in the document named
+    <a href="#">FreeType 2 System Interface</a>, then pass it to the function
+    <tt>FT_Open_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) { ..... }
+
+          ... set up stream object, with handle "stream" ...
+          
+          error = FT_Open_Face( library,
+                                stream,    /* handle to stream objects */
+                                0,         /* face_index               */
+                                &face );
+          if (error) { ... }
+    </pre></font>
+    <p>
+    custom implementations of <tt>FT_Stream</tt> are great to provide advanced
+    features like automatic support of compressed files, network transparency,
+    using UTF-16 file pathnames, etc..
+    <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
+         "<em>same value since last call</em>". By default a new face object
+         has a size whose resolutions are set to 72x72 dpi.
+         <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
+     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.
+    <p>
+    The field <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;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;glyph</b></tt>.
+  See the definition of the <tt>FT_GlyphSlot</tt> type on more details. You
+  can perfectly create a shortcut to the glyph slot as in:
+  <p>
+  <font color="blue"><pre>
+     {
+       FT_GlyphSlot  glyph;
+
+       .... load glyph ...
+       
+       glyph = face-&gt;glyph;   /* shortcut to glyph data */
+       
+       .... access glyph data as glyph-&gt;xxxx
+     }
+  </pre></font>
+  <p>  
+  For example, one can access the following fields:
+  <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>all 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>
+  When the glyph image loaded in a glyph slot is a bitmap, you can use
+  your favorite graphics library to blit it to your own surfaces.
+  <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>
+  
+<p><hr>
+

`library` +	handle to the FreeType library instance where the face object is + created + +
`filepathname` +	the font file pathname (standard C string). + +
`face_index` +	Certain font formats allow several font faces to be embedded in + a single file. + This index tells which face you want to load. An + error will be returned if its value is too large. + Index 0 always work though. + +
`face` +	A pointer to the handle that will be set to + describe the new face object. + It is set to NULL in case of error. +
`face−>num_glyphs` +	gives the number of glyphs available in the font face. A glyph + is simply a character image. It doesn't necessarily correspond to + a character code though. + +
`face−>flags` +	a 32-bit integer containing bit flags used to describe some face + properties. For example, the flag `FT_FACE_FLAG_SCALABLE` 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 FreeType API + Reference + +
`face−>units_per_EM` +	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. + +
`face−>num_fixed_sizes` +	this field gives the number of embedded bitmap strikes in + the current face. A strike 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 ! + +
`face−>fixed_sizes` +	this is a pointer to an array of `FT_Bitmap_Size` element. + each `FT_Bitmap_Size` indicates the horizontal and vertical + pixel sizes for each of the strikes that are present in the face. + +
`glyph−>format` +	Indicates the type of the loaded glyph image. Can be either + `ft_glyph_format_bitmap`, `ft_glyph_format_outline` + or other values. + +
`glyph−>metrics` +	A simple structure used to hold the glyph image's metrics. Note + that all distances are expressed in 1/64th of pixels ! + See the API reference or User Guide for a description of the + `FT_Glyph_Metrics` structure. + +
`glyph−>bitmap` +	When the glyph slot contains a bitmap, a simple `FT_Bitmap` + that describes it. See the API reference or user guide for a + description of the `FT_Bitmap` structure. + +
`glyph−>outline` +	When the glyph slot contains a scalable outline, this structure + describes it. See the definition of the `FT_Outline` + structure. +