
                                 Glyph Hell

   An introduction to glyphs, as used and defined in the FreeType engine:

                         version 1.0 (html version)

                          David Turner - 14 Jan 98

  ------------------------------------------------------------------------

Introduction:

This article discusses in great detail the definition of glyph metrics, per
se the TrueType specification, and the way they are managed and used by the
FreeType engine. This information is crucial when it comes to rendering text
strings, either in a conventional (i.e. roman) layout, or with vertical or
right-to-left ones. Some aspects like glyph rotation and transformation are
explained too.

Comments and corrections are highly welcomed, and can be sent to the
FreeType developers list.

  ------------------------------------------------------------------------

I. An overview of font files

In TrueType, a single font file is used to contain information related to
classification, modeling and rendering of text using a given typeface. This
data is located in various independent "tables", which can be sorted in four
simple classes, as described below:

   * Face Data:

     We call face data, the amount of information related to a given
     typeface, independently of any particular scaling, transformation
     and/or glyph index. This usually means some typeface-global metrics and
     attributes, like family and styles, PANOSE number, typographic
     ascenders and descenders, as well as some very TT-specific items like
     the font 'programs' found in the fpgm and prep tables, the gasp table,
     character mappings, etc.

     In FreeType, a face object is used to model a font file's face data.

   * Instance Data:

     We call instance a given pointsize/transformation, at a given device
     resolution (e.g. 8pt at 96x96 dpi, or 12pt at 300x600 dpi, etc). Some
     tables found in the font files are used to produce instance-specific
     data, like the cvt table, or the prep program. Though they're often
     part of the face data, their processing results in information called
     instance data.

     In FreeType, it is modeled through an instance object, which is always
     created from an existing face object.

   * Glyph Data:

     We call glyph data the piece of information related to specific glyphs.
     This includes the following things that are described in more details
     in the next sections:

        o the glyph's vectorial representation, also called its outline.

        o various metrics, like the glyph's bounding box, its bearings and
          advance values.

        o TrueType specifies a specific instruction bytecode, used to
          associate each glyph with a small program, called the glyph code.
          Its purpose is to grid-fit the outline to any target instance, in
          order to produce excellent output at "small" pixel sizes.

     The FreeType engine doesn't map each glyph to a single structure, as
     this would waste memory for no good reason. Rather, a glyph object is a
     container, created from any active face, which can be used to load
     and/or process any font glyph at any instance (or even no instance at
     all). Of course, the glyph properties (outline, metrics, bitmaps, etc.)
     can be extracted independently from an object once it has been loaded
     or processed.

   * Text and Layout Data:

     Finally, there is a last class of data that doesn't really fit in all
     others, and that can be called text data. It comprises information
     related to the grouping of glyphs together to form text. Simple
     examples are the kerning table, which controls the spacing between
     adjacent glyphs, as well as some of the extensions introduced in
     OpenType and GX like glyph substitution (ligatures), baseline
     management, justification, etc.

     This article focuses on the basic TrueType tables, and hence, will only
     talk about kerning, as FreeType doesn't support OpenType nor GX (yet).

  ------------------------------------------------------------------------

II. Glyph Outlines:

TrueType is a scalable font format: it is thus possible to render glyphs at
any scale, and under any affine transform, from a single source
representation. However, simply scaling vectorial shapes exhibits at small
sizes (where "small" refers here to anything smaller than at least 150
pixels) a collection of un-harmonious artifacts, like widths and/or heights
degradations.

Because of this, the format also provides a complete programming language
used to design small programs associated to each glyph. Their role is to
align the point positions on the pixel grid after the scaling. This
operation is hence called "grid-fitting", or even "hinting".

  1. Vectorial representation

     The source format of outlines is a collection of closed paths called
     "contours". Each contour delimits an outer or inner region of the
     glyph, and can be made of either line segments and/or second-order
     beziers (also called "conic beziers" or "quadratics").

     It is described internally as a series of successive points, with each
     point having an associated flag indicating whether it is "on" or "off"
     the curve. These rules are applied to decompose the contour:

        o two successive "on" points indicate a line segment joining them.

        o one "off" point amidst two "on" points indicates a conic bezier,
          the "off" point being the control point, and the "on" ones the
          start and end points.

        o finally, two successive "off" points forces the rasterizer to
          create (only during bitmap rendering) a virtual "on" point amidst
          them, at their exact middle. This greatly facilitates the
          definition of successive Bezier arcs.

                                       *            # on
                                                    * off
                                    __---__
       #-__                      _--       -_
           --__                _-            -
               --__           #               \
                   --__                        #
                       -#
                                Two "on" points
        Two "on" points       and one "off" point
                                 between them

                     *
       #            __      Two "on" points with two "off"
        \          -  -     points between them. The point
         \        /    \    marked '0' is the middle of the
          -      0      \   "off" points, and is a 'virtual'
           -_  _-       #   "on" point where the curve passes.
             --             It does not appear in the point
                            list.
             *

     Each glyph's original outline points are located on a grid of
     indivisible units. The points are stored in the font file as
     16-bit integer grid coordinates, with the grid origin's being at (0,0);
     they thus range from -16384 to 16383.

     In creating the glyph outlines, a type designer uses an imaginary
     square called the "EM square". Typically, the EM square encloses the
     capital "M" and most other letters of a typical roman alphabet. The
     square's size, i.e., the number of grid units on its sides, is very
     important for two reasons:

        o it is the reference used to scale the outlines to a given
          instance. For example, a size of 12pt at 300x300dpi corresponds to
          12*300/72 = 50 pixels. This is the size the EM square would appear
          on the output device if it was rendered directly. In other words,
          scaling from grid units to pixels uses the formula:

                      pixel_size = point_size * resolution / 72

              pixel_coordinate = grid_coordinate * pixel_size / EM_size

        o the greater the EM size is, the larger resolution the designer can
          use when digitizing outlines. For example, in the extreme example
          of an EM size of 4 units, there are only 25 point positions
          available within the EM square which is clearly not enough.
          Typical TrueType fonts use an EM size of 2048 units (note: with
          Type 1 PostScript fonts, the EM size is fixed to 1000 grid units.
          However, point coordinates can be expressed in floating values).

     Note that glyphs can freely extend beyond the EM square if the font
     designer wants this. The EM is used as a convenience, and is a valuable
     convenience from traditional typography.

          grid units are very often called "font units" or "EM units".

     IMPORTANT NOTE:

     Under FreeType, scaled pixel positions are all expressed in the 26.6
     fixed float format (made of a 26-bit integer mantissa, and a 6-bit
     fractional part). In other words, all coordinates are multiplied by 64.
     The grid lines along the integer pixel positions, are multiples of 64,
     like (0,0), (64,0), (0,64), (128,128), etc., while the pixel centers
     lie at middle coordinates (32 modulo 64) like (32,32), (96,32), etc.

  2. Hinting and Bitmap rendering

     As said before, simply scaling outlines to a specific instance always
     creates undesirable artifacts, like stems of different widths or
     heights in letters like "E" or "H". Proper glyph rendering needs that
     the scaled points are aligned along the pixel grid (hence the name
     "grid-fitting"), and that important widths and heights are respected
     throughout the whole font (for example, it is very often desirable that
     the "I" and the "T" have their central vertical line of the same pixel
     width).

     Type 1 PostScript font files include with each glyph a small series of
     distances called "hints", which are later used by the type manager to
     try grid-fitting the outlines as cleverly as possible. In one hand, it
     has the consequence that upgrading your font engine can enhance the
     visual aspects of all fonts of your system; on the other hand, the
     quality of even the best version of Adobe's Type Manager isn't always
     very pleasing at small sizes (notwithstanding font smoothing).

     TrueType takes a radically different approach: each glyph has an
     associated "program", designed in a specific geometrical language,
     which is used to align explicitly each outline point to the pixel grid,
     preserving important distances and metrics. A stack-based low-level
     bytecode is used to store it in the font file, and is interpreted later
     when rendering the scaled glyphs.

     This means that even very complex glyphs can be rendered perfectly at
     very small sizes, as long as the corresponding glyph code is designed
     correctly. Moreover, a glyph can lose some of its details, like serifs,
     at small sizes to become more readable, because the bytecode provides
     interesting features.

     However, this also have the sad implication that an ill-designed glyph
     code will always render junk, whatever the font engine's version, and
     that it's very difficult to produce quality glyph code. There are about
     200 TrueType opcodes, and no known "high-level language" for it. Most
     type artists aren't programmers at all and the only tools able to
     produce quality code from vectorial representation have been
     distributed to only a few font foundries, while tools available to the
     public, e.g. Fontographer, are usually expensive though generating
     average to mediocre glyph code.

     All this explains why an enormous number of broken or ugly "free" fonts
     have appeared on the TrueType scene, and that this format is now
     mistakenly thought as "crap" by many people. Funnily, these are often
     the same who stare at the "beauty" of the classic "Times New Roman" and
     "Arial/Helvetica" at 8 points.

     Once a glyph's code has been executed, the scan-line converter converts
     the fitted outline into a bitmap (or a pixmap with font-smoothing).

  ------------------------------------------------------------------------

III. Glyph metrics

  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, called the "pen
     position", is used to locate glyphs.

     Each layout uses a different convention for glyph placement:

        o 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.

                                        [Image]

          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:

                                       [Image]

  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:

        o 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.

        o the descent:

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

        o 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 means 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, simpler metrics are:

        o 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 also 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.

        o 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

        o 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 the
     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 is in most cases 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)

                                     [Image]

                                     [Image]

     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 implies several things:

        o 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.

        o 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, it 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.

        o 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, containing 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 section demonstrates how to use the concepts previously defined to
render text, whatever the layout you use.

  1.
  2. 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 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 arrays you pass
          to it. See the API reference for a complete description of bitmaps
          and pixmaps).

            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 item 2 until string completion. That's it!

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

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

        o For right-to-left text (like Arabic):

          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.

        o for vertical text (like Chinese or Japanese):

          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;

  4. 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 1:
               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 2:
               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:

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

       2. Store the bitmap with the following values:

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

          When you cache is set up, 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;
            }

  5. 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 that 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 (e.g. bubble-jet
     vs. laser printers) may encounter trouble:

     As the differences in advances accumulate on one line, they can sum to
     the width of one or more glyphs in extreme cases, 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 use and apply 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

       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.

  6. 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 formats. 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:

       #define ROUND(x)  ((x+32) & -64)

       pen_x += metrics.advance + ROUND( scaled_kerning );

  7. Rotated and stretched/slanted text:

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

        o The engine doesn't apply specific transformations 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
          transformations that please you (a number of APIs are there to
          help you to do it easily).

        o 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:

       /* set the flags */
       TT_Set_Instance_Transforms( instance,
                                   rotated,
                                   stretched );

       /* load a given glyph */
       TT_Get_Glyph_Outline( instance,
                             glyph,
                             index,
                             TTLOAD_DEFAULT );

       /* access its outline */
       TT_Get_Glyph_Outline( instance, &outline );

       /* in order to transform it */
       TT_Transform_Outline( outline, &matrix );
       /* and/or */
       TT_Translate_Outline( outline,
                             x_offset, y_offset );

       /* to render it */
       TT_Get_Outline_Bitmap( outline, &bitmap );

     Here is an example, assuming that the following variables

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

     define a transformation that can be correctly applied to a glyph
     outline which have been previously placed relative to the imaginary
     point position (0,0) with bearings preserved. Rendering text can now be
     done as follows:

       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 needed, 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 transformation 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.
     -----------------------------------------------------------------------

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

     The FreeType engine's scan-line converter (the component also called
     the "rasterizer") is able to convert a vectorial glyph outline into
     either a normal bitmap, or an 8-bit pixmap (a.k.a. "colored bitmaps" on
     some systems). This last feature is called "gray-level 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 as large 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-level 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 renders glyphs in the arrays you pass to 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.

     -----------------------------------------------------------------------
     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 interests you, the freetype mailing list may
     host some helpful enthusiasts ready to answer your questions. Who knows
     :-)

  9. Other interesting text processes:

        o 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 "f" followed by "i" by
          the single glyph "fi" 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.

        o Justification:

To be continued...
