doc/ttfautohint-1.pandoc

   1 % The ttfautohint library
   2 % Werner Lemberg
   3 % April 2012
   4
   5 <!--
   6   Copyright (C) 2011-2012 by Werner Lemberg.
   7
   8   This file is part of the ttfautohint library, and may only be used,
   9   modified, and distributed under the terms given in `COPYING'.  By
  10   continuing to use, modify, or distribute this file you indicate that you
  11   have read `COPYING' and understand and accept it fully.
  12
  13   The file `COPYING' mentioned in the previous paragraph is distributed
  14   with the ttfautohint library.
  15 -->
  16
  17
  18 Introduction
  19 ============
  20
  21 **ttfautohint** is a library which takes a TrueType font as the input,
  22 removes its bytecode instructions (if any), and returns a new font where all
  23 glyphs are bytecode hinted using the information given by FreeType's
  24 autohinting module.  The idea is to provide the excellent quality of the
  25 autohinter on platforms which don't use FreeType.
  26
  27 The library has a single API function, `TTF_autohint`, which is described
  28 [below](#ttf_autohint).
  29
  30 Bundled with the library there are two front-end programs, [`ttfautohint`
  31 and `ttfautohintGUI`](#ttfautohint-and-ttfautohintgui), being a command line
  32 and GUI application, respectively.
  33
  34
  35
  36 Background
  37 ==========
  38
  39 [Real-Time Grid Fitting of Typographic
  40 Outlines](http://www.tug.org/TUGboat/tb24-3/lemberg.pdf) is a scholarly
  41 paper which describes FreeType's auto-hinter in some detail.  Regarding the
  42 described data structures it's slightly out of date, but the algorithm
  43 itself hasn't changed.
  44
  45 In the following, some important concepts are introduced.  Note that
  46 ttfautohint only does hinting along the vertical direction (this is,
  47 modifying y\ coordinates).
  48
  49
  50 Segments and Edges
  51 ------------------
  52
  53 A glyph consists of one or more *contours* (this is, closed curves).  For
  54 example, glyph 'O' consists of two contours, while glyph 'I' has only one.
  55
  56 A *segment* is a series of consecutive points of a contour (including its
  57 Bézier control points) that are approximately aligned along a coordinate
  58 axis.
  59
  60 An *edge* corresponds to a single coordinate value on the main dimension
  61 that collects one or more segments (allowing for a small threshold).  While
  62 finding segments is done on the unscaled outline, finding edges is bound to
  63 the device resolution.  See [below](#hint-sets) for an example.
  64
  65 The analysis to find segments and edges is specific to a script.
  66
  67
  68 Feature Analysis
  69 ----------------
  70
  71 The auto-hinter analyzes a font in two steps.
  72
  73   * Global Analysis
  74
  75     This affects the hinting of all glyphs, trying to give them a uniform
  76     appearance.
  77
  78       + Compute standard stem widths and heights of the font.  The values
  79         are normally taken from the glyph of letter 'o'.
  80
  81       + Compute blue zones, see [below](#blue-zones).
  82
  83     If stem widths and heights of single glyphs differ by a large value, or
  84     if ttfautohint fails to find proper blue zones, hinting becomes quite
  85     poor, leading even to severe shape distortions.
  86
  87   * Glyph Analysis
  88
  89     This is a per-glyph operation.
  90
  91       + Find segments and edges.
  92
  93       + Link edges together to find stems and serifs.  The abovementioned
  94         paper gives more details on what exactly constitutes a stem or a
  95         serif and how the algorithm works.
  96
  97
  98 Blue Zones
  99 ----------
 100
 101 Outlines of certain characters are used to determine *blue zones*.  This
 102 concept is the same as with Type\ 1 fonts: All glyph points which lie in
 103 certain small horizontal zones get aligned vertically.
 104
 105 Here a table which shows the characters used by the latin module; the values
 106 are hard-coded in the source code.
 107
 108   ID    Blue zone                              Characters
 109   ----  -----------                            ------------
 110   1     top of capital letters                 THEZOCQS
 111   2     bottom of capital letters              HEZLOCUS
 112   3     top of 'small f' like letters          fijkdbh
 113   4     top of small letters                   xzroesc
 114   5     bottom of small letters                xzroesc
 115   6     bottom of descenders of small letters  pqgjy
 116
 117 The 'round' characters (e.g. 'OCQS') from Zones 1, 2, and 5 are also used to
 118 control the overshoot handling; to improve rendering at small sizes, zone\ 4
 119 gets adjusted to be on the pixel grid; cf. the [`--increase-x-height`
 120 option](#x-heights).
 121
 122
 123 Grid Fitting
 124 ------------
 125
 126 This is the central routine of the auto-hinter; its actions are highly
 127 dependent on the used script.  Currently, only support for scripts which
 128 work similarly to Latin (i.e. Greek and Cyrillic) is available.
 129
 130   * Align edges linked to blue zones.
 131
 132   * Fit edges to the pixel grid.
 133
 134   * Align serif edges.
 135
 136   * Handle remaining 'strong' points.  Such points are not part of an edge
 137     but are still important for defining the shape.  This roughly
 138     corresponds to the `IP` TrueType instruction.
 139
 140   * Everything else (the 'weak' points) is handled with an `IUP`
 141     instruction.
 142
 143
 144 Hint Sets
 145 ---------
 146
 147 A *hint set* is the *optimal* configuration for a given PPEM (pixel per EM)
 148 value.  However, it can also hint larger and smaller values.
 149
 150 Internally, ttfautohint creates hint sets for every PPEM value in the range
 151 given by the `--hinting-range-min` and `--hinting-range-max` options (this
 152 is a per-glyph operation).  If it differs to the current one, a new set is
 153 emitted.  For some glyphs it is possible that one set covers, say, the range
 154 8px-1000px, while other glyphs need 10 or more such sets.
 155
 156 Consider, for example, this glyph:
 157
 158 ```{.ditaa name="hintset"}
 159
 160     +--+  +--+  +--+
 161     |  |  |  |  |  |
 162     |  |  |  |  |  |
 163     |  |  |  +--+  |  --> y2
 164     |  +--+        |  --> y1
 165     |              |
 166     +--------------+
 167
 168 ```
 169
 170 For small PPEM values, the horizontal segments with vertical coordinates y1
 171 and y2 get unified to one edge, being positioned on one horizontal line.
 172 Starting with a certain (larger) PPEM value, this no longer happens:
 173 ttfautohint uses two edges and emits a new hint set to accomodate this
 174 situation.
 175
 176 Obviously, the more hint sets get emitted, the larger the bytecode
 177 ttfautohint adds to the output font.
 178
 179
 180 The '\.ttfautohint' Glyph
 181 -------------------------
 182
 183 ttfautohint doesn't hint subglyphs of composite glyphs separately.  Instead,
 184 it hints the whole glyph, this is, composites get recursively expanded so
 185 that they form simple glyphs, then hints are applied -- this is the normal
 186 working mode of FreeType's auto-hinter.
 187
 188 One problem, however, must be solved: Hinting for subglyphs (which usually
 189 are used as normal glyphs also) must be deactivated so that nothing but the
 190 final bytecode of the composite gets executed.
 191
 192 The trick used by ttfautohint is to prepend a composite element called
 193 '\.ttfautohint', a dummy glyph with a single point, and which has a single
 194 job: Its bytecode increases a CVT register (called `cvtl_is_subglyph` in the
 195 source code), indicating that we are within a composite glyph.  The final
 196 bytecode of the composite glyph eventually decrements the CVT register
 197 again.
 198
 199 As an example, let's consider composite glyph 'Agrave' ('À') which has the
 200 subglyph 'A' as the base and 'grave' as its accent.  After processing with
 201 ttfautohint it consists of three subglyphs: '\.ttfautohint', 'A', and
 202 'grave' (in this order).
 203
 204   Bytecode of    Action
 205   -------------  --------
 206   .ttfautohint   increase `cvtl_is_subglyph` (now: 1)
 207   A              do nothing because `cvtl_is_subglyph` > 0
 208   grave          do nothing because `cvtl_is_subglyph` > 0
 209   Agrave         decrease `cvtl_is_subglyph` (now: 0)\
 210                  apply hints because `cvtl_is_subglyph` == 0
 211
 212 All glyph point indices get adjusted since each '\.ttfautohint' subglyph
 213 shifts all following indices by one.  This must be done for both the
 214 bytecode and one subformat of `GPOS` anchor tables.
 215
 216 While this approach works fine on all tested platforms, there is one single
 217 drawback: Direct rendering of the '\.ttfautohint' subglyph (this is,
 218 rendering as a stand-alone glyph) disables proper hinting of all glyphs in
 219 the font!  Under normal circumstances this never happens because
 220 '\.ttfautohint' doesn't have an entry in the font's `cmap` table.  However,
 221 some test and demo programs like FreeType's `ftview` application or other
 222 glyph viewers which are able to bypass the `cmap` table might be affected.
 223
 224
 225 Scripts
 226 -------
 227
 228 ttfautohint checks which auto-hinting module should be used to hint a
 229 specific glyph.  To do so, it checks a glyph's Unicode character code
 230 whether it belongs to a given script.  Currently, only FreeType's 'latin'
 231 autohinting module is implemented, but more are expected to come.  Here is
 232 the hardcoded list of character ranges which are hinted by this 'latin'
 233 module.  As you can see, this also covers some non-latin scripts (in the
 234 Unicode sense) which have similar typographical properties.
 235
 236     Character range    Description
 237   -------------------  -------------
 238   0x0020 - 0x007F      Basic Latin (no control chars)
 239   0x00A0 - 0x00FF      Latin-1 Supplement (no control chars)
 240   0x0100 - 0x017F      Latin Extended-A
 241   0x0180 - 0x024F      Latin Extended-B
 242   0x0250 - 0x02AF      IPA Extensions
 243   0x02B0 - 0x02FF      Spacing Modifier Letters
 244   0x0300 - 0x036F      Combining Diacritical Marks
 245   0x0370 - 0x03FF      Greek and Coptic
 246   0x0400 - 0x04FF      Cyrillic
 247   0x0500 - 0x052F      Cyrillic Supplement
 248   0x1D00 - 0x1D7F      Phonetic Extensions
 249   0x1D80 - 0x1DBF      Phonetic Extensions Supplement
 250   0x1DC0 - 0x1DFF      Combining Diacritical Marks Supplement
 251   0x1E00 - 0x1EFF      Latin Extended Additional
 252   0x1F00 - 0x1FFF      Greek Extended
 253   0x2000 - 0x206F      General Punctuation
 254   0x2070 - 0x209F      Superscripts and Subscripts
 255   0x20A0 - 0x20CF      Currency Symbols
 256   0x2150 - 0x218F      Number Forms
 257   0x2460 - 0x24FF      Enclosed Alphanumerics
 258   0x2C60 - 0x2C7F      Latin Extended-C
 259   0x2DE0 - 0x2DFF      Cyrillic Extended-A
 260   0xA640 - 0xA69F      Cyrillic Extended-B
 261   0xA720 - 0xA7FF      Latin Extended-D
 262   0xFB00 - 0xFB06      Alphab. Present. Forms (Latin Ligs)
 263   0x1D400 - 0x1D7FF    Mathematical Alphanumeric Symbols
 264
 265 If a glyph's character code is not covered by a script range, it is not
 266 hinted (or rather, it gets hinted by the 'dummy' auto-hinting module which
 267 essentially does nothing).  This can be changed by specifying a *fallback
 268 script* with option `--latin-fallback`.
 269
 270
 271 SFNT Tables
 272 -----------
 273
 274 ttfautohint touches almost all SFNT tables within a TrueType or OpenType
 275 font.
 276
 277   * `glyf`: One glyph gets added (namely the '\.ttfautohint' glyph); all
 278     composites get an additional component; all hints in the table are
 279     replaced with new ones.
 280
 281   * `cvt`, `prep`, and `fpgm`: These tables get replaced with data
 282     necessary for the new hinting bytecode.
 283
 284   * `gasp`: Replaced with new, quite generic data.
 285
 286   * `DSIG`: Replaced with a dummy version.  ttfautohint can't digitally sign
 287     a font.
 288
 289   * `name`: The 'version' entries are modified to add information about the
 290     parameters which have been used for calling ttfautohint.  This can be
 291     controlled with the [`--no-info`](#ttfautohint-info) option.
 292
 293   * `GPOS`, `hmtx`, `loca`, `head`, `maxp`, `post`: Updated to fit the
 294     additional '\.ttfautohint' glyph, the additional subglyphs in
 295     composites, and the new hinting bytecode.
 296
 297   * `LTSH`, `hdmx`: Since ttfautohint doesn't do any horizontal hinting,
 298     those tables are superfluous and thus removed.
 299
 300   * `VDMX`: Removed, since it depends on the original bytecode which
 301     ttfautohint removes.  A font editor might recompute the necessary data
 302     later on.
 303
 304
 305 Problems
 306 --------
 307
 308 Diagonals.
 309
 310 TODO.
 311
 312
 313
 314 `ttfautohint` and `ttfautohintGUI`
 315 ==================================
 316
 317 On all supported platforms (GNU/Linux, Windows, and Mac OS\ X), the GUI
 318 looks quite similar; the used toolkit is [Qt], which in turn uses the
 319 platform's native widgets.
 320
 321 ![`ttfautohintGUI` on GNU/Linux running KDE](img/ttfautohintGUI.png)
 322
 323 Both the GUI and console version share the same features, to be discussed in
 324 the next subsection.
 325
 326
 327 Options
 328 -------
 329
 330 `ttfautohintGUI` doesn't send any output to a console; however, it accepts
 331 the same command line options as `ttfautohint`, setting default values for
 332 the GUI.
 333
 334 Long options can be given with one or two dashes, and with and without equal
 335 sign between option and argument.  This means that the following forms are
 336 acceptable: `-foo=`*bar*, `--foo=`*bar*, `-foo`\ *bar*, and `--foo`\ *bar*.
 337
 338 ### Hint Set Ranges
 339
 340 `--hinting-range-min=`*n*, `-l`\ *n*
 341 :   The minimum PPEM value (in pixels) at which hint sets are created.  The
 342     default value for *n* is\ 8.
 343 `--hinting-range-max=`*n*, `-r`\ *n*
 344 :   The maximum PPEM value (in pixels) at which hint sets are created.  The
 345     default value for *n* is 50.
 346
 347 ### Hinting Limit
 348
 349 `--hinting-limit=`*n*, `-G`\ *n*
 350 :   The *hinting limit* is the PPEM value (in pixels) where hinting gets
 351     switched off completely (using the `INSTCTRL` bytecode instruction); it
 352     has zero impact on the file size.  The default value for *n* is 200.
 353
 354     Note that hinting in the range 'hinting-range-max' up to 'hinting-limit'
 355     uses the hinting configuration for 'hinting-range-max'.
 356
 357     To omit a hinting limit, use `--hinting-limit=0` (or check the 'No
 358     Hinting Limit' box in the GUI).  Since this will cause internal math
 359     overflow in the rasterizer for large pixel values (>\ 1500px approx.) it
 360     is strongly recommended to not use this except for testing purposes.
 361
 362 ### x Heights
 363
 364 `--increase-x-height`, `-x`
 365 :   Normally, ttfautohint rounds the x\ height to the pixel grid, with a
 366     slight preference for rounding up.  If this flag is set, values are much
 367     more often rounded up.  Use this flag to increase the legibility of
 368     small sizes if necessary.
 369
 370 ### Fallback Script
 371
 372 `--latin-fallback`, `-f`
 373 :   Set fallback script to 'latin', this is, use the 'latin' auto-hinting
 374     module instead of 'none' for all glyphs which can't be assigned to a
 375     script.  See [above](#scripts) for more details.
 376
 377 ### Pre-Hinting
 378
 379 `--pre-hinting`, `-p`
 380 :   *Pre-hinting* means that a font's original bytecode is applied to all
 381     glyphs before it is replaced with bytecode created by ttfautohint.
 382     This makes only sense if your font already has some hints in it which
 383     modify the shape even at EM size (normally 2048px); for example, some
 384     CJK fonts need this because the bytecode is used to scale and shift
 385     subglyphs.  For most fonts, however, this is not the case.
 386
 387 ### ttfautohint Info
 388
 389 `--no-info`, `-n`
 390 :   Don't add ttfautohint version and command line information to the
 391     version string or strings (with name ID\ 5) in the font's 'name' table.
 392     In the GUI it is similar: If you uncheck the 'Add ttfautohint info' box,
 393     information is not added to the 'name' table.
 394
 395 ### Symbol Fonts
 396
 397 `--symbol`, `-s`
 398 :   Use default values for standard stem width and height instead of
 399     deriving them from latin character 'o'.  Use this option (usually in
 400     combination with option `--latin-fallback`) to hint symbol fonts, for
 401     example, which lack character 'o', at the expense of possibly poor
 402     hinting results at small sizes.
 403
 404 ### Font License Restrictions
 405
 406 `--ignore-permissions`, `-i`
 407 :   By default, fonts which have bit\ 1 set in the 'fsType' field of the
 408     'OS/2' table are rejected.  If you have a permission of the font's legal
 409     owner to modify the font, specify this command line option.
 410
 411     If this option is not set, `ttfautohintGUI` shows a dialogue to handle
 412     such fonts if necessary.
 413
 414 ### Miscellaneous
 415
 416 `--help`, `-h`
 417 :   On the console, print a brief documentation on standard output and exit.
 418     This doesn't work with `ttfautohintGUI` on MS Windows.
 419
 420 `--version`, `-v`
 421 :   On the console, print version information on standard output and exit.
 422     This doesn't work with `ttfautohintGUI` on MS Windows.
 423
 424
 425
 426 Samples
 427 =======
 428
 429
 430 Roboto
 431 ------
 432
 433 TODO
 434
 435
 436 Ubuntu
 437 ------
 438
 439 TODO
 440
 441
 442 [Qt]: http://qt-project.org