6 Copyright (C) 2011-2013 by Werner Lemberg.
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.
13 The file `COPYING' mentioned in the previous paragraph is distributed
14 with the ttfautohint library.
22 **ttfautohint** is a library written in\ C which takes a TrueType font as
23 the input, removes its bytecode instructions (if any), and returns a new
24 font where all glyphs are bytecode hinted using the information given by
25 FreeType's autohinting module. The idea is to provide the excellent quality
26 of the autohinter on platforms which don't use FreeType.
28 The library has a single API function, `TTF_autohint`, which is described
29 [below](#the-ttfautohint-api).
31 Bundled with the library there are two front-end programs, [`ttfautohint`
32 and `ttfautohintGUI`](#ttfautohint-and-ttfautohintgui), being a command line
33 and an application with a Graphics User Interface (GUI), respectively.
36 What exactly are hints?
37 -----------------------
39 To cite [Wikipedia](http://en.wikipedia.org/wiki/Font_hinting):
41 > **Font hinting** (also known as **instructing**) is the use of
42 > mathematical instructions to adjust the display of an outline font so that
43 > it lines up with a rasterized grid. At low screen resolutions, hinting is
44 > critical for producing a clear, legible text. It can be accompanied by
45 > antialiasing and (on liquid crystal displays) subpixel rendering for
48 and Apple's [TrueType Reference
49 Manual](https://developer.apple.com/fonts/TTRefMan/RM03/Chap3.html#features):
51 > For optimal results, a font instructor should follow these guidelines:
53 > - At small sizes, chance effects should not be allowed to magnify small
54 > differences in the original outline design of a glyph.
56 > - At large sizes, the subtlety of the original design should emerge.
59 In general, there are three possible ways to hint a glyph.
61 1. The font contains hints (in the original sense of this word) to guide
62 the rasterizer, telling it which shapes of the glyphs need special
63 consideration. The hinting logic is partly in the font and partly in
64 the rasterizer. More sophisticated rasterizers are able to produce
65 better rendering results.
67 This is how Type\ 1 and CFF font hints work.
69 2. The font contains exact instructions (also called *bytecode*) on how to
70 move the points of its outlines, depending on the resolution of the
71 output device, and which intentionally distort the (outline) shape to
72 produce a well-rasterized result. The hinting logic is in the font;
73 ideally, all rasterizers simply process these instructions to get the
74 same result on all platforms.
76 This is how TrueType hints work.
78 3. The font gets auto-hinted (at run-time). The hinting logic is
79 completely in the rasterizer. No hints in the font are used or needed;
80 instead, the rasterizer scans and analyzes the glyphs to apply
81 corrections by itself.
83 This is how FreeType's auto-hinter works; see
84 [below](#background-and-technical-details) for more.
87 What problems can arise with TrueType hinting?
88 ----------------------------------------------
90 While it is relatively easy to specify PostScript hints (either manually or
91 by an auto-hinter which works at font creation time), creating TrueType
92 hints is far more difficult. There are at least two reasons:
94 - TrueType instructions form a programming language, operating at a very
95 low level. They are comparable to assembler code, thus lacking all
96 high-level concepts to make programming more comfortable.
98 Here an example how such code looks like:
102 PUSHB[ ] /* 3 values pushed */
105 PUSHB[ ] /* 2 values pushed */
108 PUSHB[ ] /* 3 values pushed */
113 Another major obstacle is the fact that font designers usually aren't
116 - It is very time consuming to manually hint glyphs. Given that the
117 number of specialists for TrueType hinting is very limited, hinting a
118 large set of glyphs for a font or font family can become very expensive.
124 The ttfautohint library brings the excellent quality of FreeType rendering
125 to platforms which don't use FreeType, yet require hinting for text to look
126 good -- like Microsoft Windows. Roughly speaking, it converts the glyph
127 analysis done by FreeType's auto-hinting module to TrueType bytecode.
128 Internally, the auto-hinter's algorithm resembles PostScript hinting
129 methods; it thus combines all three hinting methods discussed
130 [previously](#what-exactly-are-hints).
132 The simple interface of the front-ends (both on the command line and with
133 the GUI) allows quick hinting of a whole font with a few mouse clicks or a
134 single command on the prompt. As a result, you get better rendering results
135 with web browsers, for example.
137 Across Windows rendering environments today, fonts processed with
138 ttfautohint look best with ClearType enabled. This is the default for
139 Windows\ 7. Good visual results are also seen in recent MacOS\ X versions
140 and GNU/Linux systems that use FreeType for rendering.
142 The goal of the project is to generate a 'first pass' of hinting that font
143 developers can refine further for ultimate quality.
147 `ttfautohint` and `ttfautohintGUI`
148 ==================================
150 On all supported platforms (GNU/Linux, Windows, and Mac OS\ X), the GUI
151 looks quite similar; the used toolkit is [Qt], which in turn uses the
152 platform's native widgets.
154 ![`ttfautohintGUI` on GNU/Linux running KDE](img/ttfautohintGUI.png)
156 Both the GUI and console version share the same features, to be discussed in
159 **Warning: ttfautohint cannot always process a font a second time.**
160 If the font contains composite glyphs, and option `-c` is used,
161 reprocessing with ttfautohint will fail. For this reason it is strongly
162 recommended to *not* delete the original, unhinted font so that you can
163 always rerun ttfautohint.
166 Calling `ttfautohint`
167 ---------------------
170 ttfautohint [OPTION]... [IN-FILE [OUT-FILE]]
173 The TTY binary, `ttfautohint`, works like a Unix filter, this is, it reads
174 data from standard input if no input file name is given, and it sends its
175 output to standard output if no output file name is specified.
177 A typical call looks like the following.
180 ttfautohint -v -f foo.ttf foo-autohinted.ttf
183 For demonstration purposes, here the same using a pipe and redirection.
184 Note that Windows's default command line interpreter, `cmd.exe`, doesn't
185 support piping with binary files, unfortunately.
188 cat foo.ttf | ttfautohint -v -f > foo-autohinted.ttf
192 Calling `ttfautohintGUI`
193 ------------------------
196 ttfautohintGUI [OPTION]...
199 `ttfautohintGUI` doesn't send any output to a console; however, it accepts
200 the same command line options as `ttfautohint`, setting default values for
207 Long options can be given with one or two dashes, and with and without an
208 equal sign between option and argument. This means that the following forms
209 are acceptable: `-foo=`*bar*, `--foo=`*bar*, `-foo`\ *bar*, and
212 Below, the section title refers to the command's label in the GUI, then
213 comes the name of the corresponding long command line option and its short
214 equivalent, followed by a description.
216 Background and technical details on the meaning of the various options are
217 given [afterwards](#background-and-technical-details).
219 ### Hint Set Range Minimum, Hint Set Range Maximum
221 See ['Hint Sets'](#hint-sets) for a definition and explanation.
223 `--hinting-range-min=`*n*, `-l`\ *n*
224 : The minimum PPEM value (in pixels) at which hint sets are created. The
225 default value for *n* is\ 8.
227 `--hinting-range-max=`*n*, `-r`\ *n*
228 : The maximum PPEM value (in pixels) at which hint sets are created. The
229 default value for *n* is 50.
233 `--latin-fallback`, `-f`
234 : Set fallback script to 'latin', this is, use the 'latin' auto-hinting
235 module instead of 'none' for all glyphs which can't be assigned to a
236 script. See [below](#scripts) for more details.
240 `--hinting-limit=`*n*, `-G`\ *n*
241 : The *hinting limit* is the PPEM value (in pixels) where hinting gets
242 switched off (using the `INSTCTRL` bytecode instruction); it has zero
243 impact on the file size. The default value for *n* is 200 which means
244 that the font is not hinted for PPEM values larger than 200.
246 Note that hinting in the range 'hinting-range-max' up to 'hinting-limit'
247 uses the hinting configuration for 'hinting-range-max'.
249 To omit a hinting limit, use `--hinting-limit=0` (or check the 'No
250 Hinting Limit' box in the GUI). Since this will cause internal math
251 overflow in the rasterizer for large pixel values (>\ 1500px approx.) it
252 is strongly recommended to not use this except for testing purposes.
254 ### x Height Increase Limit
256 `--increase-x-height=`*n*, `-x`\ *n*
257 : Normally, ttfautohint rounds the x\ height to the pixel grid, with a
258 slight preference for rounding up. If this flag is set, values in the
259 range 6\ PPEM to *n*\ PPEM are much more often rounded up. The default
260 value for *n* is 14. Use this flag to increase the legibility of small
261 sizes if necessary; you might get weird rendering results otherwise for
262 glyphs like 'a' or 'e', depending on the font design.
264 To switch off this feature, use `--increase-x-height=0` (or check the
265 'No x\ Height Increase' box in the GUI). To switch off rounding the
266 x\ height to the pixel grid in general, either partially or completely,
267 see ['x Height Snapping Exceptions'](#x-height-snapping-exceptions).
269 The following images again use the font 'Mertz Bold'.
271 ![At 17px, without option `-x` and '`-w ""`', the hole in glyph 'e'
272 looks very grey in the FontForge snapshot, and the GDI ClearType
273 rendering (which is the default on older Windows versions) fills it
274 completely with black because it uses B/W rendering along the y\ axis.
275 FreeType's 'light' autohint mode (which corresponds to ttfautohint's
276 'smooth' stem width algorithm) intentionally aligns horizontal lines
277 to non-integer (but still discrete) values to avoid large glyph shape
278 distortions.](img/e-17px-x14.png)
280 ![The same, this time with option `-x 17` (and
281 '`-w ""`').](img/e-17px-x17.png)
283 ### x Height Snapping Exceptions
285 `--x-height-snapping-exceptions=`*string*, `-X`\ *string*
286 : A list of comma separated PPEM values or value ranges at which no
287 x-height snapping shall be applied. A value range has the form
288 *value1*`-`*value2*, meaning *value1*\ <= PPEM <=\ *value2*. *value1*
289 or *value2* (or both) can be missing; a missing value is replaced by the
290 beginning or end of the whole interval of valid PPEM values,
291 respectively (6\ to 32767). Whitespace is not significant; superfluous
292 commas are ignored, and ranges must be specified in increasing order.
293 For example, the string `"7-9, 11, 13-"` means the values 7, 8, 9, 11,
294 13, 14, 15, etc. Consequently, if the supplied argument is `"-"`, no
295 x-height snapping takes place at all. The default is the empty string
296 (`""`), meaning no snapping exceptions.
298 Normally, x-height snapping means a slight increase in the overall
299 vertical glyph size so that the height of lowercase glyphs gets aligned
300 to the pixel grid (this is a global feature, affecting *all* glyphs of a
301 font). However, having larger vertical glyph sizes is not always
302 desired, especially if it is not possible to adjust the `usWinAscent`
303 and `usWinDescent` values from the font's `OS/2` table so that they are
304 not too tight. See ['Windows Compatibility'](#windows-compatibility)
307 ### Windows Compatibility
309 `--windows-compatibility`, `-W`
310 : This option makes ttfautohint add two artificial blue zones, positioned
311 at the `usWinAscent` and `usWinDescent` values (from the font's `OS/2`
312 table). The idea is to help ttfautohint so that the hinted glyphs stay
313 within this horizontal stripe since Windows clips everything falling
316 There is a general problem with tight values for `usWinAscent` and
317 `usWinDescent`; a good description is given in the [Vertical Metrics
318 How-To](http://typophile.com/node/13081). Additionally, there is a
319 special problem with tight values if used in combination with
320 ttfautohint because the auto-hinter tends to slightly increase the
321 vertical glyph dimensions at smaller sizes to improve legibility. This
322 enlargement can make the heights and depths of glyphs exceed the range
323 given by `usWinAscent` and `usWinDescent`.
325 If ttfautohint is part of the font creation tool chain, and the font
326 designer can adjust those two values, a better solution instead of using
327 option `-W` is to reserve some vertical space for 'padding': For the
328 auto-hinter, the difference between a top or bottom outline point before
329 and after hinting is less than 1px, thus a vertical padding of 2px is
330 sufficient. Assuming a minimum hinting size of 6ppem, adding two pixels
331 gives an increase factor of 8÷6 = 1.33. This is near to the default
332 baseline-to-baseline distance used by TeX and other sophisticated text
333 processing applications, namely 1.2×designsize, which gives satisfying
334 results in most cases. It is also near to the factor 1.25 recommended
335 in the abovementioned How-To. For example, if the vertical extension of
336 the largest glyph is 2000 units (assuming that it approximately
337 represents the designsize), the sum of `usWinAscent` and `usWinDescent`
338 could be 1.25×2000 = 2500.
340 In case ttfautohint is used as an auto-hinting tool for fonts which can
341 be no longer modified to change the metrics, option `-W` in combination
342 with '`-X "-"`' to suppress any vertical enlargement should prevent
347 `--pre-hinting`, `-p`
348 : *Pre-hinting* means that a font's original bytecode is applied to all
349 glyphs before it is replaced with bytecode created by ttfautohint.
350 This makes only sense if your font already has some hints in it which
351 modify the shape even at EM size (normally 2048px); for example, some
352 CJK fonts need this because the bytecode is used to scale and shift
353 subglyphs. For most fonts, however, this is not the case.
358 : By default, the components of a composite glyph get hinted separately.
359 If this flag is set, the composite glyph itself gets hinted (and the
360 hints of the components are ignored). Using this flag increases the
361 bytecode size a lot, however, it might yield better hinting results.
363 If this option is used (and a font actually contains composite glyphs),
364 ttfautohint cannot reprocess its own output for technical reasons, see
365 [below](#the-.ttfautohint-glyph).
370 : Use default values for standard (horizontal) stem width and height
371 instead of deriving them from latin character 'o'. Use this option
372 (usually in combination with option `--latin-fallback`) to hint symbol
373 or dingbat fonts or math glyphs, for example, which lack character 'o',
374 at the expense of possibly poor hinting results at small sizes.
379 : Strip off all hints without generating new hints. Consequently, all
380 other hinting options are ignored. This option is intended for testing
383 ### Add ttfautohint Info
386 : Don't add ttfautohint version and command line information to the
387 version string or strings (with name ID\ 5) in the font's `name` table.
388 In the GUI it is similar: If you uncheck the 'Add ttfautohint info' box,
389 information is not added to the `name` table. Except for testing and
390 development purposes it is strongly recommended to not use this option.
392 ### Strong Stem Width and Positioning
394 `--strong-stem-width=`*string*, `-w`\ *string*
395 : ttfautohint offers two different routines to handle (horizontal) stem
396 widths and stem positions: 'smooth' and 'strong'. The former uses
397 discrete values which slightly increase the stem contrast with almost no
398 distortion of the outlines, while the latter snaps both stem widths and
399 stem positions to integer pixel values as much as possible, yielding a
400 crisper appearance at the cost of much more distortion.
402 These two routines are mapped onto three possible rendering targets:
404 - grayscale rendering, with or without optimization for subpixel
405 positioning (e.g. Mac OS\ X)
407 - 'GDI ClearType' rendering: the rasterizer version, as returned by the
408 GETINFO bytecode instruction, is in the range 36\ <= version <\ 38 and
409 ClearType is enabled (e.g. Windows XP)
411 - 'DirectWrite ClearType' rendering: the rasterizer version, as returned
412 by the GETINFO bytecode instruction, is >=\ 38, ClearType is enabled,
413 and subpixel positioning is enabled also (e.g. Internet Explorer\ 9
414 running on Windows\ 7)
416 GDI ClearType uses a mode similar to B/W rendering along the vertical
417 axis, while DW ClearType applies grayscale rendering. Additionally,
418 only DW ClearType provides subpixel positioning along the x\ axis. For
419 what it's worth, the rasterizers version\ 36 and version\ 38 in
420 Microsoft Windows are two completely different rendering engines.
422 The command line option expects *string* to contain up to three letters
423 with possible values '`g`' for grayscale, '`G`' for GDI ClearType, and
424 '`D`' for DW ClearType. If a letter is found in *string*, the strong
425 stem width routine is used for the corresponding rendering target. The
426 default value is '`G`' which means that strong stem width handling is
427 activated for GDI ClearType only. To use smooth stem width handling for
428 all three rendering targets, use the empty string as an argument,
429 usually connoted with '`""`'.
431 In the GUI, simply set the corresponding check box to select the stem
432 width routine for a given rendering target.
434 The following FontForge snapshot images use the font ['Mertz
435 Bold'](http://code.newtypography.co.uk/mertz-sans/) (still under
436 development) from [Vernon Adams].
438 ![The left part shows the glyph 'g' unhinted at 26px, the right part
439 with hints, using the 'smooth' stem algorithm.](img/ff-g-26px.png)
441 ![The same, but this time using the 'strong'
442 algorithm. Note how the stems are aligned to the pixel
443 grid.](img/ff-g-26px-wD.png)
445 ### Font License Restrictions
447 `--ignore-restrictions`, `-i`
448 : By default, fonts which have bit\ 1 set in the 'fsType' field of the
449 `OS/2` table are rejected. If you have a permission of the font's legal
450 owner to modify the font, specify this command line option.
452 If this option is not set, `ttfautohintGUI` shows a dialogue to handle
453 such fonts if necessary.
458 : On the console, print a brief documentation on standard output and exit.
459 This doesn't work with `ttfautohintGUI` on MS Windows.
462 : On the console, print version information on standard output and exit.
463 This doesn't work with `ttfautohintGUI` on MS Windows.
466 : Print *a lot* of debugging information on standard error while
467 processing a font (you should redirect stderr to a file). This
468 doesn't work with `ttfautohintGUI` on MS Windows.
472 Background and Technical Details
473 ================================
475 [Real-Time Grid Fitting of Typographic
476 Outlines](http://www.tug.org/TUGboat/tb24-3/lemberg.pdf) is a scholarly
477 paper which describes FreeType's auto-hinter in some detail. Regarding the
478 described data structures it is slightly out of date, but the algorithm
479 itself hasn't changed.
481 The next few subsections are mainly based on this article, introducing some
482 important concepts. Note that ttfautohint only does hinting along the
483 vertical direction (this is, modifying y\ coordinates).
489 A glyph consists of one or more *contours* (this is, closed curves). For
490 example, glyph 'O' consists of two contours, while glyph 'I' has only one.
492 ![The letter 'O' has two contours, an inner and an outer one, while letter
493 'I' has only an outer contour.](img/o-and-i)
495 A *segment* is a series of consecutive points of a contour (including its
496 Bézier control points) that are approximately aligned along a coordinate
499 ![A serif. Contour and control points are represented by squares and
500 circles, respectively. The bottom 'line' DE is approximately aligned
501 along the horizontal axis, thus it forms a segment of 7\ points. Together
502 with the two other horizontal segments, BC and FG, they form two edges
503 (BC+FG, DE).](img/segment-edge)
505 An *edge* corresponds to a single coordinate value on the main dimension
506 that collects one or more segments (allowing for a small threshold). While
507 finding segments is done on the unscaled outline, finding edges is bound to
508 the device resolution. See [below](#hint-sets) for an example.
510 The analysis to find segments and edges is specific to a script.
516 The auto-hinter analyzes a font in two steps. Right now, everything
517 described below happens for the horizontal axis only, providing vertical
522 This affects the hinting of all glyphs, trying to give them a uniform
525 + Compute standard stem widths and heights of the font. The values
526 are normally taken from the glyph of letter 'o'.
528 + Compute blue zones, see [below](#blue-zones).
530 If stem widths and heights of single glyphs differ by a large value, or
531 if ttfautohint fails to find proper blue zones, hinting becomes quite
532 poor, leading even to severe shape distortions.
536 This is a per-glyph operation.
538 + Find segments and edges.
540 + Link edges together to find stems and serifs. The abovementioned
541 paper gives more details on what exactly constitutes a stem or a
542 serif and how the algorithm works.
548 ![Two blue zones relevant to the glyph 'a'. Vertical point coordinates of
549 *all* glyphs within these zones are aligned.](img/blue-zones)
551 Outlines of certain characters are used to determine *blue zones*. This
552 concept is the same as with Type\ 1 fonts: All glyph points which lie in
553 certain small horizontal zones get aligned vertically.
555 Here a table which shows the characters used by the latin module; the values
556 are hard-coded in the source code.
558 ID Blue zone Characters
559 ---- ----------- ------------
560 1 top of capital letters THEZOCQS
561 2 bottom of capital letters HEZLOCUS
562 3 top of 'small f' like letters fijkdbh
563 4 top of small letters xzroesc
564 5 bottom of small letters xzroesc
565 6 bottom of descenders of small letters pqgjy
567 The 'round' characters (e.g. 'OCQS') from Zones 1, 2, and 5 are also used to
568 control the overshoot handling; to improve rendering at small sizes, zone\ 4
569 gets adjusted to be on the pixel grid; cf. the [`--increase-x-height`
570 option](#x-height-increase-limit).
572 ![This image shows the relevant glyph terms for vertical blue zone
573 positions.](img/glyph-terms)
579 Aligning outlines along the grid lines is called *grid fitting*. It doesn't
580 necessarily mean that the outlines are positioned *exactly* on the grid,
581 however, especially if you want a smooth appearance at different sizes.
582 This is the central routine of the auto-hinter; its actions are highly
583 dependent on the used script. Currently, only support for scripts which
584 work similarly to Latin (i.e. Greek and Cyrillic) is available.
586 * Align edges linked to blue zones.
588 * Fit edges to the pixel grid.
592 * Handle remaining 'strong' points. Such points are not part of an edge
593 but are still important for defining the shape. This roughly
594 corresponds to the `IP` TrueType instruction.
596 * Everything else (the 'weak' points) is handled with an `IUP`
599 The following images illustrate the hinting process, using glyph 'a' from
600 the freely available font ['Ubuntu Book'](http://font.ubuntu.com). The
601 manual hints were added by [Dalton Maag Ltd], the used application to create
602 the hinting debug snapshots was [FontForge].
604 ![Before hinting.](img/a-before-hinting.png)
606 ![After hinting, using manual hints.](img/a-after-hinting.png)
608 ![After hinting, using ttfautohint. Note that the hinting process
609 doesn't change horizontal positions.](img/a-after-autohinting.png)
615 In ttfautohint terminology, a *hint set* is the *optimal* configuration for
616 a given PPEM (pixel per EM) value.
618 In the range given by the `--hinting-range-min` and `--hinting-range-max`
619 options, ttfautohint creates hint sets for every PPEM value. For each
620 glyph, ttfautohint automatically determines if a new set should be emitted
621 for a PPEM value if it finds that it differs from a previous one. For some
622 glyphs it is possible that one set covers, say, the range 8px-1000px, while
623 other glyphs need 10 or more such sets.
625 In the PPEM range below `--hinting-range-min`, ttfautohint always uses just
626 one set, in the PPEM range between `--hinting-range-max` and
627 `--hinting-limit`, it also uses just one set.
629 One of the hinting configuration parameters is the decision which segments
630 form an edge. For example, let us assume that two segments get aligned on a
631 single horizontal edge at 11px, while two edges are used at 12px.
632 This change makes ttfautohint emit a new hint set to accomodate this
635 The next images illustrate this, using a Cyrillic letter (glyph 'afii10108')
636 from the 'Ubuntu book' font, processed with ttfautohint.
638 ![Before hinting, size 11px.](img/afii10108-11px-before-hinting.png)
640 ![After hinting, size 11px. Segments 43-27-28 and 14-15 are aligned on a
641 single edge, as are segments 26-0-1 and
642 20-21.](img/afii10108-11px-after-hinting.png)
644 ![Before hinting, size 12px.](img/afii10108-12px-before-hinting.png)
646 ![After hinting, size 12px. The segments are not aligned. While
647 segments 43-27-28 and 20-21 now have almost the same horizontal position,
648 they don't form an edge because the outlines passing through the segments
649 point into different directions.](img/afii10108-12px-after-hinting.png)
651 Obviously, the more hint sets get emitted, the larger the bytecode
652 ttfautohint adds to the output font. To find a good value\ *n* for
653 `--hinting-range-max`, some experimentation is necessary since *n* depends
654 on the glyph shapes in the input font. If the value is too low, the hint
655 set created for the PPEM value\ *n* (this hint set gets used for all larger
656 PPEM values) might distort the outlines too much in the PPEM range given
657 by\ *n* and the value set by `--hinting-limit` (at which hinting gets
658 switched off). If the value is too high, the font size increases due to
659 more hint sets without any noticeable hinting effects.
661 Similar arguments hold for `--hinting-range-min` except that there is no
662 lower limit at which hinting is switched off.
664 An example. Let's assume that we have a hinting range 10\ <= ppem <=\ 100,
665 and the hinting limit is set to 250. For a given glyph, ttfautohint finds
666 out that four hint sets must be computed to exactly cover thes hinting
667 range: 10-15, 16-40, 41-80, and 81-100. For ppem values below 10ppem, the
668 hint set covering 10-15ppem is used, for ppem values larger than 100 the
669 hint set covering 81-100ppem is used. For ppem values larger than 250, no
670 hinting gets applied.
673 The '\.ttfautohint' Glyph
674 -------------------------
676 If [option `--composites`](#hint-composites) is used, ttfautohint doesn't
677 hint subglyphs of composite glyphs separately. Instead, it hints the whole
678 glyph, this is, composites get recursively expanded internally so that they
679 form simple glyphs, then hints are applied -- this is the normal working
680 mode of FreeType's auto-hinter.
682 One problem, however, must be solved: Hinting for subglyphs (which usually
683 are used as normal glyphs also) must be deactivated so that nothing but the
684 final bytecode of the composite gets executed.
686 The trick used by ttfautohint is to prepend a composite element called
687 '\.ttfautohint', a dummy glyph with a single point, and which has a single
688 job: Its bytecode increases a variable (to be more precise, it is a CVT
689 register called `cvtl_is_subglyph` in the source code), indicating that we
690 are within a composite glyph. The final bytecode of the composite glyph
691 eventually decrements this variable again.
693 As an example, let's consider composite glyph 'Agrave' ('À') which has the
694 subglyph 'A' as the base and 'grave' as its accent. After processing with
695 ttfautohint it consists of three components: '\.ttfautohint', 'A', and
696 'grave' (in this order).
699 ------------- --------
700 .ttfautohint increase `cvtl_is_subglyph` (now: 1)
701 A do nothing because `cvtl_is_subglyph` > 0
702 grave do nothing because `cvtl_is_subglyph` > 0
703 Agrave decrease `cvtl_is_subglyph` (now: 0)\
704 apply hints because `cvtl_is_subglyph` == 0
706 Some technical details (which you might skip): All glyph point indices get
707 adjusted since each '\.ttfautohint' subglyph shifts all following indices by
708 one. This must be done for both the bytecode and one subformat of
709 OpenType's `GPOS` anchor tables.
711 While this approach works fine on all tested platforms, there is one single
712 drawback: Direct rendering of the '\.ttfautohint' subglyph (this is,
713 rendering as a stand-alone glyph) disables proper hinting of all glyphs in
714 the font! Under normal circumstances this never happens because
715 '\.ttfautohint' doesn't have an entry in the font's `cmap` table. (However,
716 some test and demo programs like FreeType's `ftview` application or other
717 glyph viewers which are able to bypass the `cmap` table might be affected.)
723 ttfautohint checks which auto-hinting module should be used to hint a
724 specific glyph. To do so, it checks a glyph's Unicode character code
725 whether it belongs to a given script. Currently, only FreeType's 'latin'
726 autohinting module is implemented, but more are expected to come. Here is
727 the hardcoded list of character ranges which are hinted by this 'latin'
728 module. As you can see, this also covers some non-latin scripts (in the
729 Unicode sense) which have similar typographical properties.
731 Character range Description
732 --------------------- -------------
733 `0x0020` - `0x007F` Basic Latin (no control characters)
734 `0x00A0` - `0x00FF` Latin-1 Supplement (no control characters)
735 `0x0100` - `0x017F` Latin Extended-A
736 `0x0180` - `0x024F` Latin Extended-B
737 `0x0250` - `0x02AF` IPA Extensions
738 `0x02B0` - `0x02FF` Spacing Modifier Letters
739 `0x0300` - `0x036F` Combining Diacritical Marks
740 `0x0370` - `0x03FF` Greek and Coptic
741 `0x0400` - `0x04FF` Cyrillic
742 `0x0500` - `0x052F` Cyrillic Supplement
743 `0x1D00` - `0x1D7F` Phonetic Extensions
744 `0x1D80` - `0x1DBF` Phonetic Extensions Supplement
745 `0x1DC0` - `0x1DFF` Combining Diacritical Marks Supplement
746 `0x1E00` - `0x1EFF` Latin Extended Additional
747 `0x1F00` - `0x1FFF` Greek Extended
748 `0x2000` - `0x206F` General Punctuation
749 `0x2070` - `0x209F` Superscripts and Subscripts
750 `0x20A0` - `0x20CF` Currency Symbols
751 `0x2150` - `0x218F` Number Forms
752 `0x2460` - `0x24FF` Enclosed Alphanumerics
753 `0x2C60` - `0x2C7F` Latin Extended-C
754 `0x2DE0` - `0x2DFF` Cyrillic Extended-A
755 `0x2E00` - `0x2E7F` Supplemental Punctuation
756 `0xA640` - `0xA69F` Cyrillic Extended-B
757 `0xA720` - `0xA7FF` Latin Extended-D
758 `0xFB00` - `0xFB06` Alphabetical Presentation Forms (Latin Ligatures)
759 `0x1D400` - `0x1D7FF` Mathematical Alphanumeric Symbols
760 `0x1F100` - `0x1F1FF` Enclosed Alphanumeric Supplement
762 If a glyph's character code is not covered by a script range, it is not
763 hinted (or rather, it gets hinted by the 'dummy' auto-hinting module which
764 essentially does nothing). This can be changed by specifying a *fallback
765 script* with [option `--latin-fallback`](#fallback-script).
767 It is planned to extend ttfautohint so that the `GSUB` OpenType table gets
768 analyzed, mapping character codes to all glyph indices which can be reached
769 by switching on or off various OpenType features.
775 ttfautohint touches almost all SFNT tables within a TrueType or OpenType
776 font. Note that only OpenType fonts with TrueType outlines are supported.
777 OpenType fonts with a `CFF` table (this is, with PostScript outlines) won't
780 * `glyf`: All hints in the table are replaced with new ones. If option
781 [`--composites`](#hint-composites) is used, one glyph gets added (namely
782 the '\.ttfautohint' glyph) and all composites get an additional
785 * `cvt`, `prep`, and `fpgm`: These tables get replaced with data
786 necessary for the new hinting bytecode.
788 * `gasp`: Set up to always use grayscale rendering with grid-fitting
789 for standard hinting, and symmetric grid-fitting and symmetric
790 smoothing for horizontal subpixel hinting (ClearType).
792 * `DSIG`: If it exists, it gets replaced with a dummy version.
793 ttfautohint can't digitally sign a font; you have to do that afterwards.
795 * `name`: The 'version' entries are modified to add information about the
796 parameters which have been used for calling ttfautohint. This can be
797 controlled with the [`--no-info`](#add-ttfautohint-info) option.
799 * `GPOS`, `hmtx`, `loca`, `head`, `maxp`, `post`: Updated to fit the
800 additional '\.ttfautohint' glyph, the additional subglyphs in
801 composites, and the new hinting bytecode.
803 * `LTSH`, `hdmx`: Since ttfautohint doesn't do any horizontal hinting,
804 those tables are superfluous and thus removed.
806 * `VDMX`: Removed, since it depends on the original bytecode which
807 ttfautohint removes. A font editor might recompute the necessary data