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