subsys/win32k/freetype/docs/tutorial/index.html

   1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type"
   5         content="text/html; charset=iso-8859-1">
   6   <meta name="Author"
   7         content="David Turner">
   8   <title>FreeType 2 Tutorial</title>
   9 </head>
  10
  11 <body text="#000000"
  12       bgcolor="#FFFFFF"
  13       link="#0000EF"
  14       vlink="#51188E"
  15       alink="#FF0000">
  16
  17 <h1 align=center>
  18   FreeType 2.0 Tutorial
  19 </h1>
  20
  21 <h3 align=center>
  22   &copy; 2000 David Turner
  23     (<a href="mailto:david@freetype.org">david@freetype.org</a>)<br>
  24   &copy; 2000 The FreeType Development Team
  25     (<a href="http://www.freetype.org">www.freetype.org</a>)
  26 </h3>
  27
  28 <center>
  29 <table width="70%">
  30 <tr><td>
  31
  32   <hr>
  33
  34   <h2>
  35     Introduction
  36   </h2>
  37
  38   <p>This short tutorial will teach you how to use the FreeType&nbsp;2
  39   library in your own applications.</p>
  40
  41   <hr>
  42
  43     <h3>
  44       1. Header files
  45     </h3>
  46
  47     <p>To include the main FreeType header file, simply say</p>
  48
  49     <font color="blue">
  50     <pre>
  51     #include &lt;freetype/freetype.h&gt;</pre>
  52     </font>
  53
  54     <p>in your application code.  Note that other files are available in the
  55     FreeType include directory, most of them being included by
  56     <tt>"freetype.h"</tt>.  They will be described later in this
  57     tutorial.</p>
  58
  59     <hr>
  60
  61     <h3>
  62       2. Initialize the library
  63     </h3>
  64
  65     <p>Simply create a variable of type <tt>FT_Library</tt> named, for
  66     example, <tt>library</tt>, and call the function
  67     <tt>FT_Init_FreeType()</tt> as in</p>
  68
  69     <font color="blue">
  70     <pre>
  71     #include &lt;freetype/freetype.h&gt;
  72
  73     FT_Library  library;
  74
  75     ...
  76
  77     {
  78       ...
  79       error = FT_Init_FreeType( &library );
  80       if ( error )
  81       {
  82         ... an error occurred during library initialization ...
  83       }
  84     }</pre>
  85     </font>
  86
  87     <p>This function is in charge of the following:</p>
  88
  89     <ul>
  90       <li>
  91          <p>Creating a new instance of the FreeType&nbsp;2 library, and set
  92          the handle <tt>library</tt> to it.</p>
  93       </li>
  94       <li>
  95         <p>Load each modules that FreeType knows about in the library.
  96         This means that by default, your new <tt>library</tt> object is able
  97         to handle TrueType, Type&nbsp;1, CID-keyed & OpenType/CFF fonts
  98         gracefully.</p>
  99       </li>
 100     </ul>
 101
 102     <p>As you can see, the function returns an error code, like most others
 103     in the FreeType API.  An error code of&nbsp;0 <em>always</em> means that
 104     the operation was successful; otherwise, the value describes the error,
 105     and <tt>library</tt> is set to NULL.</p>
 106
 107     <hr>
 108
 109     <h3>
 110       3. Load a font face
 111     </h3>
 112
 113       <h4>
 114         a. From a font file
 115       </h4>
 116
 117       <p>Create a new <em>face</em> object by calling <tt>FT_New_Face</tt>.
 118       A <em>face</em> describes a given typeface and style.  For example,
 119       "Times New Roman Regular" and "Times New Roman Italic" correspond to
 120       two different faces.</p>
 121
 122       <font color="blue">
 123       <pre>
 124     FT_Library   library;   /* handle to library     */
 125     FT_Face      face;      /* handle to face object */
 126
 127     error = FT_Init_FreeType( &library );
 128     if ( error ) { ... }
 129
 130     error = FT_New_Face( library,
 131                          "/usr/share/fonts/truetype/arial.ttf",
 132                          0,
 133                          &face );
 134     if ( error == FT_Err_Unknown_File_Format )
 135     {
 136       ... the font file could be opened and read, but it appears
 137       ... that its font format is unsupported
 138     }
 139     else if ( error )
 140     {
 141       ... another error code means that the font file could not
 142       ... be opened or read, or simply that it is broken...
 143     }</pre>
 144       </font>
 145
 146       <p>As you can certainly imagine, <tt>FT_New_Face</tt> opens a font
 147       file, then tries to extract one face from it.  Its parameters are</p>
 148
 149       <table cellpadding=5>
 150         <tr valign="top">
 151           <td>
 152             <tt><b>library</b></tt>
 153           </td>
 154           <td>
 155             <p>handle to the FreeType library instance where the face object
 156             is created</p>
 157           </td>
 158         </tr>
 159         <tr valign="top">
 160           <td>
 161             <tt><b>filepathname</b></tt>
 162           </td>
 163           <td>
 164             <p>the font file pathname (standard C string).</p>
 165           </td>
 166         </tr>
 167         <tr valign="top">
 168           <td>
 169             <tt><b>face_index</b></tt>
 170           </td>
 171           <td>
 172             <p>Certain font formats allow several font faces to be embedded
 173             in a single file.</p>
 174
 175             <p>This index tells which face you want to load.  An error will
 176             be returned if its value is too large.</p>
 177
 178             <p>Index 0 always work though.</p>
 179           </td>
 180         </tr>
 181         <tr valign="top">
 182           <td>
 183             <tt><b>face</b></tt>
 184           </td>
 185           <td>
 186             <p>A <em>pointer</em> to the handle that will be set to describe
 187             the new face object.</p>
 188
 189             <p>It is set to NULL in case of error.</p>
 190           </td>
 191         </tr>
 192       </table>
 193
 194       <p>To know how many faces a given font file contains, simply load its
 195       first face (use <tt>face_index</tt>=0), then see the value of
 196       <tt>face->num_faces</tt> which indicates how many faces are embedded
 197       in the font file.</p>
 198
 199       <h4>
 200         b. From memory
 201       </h4>
 202
 203       <p>In the case where you have already loaded the font file in memory,
 204       you can similarly create a new face object for it by calling
 205       <tt>FT_New_Memory_Face</tt> as in</p>
 206
 207       <font color="blue">
 208       <pre>
 209     FT_Library   library;   /* handle to library     */
 210     FT_Face      face;      /* handle to face object */
 211
 212     error = FT_Init_FreeType( &library );
 213     if ( error ) { ... }
 214
 215     error = FT_New_Memory_Face( library,
 216                                 buffer,    /* first byte in memory */
 217                                 size,      /* size in bytes        */
 218                                 0,         /* face_index           */
 219                                 &face );
 220     if ( error ) { ... }</pre>
 221       </font>
 222
 223       <p>As you can see, <tt>FT_New_Memory_Face()</tt> simply takes a
 224       pointer to the font file buffer and its size in bytes instead of a
 225       file pathname.  Other than that, it has exactly the same semantics as
 226       <tt>FT_New_Face()</tt>.</p>
 227
 228       <h4>
 229         c. From other sources (compressed files, network, etc.)
 230       </h4>
 231
 232       <p>There are cases where using a file pathname or preloading the file
 233       in memory is simply not enough.  With FreeType&nbsp;2, it is possible
 234       to provide your own implementation of i/o routines.</p>
 235
 236       <p>This is done through the <tt>FT_Open_Face()</tt> function, which
 237       can be used to open a new font face with a custom input stream, select
 238       a specific driver for opening, or even pass extra parameters to the
 239       font driver when creating the object.  We advise you to refer to the
 240       FreeType&nbsp;2 reference manual in order to learn how to use it.</p>
 241
 242       <p>Note that providing a custom stream might also be used to access a
 243       TrueType font embedded in a Postscript Type&nbsp;42 wrapper.</p>
 244
 245       <hr>
 246
 247     <h3>
 248       4. Accessing face content
 249     </h3>
 250
 251     <p>A <em>face object</em> models all information that globally describes
 252     the face.  Usually, this data can be accessed directly by dereferencing
 253     a handle, like</p>
 254
 255     <table cellpadding=5>
 256       <tr valign="top">
 257         <td>
 258           <tt><b>face->num_glyphs</b></tt>
 259         </td>
 260         <td>
 261           <p>Gives the number of <em>glyphs</em> available in the font face.
 262           A glyph is simply a character image.  It doesn't necessarily
 263           correspond to a <em>character code</em> though.</p>
 264         </td>
 265       </tr>
 266       <tr valign="top">
 267         <td>
 268           <tt><b>face->flags</b></tt>
 269         </td>
 270         <td>
 271           <p>A 32-bit integer containing bit flags used to describe some
 272           face properties.  For example, the flag
 273           <tt>FT_FACE_FLAG_SCALABLE</tt> is used to indicate that the face's
 274           font format is scalable and that glyph images can be rendered for
 275           all character pixel sizes.  For more information on face flags,
 276           please read the <a href="#">FreeType&nbsp;2 API Reference</a>.</p>
 277         </td>
 278       </tr>
 279       <tr valign="top">
 280         <td>
 281           <tt><b>face->units_per_EM</b></tt>
 282         </td>
 283         <td>
 284           <p>This field is only valid for scalable formats (it is set to 0
 285           otherwise).  It indicates the number of font units covered by the
 286           EM.</p>
 287         </td>
 288       </tr>
 289       <tr valign="top">
 290         <td>
 291           <tt><b>face->num_fixed_sizes</b></tt>
 292         </td>
 293         <td>
 294           <p>This field gives the number of embedded bitmap <em>strikes</em>
 295           in the current face.  A <em>strike</em> is simply a series of
 296           glyph images for a given character pixel size.  For example, a
 297           font face could include strikes for pixel sizes 10, 12
 298           and&nbsp;14.  Note that even scalable font formats can have
 299           embedded bitmap strikes!</p>
 300         </td>
 301       </tr>
 302       <tr valign="top">
 303         <td>
 304           <tt><b>face->fixed_sizes</b></tt>
 305         </td>
 306         <td>
 307           <p>this is a pointer to an array of <tt>FT_Bitmap_Size</tt>
 308           elements.  Each <tt>FT_Bitmap_Size</tt> indicates the horizontal
 309           and vertical <em>pixel sizes</em> for each of the strikes that are
 310           present in the face.</p>
 311         </td>
 312       </tr>
 313     </table>
 314
 315     <p>For a complete listing of all face properties and fields, please read
 316     the <a href="#">FreeType&nbsp;2 API Reference</a>.<p>
 317
 318     <hr>
 319
 320     <h3>
 321       5. Setting the current pixel size
 322     </h3>
 323
 324     <p>FreeType 2 uses "<em>size objects</em>" to model all
 325        information related to a given character size for a given face.
 326        For example, a size object will hold the value of certain metrics
 327        like the ascender or  text height, expressed in 1/64th of a pixel,
 328        for a character size of 12 points.</p>
 329
 330     <p>When the <tt>FT_New_Face</tt> function is called (or one of its
 331        cousins), it <b>automatically</b> creates a new size object for
 332        the returned face. This size object is directly accessible as
 333        <b><tt>face->size</tt></b>.</p>
 334
 335     <p><em>NOTA BENE: a single face object can deal with one or more size
 336        objects at a time, however, this is something that few programmers
 337        really need to do. We have thus have decided to simplify the API for
 338        the most common use (i.e. one size per face), while keeping this
 339        feature available through additional fuctions.</em></p>
 340
 341     <p>When a new face object is created, its size object defaults to the
 342        character size of 10&nbsp;pixels (both horizontally and vertically) for
 343        scalable formats.  For fixed-sizes formats, the size is more or less
 344        undefined, which is why you must set it before trying to load a
 345        glyph.</p>
 346
 347     <p>To do that, simply call <tt>FT_Set_Char_Size()</tt>.  Here is an
 348        example where the character size is set to 16pt for a 300x300&nbsp;dpi
 349        device:</p>
 350
 351     <font color="blue">
 352     <pre>
 353     error = FT_Set_Char_Size(
 354               face,    /* handle to face object           */
 355               0,       /* char_width in 1/64th of points  */
 356               16*64,   /* char_height in 1/64th of points */
 357               300,     /* horizontal device resolution    */
 358               300 );   /* vertical device resolution      */</pre>
 359     </font>
 360
 361     <p>You will notice that:</p>
 362
 363     <ul>
 364       <li>
 365         <p>The character width and heights are specified in 1/64th of
 366         points. A point is a <em>physical</em> distance, equaling 1/72th
 367         of an inch, it's not a pixel..<p>
 368       </li>
 369       <li>
 370         <p>The horizontal and vertical device resolutions are expressed in
 371         <em>dots-per-inch</em>, or <em>dpi</em>. You can use 72 or
 372         96&nbsp;dpi for display devices like the screen. The resolution
 373         is used to compute the character pixel size from the character
 374         point size.</p>
 375       </li>
 376       <li>
 377         <p>A value of&nbsp;0 for the character width means "<em>same as
 378         character height</em>", a value of&nbsp;0 for the character height
 379         means "<em>same as character width</em>".  Otherwise, it is possible
 380         to specify different char widths and heights.</p>
 381       </li>
 382       <li>
 383         <p>Using a value of 0 for the horizontal or vertical resolution means
 384         72&nbsp;dpi, which is the default.</p>
 385       </li>
 386       <li>
 387         <p>The first argument is a handle to a face object, not a size
 388            object. That's normal, and must be seen as a convenience.</p>
 389       </li>
 390     </ul>
 391
 392     <p>This function computes the character pixel size that corresponds to
 393     the character width and height and device resolutions.  However, if you
 394     want to specify the pixel sizes yourself, you can simply call
 395     <tt>FT_Set_Pixel_Sizes()</tt>, as in</p>
 396
 397     <font color="blue">
 398     <pre>
 399     error = FT_Set_Pixel_Sizes(
 400               face,   /* handle to face object            */
 401               0,      /* pixel_width                      */
 402               16 );   /* pixel_height                     */</pre>
 403     </font>
 404
 405     <p>This example will set the character pixel sizes to 16x16&nbsp;pixels.
 406     As previously, a value of&nbsp;0 for one of the dimensions means
 407     "<em>same as the other</em>".</p>
 408
 409     <p>Note that both functions return an error code.  Usually, an error
 410     occurs with a fixed-size font format (like FNT or PCF) when trying to
 411     set the pixel size to a value that is not listed in the
 412     <tt><b>face->fixed_sizes</b></tt> array.</p>
 413
 414     <hr>
 415
 416     <h3>
 417       6. Loading a glyph image
 418     </h3>
 419
 420       <h4>
 421         a. Converting a character code into a glyph index
 422       </h4>
 423
 424       <p>Usually, an application wants to load a glyph image based on its
 425       <em>character code</em>, which is a unique value that defines the
 426       character for a given <em>encoding</em>.  For example, the character
 427       code&nbsp;65 represents the `A' in ASCII encoding.</p>
 428
 429       <p>A face object contains one or more tables, called
 430       <em>charmaps</em>, that are used to convert character codes to glyph
 431       indices.  For example, most TrueType fonts contain two charmaps.  One
 432       is used to convert Unicode character codes to glyph indices, the other
 433       is used to convert Apple Roman encoding into glyph indices.  Such
 434       fonts can then be used either on Windows (which uses Unicode) and
 435       Macintosh (which uses Apple Roman, bwerk).  Note also that a given
 436       charmap might not map to all the glyphs present in the font.</p>
 437
 438       <p>By default, when a new face object is created, it lists all the
 439       charmaps contained in the font face and selects the one that supports
 440       Unicode character codes if it finds one.  Otherwise, it tries to find
 441       support for Latin-1, then ASCII.</p>
 442
 443       <p>We will describe later how to look for specific charmaps in a face.
 444       For now, we will assume that the face contains at least a Unicode
 445       charmap that was selected during <tt>FT_New_Face()</tt>.  To convert a
 446       Unicode character code to a font glyph index, we use
 447       <tt>FT_Get_Char_Index()</tt> as in</p>
 448
 449       <font color="blue">
 450       <pre>
 451     glyph_index = FT_Get_Char_Index( face, charcode );</pre>
 452       </font>
 453
 454       <p>This will look the glyph index corresponding to the given
 455       <tt>charcode</tt> in the charmap that is currently selected for the
 456       face.  If charmap is selected, the function simply returns the
 457       charcode.</p>
 458
 459       <p>Note that this is one of the rare FreeType functions that do not
 460       return an error code.  However, when a given character code has no
 461       glyph image in the face, the value&nbsp;0 is returned.  By convention,
 462       it always correspond to a special glyph image called the <b>missing
 463       glyph</b>, which usually is represented as a box or a space.</p>
 464
 465       <h4>
 466         b. Loading a glyph from the face
 467       </h4>
 468
 469       <p>Once you have a glyph index, you can load the corresponding glyph
 470       image.  Note that the glyph image can be in several formats.  For
 471       example, it will be a bitmap for fixed-size formats like FNT, FON, or
 472       PCF.  It will also be a scalable vector outline for formats like
 473       TrueType or Type&nbsp;1.  The glyph image can also be stored in an
 474       alternate way that is not known at the time of writing this
 475       documentation.</p>
 476
 477       <p>The glyph image is always stored in a special object called a
 478       <em>glyph slot</em>.  As its name suggests, a glyph slot is simply a
 479       container that is able to hold one glyph image at a time, be it a
 480       bitmap, an outline, or something else.  Each face object has a single
 481       glyph slot object that can be accessed as
 482       <b><tt>face->glyph</tt></b>.</p>
 483
 484       <p>Loading a glyph image into the slot is performed by calling
 485       <tt>FT_Load_Glyph()</tt> as in</p>
 486
 487       <font color="blue">
 488       <pre>
 489     error = FT_Load_Glyph(
 490               face,          /* handle to face object */
 491               glyph_index,   /* glyph index           */
 492               load_flags );  /* load flags, see below */</pre>
 493       </font>
 494
 495       <p>The <tt>load_flags</tt> value is a set of bit flags used to
 496       indicate some special operations.  The default value
 497       <tt>FT_LOAD_DEFAULT</tt> is&nbsp;0.</p>
 498
 499       <p>This function will try to load the corresponding glyph image
 500          from the face. Basically, this means that:</p>
 501
 502       <ul>
 503         <li>
 504           <p>If a bitmap is found for the corresponding glyph and pixel
 505              size, it will in the slot (embedded bitmaps are always
 506              favored over native image formats, because we assume that
 507              they are higher-quality versions of the same image. This
 508              can be ignored by using the FT_LOAD_NO_BITMAP flag)</p>
 509         </li>
 510
 511         <li>
 512           <p>Otherwise, a native image for the glyph will be loaded.
 513              It will also be scaled to the current pixel size, as
 514              well as hinted for certain formats like TrueType and
 515              Type1.</p>
 516         </li>
 517       </ul>
 518
 519       <p>The field <tt><b>glyph->format</b></tt> describe the format
 520          used to store the glyph image in the slot. If it is not
 521          <tt>ft_glyph_format_bitmap</tt>, one can immediately
 522          convert it to a bitmap through <tt>FT_Render_Glyph</tt>,
 523          as in:</p>
 524
 525       <font color="blue">
 526       <pre>
 527    error = FT_Render_Glyph(
 528                   face->glyph,      /* glyph slot  */
 529                   render_mode );    /* render mode */
 530       </pre>
 531       </font>
 532
 533       <p>The parameter <tt>render_mode</tt> is a set of bit flags used
 534          to specify how to render the glyph image. Set it to 0 to render
 535          a monochrome bitmap, or to <tt>ft_render_mode_antialias</tt> to
 536          generate a high-quality (256 gray levels) anti-aliased bitmap
 537          from the glyph image.</p>
 538
 539       <p>Once you have a bitmap glyph image, you can access it directly
 540          through <tt><b>glyph->bitmap</b></tt> (a simple bitmap descriptor),
 541          and position it through <tt><b>glyph->bitmap_left</b></tt> and
 542          <tt><b>glyph->bitmap_top</b></tt>.</p>
 543
 544       <p>Note that <tt>bitmap_left</tt> is the horizontal distance from the
 545          current pen position to the left-most border of the glyph bitmap,
 546          while <tt>bitmap_top</tt> is the vertical distance from the
 547          pen position (on the baseline) to the top-most border of the
 548          glyph bitmap. <em>It is positive to indicate an upwards
 549          distance</em>.</p>
 550
 551       <p>The next section will detail the content of a glyph slot and
 552          how to access specific glyph information (including metrics).</p>
 553
 554       <h4>
 555         c. Using other charmaps
 556       </h4>
 557
 558       <p>As said before, when a new face object is created, it will look for
 559       a Unicode, Latin-1, or ASCII charmap and select it.  The currently
 560       selected charmap is accessed via <b><tt>face->charmap</tt></b>.  This
 561       field is NULL when no charmap is selected, which typically happens
 562       when you create a new <tt>FT_Face</tt> object from a font file that
 563       doesn't contain an ASCII, Latin-1, or Unicode charmap (rare
 564       stuff).</p>
 565
 566       <p>There are two ways to select a different charmap with FreeType 2.
 567          The easiest is when the encoding you need already has a corresponding
 568          enumeration defined in <tt>&lt;freetype/freetype.h&gt;</tt>, as
 569          <tt>ft_encoding_big5</tt>. In this case, you can simply call
 570          <tt>FT_Select_CharMap</tt> as in:</p>
 571
 572       <font color="blue"><pre>
 573     error = FT_Select_CharMap(
 574                     face,                 /* target face object */
 575                     ft_encoding_big5 );   /* encoding..         */
 576       </pre></font>
 577
 578       <p>Another way is to manually parse the list of charmaps for the
 579          face, this is accessible through the fields
 580          <tt><b>num_charmaps</b></tt> and <tt><b>charmaps</b></tt>
 581          (notice the 's') of the face object. As you could expect,
 582          the first is the number of charmaps in the face, while the
 583          second is <em>a table of pointers to the charmaps</em>
 584          embedded in the face.</p>
 585
 586       <p>Each charmap has a few visible fields used to describe it more
 587          precisely. Mainly, one will look at
 588          <tt><b>charmap->platform_id</b></tt> and
 589          <tt><b>charmap->encoding_id</b></tt> that define a pair of
 590          values that can be used to describe the charmap in a rather
 591          generic way.</p>
 592
 593       <p>Each value pair corresponds to a given encoding. For example,
 594          the pair (3,1) corresponds to Unicode. Their list is
 595          defined in the TrueType specification but you can also use the
 596          file <tt>&lt;freetype/ftnameid.h&gt;</tt> which defines several
 597          helpful constants to deal with them..</p>
 598
 599       <p>To look for a specific encoding, you need to find a corresponding
 600          value pair in the specification, then look for it in the charmaps
 601          list. Don't forget that some encoding correspond to several
 602          values pair (yes it's a real mess, but blame Apple and Microsoft
 603          on such stupidity..). Here's some code to do it:</p>
 604
 605       <font color="blue">
 606       <pre>
 607     FT_CharMap  found = 0;
 608     FT_CharMap  charmap;
 609     int         n;
 610
 611     for ( n = 0; n &lt; face->num_charmaps; n++ )
 612     {
 613       charmap = face->charmaps[n];
 614       if ( charmap->platform_id == my_platform_id &&
 615            charmap->encoding_id == my_encoding_id )
 616       {
 617         found = charmap;
 618         break;
 619       }
 620     }
 621
 622     if ( !found ) { ... }
 623
 624     /* now, select the charmap for the face object */
 625     error = FT_Set_CharMap( face, found );
 626     if ( error ) { ... }</pre>
 627       </font>
 628
 629      <p>Once a charmap has been selected, either through
 630         <tt>FT_Select_CharMap</tt> or <tt>FT_Set_CharMap</tt>,
 631         it is used by all subsequent calls to
 632         <tt>FT_Get_Char_Index()</tt>.</p>
 633
 634
 635       <h4>
 636         d. Glyph Transforms:
 637       </h4>
 638
 639       <p>It is possible to specify an affine transformation to be applied
 640          to glyph images when they're loaded. Of course, this will only
 641          work for scalable (vectorial) font formats.</p>
 642
 643       <p>To do that, simply call <tt>FT_Set_Transform</tt>, as in:</p>
 644
 645      <font color="blue"><pre>
 646    error = FT_Set_Transform(
 647                     face,           /* target face object    */
 648                     &amp;matrix,    /* pointer to 2x2 matrix */
 649                     &amp;delta );   /* pointer to 2d vector  */
 650      </pre></font>
 651
 652       <p>This function will set the current transform for a given face
 653          object. Its second parameter is a pointer to a simple
 654          <tt>FT_Matrix</tt> structure that describes a 2x2 affine matrix.
 655          The third parameter is a pointer to a <tt>FT_Vector</tt> structure
 656          that describe a simple 2d vector.</p>
 657
 658       <p>Note that the matrix pointer can be set to NULL, (in which case
 659          the identity transform will be used). Coefficients of the matrix
 660          are in 16.16 fixed float units.</p>
 661
 662       <p>The vector pointer can also be set to NULL (in which case a delta
 663          of (0,0) will be used). The vector coordinates are expressed in
 664          1/64th of a pixel (also known as 26.6 fixed floats).</p>
 665
 666       <p><em>NOTA BENE: The transform is applied every glyph that is loaded
 667          through <tt>FT_Load_Glyph</tt>. Note that loading a glyph bitmap
 668          with a non-trivial transform will produce an error..</em></p>
 669
 670       <hr>
 671
 672     <h3>
 673       7. Accessing glyph image data
 674     </h3>
 675
 676     <p>Glyph image data is accessible through <tt><b>face->glyph</b></tt>.
 677     See the definition of the <tt>FT_GlyphSlot</tt> type for more details.
 678     As stated previously, each face has a single glyph slot, where
 679     <em>one</em> glyph image <em>at a time</em> can be loaded.  Each time
 680     you call <tt>FT_Load_Glyph()</tt>, you erase the content of the glyph
 681     slot with a new glyph image.</p>
 682
 683     <p>Note however that the glyph slot object itself doesn't change, only
 684     its content, which means that you can perfectly create a "shortcut" to
 685     access it as in</p>
 686
 687     <font color="blue">
 688     <pre>
 689     {
 690       /* shortcut to glyph slot */
 691       FT_GlyphSlot  glyph = face->glyph;
 692
 693       for ( n = 0; n &lt; face->num_glyphs; n++ )
 694       {
 695         ... load glyph n ...
 696         ... access glyph data as glyph->xxxx
 697       }
 698     }</pre>
 699     </font>
 700
 701     <p>The <tt>glyph</tt> variable will be valid until its parent
 702     <tt>face</tt> is destroyed.  Here are a few important fields of the
 703     glyph slot:<p>
 704
 705     <table cellpadding=5>
 706       <tr valign="top">
 707         <td>
 708           <tt><b>glyph->format</b></tt>
 709         </td>
 710         <td>
 711           <p>Indicates the type of the loaded glyph image.  Can be either
 712           <tt>ft_glyph_format_bitmap</tt>, <tt>ft_glyph_format_outline</tt>,
 713           or other values.</p>
 714         </td>
 715       </tr>
 716       <tr valign="top">
 717         <td>
 718           <tt><b>glyph->metrics</b></tt>
 719         </td>
 720         <td>
 721           <p>A simple structure used to hold the glyph image's metrics.
 722           Note that <em>most distances are expressed in 1/64th of
 723           pixels!</em> See the API reference or the user guide for a
 724           description of the <tt>FT_Glyph_Metrics</tt> structure.</p>
 725         </td>
 726       </tr>
 727       <tr valign="top">
 728         <td>
 729           <tt><b>glyph->bitmap</b></tt>
 730         </td>
 731         <td>
 732           <p>If the glyph slot contains a bitmap, a simple
 733           <tt>FT_Bitmap</tt> that describes it.  See the API reference or
 734           user guide for a description of the <tt>FT_Bitmap</tt>
 735           structure.</p>
 736         </td>
 737       </tr>
 738       <tr valign="top">
 739         <td>
 740           <tt><b>glyph->outline</b></tt>
 741         </td>
 742         <td>
 743           <p>When the glyph slot contains a scalable outline, this structure
 744           describes it. See the definition of the <tt>FT_Outline</tt>
 745           structure.</p>
 746         </td>
 747       </tr>
 748     </table>
 749
 750     <h3>
 751       8. Rendering glyph outlines into bitmaps
 752     </h3>
 753
 754     <p>You can easily test the format of the glyph image by inspecting the
 755     <tt>face->glyph->format</tt> variable.  If its value is
 756     <tt>ft_glyph_format_bitmap</tt>, the glyph image that was loaded is a
 757     bitmap that can be directly blit to your own surfaces through your
 758     favorite graphics library (FreeType&nbsp;2 doesn't provide bitmap
 759     blitting routines, as you may imagine&nbsp;:-)</p>
 760
 761     <p>If the format is <tt>ft_glyph_format_outline</tt> or something else,
 762     the library provides a means to convert such glyph images to bitmaps
 763     through what are called <b>rasters</b>.</p>
 764
 765     <p>On the other hand, if the image is a scalable outline or something
 766     else, FreeType provides a function to convert the glyph image into a
 767     pre-existing bitmap that you will handle to it, named
 768     <tt>FT_Get_Glyph_Bitmap</tt>.  Here's a <em>simple</em> example code
 769     that renders an outline into a <b>monochrome</b> bitmap:</p>
 770
 771     <font color="blue">
 772     <pre>
 773     {
 774       FT_GlyphSlot  glyph;
 775
 776       ... load glyph ...
 777
 778       glyph = face-&gt;glyph;   /* shortcut to glyph data */
 779       if ( glyph->format == ft_glyph_format_outline )
 780       {
 781         FT_Bitmap  bit;
 782
 783         /* set-up a bitmap descriptor for our target bitmap */
 784         bit.rows       = bitmap_height;
 785         bit.width      = bitmap_width;
 786         bit.pitch      = bitmap_row_bytes;
 787         /* render into a mono bitmap */
 788         bit.pixel_mode = ft_pixel_mode_mono;
 789         bit.buffer     = bitmap_buffer;
 790
 791         /* render the outline directly into the bitmap */
 792         error = FT_Get_Glyph_Bitmap( face, &bit );
 793         if ( error ) { ... }
 794       }
 795     }</pre>
 796     </font>
 797
 798     <p>You should note that <b><em><tt>FT_Get_Glyph_Bitmap()</tt> doesn't
 799     create the bitmap</em></b>.  It only needs a descriptor, of type
 800     <tt>FT_Bitmap</tt>, and writes directly into it.</p>
 801
 802     <p>Note that the FreeType scan-converter for outlines can also generate
 803     anti-aliased glyph bitmaps with 128 level of grays.  For now, it is
 804     restricted to rendering to 8-bit gray-level bitmaps, though this may
 805     change in the future.  Here is some code to do just that:</p>
 806
 807     <font color="blue">
 808     <pre>
 809     {
 810       FT_GlyphSlot  glyph;
 811
 812       ... load glyph ...
 813
 814       glyph = face->glyph;   /* shortcut to glyph data */
 815       if ( glyph->format == ft_glyph_format_outline )
 816       {
 817         FT_Bitmap  bit;
 818
 819         /* set-up a bitmap descriptor for our target bitmap */
 820         bit.rows       = bitmap_height;
 821         bit.width      = bitmap_width;
 822         bit.pitch      = bitmap_row_bytes;
 823         /* 8-bit gray-level bitmap */
 824         bit.pixel_mode = ft_pixel_mode_gray;
 825         /* MUST be 128 for now     */
 826         bit.grays      = 128;
 827         bit.buffer     = bitmap_buffer;
 828
 829         /* clean the bitmap - IMPORTANT */
 830         memset( bit.buffer, 0, bit.rows*bit.pitch );
 831
 832         /* render the outline directly into the bitmap */
 833         error = FT_Get_Glyph_Bitmap( face, &bit );
 834         if ( error ) { ... }
 835       }
 836     }</pre>
 837     </font>
 838
 839     <p>You will notice that</p>
 840
 841     <ul>
 842       <li>
 843         <p>As previously, <tt>FT_Get_Glyph_Bitmap()</tt> doesn't generate
 844         the bitmap, it simply renders to it.</p>
 845       </li>
 846       <li>
 847         <p>The target bitmap must be cleaned before calling the function.
 848         This is a limitation of our current anti-aliasing algorithm and is
 849         EXTREMELY important.</p>
 850       </li>
 851       <li>
 852         <p>The anti-aliaser uses 128&nbsp;levels of grays exclusively for
 853         now (this will probably change in a near future).  This means that
 854         you <b>must</b> set <tt>bit.grays</tt> to&nbsp;128.  The generated
 855         image uses values from 0 (back color) to 127 (foreground color).</p>
 856       </li>
 857       <li>
 858         <p>It is <b>not</b> possible to render directly an anti-aliased
 859         outline into a pre-existing gray-level bitmap, or even any
 860         colored-format one (like RGB16 or paletted 8-bits).  We will not
 861         discuss this issue in great details here, but the reason is that we
 862         do not want to deal with graphics composition (or alpha-blending)
 863         within FreeType.<p/>
 864       </li>
 865     </ul>
 866 </td></tr>
 867 </table>
 868 </center>
 869
 870 </body>
 871 </html>