freetype1/docs/glyphs.htm

   1 <html>
   2 <head>
   3 <title>An introduction to glyphs</title>
   4
   5 <META name="description"
   6   content="Glyphs in the FreeType engine">
   7 <META name="keywords"
   8   content="FreeType TrueType library engine glyphs baseline bearing
   9            bounding box">
  10 </head>
  11
  12 <body text="#000000"
  13       bgcolor="#FFFFFF"
  14       link="#0000EF"
  15       vlink="#51188E"
  16       alink="#FF0000">
  17
  18
  19 <font size=1>http://www.freetype.org</font><p>
  20
  21 <center>
  22   <font size="+2">Glyph Hell<p>
  23
  24   <font size="+1">An introduction to glyphs, as used and defined in
  25   the FreeType engine<p>
  26 </center>
  27
  28 <hr><p>
  29
  30 <font size="+2">Introduction<p>
  31
  32 <font size="+0">This article discusses in great detail the definition
  33 of glyph metrics, per se the TrueType specification, and the way they
  34 are managed and used by the FreeType engine.  This information is
  35 crucial when it comes to rendering text strings, either in a
  36 conventional (i.e. Roman) layout, or with vertical or right-to-left
  37 ones.  Some aspects like glyph rotation and transformation are
  38 explained too.<p>
  39
  40 Comments and corrections are highly welcome, and can be sent to the
  41 <a href="mailto:devel@freetype.org">FreeType developers list</a>.<p>
  42
  43 <hr><p>
  44
  45
  46 <font size="+2">I. An overview of font files<p>
  47
  48 <font size="+0">In TrueType, a single font file is used to contain
  49 information related to classification, modeling and rendering of text
  50 using a given typeface.  This data is located in various independent
  51 `tables', which can be sorted in four simple classes, as described
  52 below:<p>
  53
  54 <ul>
  55
  56   <b><font size="+1"><li>Face Data</font></b><p>
  57
  58     We call <i>face data</i> the amount of information related to a
  59     given typeface, independently of any particular scaling,
  60     transformation, and/or glyph index.  This usually means some
  61     typeface-global metrics and attributes, like family and styles,
  62     PANOSE number, typographic ascenders and descenders, as well as
  63     some very TrueType specific items like the font `programs' found
  64     in the <i>fpgm</i> and <i>prep</i> tables, the <i>gasp</i> table,
  65     character mappings, etc.<p>
  66
  67     In FreeType, a <i>face object</i> is used to model a font file's
  68     face data.<p>
  69
  70   <b><font size="+1"><li>Instance Data</font></b><p>
  71
  72     We call <i>instance</i> a given pointsize/transformation, at a
  73     given device resolution (e.g.&nbsp;8pt at 96x96dpi, or 12pt at
  74     300x600dpi, etc).  Some tables found in the font files are used to
  75     produce instance-specific data, like the <i>cvt</i> table, or the
  76     <i>prep</i> program.  Though they are often part of the face data,
  77     their processing results in information called <i>instance
  78     data</i>.<p>
  79
  80     In FreeType, it is modeled through an <i>instance object</i>,
  81     which is always created from an existing face object.<p>
  82
  83   <b><font size="+1"><li>Glyph Data</font></b><p>
  84
  85     We call <i>glyph data</i> the piece of information related to
  86     specific glyphs.  This includes the following things that are
  87     described in more details in the next sections:<p>
  88
  89     <ul>
  90
  91       <li>The glyph's vectorial representation, also called its
  92         <i>outline</i>.<p>
  93
  94       <li>Various metrics, like the glyph's <i>bounding box</i>, its
  95         <i>bearings</i> and <i>advance</i> values.<p>
  96
  97       <li>TrueType specifies a specific instruction <i>bytecode</i>,
  98         used to associate each glyph with a small <i>program</i>,
  99         called the <i>glyph code</i>.  Its purpose is to grid-fit the
 100         outline to any target instance, in order to produce excellent
 101         output at small pixel sizes.
 102
 103     </ul><p>
 104
 105     The FreeType engine doesn't map each glyph to a single structure,
 106     as this would waste memory for no good reason.  Rather, a <i>glyph
 107     object</i> is a <i>container</i>, created from any active face,
 108     which can be used to load and/or process any font glyph at any
 109     instance (or even no instance at all).  Of course, the glyph
 110     properties (outline, metrics, bitmaps, etc.) can be extracted
 111     independently from an object once it has been loaded or
 112     processed.<p>
 113
 114   <b><font size="+1"><li>Text and Layout Data</font></b><p>
 115
 116     Finally, there is a last class of data that doesn't really fit in
 117     all others, and that can be called <i>text</i> data.  It comprises
 118     information related to the grouping of glyphs together to form
 119     text.  Simple examples are the <i>kerning</i> table, which
 120     controls the spacing between adjacent glyphs, as well as some of
 121     the extensions introduced in <i>TrueType Open</i>,
 122     <i>OpenType</i>, and <i>TrueType GX</i> like glyph substitution
 123     (ligatures, vertical representations), baseline management,
 124     justification, etc.<p>
 125
 126     This article focuses on the basic TrueType tables, and hence, will
 127     only talk about kerning, as FreeType doesn't support OpenType nor
 128     GX (yet).  [Support for TrueType Open is already partially
 129     available.]
 130
 131 </ul><p>
 132
 133 <hr><p>
 134
 135
 136 <font size="+2">II. Glyph Outlines<p>
 137
 138 <font size="+0">TrueType is a scalable font format; it is thus
 139 possible to render glyphs at any scale, and under any affine
 140 transform, from a single source representation.  However, simply
 141 scaling vectorial shapes exhibits at small sizes (where `small' refers
 142 here to anything smaller than at least 150&nbsp;pixels) a collection
 143 of un-harmonious artifacts, like widths and/or heights
 144 degradations.<p>
 145
 146 Because of this, the format also provides a complete programming
 147 language used to design small programs associated to each glyph.  Its
 148 role is to align the point positions on the pixel grid after the
 149 scaling.  This operation is hence called <i>grid-fitting</i>, or even
 150 <i>hinting</i>.<p>
 151
 152 <ol>
 153
 154   <font size="+1"><li>Vectorial representation</font><p>
 155
 156     The source format of outlines is a collection of closed paths
 157     called <i>contours</i>.  Each contour delimits an outer or inner
 158     region of the glyph, and can be made of either line segments
 159     and/or second-order beziers (also called <i>conic beziers</i> or
 160     <i>quadratics</i>).<p>
 161
 162     It is described internally as a series of successive points, with
 163     each point having an associated flag indicating whether it is `on'
 164     or `off' the curve.  These rules are applied to decompose the
 165     contour:<p>
 166
 167     <ul>
 168
 169       <li>Two successive `on' points indicate a line segment joining
 170         them.<p>
 171
 172       <li>One `off' point amidst two `on' points indicates a conic
 173         bezier, the `off' point being the control point, and the `on'
 174         ones the start and end points.<p>
 175
 176       <li>Finally, two successive `off' points forces the rasterizer
 177         to create (only during bitmap rendering) a virtual `on' point
 178         amidst them, at their exact middle.  This greatly facilitates
 179         the definition of successive Bezier arcs.
 180
 181     </ul><p>
 182
 183 <pre>
 184                                   *              # on
 185                                                  * off
 186                                __---__
 187   #-__                      _--       -_
 188       --__                _-            -
 189           --__           #               \
 190               --__                        #
 191                   -#
 192                            Two `on' points
 193    Two `on' points       and one `off' point
 194                             between them
 195
 196
 197
 198                 *
 199   #            __      Two `on' points with two `off'
 200    \          -  -     points between them.  The point
 201     \        /    \    marked `0' is the middle of the
 202      -      0      \   `off' points, and is a `virtual
 203       -_  _-       #   on' point where the curve passes.
 204         --             It does not appear in the point
 205                        list.
 206         *
 207 </pre>
 208
 209     <img src="image/emsquare.gif" align="right" width=333 height=274>
 210
 211     Each glyph's original outline points are located on a grid of
 212     indivisible units.  The points are stored in the font file as
 213     16-bit integer grid coordinates, with the grid origin's being at
 214     (0,0); they thus range from -16384 to&nbsp;16383.<p>
 215
 216     In creating the glyph outlines, a type designer uses an imaginary
 217     square called the <i>EM square</i>.  Typically, the EM square
 218     encloses the capital letter `M' and most other letters of a
 219     typical roman alphabet.  The square's size, i.e., the number of
 220     grid units on its sides, is very important for two reasons:<p>
 221
 222     <ul>
 223
 224       <li>It is the reference used to scale the outlines to a given
 225         instance.  For example, a size of 12pt at 300x300dpi
 226         corresponds to 12*300/72&nbsp;= 50&nbsp;pixels.  This is the
 227         size the EM square would appear on the output device if it was
 228         rendered directly.  In other words, scaling from grid units to
 229         pixels uses the formula<p>
 230
 231         <center>
 232           pixel_size&nbsp;= point_size&nbsp;*
 233                             resolution&nbsp;/&nbsp;72
 234         </center><p>
 235
 236         <center>
 237           pixel_coordinate&nbsp;= grid_coordinate&nbsp;*
 238                                   pixel_size&nbsp;/&nbsp;EM_size
 239         </center><p>
 240
 241       <li>The greater the EM size is, the larger resolution the
 242         designer can use when digitizing outlines.  For example, in
 243         the extreme example of an EM size of 4&nbsp;units, there are
 244         only 25&nbsp;point positions available within the EM square
 245         which is clearly not enough.  Typical TrueType fonts use an EM
 246         size of 2048&nbsp;units (note: with Type&nbsp;1 PostScript
 247         fonts, the EM size is fixed to 1000&nbsp;grid units.  However,
 248         point coordinates can be expressed in floating values).
 249
 250     </ul><p>
 251
 252     Note that glyphs can freely extend beyond the EM square if the
 253     font designer wants this.  The EM is used as a convenience, and is
 254     a valuable convenience from traditional typography.<p>
 255
 256     <center>
 257       <font size="+1">
 258       Grid units are very often called <i>font units</i> or <i>EM
 259       units</i>.
 260       </font>
 261     </center><p>
 262
 263     <hr>
 264     <i>IMPORTANT NOTE:</i><p>
 265
 266     Under FreeType, scaled pixel positions are all expressed in the
 267     26.6 fixed float format (made of a 26-bit integer mantissa, and a
 268     6-bit fractional part).  In other words, all coordinates are
 269     multiplied by&nbsp;64.  The grid lines along the integer pixel
 270     positions, are multiples of&nbsp;64, like (0,0), (64,0), (0,64),
 271     (128,128), etc., while the pixel centers lie at middle coordinates
 272     (32&nbsp;modulo&nbsp;64) like (32,32), (96,32), etc.
 273     <hr><p>
 274
 275   <font size="+1"><li>Hinting and Bitmap rendering</font><p>
 276
 277     As said before, simply scaling outlines to a specific instance
 278     always creates undesirable artifacts, like stems of different
 279     widths or heights in letters like `E' or `H'.  Proper glyph
 280     rendering needs that the scaled points are aligned along the pixel
 281     grid (hence the name <i>grid-fitting</i>), and that important
 282     widths and heights are respected throughout the whole font (for
 283     example, it is very often desirable that the letters `I' and `T'
 284     have their central vertical line of the same pixel width).<p>
 285
 286     Type&nbsp;1 PostScript font files include with each glyph a small
 287     series of distances called <i>hints</i>, which are later used by
 288     the type manager to try grid-fitting the outlines as cleverly as
 289     possible.  On one hand, it has the consequence that upgrading your
 290     font engine can enhance the visual aspects of all fonts of your
 291     system; on the other hand, the quality of even the best version of
 292     Adobe's Type Manager isn't always very pleasing at small sizes
 293     (notwithstanding font smoothing).<p>
 294
 295     TrueType takes a radically different approach: Each glyph has an
 296     associated `program', designed in a specific geometrical language,
 297     which is used to align explicitly each outline point to the pixel
 298     grid, preserving important distances and metrics.  A stack-based
 299     low-level bytecode is used to store it in the font file, and is
 300     interpreted later when rendering the scaled glyphs.<p>
 301
 302     This means that even very complex glyphs can be rendered perfectly
 303     at very small sizes, as long as the corresponding glyph code is
 304     designed correctly.  Moreover, a glyph can loose some of its
 305     details, like serifs, at small sizes to become more readable,
 306     because the bytecode provides interesting features.<p>
 307
 308     However, this also have the sad implication that an ill-designed
 309     glyph code will always render junk, whatever the font engine's
 310     version, and that it's very difficult to produce quality glyph
 311     code.  There are about 200&nbsp;TrueType opcodes, and no known
 312     `high-level language' for it.  Most type artists aren't
 313     programmers at all and the only tools able to produce quality code
 314     from vectorial representation have been distributed to only a few
 315     font foundries, while tools available to the public, e.g.
 316     Fontographer, are usually expensive though generating average to
 317     mediocre glyph code.<p>
 318
 319     All this explains why an enormous number of broken or ugly `free'
 320     fonts have appeared on the TrueType scene, and that this format is
 321     now mistakenly thought as `crap' by many people.  Funnily, these
 322     are often the same who stare at the `beauty' of the classic `Times
 323     New Roman' and `Arial/Helvetica' at 8&nbsp;points.<p>
 324
 325     Once a glyph's code has been executed, the scan-line converter
 326     converts the fitted outline into a bitmap (or a pixmap with
 327     font-smoothing).
 328
 329 </ol><p>
 330
 331
 332 <hr><p>
 333
 334 <font size="+2">III. Glyph metrics</font><p>
 335
 336 <ol>
 337
 338   <font size="+1"><li>Baseline, Pens and Layouts</font><p>
 339
 340     The baseline is an imaginary line that is used to `guide' glyphs
 341     when rendering text.  It can be horizontal (e.g. Roman, Cyrillic,
 342     Arabic, etc.) or vertical (e.g. Chinese, Japanese, etc).
 343     Moreover, to render text, a virtual point, located on the
 344     baseline, called the <i>pen position</i>, is used to locate
 345     glyphs.<p>
 346
 347     Each layout uses a different convention for glyph placement:<p>
 348
 349     <ul>
 350
 351       <li>With horizontal layout, glyphs simply `rest' on the
 352         baseline.  Text is rendered by incrementing the pen position,
 353         either to the right or to the left.<p>
 354
 355         <center>
 356           <img src="image/baseline.gif" width=458 height=179><p>
 357         </center>
 358
 359         The distance between two successive pen positions is
 360         glyph-specific and is called the <i>advance width</i>.  Note
 361         that its value is <b>always</b> positive, even for
 362         right-to-left oriented alphabets, like Arabic.  This
 363         introduces some differences in the way text is rendered.<p>
 364
 365         <hr>
 366         <i>IMPORTANT NOTE:</i><p>
 367
 368         The pen position is always placed on the baseline in
 369         TrueType, unlike the convention used by some graphics
 370         systems, like Windows, to always put the pen above the line,
 371         at the ascender's position.
 372         <hr><p>
 373
 374       <li>With vertical layout, glyphs are centered around the
 375         baseline:<p>
 376
 377         <center>
 378           <img src="image/baselin2.gif" width=162 height=275>
 379         </center>
 380
 381     </ul><p>
 382
 383     <font size="+1"><li>Typographic metrics and bounding
 384       boxes</font><p>
 385
 386       A various number of face metrics are defined for all glyphs in
 387       a given font.  Three of them have a rather curious status in
 388       the TrueType specification; they only apply to horizontal
 389       layouts:<p>
 390
 391       <ul>
 392
 393         <li>The <i>ascent</i><p>
 394
 395           This is the distance from the baseline to the highest/upper
 396           grid coordinate used to place an outline point.  It is a
 397           positive value, due to the grid's orientation with the
 398           y&nbsp;axis upwards.<p>
 399
 400         <li>The <i>descent</i><p>
 401
 402           The distance from the baseline to the lowest grid coordinate
 403           used to place an outline point.  This is a negative value,
 404           due to the grid's orientation.<p>
 405
 406         <li>The <i>linegap</i><p>
 407
 408           The distance that must be placed between two lines of text.
 409           The baseline-to-baseline distance should be computed as<p>
 410
 411           <center>
 412             ascent&nbsp;- descent&nbsp;+ linegap
 413           </center><p>
 414
 415           if you use the typographic values.
 416
 417       </ul><p>
 418
 419       The problem with these metrics is that they appear three times
 420       in a single font file, each version having a slightly different
 421       meaning:<p>
 422
 423       <ol>
 424
 425         <li>The font's horizontal header provides the ascent, descent
 426           and linegap fields, which are used to express the designer's
 427           intents, rather than the real values that may be computed
 428           from all glyphs in the outline.  These are used by the
 429           Macintosh font engine to perform font mapping (i.e. font
 430           substitution).<p>
 431
 432         <li>The OS/2 table provides the <i>usWinAscent</i> and
 433           <i>usWinDescent</i> fields.  These values are computed for
 434           glyphs of the Windows ANSI charset only, which means that
 435           they are wrong for any other glyph.  Note that
 436           <i>usWinDescent</i> is always positive (i.e. looks like
 437           `-descent').<p>
 438
 439         <li>The OS/2 table provides the <i>typoAscender</i>,
 440           <i>typoDescender</i> and <i>typoLinegap</i> values, which
 441           hopefully concern the whole font file.  These are the
 442           correct system-independent values!
 443
 444       </ol><p>
 445
 446       All metrics are expressed in font units.  If you want to use any
 447       of the two first versions of these metrics, the TrueType
 448       specification contains some considerations and computing tips
 449       that might help you.<p>
 450
 451       Other, simpler metrics are:<p>
 452
 453       <ul>
 454
 455         <li>The glyph's bounding box, also called <i>bbox</i><p>
 456
 457           This is an imaginary box that encloses any glyph (usually as
 458           tightly as possible).  It is represented by four fields,
 459           namely <i>xMin</i>, <i>yMin</i>, <i>xMax</i>, and
 460           <i>yMax</i>, that can be computed for any outline.  In
 461           FreeType, their values can be in font units (if measured in
 462           the original outline) or in 26.6&nbsp;pixel units (if
 463           measured on scaled outlines).<p>
 464
 465           Note that if it wasn't for grid-fitting, you wouldn't need
 466           to know a box's complete values, but only its dimensions to
 467           know how big is a glyph outline/bitmapa.  However, correct
 468           rendering of hinted glyphs needs the preservation of
 469           important grid alignment on each glyph translation/placement
 470           on the baseline, which is why FreeType always returns the
 471           complete glyph outline.<p>
 472
 473           Note also that the font's header contains a global font
 474           bounding box in font units which should enclose all glyphs
 475           in a font.  This can be used to pre-compute the maximum
 476           dimensions of any glyph at a given instance.<p>
 477
 478         <li>The <i>internal leading</i><p>
 479
 480           This concept comes directly from the world of traditional
 481           typography.  It represents the amount of space within the
 482           `leading' which is reserved for glyph features that lay
 483           outside of the EM square (like accentuation).  It usually
 484           can be computed as<p>
 485
 486           <center>
 487             internal_leading&nbsp;= ascent&nbsp;- descent&nbsp;-
 488                                     EM_size
 489           </center><p>
 490
 491         <li>The <i>external leading</i><p>
 492
 493           This is another name for the linegap.
 494
 495       </ul><p>
 496
 497     <font size="+1"><li><i>Bearings</i> and <i>Advances</i></font><p>
 498
 499       Each glyph has also distances called <i>bearings</i> and
 500       <i>advances</i>.  Their definition is constant, but their values
 501       depend on the layout, as the same glyph can be used to render
 502       text either horizontally or vertically.<p>
 503
 504       <ol>
 505         <li>The <i>left side bearing</i>: a.k.a. <i>bearingX</i><p>
 506
 507           This is the horizontal distance from the current pen
 508           position to the glyph's left bounding box edge.  It is
 509           positive for horizontal layouts, and most generally negative
 510           for vertical one.<p>
 511
 512         <li>The <i>top side bearing</i>: a.k.a. <i>bearingY</i><p>
 513
 514           This is the vertical distance from the baseline to the top
 515           of the glyph's bounding box.  It is usually positive for
 516           horizontal layouts, and negative for vertical ones<p>
 517
 518         <li>The <i>advance width</i>: a.k.a. <i>advanceX</i><p>
 519
 520           This is the horizontal distance the pen position must be
 521           incremented (for left-to-right writing) or decremented (for
 522           right-to-left writing) by after each glyph is rendered when
 523           processing text.  It is always positive for horizontal
 524           layouts, and null for vertical ones.<p>
 525
 526         <li>The <i>advance height</i>: a.k.a. <i>advanceY</i><p>
 527
 528           This is the vertical distance the pen position must be
 529           decremented by after each glyph is rendered.  It is always
 530           null for horizontal layouts, and positive for vertical
 531           layouts.<p>
 532
 533         <li>The <i>glyph width</i><p>
 534
 535           The glyph's horizontal extent.  More simply, it is
 536           (bbox.xMax&nbsp;- bbox.xMin) for unscaled font coordinates.
 537           For scaled glyphs, its computation requests specific care,
 538           described in the grid-fitting chapter below.<p>
 539
 540         <li>The <i>glyph height</i><p>
 541
 542           The glyph's vertical extent.  More simply, it is
 543           (bbox.yMax&nbsp;- bbox.yMin) for unscaled font coordinates.
 544           For scaled glyphs, its computation requests specific care,
 545           described in the grid-fitting chapter below.<p>
 546
 547         <li>The <i>right side bearing</i><p>
 548
 549           Only used for horizontal layouts to describe the distance
 550           from the bbox's right edge to the advance width.  It is in
 551           most cases a non-negative number.  The FreeType library
 552           doesn't provide this metric directly, as it isn't really
 553           part of the TrueType specification.  It can be computed
 554           simply as<p>
 555
 556           <center>
 557             advance_width&nbsp;- left_side_bearing&nbsp;- (xMax-xMin)
 558           </center>
 559
 560       </ol><p>
 561
 562       <center>
 563         <img src="image/metrics.gif" width=388 height=253><p>
 564
 565         <img src="image/metrics2.gif" width=294 height=278>
 566       </center><p>
 567
 568       Finally, if you use `ABC widths' under Windows and OS/2, the
 569       following relations apply:
 570
 571 <pre>
 572   A = left side bearing
 573   B = width
 574   C = right side bearing
 575
 576   A+B+C = advance width
 577 </pre>
 578
 579     <font size="+1"><li>The effects of grid-fitting</font><p>
 580
 581       All these metrics are stored in font units in the font file.
 582       They must be scaled and grid-fitted properly to be used at a
 583       specific instance.  This implies several things:<p>
 584
 585       <ul>
 586
 587         <li>First, a glyph program not only aligns the outline along
 588           the grid pixel, it also processes the left side bearing and
 589           the advance width.  Other grid-fitted metrics are usually
 590           available in optional TrueType tables if you need them.<p>
 591
 592         <li>A glyph program may decide to extend or stretch any of
 593           these two metrics if it has a need for it.  This means that
 594           you cannot assume that the fitted metrics are simply equal
 595           to the scaled one plus or minus a liberal distance
 596           <&nbsp;1&nbsp;pixel (i.e., less than 64&nbsp;fractional
 597           pixel units).  For example, it is often necessary to stretch
 598           the letter `m' horizontally at small pixel sizes to make all
 599           vertical stems visible, while the same glyph can be
 600           perfectly `square' at larger sizes.<p>
 601
 602         <li>Querying the fitted metrics of all glyphs at a given
 603           instance is very slow, as it needs to load and process each
 604           glyph independently.  For this reason, some optional
 605           TrueType tables are defined in the specification, containing
 606           pre-computed metrics for specific instances (the most
 607           commonly used, like 8, 9, 10, 11, 12, and 14&nbsp;points at
 608           96dpi, for example).  These tables aren't always present in
 609           a TrueType font.<p>
 610
 611           If you don't need the exact fitted value, it's much faster
 612           to query the metrics in font units, then scale them to the
 613           instance's dimensions.
 614
 615       </ul><p>
 616
 617       <hr>
 618       <i>IMPORTANT NOTE:</i><p>
 619
 620       Another very important consequence of grid-fitting is the fact
 621       that moving a fitted outline by a non-integer pixel distance
 622       will simply ruin the hinter's work, as alignments won't be
 623       preserved.  The translated glyph will then look `ugly' when
 624       converted to a bitmap!<p>
 625
 626       In other words, each time you want to translate a fitted glyph
 627       outline, you must take care of only using integer pixel
 628       distances (the x and y&nbsp;offsets must be multiples
 629       of&nbsp;64, which equals to&nbsp;1.0 in the 26.6 fixed float
 630       format).
 631
 632       If you don't care about grid-fitting (typically when rendering
 633       rotated text), you can use any offset you want and use sub-pixel
 634       glyph placement.
 635       <hr><p>
 636
 637   </ol>
 638
 639 <hr><p>
 640
 641
 642 <font size="+2">IV. Text processing</font><p>
 643
 644 This section demonstrates how to use the concepts previously defined
 645 to render text, whatever the layout you use.<p>
 646
 647 <ol>
 648
 649   <font size="+1"><li>Writing simple text strings</font><p>
 650
 651     We will start by generating a simple string with a Roman alphabet.
 652     The layout is thus horizontal, left to right.<p>
 653
 654     For now, we will assume all glyphs are rendered in a single target
 655     bitmap.  The case of generating individual glyph bitmaps, then
 656     placing them on demand on a device is presented in a later chapter
 657     of this section.<p>
 658
 659     Rendering the string needs to place each glyph on the baseline;
 660     this process looks like the following:<p>
 661
 662     <ol>
 663
 664       <li>Place the pen to the cursor position.  The pen is always
 665         located on the baseline.  Its coordinates must be grid-fitted
 666         (i.e. multiples of&nbsp;64)!<p>
 667
 668 <pre>
 669   pen_x = cursor_x;
 670   pen_y = cursor_y;
 671 </pre>
 672
 673       <li>Load the glyph outline and its metrics.  Using the flag
 674         TTLOAD_DEFAULT will scale and hint the glyph:
 675
 676 <pre>
 677   TT_Load_Glyph( instance,
 678                  glyph,
 679                  glyph_index,
 680                  TTLOAD_DEFAULT );
 681
 682   TT_Get_Glyph_Metrics( glyph, &metrics );
 683   TT_Get_Glyph_Outline( glyph, &outline );
 684 </pre>
 685
 686       <li>The loader always places the glyph outline relative to the
 687         imaginary pen position (0,0).  You thus simply need to
 688         translate the outline by the vector:
 689
 690 <pre>
 691   ( pen_x, pen_y )
 692 </pre>
 693
 694         To place it on its correct position, you can use the call
 695
 696 <pre>
 697   TT_Translate_Outline( outline, pen_x, pen_y );
 698 </pre>
 699
 700       <li>Render the outline in the target bitmap, the glyph will be
 701         surimposed on it with a binary `or' operation (FreeType never
 702         creates glyph bitmaps by itself, it simply renders glyphs in
 703         the arrays you pass to it.  See the API reference for a
 704         complete description of bitmaps and pixmaps).
 705
 706 <pre>
 707   TT_Get_Outline_Bitmap( outline, &target_bitmap );
 708 </pre>
 709
 710         <hr>
 711         <i>IMPORTANT NOTE:</i><p>
 712
 713         If you don't want to access the outline in your code, you can
 714         also use the API function TT_Get_Glyph_Bitmap() which does the
 715         same as the previous lines:
 716
 717 <pre>
 718   TT_Get_Glyph_Outline( glyph, &outline );
 719   TT_Translate_Outline( outline, x_offset, y_offset );
 720   TT_Get_Outline_Bitmap( outline, &target_bitmap );
 721   TT_Translate_Outline( outline, -x_offset, -y_offset );
 722 </pre>
 723
 724         is equivalent to:
 725
 726 <pre>
 727   TT_Get_Glyph_Bitmap( glyph,
 728                        x_offset,
 729                        y_offset,
 730                        &target_bitmap );
 731 </pre>
 732         <hr><p>
 733
 734       <li>Now advance the pen to its next position.  The advance is
 735         always grid-fitted when the glyph was hinted:<p>
 736
 737 <pre>
 738   pen_x += metrics.advance;
 739 </pre>
 740
 741         The advance being grid-fitted, the pen position remains
 742         aligned on the grid.<p>
 743
 744       <li>Start over on item&nbsp;2 until string completion.  That's
 745         it!
 746
 747     </ol><p>
 748
 749   <font size="+1"><li>Writing right-to-left and vertical text</font><p>
 750
 751     Generating strings for different layouts is very similar.  Here
 752     are the most important differences.<p>
 753
 754     <ul>
 755
 756       <li>For right-to-left text (like Arabic)<p>
 757
 758         The main difference here is that, as the advance width and
 759         left side bearings are oriented against the flow of text, the
 760         pen position must be <i>decremented</i> by the advance width,
 761         <i>before</i> placing and rendering the glyph.  Other than
 762         that, the rest is strictly similar.<p>
 763
 764       <li>For vertical text (like Chinese or Japanese)<p>
 765
 766         In this case, the baseline is vertical, which means that the
 767         pen position must be shifted in the vertical direction.  You
 768         need the vertical glyph metrics to do that (using the
 769         TT_Get_Big_Glyph_Metrics() function).<p>
 770
 771         Once you get these, the rest of the process is very similar.
 772         The glyph outline is placed relative to an imaginary origin of
 773         (0,0), and you should translate it to the pen position before
 774         rendering it.<p>
 775
 776         The big difference is that you must decrement pen_y, rather
 777         than increment pen_x (this is for the TrueType convention of y
 778         oriented upwards).
 779
 780 <pre>
 781   pen_y -= metrics.advance;
 782 </pre>
 783
 784     </ul><p>
 785
 786   <font size="+1"><li>Generating individual glyph bitmaps and using
 787     them to render text</font><p>
 788
 789     Loading each glyph when rendering text is slow, and it's much
 790     more efficient to render each one in a standalone bitmap to place
 791     it in a cache.  Text can then be rendered fast by applying simple
 792     blit operations on the target device.<p>
 793
 794     To be able to render text correctly with the bitmaps, you must
 795     record and associate with them its fitted bearings and advances.
 796     Hence the following process:<p>
 797
 798     <ol>
 799
 800       <li>Generate the bitmaps.<p>
 801
 802         <ul>
 803
 804           <li>Load the glyph and get its metrics.
 805
 806 <pre>
 807   TT_Load_Glyph( instance,
 808                  glyph,
 809                  glyph_index,
 810                  TTLOAD_DEFAULT );
 811
 812   TT_Get_Glyph_Metrics( glyph, &metrics );
 813 </pre>
 814
 815             The bbox is always fitted when calling
 816             TT_Get_Glyph_Metrics() on a hinted glyph.  You can then
 817             easily compute the glyph's dimension in pixels as:
 818
 819 <pre>
 820   width  = (bbox.xMax - bbox.xMin) / 64;
 821   height = (bbox.yMax - bbox.yMin) / 64;
 822 </pre>
 823
 824             NOTE 1:<br>
 825             The fitted bounding box always contains all the dropouts
 826             that may be produced by the scan-line converter.  This
 827             width and height are thus valid for all kinds of
 828             glyphs).<p>
 829
 830             NOTE 2:<br>
 831             If you want to compute the dimensions of a rotated
 832             outline's bitmap, compute its bounding box with
 833             TT_Get_Outline_BBox(), then grid-fit the bbox manually:
 834
 835 <pre>
 836   #define  FLOOR(x)    ((x) & -64)
 837   #define  CEILING(x)  (((x)+63) & -64)
 838
 839   xMin = FLOOR(xMin);
 840   yMin = FLOOR(yMin);
 841   yMin = CEILING(xMax);
 842   yMax = CEILING(yMax);
 843 </pre>
 844
 845             then compute width and height as above.<p>
 846
 847           <li>Create a bitmap of the given dimension, e.g.:
 848
 849 <pre>
 850   bitmap.width  = width;
 851   bitmap.cols   = (width+7) & -8;
 852   bitmap.rows   = height;
 853   bitmap.flow   = TT_Flow_Up;
 854   bitmap.size   = bitmap.cols * bitmap.rows;
 855   bitmap.buffer = malloc( bitmap.size );
 856 </pre>
 857
 858           <li>Render the glyph into the bitmap.<p>
 859
 860             Don't forget to shift it by (-xMin, -yMin) to fit it in
 861             the bitmap:
 862
 863 <pre>
 864   /* Note that the offsets must be grid-fitted to */
 865   /* preserve hinting!                            */
 866   TT_Get_Glyph_Bitmap( glyph,
 867                        &bitmap,
 868                        -bbox.xMin,
 869                        -bbox.yMin );
 870 </pre>
 871
 872         </ul>
 873
 874       <li>Store the bitmap with the following values:
 875
 876 <pre>
 877   bearingX / 64 = left side bearing in pixels
 878   advance / 64  = advance width/height in pixels
 879 </pre>
 880
 881         When your cache is set up, you can then render text using a
 882         scheme similar to the ones describe in&nbsp;1. and&nbsp;2.,
 883         with the exception that now pen positions and metrics are
 884         expressed in pixel values.  We are done!
 885
 886 <pre>
 887   pen_x = cursor_x;
 888   pen_y = cursor_y;
 889
 890   while ( glyph_to_render )
 891   {
 892     access_cache( glyph_index, metrics, bitmap );
 893
 894     blit_bitmap_to_position
 895      ( pen_x + bearingX,
 896        pen_y (+ bearingY depending on orientation ) );
 897
 898     pen_x += advance;
 899   }
 900 </pre>
 901
 902     </ol>
 903
 904   <font size="+1"><li>Device-independent text rendering</font><p>
 905
 906     The previously described rendering processes all align glyphs on
 907     the baseline according to metrics fitted for the display's
 908     distance.  In some cases, the display isn't the final output, and
 909     placing the glyphs in a device-independent way is more important
 910     than anything.<p>
 911
 912     A typical case is a word processor which displays text as it
 913     should appear on paper when printed.  As you've probably noticed,
 914     the glyphs aren't always spaced uniformly on the screen as you
 915     type them, sometimes the space between an `m' and a `t' is too
 916     small, some other it is too large, etc.<p>
 917
 918     These differences are simply due to the fact that the word
 919     processor aligns glyphs in an device-independent way, using
 920     original metrics in font units to do it, then scale them as it
 921     can to display text on screen, usually at a very smaller
 922     resolution than your printer's one.<p>
 923
 924     Device-independence is a crucial part of document portability,
 925     and it is very saddening to see that most professional word
 926     processors don't do it correctly.  For example, MS&nbsp;Word uses
 927     the fitted metrics of the printer's resolution, rather than the
 928     originals in font units.<p>
 929
 930     This is great to get sure that your text prints very well on your
 931     printer, but it also implies that someone printing the exact same
 932     document on a device with different output resolutions (e.g.
 933     bubble-jet vs. laser printers) may encounter trouble.<p>
 934
 935     As the differences in advances accumulate on one line, they can
 936     sum to the width of one or more glyphs in extreme cases, which is
 937     enough to `overflow' the automatic justification algorithm.  This
 938     may add additional lines of printed text, or even remove some.
 939     Moreover, supplemental lines can produce unexpected page breaks
 940     and `blank' pages.  This can be extremely painful when working
 941     with large documents, as this `feature' may require you to
 942     redesign completely your formatting to re-print it.<p>
 943
 944     In conclusion, if you want portable document rendering, never
 945     hesitate to use and apply device-independent terms!  For example,
 946     a simple way to produce text would be:<p>
 947
 948     <ol>
 949
 950       <li>Get a scale to convert from your device-independent units
 951         to 26.6 pixels.<p>
 952
 953       <li>Get another scale to convert from original font units to
 954         device-independent units.<p>
 955
 956       <li>Perform pen placement and advances in device-independent
 957         units.<p>
 958
 959       <li>To render each glyph, compute the pen's rounded position,
 960         as well as the rounded glyph left side bearing, both
 961         expressed in 26.6 pixels (don't use the fitted metrics).  You
 962         will then be able to place the glyph and/or blit its bitmap.
 963
 964     </ol><p>
 965
 966   <font size="+1"><li>Kerning glyphs</font><p>
 967
 968     An interesting effect that most people appreciate is
 969     <i>kerning</i>.  It consists of modifying the spacing between two
 970     successive glyphs according to their outlines.  For example, the
 971     letters `T' and a `y' can be easily moved closer, as the top of
 972     the `y' fits nicely under the `T's upper right bar.<p>
 973
 974     To perform kerning, the TrueType specification provides a
 975     specific table (its tag being `kern'), with several storage
 976     formats.  This section doesn't explain how to access this
 977     information; however, you can have a look at the standard
 978     extension called `ttkern.h' which comes with FreeType.<p>
 979
 980     The <i>kerning distance</i> between two glyphs is a value
 981     expressed in font units which indicates whether their outline can
 982     be moved together or apart when one follows the other.  The
 983     distance isn't reflexive, which means that the kerning for the
 984     glyph pair (`T',`y') isn't the same as the one for (`y',`T').<p>
 985
 986     The value is positive when the glyphs must be moved apart, and
 987     negative when they must be moved closer.  You can implement
 988     kerning simply by adding its scaled and rounded value to the
 989     advance width when moving the pen position.  Here an example for
 990     horizontal kerning:
 991
 992 <pre>
 993   #define ROUND( x )  ( (x + 32) & -64 )
 994
 995   scaled_kerning = kerning * imetrics.x_scale / 0x10000;
 996
 997   pen_x += metrics.advance + ROUND( scaled_kerning );
 998 </pre>
 999
1000   <font size="+1"><li>Rotated and stretched/slanted text</font><p>
1001
1002     In order to produce rotated glyphs with FreeType, one must
1003     understand a few things:<p>
1004
1005     <ul>
1006
1007       <li>The engine doesn't apply specific transformations to the
1008         glyphs it loads and processes (other than the simpler
1009         resolution-base scaling and grid-fitting).  If you want to
1010         rotate glyphs, you will have to load their outline, then apply
1011         the geometric transformations that please you (a number of
1012         APIs are there to help you to do it easily).<p>
1013
1014       <li>Even if the glyph loader hints `straight' glyphs, it is
1015         possible to inform the font and glyph programs that you're
1016         going to later transform the resulting outlines.  Two flags
1017         can be passed to the bytecode interpreter:<p>
1018
1019         <ul>
1020
1021           <li>The `rotated' flag indicates that you are going to
1022             rotate the glyphs in a non-trivial direction (i.e., on
1023             neither of the two coordinate axis).  You are advised not
1024             to set it when writing 90&nbsp;degrees-rotated text for
1025             example.<p>
1026
1027           <li>The `stretched' flag indicates that you are going to
1028             apply a transformation that will distort distances.  While
1029             rotations and symmetries keep distances constant, slanting
1030             and stretching do modify them.
1031
1032         </ul>
1033
1034     </ul><p>
1035
1036     These flags can be interpreted by the glyph code to toggle certain
1037     processings which vary from one font to the other.  However, most
1038     of the TrueType fonts that were tested with FreeType, if not all
1039     of them, simply change the dropout-mode when any of these flags is
1040     set, and/or disable hinting when rotation is detected.  We advise
1041     you to never set these flags, even when rotating text.  For what
1042     it's worth, hinted rotated text is no uglier than un-hinted
1043     one.<p>
1044
1045     You can use the function TT_Set_Instance_Transform_Flags() to set
1046     them.  Then, rendering can be done with the following calls:
1047
1048 <pre>
1049   /* set the flags */
1050   TT_Set_Instance_Transforms( instance,
1051                               rotated,
1052                               stretched );
1053
1054   /* load a given glyph */
1055   TT_Get_Glyph_Outline( instance,
1056                         glyph,
1057                         index,
1058                         TTLOAD_DEFAULT );
1059
1060   /* access its outline */
1061   TT_Get_Glyph_Outline( instance, &outline );
1062
1063   /* in order to transform it */
1064   TT_Transform_Outline( outline, &matrix );
1065   /* and/or */
1066   TT_Translate_Outline( outline,
1067                         x_offset, y_offset );
1068
1069   /* to render it */
1070   TT_Get_Outline_Bitmap( outline, &bitmap );
1071 </pre>
1072
1073     Here is an example, assuming that the following variables
1074
1075 <pre>
1076   TT_Matrix  matrix;        /* 2x2 matrix */
1077   TT_Pos     x_off, y_off;  /* corrective offsets */
1078 </pre>
1079
1080     define a transformation that can be correctly applied to a glyph
1081     outline which have been previously placed relative to the
1082     imaginary point position (0,0) with bearings preserved.  Rendering
1083     text can now be done as follows:<p>
1084
1085     <ol>
1086
1087       <li>Initialize the pen position; when rotating, it is extremely
1088         well advised to use sub-pixel placement as you don't care
1089         about hinting.
1090
1091 <pre>
1092   pen_x = cursor_x;
1093   pen_y = cursor_y;
1094 </pre>
1095
1096       <li>Transform the glyph as needed, then translate it to the
1097         current pen position:
1098
1099 <pre>
1100   TT_Transform_Outline( outline, &matrix );
1101   TT_Translate_Outline( outline,
1102                         pen_x + x_off,
1103                         pen_y + y_off );
1104 </pre>
1105
1106         (Note that the transformation offsets have been included in
1107         the translation.)<p>
1108
1109       <li>Render the bitmap, as it has now been placed correctly.<p>
1110
1111       <li>To change the pen position, transform the vector (0,advance)
1112         with your matrix, and add it:
1113
1114 <pre>
1115   vec_x = metrics.advance;
1116   vec_y = 0;
1117   TT_Transform_Vector( &vec_x, &vec_y, &matrix );
1118   pen_x += vec_x;
1119   pen_y += vec_y;
1120 </pre>
1121
1122       <li>Start over at&nbsp;2. until completion.
1123
1124     </ol><p>
1125
1126     <hr>
1127     <i>IMPORTANT NOTE:</i><p>
1128
1129     Do not grid-fit the pen position before rendering your glyph when
1130     rendering rotated text.  If you do, your transformed baseline
1131     won't be preserved on each glyph, and the text will look like it's
1132     `hopping' randomly.  This is particularly visible at small
1133     sizes.<p>
1134
1135     Sub-pixel precision placement is <i>very</i> important for clean
1136     rotated text.
1137     <hr><p>
1138
1139   <font size="+1"><li>Font-smoothing, a.k.a. gray-levels
1140     rendering</font><p>
1141
1142     The FreeType engine's scan-line converter (the component also
1143     called the <i>rasterizer</i>) is able to convert a vectorial glyph
1144     outline into either a normal bitmap, or an 8-bit pixmap (a.k.a.
1145     <i>colored bitmaps</i> on some systems).  This last feature is
1146     called <i>gray-level rendering</i> or <i>font-smoothing</i>,
1147     because it uses a user-supplied palette to produce anti-aliased
1148     versions of the glyphs.<p>
1149
1150     Its principle is to render a bitmap which is twice as large than
1151     the target pixmap, then simply filtering it using a 2x2
1152     summation.<p>
1153
1154     <hr>
1155     <i>NOTE:</i><p>
1156
1157     FreeType's scan-line converter doesn't use or need an intermediate
1158     second bitmap.  Rather, filtering is performed in a single pass
1159     during the sweep (see the file `raster.txt' for more information
1160     about it).
1161     <hr><p>
1162
1163     You'll notice that, as with Windows&nbsp;95, FreeType's rasterizer
1164     only grays those parts of the glyph which need it, i.e., diagonals
1165     and curves, while keeping horizontal and vertical stems straight
1166     `black'.  This greatly improves the legibility of text, while
1167     avoiding the `blurry' look anti-aliased fonts typically found with
1168     Adobe's Type Manager or Acrobat.<p>
1169
1170     There are thus five available gray-levels, ranging from 0
1171     to&nbsp;4, where level&nbsp;0 and level&nbsp;4 are the background
1172     and foreground colors, respectively, and where levels&nbsp;1,
1173     2,&nbsp;3 are intermediate.  For example, to render black text on
1174     a white background, one can use a palette like:<p>
1175
1176     <ul>
1177
1178       palette[0]&nbsp;= white (background)  <br>
1179       palette[1]&nbsp;= light gray          <br>
1180       palette[2]&nbsp;= medium gray         <br>
1181       palette[3]&nbsp;= dark gray           <br>
1182       palette[4]&nbsp;= black (foreground)  <br>
1183
1184     </ul><p>
1185
1186     To set the engine's gray-level palette, simply use the API
1187     function TT_Set_Raster_Palette() after initialization.  It expects
1188     an array of 5&nbsp;chars which will be used to render the
1189     pixmaps.<p>
1190
1191     Note that the rasterizer doesn't create bitmaps or pixmaps.
1192     Rather, it simply renders glyphs in the arrays you pass to it.
1193     The generated glyph bitmaps are simply `or'-ed to the target (with
1194     0 being the background as a convention); in the case of pixmaps,
1195     pixels are simply written to the buffer, in spans of four aligned
1196     bytes.<p>
1197
1198     <hr>
1199     <i>NOTE:</i><p>
1200
1201     The raster isn't able to superpose `transparent' glyphs on the
1202     target pixmap.  This means that you should always call the API
1203     functions TT_Get_Glyph_Pixmap() and TT_Get_Outline_Pixmap() with
1204     an empty map, and perform the superposition yourself.<p>
1205
1206     This can be more or less tricky, depending on the palette you are
1207     using and your target graphics resolution.  One of the components
1208     found in the test directory, called `display.c', has large
1209     comments on the way it implements it for the test programs.  You
1210     are encouraged to read the test program sources to understand how
1211     one can take advantage of font smoothing.<p>
1212
1213     Pixmap surimposition is too system-specific a feature to be part
1214     of the FreeType engine.  Moreover, not everybody needs it!
1215     <hr><p>
1216
1217     Finally, the question of sur-imposing anti-aliased colored text on
1218     any texture, since being even more tricky, is left as an exercise
1219     to the reader&nbsp;;-) If this topic really interests you, the
1220     FreeType mailing list may host some helpful enthusiasts ready to
1221     answer your questions.  Who knows&nbsp;:-)<p>
1222
1223   <font size="+1"><li>Other interesting text processes</font><p>
1224
1225     <ul>
1226
1227       <li>Glyph substitution<p>
1228
1229         Substitution is used to replace one glyph by another when some
1230         specific condition is met in the text string.  Its most common
1231         examples are ligatures (like replacing the `f' followed by `i'
1232         by the single glyph `fi' if available in the font), as well as
1233         positional selection as performed in the Arabic script (for
1234         those not aware of this, each letter of the Arabic alphabet
1235         can be written differently according to its position on words:
1236         starting, ending, intermediate, or isolated).<p>
1237
1238         The base TrueType format doesn't define any table for glyph
1239         substitution.  However, GX, TrueType Open, and OpenType
1240         provide (incompatible) extensions to perform it.  Of course,
1241         it isn't supported by the engine, but an extension could be
1242         easily written to access the required tables.<p>
1243
1244         [Support for TrueType Open is already partially available.]<p>
1245
1246       <li>Justification<p>
1247
1248         ...
1249
1250     </ul>
1251
1252 </ol>
1253
1254 To be continued...
1255
1256 </body>
1257 </html>