1. Baseline, Pens and Layouts :

   The baseline is an imaginary line that is used to "guide" glyphs when rendering text. It can be horizontal (e.g. roman, cyrillic,arabic, etc..) or vertical (e.g. chinese, japanese, korean, etc..). Moreover, to render text, a virtual point, located on the baseline, and called the "pen position" is used to locate glyphs.

   Each layout uses a different convention for glyph placement :

   • with horizontal layout, glyphs simply "rest" on the baseline. Text is rendered by incrementing the pen position, either to the right or to the left.

     

     the distance between two successive pen positions is glyph-specific and is called the "advance width". Note that its value is _always_ positive, even for right-to-left oriented alphabets, like arabic. This introduces some differences in the way text is rendered.

     ---

     IMPORTANT NOTE :

     the pen position is always placed on the baseline in TrueType, unlike the convention used by some graphics systems, like Windows, to always put the pen above the line, at the ascender's position.

     ---

     with a vertical layout, glyphs are centered around the baseline :

     
2. Typographic metrics and bounding boxes :

   A various number of face metrics are defined for all glyphs in a given font. Three of them have a rather curious status in the TrueType specification; they only apply to horizontal layouts :

   • the ascent : this is the distance from the baseline to the highest/upper grid coordinate used to place an outline point. It is a positive value, due to the grid's orientation with the Y axis upwards.

   • the descent : the distance from the baseline and the lowest grid coordinate used to place an outline point. This is a negative value, due to the grid's orientation.

   • the linegap : the distance that must be placed between two lines of text. The baseline-to-baseline distance should be computed as : "ascent - descent + linegap" if you use the typographic values.

   The problem with these metrics is that they appear three times in a single font file, each version having a slightly different meaning :

   1. the font's horizontal header provides the ascent, descent and linegap fields, which are used to express the designer's intents, rather than the real values that may be computed from all glyphs in the outline. These are used by the Macintosh font engine to perform font mapping (i.e. font substitution).

   2. the OS/2 table provides the usWinAscent and usWinDescent fields. These values are computed for glyphs of the Windows ANSI charset only, which mean that they're wrong for any other glyph. Note that usWinDescent is always positive (i.e. looks like "-descent" )

   3. the OS/2 table provides the typoAscender, typoDescender and typoLinegap values, which hopefully concern the whole font file. These are the correct system-independent values !

   All metrics are expressed in font units. If you want to use any of the two first versions of these metrics, the TrueType specification contains some considerations and computing tips that might help you.

   Other, more simple, metrics are :

   • the glyph's bounding box, also called "bbox" : this is an imaginary box that encloses any glyph as tightly as possible. It is represented by four fields, namely xMin, yMin, xMax and yMax, that can be computed for any outline. Their values can be in font units (if measured in the original outline) or in 26.6 pixel units (when measured on scaled outlines).

     Note that if it wasn't for grid-fitting, you wouldn't need to know a box's complete values, but only its dimensions to know how big is a glyph outline/bitmap. However, correct rendering of hinted glyphs needs the preservation of important grid alignment on each glyph translation/placement on the baseline. which is why FreeType returns always the complete glyph outline.

     Note that the font's header contains a global font bbox in font units which should enclose all glyphs in a font. This can be used to pre-compute the maximum dimensions of any glyph at a given instance.

   • the internal leading : this concept comes directly from the world of traditional typography. It represents the amount of space within the "leading" which is reserved for glyph features that lay outside of the EM square (like accentuation). It usually can be computed as :
     internal leading = ascent - descent - EM_size

   • the external leading : this is another name for the line gap

3. Bearings and Advances :

   Each glyph has also distances called bearings and advances. Their definition is constant, but their values depend on the layout, as a same glyph can be used to render text either horizontally or vertically :

   1. the left side bearing : a.k.a "bearingX"

      this is the horizontal distance from the current pen position to the glyph's left bbox edge. It is positive for horizontal layouts, and most generally negative for vertical one.

   2. the top side bearing : a.k.a. "bearingY"

      this is the vertical distance from the baseline to the top of the glyph's bbox. It is usually positive for horizontal layouts, and negative for vertical ones

   3. the advance width : a.k.a "advanceX"

      is the horizontal distance the pen position must be incremented (for left-to-right writing) or decremented (for right-to-left writing) by after each glyph is rendered when processing text. It is always positive for horizontal layouts, and null for vertical ones.

   4. the advance height : a.k.a "advanceY"

      is the vertical distance the pen position must be decremented by after each glyph is rendered. It is always null for horizontal layouts, and positive for vertical layouts.

   5. the glyph width :

      this is simply the glyph's horizontal extent. More simply it is (bbox.xMax-bbox.xMin) for unscaled font coordinates. For scaled glyphs, its computation requests specific care, described in the grid-fitting chapter below.

   6. the glyph height :

      this is simply the glyph's vertical extent. More simply, it is (bbox.yMax-bbox.yMin) for unscaled font coordinates. For scaled glyphs, its computation requests specific care, described in the grid-fitting chapter below.

   7. the right side bearing :

      is only used for horizontal layouts, to describe the distance from the bbox's right edge to the advance width. It's most usually a non-negative number. The FreeType doesn't provide this metric directly, as it isn't really part of the TrueType specification. It can be computed simply as :

      advance_width - left_side_bearing - (xMax-xMin)

   

   

   Finally, if you're used to Windows and OS/2 "ABC widths", the following relations apply :

           A = left side bearing
           B = width
           C = right side bearing
   
           A+B+C = advance width
   

4. The effects of Grid-fitting :

   All these metrics are stored in font units in the font file. They must be scaled and grid-fitted properly to be used at a specific instance. This means several things :

   • first, a glyph program not only aligns the outline along the grid pixel, it also processes the left side bearing and the advance width. other grid-fitted metrics are usually available in optional TrueType tables, if you need them.

   • a glyph program may decide to extend or stretch any of these two metrics if it feels a need for it. This means that you cannot assume that the fitted metrics are simply equal to the scaled one plus or minus a liberal distance < 1 pixel (i.e. under 64 fractional pixel units). For example, its is often necessary to stretch the letter "m" horizontally at small pixel sizes to make all feet visible, while the same glyph can be perfectly "square" at larger sizes.

   • querying the fitted metrics of all glyphs at a given instance is very slow, as it needs to load and process each glyph independently. For this reasons, some optional TrueType tables are defined in the specification, to contain pre-computed metrics for specific instances (the most commonly used, like 8, 9, 10, 11, 12 and 14 points at 96 dpi, for example..). These tables aren't always present in a TrueType font.

     If you don't need the exact fitted value, it's much faster to query the metrics in font units, then scale them to the instance's dimensions.

   ---

   IMPORTANT NOTE :
   Another very important consequence of grid-fitting is the fact that moving a fitted outline by a non-integer pixel distance will simply ruin the hinter's work, as alignments won't be preserved. The translated glyph will then look "ugly" when converted to a bitmap !!

   In other words, each time you want to translate a fitted glyph outline, you must take care of only using integer pixel distances (the x and y offsets must be multiples of 64, which equals to 1.0 in the 26.6 fixed float format). If you don't care about grid-fitting (typically when rendering rotated text), you can use any offset you want and use sub-pixel glyph placement.

   ---

IV. Text processing

This sections demonstrates how to use the concepts previously defined to render text, whatever the layout you use.

1. Writing simple text strings :

   We'll start by generating a simple string with a roman alphabet. The layout is thus horizontal, left to right.

   For now, we'll assume to all glyphs are rendered in a single target bitmap. The case of generating individual glyph bitmaps, then placing them on demand on a device is presented in a later chapter of this section (see below).

   Rendering the string needs to place each glyph on the baseline; this process looks like :

   1. place the pen to the cursor position. The pen is always located on the baseline. These coordinates must be grid-fitted (i.e. multiples of 64) !

          pen_x = cursor_x;    
          pen_y = cursor_y;
      

   2. load the glyph outline and its metrics. Using the flag TTLOAD_DEFAULT will scale and hint the glyph :

          TT_Load_Glyph( instance, 
                         glyph, 
                         glyph_index,
                         TTLOAD_DEFAULT );
      
          TT_Get_Glyph_Metrics( glyph, &metrics );
          TT_Get_Glyph_Outline( glyph, &outline );
      

   3. The loader always places the glyph outline relative to the imaginary pen position (0,0). You thus simply need to translate the outline by the vector :

          ( pen_x, pen_y )
      

      to place it on its correct position, you can use the call

          TT_Translate_Outline( outline, pen_x, pen_y );
      

   4. render the outline in the target bitmap, the glyph will be surimposed on it with a binary "or" (FreeType never creates glyph bitmaps by itself, it simply renders glyphs in the ones you pass to it. See the API reference for a complete description of maps).

                    TT_Get_Outline_Bitmap( outline, &target_bitmap );
      

      ---

      IMPORTANT NOTE :
      If you don't want to access the outline in your code, you can also use the API TT_Get_Glyph_Bitmap which works the same as the previous lines :

                 
          TT_Get_Glyph_Outline( glyph, &outline );
          TT_Translate_Outline( outline, x_offset, y_offset
          TT_Get_Outline_Bitmap( outline, &target_bitmap );
          TT_Translate_Outline( outline, -x_offset, -y_offset );
      

      being equivalent to :

                 
          TT_Get_Glyph_Bitmap( glyph, 
                               x_offset, 
                               y_offset, 
                               &target_bitmap );
      
      

   5. now advance the pen to its next position, the advance is always grid-fitted when the glyph was hinted :

                    pen_x += metrics.advance;
      

      the advance being grid-fitted, the pen position remains aligned on the grid..

   6. start over on b. until string completion.. That's it !

2. Writing right-to-left and vertical text :

   Generating strings for different layouts is very similar. Here are the most important differences :

   • For right-to-left text : like arabic script :

     the main difference here is that, as the advance width and left side bearings are oriented against the flow of text, the pen position must be decremented by the advance width, before placing and rendering the glyph. Other than that, the rest is strictly similar.

   • for vertical text : for most Chinese-Japanse-Korean (CJK) fonts

     in this case, the baseline is vertical, which means that the pen position must be shifted in the vertical direction. You need the vertical glyph metrics to do that.

     ---

     There is no way to do that now with FreeType. However, it will be probably implemented with the help of an additional glyph property. For example, calling a function like :

         TT_Set_Glyph_Layout( glyph, TT_LAYOUT_VERTICAL );
     

     will force the function TT_Get_Glyph_Metrics to place the vertical glyph metrics in the "bearingX", "bearingY" and "advance" metrics fields, instead of the default horizontal ones. Another function will be probably provided to return all glyph metrics at once (horizontal and vertical)..

     ---

     Once you get these, the rest of the process is very similar. The glyph outline is placed relative to an imaginary origin of (0,0), and you should translate it to the pen position before rendering it.

     The big difference is that you must decrement pen_y, rather than increment pen_x (this is for the TrueType convention of Y oriented upwards!).

         pen_y -= metrics.advance;
     

3. Generating individual glyph bitmaps and using them to render text :

   Loading each glyph when rendering text is slow, and it's much more efficient to render each one in a standalone bitmap to place it in a cache. Text can then be rendered fast by applying simple blit operations on the target device.

   To be able to render text correctly with the bitmaps, you must record and associate with them its fitted bearings and advances. Hence the following process :

   1. Generate the bitmaps :

      - load the glyph and get its metrics

          TT_Load_Glyph( instance, 
                         glyph, 
                         glyph_index,
                         TTLOAD_DEFAULT );
      
          TT_Get_Glyph_Metrics( glyph, &metrics );
      

      the bbox is always fitted when calling TT_Get_Glyph_Metrics on a hinted glyph. You can then easily compute the glyph's dimension in pixels as :

          width  = (bbox.xMax - bbox.xMin)/64;
          height = (bbox.yMax - bbox.yMin)/64;
      

      (note : the fitted boudning box always contains all the dropouts that may be produced by the scan-line converter. These width and height are thus valid for all kinds of glyphs).

      NOTE :
      If you want to compute the dimensions of a rotated outline's bitmap, compute its bounding box with TT_Get_Outline_BBox(), then grid-fit the bbox manually:

          #define  FLOOR(x)    ((x) & -64)
          #define  CEILING(x)  (((x)+63) & -64)
      
          xMin = FLOOR(xMin);
          yMin = FLOOR(yMin);
          yMin = CEILING(xMax);
          yMax = CEILING(yMax);
      

      then compute width and height as above..

      - create a bitmap of the given dimension, e.g. :

          bitmap.width  = width;
          bitmap.cols   = (width+7) & -8;
          bitmap.rows   = height;
          bitmap.flow   = TT_Flow_Up;
          bitmap.size   = bitmap.cols * bitmap.rows;
          bitmap.buffer = malloc( bitmap.size );
      

      - render the glyph into the bitmap.

      Don't forget to shift it by ( -xMin, -yMin ) to fit it in the bitmap :

          TT_Get_Glyph_Bitmap( glyph,        // Note that the
                               &bitmap,      // offsets must
                               -bbox.xMin,   // be grid-fitted
                               -bbox.yMin ); // to preserve
                                             // hinting !!
      

   2. Store the bitmap with the following values :

          bearingX/64 = the left side bearing in pixels
          advance/64  = the advance width/height in pixels
      

      When you cache is setup, you can them render text using a scheme similar to the ones describe in 1. and 2., with the exception that now, pen positions and metrics are expressed in pixel values.. Et Voila ! :

          pen_x = cursor_x; 
          pen_y = cursor_y;
      
          while (glyph_to_render)
          {
            access_cache( glyph_index, metrics, bitmap );
      
            blit bitmap to position
      
                 ( pen_x + bearingX, 
                   pen_y (+ bearingY depending on orientation ) );
      
            pen_x += advance;
          }
      

4. Device-independent text rendering :

   The previous rendering processes all aligned glyphs on the baseline according to metrics fitted for the display's distance. In some cases, the display isn't the final output, and placing the glyphs in a device-independent way is more important than anything.

   A typical case is a word processor, which displays text as it should appear on paper when printed. As you've probably noticed, the glyphs aren't always spaced uniformly on the screen as you type them, sometimes the space between an "m" and a "t" is too small, some other it is too large, etc..

   These differences are simply due to the fact that the word processor aligns glyphs in an device-independent way, using original metrics in font units to do it, then scale them as it can to display text on screen, usually at a very smaller resolution than your printer's one.

   Device-independence is a crucial part of document portability, and it is very saddening to see that most professional word processors don't do it correctly. For example, MS Word uses the fitted metrics of the printer's resolution, rather than the originals in font units.

   This is great to get sure than your text prints very well on your printer, but it also implies that someone printing the exact same document on a device with different output resolutions (i.e. bubble-jet vs. laser printers) may encounter trouble :

   As the differences in advances accumulate on one line, they can easily sum to the width of one or more glyphs, which is enough to "overflow" the automatic justification. This may add additional lines of printed text, or even remove some. Moreover, supplemental lines can produce unexpected page breaks and "blank" pages. This can be extremely painful when working with large documents, as this "feature" may require you to redesign completely your formatting to re-print it.

   In conclusion, if you want portable document rendering, never hesitate to compute in device-independent terms !! For example, a simple way to produce text would be :

   1. get a scale to convert from your device-independent units to 26.6 pixels

   2. get another scale to convert from original font units to device-independent units

   3. perform pen placement and advances in device-independent units, with the lim

   4. to render each glyph, compute the pen's rounded position, as well as the rounded glyph left side bearing, both expressed in 26.6 pixels (don't use the fitted metrics). You will then be able to place the glyph and/or blit its bitmap.

5. Kerning glyphs :

   An interesting effect that most people appreciate is "kerning". It consists in modifying the spacing between two successive glyphs according to their outlines. For example, a "T" and a "y" can be easily moved closer, as the top of the "y" fits nicely under the "T"'s upper right bar.

   To perform kerning, the TrueType specification provides a specific table (its tag being "kern"), with several storage format. This section doesn't explain how to access this information; however, you can have a look at the standard extension called "ttkern.h" which comes with FreeType.

   the "kerning distance" between two glyphs is a value expressed in font units which indicate whether their outline can be moved together or apart when one follows the other. The distance isn't reflexive, which means that the kerning for the glyph pair ("T","y") isn't the same as the one for ("y","T").

   the value is positive when the glyphs must be moved apart, and negative when they must be moved closer. You can implement kerning simply by adding its scaled and rounded value to the advance width when moving the pen position. For example :

          with
            #define ROUND(x)  ((x+32) & -64)
   
            pen_x += metrics.advance + ROUND( scaled_kerning );
   

   
   
6. Rotated and Stretched/Slanted text :

   In order to produce rotated glyphs with FreeType, one must understand a few things :

   • The engine doesn't apply specific transforms to the glyphs it loads and processes (other than the simpler resolution-base scaling and grid-fitting). If you want to rotate glyphs, you will have to load their outline, then apply the geometric transforms that please you (a number of APIs are there to help you do it easily)

   • Even if the glyph loader hints "straight" glyphs, it is possible to inform the font and glyph programs that you're going to later transform the resultant outlines. Two flags can be passed to the bytecode interpreter :
     • the "rotated" flag indicates that you're going to rotate the glyphs, in a non-trivial direction (i.e. on neither of the two coordinate axis). You're advised not to set it when writing 90 degrees-rotated text, for example.

     • the "stretched" flag indicates that you're going to apply a transform that will distort distances. While rotations and symmetries keep distances constants, slanting and stretching do modify them.

   These flags can be interpreted by the glyph code to toggle certain processings, which vary from one font to the other. However, most of the TrueType fonts that were tested with FreeType, if not all of them, simply change the dropout-mode when any of these flags is set, and/or disable hinting when rotation is detected. We advise you to never set these flags, even when rotating text. For what it's worth, hinted rotated text is no uglier than un-hinted one.

   You can use the function TT_Set_Instance_Transform_Flags to set them. Then, rendering can be done with the following calls :

       TT_Set_Instance_Transforms( instance, rotated, stretched );
       // set the flags
   
       TT_Get_Glyph_Outline( instance, glyph, index, TTLOAD_DEFAULT );
       // load a given glyph
   
       TT_Get_Glyph_Outline( instance, &outline );
       // access its outline
   
       TT_Transform_Outline( outline, &matrix ); and/or
       TT_Translate_Outline( outline, x_offset, y_offset );
       // in order to transform it
   
       TT_Get_Outline_Bitmap( outline, &bitmap );
       // to render it.
   

   Here is an example, assuming that the following variables :

       TT_Matrix  matrix;        // 2x2 matrix
       TT_Pos     x_off, y_off;  // corrective offsets
   

   define a transform that can correctly be applied to a glyph outline which have been previously placed relative the imaginary point position (0,0) with bearings preserved, rendering text can be done as follow :
   1. initialize the pen position, when rotating, it is extremely well advised to use sub-pixel placement as you don't care about hinting.

          pen_x = cursor_x;
          pen_y = cursor_y;
      

   2. transform the glyph as need, then translate it to the current pen position :

          TT_Transform_Outline( outline, &matrix );
          TT_Translate_Outline( outline, 
                                pen_x + x_off, 
                                pen_y + y_off );
      

      (note that the transform's offsets have been included in the translation)

   3. render the bitmap, as it has now been placed correctly

   4. to change the pen position, transform the vector (0,advance) with your matrix, and add it :

                    vec_x = metrics.advance;
                    vec_y = 0;
                    TT_Transform_Vector( &vec_x, &vec_y, &matrix );
                    pen_x += vec_x;
                    pen_y += vec_y;
      

   5. start over at 2. until completion

   ---

   IMPORTANT NOTE :
   Do not grid-fit the pen position before rendering your glyph when rendering rotated text. If you do, your transformed baseline won't be preserved on each glyph, and the text will look like it's "hopping" randomly. This is particularly visible at small sizes.

   sub-pixel precision placement is _very_ important for clean rotated text.

   ---

7. Font-smoothing, a.k.a. gray-levels rendering

   The FreeType engine's scan-line converter (the component also called the "raster" ) is able to convert a vectorial glyph outline into either a normal bitmap, or an 8-bit pixmap (a.k.a. called "colored bitmaps" on some systems). This last feature is called "gray-levels rendering" or "font-smoothing", because it uses a user-supplied palette to produce anti-aliased versions of the glyphs.

   Its principle is to render a bitmap which is twice larger than the target pixmap, then simply filter it using a 2x2 sommation.

   ---

   NOTE :
   FreeType's scan-line converter doesn't use or need an intermediate double bitmap. Rather, filtering is performed in a single pass, during the sweep (see the file raster.txt for more information about it).

   ---

   You'll notice that, as with Win95, FreeType's raster only grays those parts of the glyph which need it, i.e. diagonals and curves, while keeping horizontal and vertical stems straight "black". This improves greatly the legibility of text, while avoiding the "blurry" look anti-aliased fonts typically have with Adobe's Type Manager or Acrobat.

   There are thus five available gray-levels, ranging from 0 to 4, where level 0 and level 4 are the background and foreground colors, respectively, and where levels 1, 2, 3 are intermediate. For example, to render black text on a white background, one can use a palette like :

   palette[0] = white ( background )
   palette[1] = light gray
   palette[2] = medium gray
   palette[3] = dark gray
   palette[4] = black ( foreground )
   

   To set the engine's gray-levels palette, simply use the API TT_Set_Raster_Palette after initialization. It expects an array of 5 chars, which will be used to render the pixmaps.

   Note that the raster doesn't create bitmaps or pixmaps. Rather, it simply render glyphs in the ones you pass it. The generated glyph bitmaps are simply "or"-ed to the target (with 0 being the background as a convention); in the case of pixmaps, pixels are simply written to the buffer, in spans of four aligned bytes. Then :

   ---

   NOTE :
   The raster isn't able to superpose "transparent" glyphs on the target pixmap. This means that you should always call the APIs TT_Get_Glyph_Pixmap and TT_Get_Outline_Pixmap with an empty map, and perform the superposition yourself.

   This can be more or less tricky, depending on the palette you're using and your target graphics resolution. One of the components found in the test directory, called "display.c" has large comments on the way it implements it for the test programs. You're encouraged to read the test programs sources to understand how one can take advantage of font smoothing

   Pixmap surimposition is too system-specific a feature to be part of the FreeType engine. Moreover, not everybody needs it !

   ---

   Finally, the question of sur-imposing anti-aliased colored text on any texture being even more tricky, it is left as an exercise to the reader.. ;-) If this topic really interest you, the freetype mailing list may host some helpful enthusiasts ready to answer your questions.. who knows :-)

8. Other interesting text processes :
   • Glyph substitution :

     Substitution is used to replace one glyph by another when some specific condition is met in the text string. Its most common examples are ligatures ( like replacing the "o" followed by "e" by the single glyph ofr "oe" when available in the font ), as well as positional selection as performed in the arabic script (for those not aware of this, each letter of the arabic alphabet can be written differently according to its position on words : starting, ending, intermediate or isolated).

     The base TrueType format doesn't define any table for glyph substitution. However, both GX and OpenType provide (incompatible) extensions to perform it. Of course, it isn't supported by the engine, but an extension could be easily written to access the required tables.

   • Justification :

     ---

     ---