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 not 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.
355 ### Hint With Components
358 : Hint glyph components separately instead of hinting composite glyphs as
359 a whole. Using this flag reduces the bytecode size enormously, however,
360 it might yield worse results. In the GUI it is similar: If you uncheck
361 the 'Process With Components' box, glyph components are hinted
364 If a font contains composite glyphs and those glyphs are hinted as a
365 whole, ttfautohint cannot reprocess its own output.
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.
376 ### Add ttfautohint Info
379 : Don't add ttfautohint version and command line information to the
380 version string or strings (with name ID\ 5) in the font's `name` table.
381 In the GUI it is similar: If you uncheck the 'Add ttfautohint info' box,
382 information is not added to the `name` table. Except for testing and
383 development purposes it is strongly recommended to not use this option.
385 ### Strong Stem Width and Positioning
387 `--strong-stem-width=`*string*, `-w`\ *string*
388 : ttfautohint offers two different routines to handle (horizontal) stem
389 widths and stem positions: 'smooth' and 'strong'. The former uses
390 discrete values which slightly increase the stem contrast with almost no
391 distortion of the outlines, while the latter snaps both stem widths and
392 stem positions to integer pixel values as much as possible, yielding a
393 crisper appearance at the cost of much more distortion.
395 These two routines are mapped onto three possible rendering targets:
397 - grayscale rendering, with or without optimization for subpixel
398 positioning (e.g. Mac OS\ X)
400 - 'GDI ClearType' rendering: the rasterizer version, as returned by the
401 GETINFO bytecode instruction, is in the range 36\ <= version <\ 38 and
402 ClearType is enabled (e.g. Windows XP)
404 - 'DirectWrite ClearType' rendering: the rasterizer version, as returned
405 by the GETINFO bytecode instruction, is >=\ 38, ClearType is enabled,
406 and subpixel positioning is enabled also (e.g. Internet Explorer\ 9
407 running on Windows\ 7)
409 GDI ClearType uses a mode similar to B/W rendering along the vertical
410 axis, while DW ClearType applies grayscale rendering. Additionally,
411 only DW ClearType provides subpixel positioning along the x\ axis. For
412 what it's worth, the rasterizers version\ 36 and version\ 38 in
413 Microsoft Windows are two completely different rendering engines.
415 The command line option expects *string* to contain up to three letters
416 with possible values '`g`' for grayscale, '`G`' for GDI ClearType, and
417 '`D`' for DW ClearType. If a letter is found in *string*, the strong
418 stem width routine is used for the corresponding rendering target. The
419 default value is '`G`' which means that strong stem width handling is
420 activated for GDI ClearType only. To use smooth stem width handling for
421 all three rendering targets, use the empty string as an argument,
422 usually connoted with '`""`'.
424 In the GUI, simply set the corresponding check box to select the stem
425 width routine for a given rendering target.
427 The following FontForge snapshot images use the font ['Mertz
428 Bold'](http://code.newtypography.co.uk/mertz-sans/) (still under
429 development) from [Vernon Adams].
431 ![The left part shows the glyph 'g' unhinted at 26px, the right part
432 with hints, using the 'smooth' stem algorithm.](img/ff-g-26px.png)
434 ![The same, but this time using the 'strong'
435 algorithm. Note how the stems are aligned to the pixel
436 grid.](img/ff-g-26px-wD.png)
438 ### Font License Restrictions
440 `--ignore-restrictions`, `-i`
441 : By default, fonts which have bit\ 1 set in the 'fsType' field of the
442 `OS/2` table are rejected. If you have a permission of the font's legal
443 owner to modify the font, specify this command line option.
445 If this option is not set, `ttfautohintGUI` shows a dialogue to handle
446 such fonts if necessary.
451 : On the console, print a brief documentation on standard output and exit.
452 This doesn't work with `ttfautohintGUI` on MS Windows.
455 : On the console, print version information on standard output and exit.
456 This doesn't work with `ttfautohintGUI` on MS Windows.
459 : Print *a lot* of debugging information on standard error while
460 processing a font (you should redirect stderr to a file). This
461 doesn't work with `ttfautohintGUI` on MS Windows.
465 Background and Technical Details
466 ================================
468 [Real-Time Grid Fitting of Typographic
469 Outlines](http://www.tug.org/TUGboat/tb24-3/lemberg.pdf) is a scholarly
470 paper which describes FreeType's auto-hinter in some detail. Regarding the
471 described data structures it is slightly out of date, but the algorithm
472 itself hasn't changed.
474 The next few subsections are mainly based on this article, introducing some
475 important concepts. Note that ttfautohint only does hinting along the
476 vertical direction (this is, modifying y\ coordinates).
482 A glyph consists of one or more *contours* (this is, closed curves). For
483 example, glyph 'O' consists of two contours, while glyph 'I' has only one.
485 ![The letter 'O' has two contours, an inner and an outer one, while letter
486 'I' has only an outer contour.](img/o-and-i)
488 A *segment* is a series of consecutive points of a contour (including its
489 Bézier control points) that are approximately aligned along a coordinate
492 ![A serif. Contour and control points are represented by squares and
493 circles, respectively. The bottom 'line' DE is approximately aligned
494 along the horizontal axis, thus it forms a segment of 7\ points. Together
495 with the two other horizontal segments, BC and FG, they form two edges
496 (BC+FG, DE).](img/segment-edge)
498 An *edge* corresponds to a single coordinate value on the main dimension
499 that collects one or more segments (allowing for a small threshold). While
500 finding segments is done on the unscaled outline, finding edges is bound to
501 the device resolution. See [below](#hint-sets) for an example.
503 The analysis to find segments and edges is specific to a script.
509 The auto-hinter analyzes a font in two steps. Right now, everything
510 described below happens for the horizontal axis only, providing vertical
515 This affects the hinting of all glyphs, trying to give them a uniform
518 + Compute standard stem widths and heights of the font. The values
519 are normally taken from the glyph of letter 'o'.
521 + Compute blue zones, see [below](#blue-zones).
523 If stem widths and heights of single glyphs differ by a large value, or
524 if ttfautohint fails to find proper blue zones, hinting becomes quite
525 poor, leading even to severe shape distortions.
529 This is a per-glyph operation.
531 + Find segments and edges.
533 + Link edges together to find stems and serifs. The abovementioned
534 paper gives more details on what exactly constitutes a stem or a
535 serif and how the algorithm works.
541 ![Two blue zones relevant to the glyph 'a'. Vertical point coordinates of
542 *all* glyphs within these zones are aligned.](img/blue-zones)
544 Outlines of certain characters are used to determine *blue zones*. This
545 concept is the same as with Type\ 1 fonts: All glyph points which lie in
546 certain small horizontal zones get aligned vertically.
548 Here a table which shows the characters used by the latin module; the values
549 are hard-coded in the source code.
551 ID Blue zone Characters
552 ---- ----------- ------------
553 1 top of capital letters THEZOCQS
554 2 bottom of capital letters HEZLOCUS
555 3 top of 'small f' like letters fijkdbh
556 4 top of small letters xzroesc
557 5 bottom of small letters xzroesc
558 6 bottom of descenders of small letters pqgjy
560 The 'round' characters (e.g. 'OCQS') from Zones 1, 2, and 5 are also used to
561 control the overshoot handling; to improve rendering at small sizes, zone\ 4
562 gets adjusted to be on the pixel grid; cf. the [`--increase-x-height`
563 option](#x-height-increase-limit).
565 ![This image shows the relevant glyph terms for vertical blue zone
566 positions.](img/glyph-terms)
572 Aligning outlines along the grid lines is called *grid fitting*. It doesn't
573 necessarily mean that the outlines are positioned *exactly* on the grid,
574 however, especially if you want a smooth appearance at different sizes.
575 This is the central routine of the auto-hinter; its actions are highly
576 dependent on the used script. Currently, only support for scripts which
577 work similarly to Latin (i.e. Greek and Cyrillic) is available.
579 * Align edges linked to blue zones.
581 * Fit edges to the pixel grid.
585 * Handle remaining 'strong' points. Such points are not part of an edge
586 but are still important for defining the shape. This roughly
587 corresponds to the `IP` TrueType instruction.
589 * Everything else (the 'weak' points) is handled with an `IUP`
592 The following images illustrate the hinting process, using glyph 'a' from
593 the freely available font ['Ubuntu Book'](http://font.ubuntu.com). The
594 manual hints were added by [Dalton Maag Ltd], the used application to create
595 the hinting debug snapshots was [FontForge].
597 ![Before hinting.](img/a-before-hinting.png)
599 ![After hinting, using manual hints.](img/a-after-hinting.png)
601 ![After hinting, using ttfautohint. Note that the hinting process
602 doesn't change horizontal positions.](img/a-after-autohinting.png)
608 In ttfautohint terminology, a *hint set* is the *optimal* configuration for
609 a given PPEM (pixel per EM) value.
611 In the range given by the `--hinting-range-min` and `--hinting-range-max`
612 options, ttfautohint creates hint sets for every PPEM value. For each
613 glyph, ttfautohint automatically determines if a new set should be emitted
614 for a PPEM value if it finds that it differs from a previous one. For some
615 glyphs it is possible that one set covers, say, the range 8px-1000px, while
616 other glyphs need 10 or more such sets.
618 In the PPEM range below `--hinting-range-min`, ttfautohint always uses just
619 one set, in the PPEM range between `--hinting-range-max` and
620 `--hinting-limit`, it also uses just one set.
622 One of the hinting configuration parameters is the decision which segments
623 form an edge. For example, let us assume that two segments get aligned on a
624 single horizontal edge at 11px, while two edges are used at 12px.
625 This change makes ttfautohint emit a new hint set to accomodate this
628 The next images illustrate this, using a Cyrillic letter (glyph 'afii10108')
629 from the 'Ubuntu book' font, processed with ttfautohint.
631 ![Before hinting, size 11px.](img/afii10108-11px-before-hinting.png)
633 ![After hinting, size 11px. Segments 43-27-28 and 14-15 are aligned on a
634 single edge, as are segments 26-0-1 and
635 20-21.](img/afii10108-11px-after-hinting.png)
637 ![Before hinting, size 12px.](img/afii10108-12px-before-hinting.png)
639 ![After hinting, size 12px. The segments are not aligned. While
640 segments 43-27-28 and 20-21 now have almost the same horizontal position,
641 they don't form an edge because the outlines passing through the segments
642 point into different directions.](img/afii10108-12px-after-hinting.png)
644 Obviously, the more hint sets get emitted, the larger the bytecode
645 ttfautohint adds to the output font. To find a good value\ *n* for
646 `--hinting-range-max`, some experimentation is necessary since *n* depends
647 on the glyph shapes in the input font. If the value is too low, the hint
648 set created for the PPEM value\ *n* (this hint set gets used for all larger
649 PPEM values) might distort the outlines too much in the PPEM range given
650 by\ *n* and the value set by `--hinting-limit` (at which hinting gets
651 switched off). If the value is too high, the font size increases due to
652 more hint sets without any noticeable hinting effects.
654 Similar arguments hold for `--hinting-range-min` except that there is no
655 lower limit at which hinting is switched off.
657 An example. Let's assume that we have a hinting range 10\ <= ppem <=\ 100,
658 and the hinting limit is set to 250. For a given glyph, ttfautohint finds
659 out that four hint sets must be computed to exactly cover thes hinting
660 range: 10-15, 16-40, 41-80, and 81-100. For ppem values below 10ppem, the
661 hint set covering 10-15ppem is used, for ppem values larger than 100 the
662 hint set covering 81-100ppem is used. For ppem values larger than 250, no
663 hinting gets applied.
666 The '\.ttfautohint' Glyph
667 -------------------------
669 [The behaviour described in this section does not apply if [option
670 `--components`](#hint-with-components) is used.]
672 By default, ttfautohint doesn't hint subglyphs of composite glyphs
673 separately. Instead, it hints the whole glyph, this is, composites get
674 recursively expanded internally so that they form simple glyphs, then hints
675 are applied -- this is the normal working mode of FreeType's auto-hinter.
677 One problem, however, must be solved: Hinting for subglyphs (which usually
678 are used as normal glyphs also) must be deactivated so that nothing but the
679 final bytecode of the composite gets executed.
681 The trick used by ttfautohint is to prepend a composite element called
682 '\.ttfautohint', a dummy glyph with a single point, and which has a single
683 job: Its bytecode increases a variable (to be more precise, it is a CVT
684 register called `cvtl_is_subglyph` in the source code), indicating that we
685 are within a composite glyph. The final bytecode of the composite glyph
686 eventually decrements this variable again.
688 As an example, let's consider composite glyph 'Agrave' ('À') which has the
689 subglyph 'A' as the base and 'grave' as its accent. After processing with
690 ttfautohint it consists of three subglyphs: '\.ttfautohint', 'A', and
691 'grave' (in this order).
694 ------------- --------
695 .ttfautohint increase `cvtl_is_subglyph` (now: 1)
696 A do nothing because `cvtl_is_subglyph` > 0
697 grave do nothing because `cvtl_is_subglyph` > 0
698 Agrave decrease `cvtl_is_subglyph` (now: 0)\
699 apply hints because `cvtl_is_subglyph` == 0
701 Some technical details (which you might skip): All glyph point indices get
702 adjusted since each '\.ttfautohint' subglyph shifts all following indices by
703 one. This must be done for both the bytecode and one subformat of
704 OpenType's `GPOS` anchor tables.
706 While this approach works fine on all tested platforms, there is one single
707 drawback: Direct rendering of the '\.ttfautohint' subglyph (this is,
708 rendering as a stand-alone glyph) disables proper hinting of all glyphs in
709 the font! Under normal circumstances this never happens because
710 '\.ttfautohint' doesn't have an entry in the font's `cmap` table. (However,
711 some test and demo programs like FreeType's `ftview` application or other
712 glyph viewers which are able to bypass the `cmap` table might be affected.)
717 ttfautohint checks which auto-hinting module should be used to hint a
718 specific glyph. To do so, it checks a glyph's Unicode character code
719 whether it belongs to a given script. Currently, only FreeType's 'latin'
720 autohinting module is implemented, but more are expected to come. Here is
721 the hardcoded list of character ranges which are hinted by this 'latin'
722 module. As you can see, this also covers some non-latin scripts (in the
723 Unicode sense) which have similar typographical properties.
725 Character range Description
726 --------------------- -------------
727 `0x0020` - `0x007F` Basic Latin (no control characters)
728 `0x00A0` - `0x00FF` Latin-1 Supplement (no control characters)
729 `0x0100` - `0x017F` Latin Extended-A
730 `0x0180` - `0x024F` Latin Extended-B
731 `0x0250` - `0x02AF` IPA Extensions
732 `0x02B0` - `0x02FF` Spacing Modifier Letters
733 `0x0300` - `0x036F` Combining Diacritical Marks
734 `0x0370` - `0x03FF` Greek and Coptic
735 `0x0400` - `0x04FF` Cyrillic
736 `0x0500` - `0x052F` Cyrillic Supplement
737 `0x1D00` - `0x1D7F` Phonetic Extensions
738 `0x1D80` - `0x1DBF` Phonetic Extensions Supplement
739 `0x1DC0` - `0x1DFF` Combining Diacritical Marks Supplement
740 `0x1E00` - `0x1EFF` Latin Extended Additional
741 `0x1F00` - `0x1FFF` Greek Extended
742 `0x2000` - `0x206F` General Punctuation
743 `0x2070` - `0x209F` Superscripts and Subscripts
744 `0x20A0` - `0x20CF` Currency Symbols
745 `0x2150` - `0x218F` Number Forms
746 `0x2460` - `0x24FF` Enclosed Alphanumerics
747 `0x2C60` - `0x2C7F` Latin Extended-C
748 `0x2DE0` - `0x2DFF` Cyrillic Extended-A
749 `0x2E00` - `0x2E7F` Supplemental Punctuation
750 `0xA640` - `0xA69F` Cyrillic Extended-B
751 `0xA720` - `0xA7FF` Latin Extended-D
752 `0xFB00` - `0xFB06` Alphabetical Presentation Forms (Latin Ligatures)
753 `0x1D400` - `0x1D7FF` Mathematical Alphanumeric Symbols
754 `0x1F100` - `0x1F1FF` Enclosed Alphanumeric Supplement
756 If a glyph's character code is not covered by a script range, it is not
757 hinted (or rather, it gets hinted by the 'dummy' auto-hinting module which
758 essentially does nothing). This can be changed by specifying a *fallback
759 script* with [option `--latin-fallback`](#fallback-script).
761 It is planned to extend ttfautohint so that the `GSUB` OpenType table gets
762 analyzed, mapping character codes to all glyph indices which can be reached
763 by switching on or off various OpenType features.
769 ttfautohint touches almost all SFNT tables within a TrueType or OpenType
770 font. Note that only OpenType fonts with TrueType outlines are supported.
771 OpenType fonts with a `CFF` table (this is, with PostScript outlines) won't
774 * `glyf`: One glyph gets added (namely the '\.ttfautohint' glyph); all
775 composites get an additional component; all hints in the table are
776 replaced with new ones.
778 * `cvt`, `prep`, and `fpgm`: These tables get replaced with data
779 necessary for the new hinting bytecode.
781 * `gasp`: Set up to always use grayscale rendering with grid-fitting
782 for standard hinting, and symmetric grid-fitting and symmetric
783 smoothing for horizontal subpixel hinting (ClearType).
785 * `DSIG`: If it exists, it gets replaced with a dummy version.
786 ttfautohint can't digitally sign a font; you have to do that afterwards.
788 * `name`: The 'version' entries are modified to add information about the
789 parameters which have been used for calling ttfautohint. This can be
790 controlled with the [`--no-info`](#ttfautohint-info) option.
792 * `GPOS`, `hmtx`, `loca`, `head`, `maxp`, `post`: Updated to fit the
793 additional '\.ttfautohint' glyph, the additional subglyphs in
794 composites, and the new hinting bytecode.
796 * `LTSH`, `hdmx`: Since ttfautohint doesn't do any horizontal hinting,
797 those tables are superfluous and thus removed.
799 * `VDMX`: Removed, since it depends on the original bytecode which
800 ttfautohint removes. A font editor might recompute the necessary data