6 Copyright (C) 2011-2014 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 that 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 that 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 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 that 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 that 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 latn 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 latn > 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 `--default-script=`*s*, `-D-`\ *s*
234 : Set default script to tag *s*, which is a string consisting of four
235 lowercase characters like `latn` or `dflt`. It is needed to specify the
236 OpenType default script: After applying all features that are handled
237 specially (like small caps or superscript), ttfautohint uses this value
238 for the remaining features. The default value is `latn`.
242 `--fallback-script=`*s*, `-f`\ *s*
243 : Set fallback script to tag *s*, which is a string consisting of four
244 characters like `latn` or `dflt`. It gets used for for all glyphs that
245 can't be assigned to a script automatically. See [below](#scripts) for
250 `--hinting-limit=`*n*, `-G`\ *n*
251 : The *hinting limit* is the PPEM value (in pixels) where hinting gets
252 switched off (using the `INSTCTRL` bytecode instruction); it has zero
253 impact on the file size. The default value for *n* is 200, which means
254 that the font is not hinted for PPEM values larger than 200.
256 Note that hinting in the range 'hinting-range-max' up to 'hinting-limit'
257 uses the hinting configuration for 'hinting-range-max'.
259 To omit a hinting limit, use `--hinting-limit=0` (or check the 'No
260 Hinting Limit' box in the GUI). Since this will cause internal math
261 overflow in the rasterizer for large pixel values (>\ 1500px approx.) it
262 is strongly recommended to not use this except for testing purposes.
264 ### x Height Increase Limit
266 `--increase-x-height=`*n*, `-x`\ *n*
267 : Normally, ttfautohint rounds the x\ height to the pixel grid, with a
268 slight preference for rounding up. If this flag is set, values in the
269 range 6\ PPEM to *n*\ PPEM are much more often rounded up. The default
270 value for *n* is 14. Use this flag to increase the legibility of small
271 sizes if necessary; you might get weird rendering results otherwise for
272 glyphs like 'a' or 'e', depending on the font design.
274 To switch off this feature, use `--increase-x-height=0` (or check the
275 'No x\ Height Increase' box in the GUI). To switch off rounding the
276 x\ height to the pixel grid in general, either partially or completely,
277 see ['x Height Snapping Exceptions'](#x-height-snapping-exceptions).
279 The following images again use the font 'Mertz Bold'.
281 ![At 17px, without option `-x` and '`-w ""`', the hole in glyph 'e'
282 looks very grey in the FontForge snapshot, and the GDI ClearType
283 rendering (which is the default on older Windows versions) fills it
284 completely with black because it uses B/W rendering along the y\ axis.
285 FreeType's 'light' autohint mode (which corresponds to ttfautohint's
286 'smooth' stem width algorithm) intentionally aligns horizontal lines
287 to non-integer (but still discrete) values to avoid large glyph shape
288 distortions.](img/e-17px-x14.png)
290 ![The same, this time with option `-x 17` (and
291 '`-w ""`').](img/e-17px-x17.png)
293 ### x Height Snapping Exceptions
295 `--x-height-snapping-exceptions=`*string*, `-X`\ *string*
296 : A list of comma separated PPEM values or value ranges at which no
297 x-height snapping shall be applied. A value range has the form
298 *value1*`-`*value2*, meaning *value1*\ <= PPEM <=\ *value2*. *value1*
299 or *value2* (or both) can be missing; a missing value is replaced by the
300 beginning or end of the whole interval of valid PPEM values,
301 respectively (6\ to 32767). Whitespace is not significant; superfluous
302 commas are ignored, and ranges must be specified in increasing order.
303 For example, the string `"7-9, 11, 13-"` means the values 7, 8, 9, 11,
304 13, 14, 15, etc. Consequently, if the supplied argument is `"-"`, no
305 x-height snapping takes place at all. The default is the empty string
306 (`""`), meaning no snapping exceptions.
308 Normally, x-height snapping means a slight increase in the overall
309 vertical glyph size so that the height of lowercase glyphs gets aligned
310 to the pixel grid (this is a global feature, affecting *all* glyphs of a
311 font). However, having larger vertical glyph sizes is not always
312 desired, especially if it is not possible to adjust the `usWinAscent`
313 and `usWinDescent` values from the font's `OS/2` table so that they are
314 not too tight. See ['Windows Compatibility'](#windows-compatibility)
317 ### Windows Compatibility
319 `--windows-compatibility`, `-W`
320 : This option makes ttfautohint add two artificial blue zones, positioned
321 at the `usWinAscent` and `usWinDescent` values (from the font's `OS/2`
322 table). The idea is to help ttfautohint so that the hinted glyphs stay
323 within this horizontal stripe since Windows clips everything falling
326 There is a general problem with tight values for `usWinAscent` and
327 `usWinDescent`; a good description is given in the [Vertical Metrics
328 How-To](http://typophile.com/node/13081). Additionally, there is a
329 special problem with tight values if used in combination with
330 ttfautohint because the auto-hinter tends to slightly increase the
331 vertical glyph dimensions at smaller sizes to improve legibility. This
332 enlargement can make the heights and depths of glyphs exceed the range
333 given by `usWinAscent` and `usWinDescent`.
335 If ttfautohint is part of the font creation tool chain, and the font
336 designer can adjust those two values, a better solution instead of using
337 option `-W` is to reserve some vertical space for 'padding': For the
338 auto-hinter, the difference between a top or bottom outline point before
339 and after hinting is less than 1px, thus a vertical padding of 2px is
340 sufficient. Assuming a minimum hinting size of 6ppem, adding two pixels
341 gives an increase factor of 8÷6 = 1.33. This is near to the default
342 baseline-to-baseline distance used by TeX and other sophisticated text
343 processing applications, namely 1.2×designsize, which gives satisfying
344 results in most cases. It is also near to the factor 1.25 recommended
345 in the abovementioned how-to. For example, if the vertical extension of
346 the largest glyph is 2000 units (assuming that it approximately
347 represents the designsize), the sum of `usWinAscent` and `usWinDescent`
348 could be 1.25×2000 = 2500.
350 In case ttfautohint is used as an auto-hinting tool for fonts that can
351 be no longer modified to change the metrics, option `-W` in combination
352 with '`-X "-"`' to suppress any vertical enlargement should prevent
357 `--pre-hinting`, `-p`
358 : *Pre-hinting* means that a font's original bytecode is applied to all
359 glyphs before it is replaced with bytecode created by ttfautohint.
360 This makes only sense if your font already has some hints in it that
361 modify the shape even at EM size (normally 2048px); for example, some
362 CJK fonts need this because the bytecode is used to scale and shift
363 subglyphs. For most fonts, however, this is not the case.
368 : By default, the components of a composite glyph get hinted separately.
369 If this flag is set, the composite glyph itself gets hinted (and the
370 hints of the components are ignored). Using this flag increases the
371 bytecode size a lot, however, it might yield better hinting results.
373 If this option is used (and a font actually contains composite glyphs),
374 ttfautohint currently cannot reprocess its own output for technical
375 reasons, see [below](#the-.ttfautohint-glyph).
380 : Apply default values for standard (horizontal) stem width and height
381 instead of deriving them from a script-specific, hard-coded default
382 character (which usually resembles the shape of a lowercase 'o'). Use
383 this option (usually in combination with option `--fallback-script`) to
384 hint symbol or dingbat fonts or math glyphs, for example, that lack a
385 default character, at the expense of possibly poor hinting results at
391 : Strip off all hints without generating new hints. Consequently, all
392 other hinting options are ignored. This option is intended for testing
395 ### Add ttfautohint Info
398 : Don't add ttfautohint version and command line information to the
399 version string or strings (with name ID\ 5) in the font's `name` table.
400 In the GUI it is similar: If you uncheck the 'Add ttfautohint info' box,
401 information is not added to the `name` table. Except for testing and
402 development purposes it is strongly recommended to not use this option.
404 ### Strong Stem Width and Positioning
406 `--strong-stem-width=`*string*, `-w`\ *string*
407 : ttfautohint offers two different routines to handle (horizontal) stem
408 widths and stem positions: 'smooth' and 'strong'. The former uses
409 discrete values that slightly increase the stem contrast with almost no
410 distortion of the outlines, while the latter snaps both stem widths and
411 stem positions to integer pixel values as much as possible, yielding a
412 crisper appearance at the cost of much more distortion.
414 These two routines are mapped onto three possible rendering targets:
416 - grayscale rendering, with or without optimization for subpixel
417 positioning (e.g. Mac OS\ X)
419 - 'GDI ClearType' rendering: the rasterizer version, as returned by the
420 GETINFO bytecode instruction, is in the range 36\ <= version <\ 38 and
421 ClearType is enabled (e.g. Windows XP)
423 - 'DirectWrite ClearType' rendering: the rasterizer version, as returned
424 by the GETINFO bytecode instruction, is >=\ 38, ClearType is enabled,
425 and subpixel positioning is enabled also (e.g. Internet Explorer\ 9
426 running on Windows\ 7)
428 GDI ClearType uses a mode similar to B/W rendering along the vertical
429 axis, while DW ClearType applies grayscale rendering. Additionally,
430 only DW ClearType provides subpixel positioning along the x\ axis. For
431 what it's worth, the rasterizers version\ 36 and version\ 38 in
432 Microsoft Windows are two completely different rendering engines.
434 The command line option expects *string* to contain up to three letters
435 with possible values '`g`' for grayscale, '`G`' for GDI ClearType, and
436 '`D`' for DW ClearType. If a letter is found in *string*, the strong
437 stem width routine is used for the corresponding rendering target (and
438 smooth stem width handling otherwise). The default value is '`G`', which
439 means that strong stem width handling is activated for GDI ClearType
440 only. To use smooth stem width handling for all three rendering
441 targets, use the empty string as an argument, usually connoted with
444 In the GUI, simply set the corresponding check box to select the strong
445 width routine for a given rendering target. If you unset the check box,
446 the smooth width routine gets used.
448 The following FontForge snapshot images use the font ['Mertz
449 Bold'](http://code.newtypography.co.uk/mertz-sans/) (still under
450 development) from [Vernon Adams].
452 ![The left part shows the glyph 'g' unhinted at 26px, the right part
453 with hints, using the 'smooth' stem algorithm.](img/ff-g-26px.png)
455 ![The same, but this time using the 'strong'
456 algorithm. Note how the stems are aligned to the pixel
457 grid.](img/ff-g-26px-wD.png)
459 ### Font License Restrictions
461 `--ignore-restrictions`, `-i`
462 : By default, fonts that have bit\ 1 set in the 'fsType' field of the
463 `OS/2` table are rejected. If you have a permission of the font's legal
464 owner to modify the font, specify this command line option.
466 If this option is not set, `ttfautohintGUI` shows a dialogue to handle
467 such fonts if necessary.
472 : On the console, print a brief documentation on standard output and exit.
473 This doesn't work with `ttfautohintGUI` on MS Windows.
476 : On the console, print version information on standard output and exit.
477 This doesn't work with `ttfautohintGUI` on MS Windows.
480 : Print *a lot* of debugging information on standard error while
481 processing a font (you should redirect stderr to a file). This
482 doesn't work with `ttfautohintGUI` on MS Windows.
486 Background and Technical Details
487 ================================
489 [Real-Time Grid Fitting of Typographic
490 Outlines](http://www.tug.org/TUGboat/tb24-3/lemberg.pdf) is a scholarly
491 paper that describes FreeType's auto-hinter in some detail. Regarding the
492 described data structures it is slightly out of date, but the algorithm
493 itself hasn't changed.
495 The next few subsections are mainly based on this article, introducing some
496 important concepts. Note that ttfautohint only does hinting along the
497 vertical direction (this is, modifying y\ coordinates).
503 A glyph consists of one or more *contours* (this is, closed curves). For
504 example, glyph 'O' consists of two contours, while glyph 'I' has only one.
506 ![The letter 'O' has two contours, an inner and an outer one, while letter
507 'I' has only an outer contour.](img/o-and-i)
509 A *segment* is a series of consecutive points of a contour (including its
510 Bézier control points) that are approximately aligned along a coordinate
513 ![A serif. Contour and control points are represented by squares and
514 circles, respectively. The bottom 'line' DE is approximately aligned
515 along the horizontal axis, thus it forms a segment of 7\ points. Together
516 with the two other horizontal segments, BC and FG, they form two edges
517 (BC+FG, DE).](img/segment-edge)
519 An *edge* corresponds to a single coordinate value on the main dimension
520 that collects one or more segments (allowing for a small threshold). While
521 finding segments is done on the unscaled outline, finding edges is bound to
522 the device resolution. See [below](#hint-sets) for an example.
524 The analysis to find segments and edges is specific to a script.
530 The auto-hinter analyzes a font in two steps. Right now, everything
531 described below happens for the horizontal axis only, providing vertical
536 This affects the hinting of all glyphs, trying to give them a uniform
539 + Compute standard stem widths and heights of the font. The values
540 are normally taken from a glyph that resembles letter 'o'.
542 + Compute blue zones, see [below](#blue-zones).
544 If stem widths and heights of single glyphs differ by a large value, or
545 if ttfautohint fails to find proper blue zones, hinting becomes quite
546 poor, leading even to severe shape distortions.
549 Table: script-specific standard characters of the 'latin' module
551 script standard character
552 -------- --------------------
553 `cyrl` 'о', U+043E, CYRILLIC SMALL LETTER O
554 `grek` 'ο', U+03BF, GREEK SMALL LETTER OMICRON
555 `hebr` 'ם', U+05DD, HEBREW LETTER FINAL MEM
556 `latn` 'o', U+006F, LATIN SMALL LETTER O
561 This is a per-glyph operation.
563 + Find segments and edges.
565 + Link edges together to find stems and serifs. The abovementioned
566 paper gives more details on what exactly constitutes a stem or a
567 serif and how the algorithm works.
573 ![Two blue zones relevant to the glyph 'a'. Vertical point coordinates of
574 *all* glyphs within these zones are aligned, provided the blue zone is
575 active (this is, its vertical size is smaller than
576 3/4\ pixels).](img/blue-zones)
578 Outlines of certain characters are used to determine *blue zones*. This
579 concept is the same as with Type\ 1 fonts: All glyph points that lie in
580 certain small horizontal zones get aligned vertically.
582 Here a series of tables that show the blue zone characters of the latin
583 module's available scripts; the values are hard-coded in the source code.
586 Table: `latn` blue zones
588 ID Blue zone Characters
589 ---- ----------- ------------
590 1 top of capital letters THEZOCQS
591 2 bottom of capital letters HEZLOCUS
592 3 top of 'small f' like letters fijkdbh
593 4 top of small letters xzroesc
594 5 bottom of small letters xzroesc
595 6 bottom of descenders of small letters pqgjy
598 The 'round' characters (e.g. 'OCQS') from Zones 1, 2, and 5 are also used to
599 control the overshoot handling; to improve rendering at small sizes, zone\ 4
600 gets adjusted to be on the pixel grid; cf. the [`--increase-x-height`
601 option](#x-height-increase-limit).
604 Table: `grek` blue zones
606 ID Blue zone Characters
607 ---- ----------- ------------
608 1 top of capital letters ΓΒΕΖΘΟΩ
609 2 bottom of capital letters ΒΔΖΞΘΟ
610 3 top of 'small beta' like letters βθδζλξ
611 4 top of small letters αειοπστω
612 5 bottom of small letters αειοπστω
613 6 bottom of descenders of small letters βγημρφχψ
616 Table: `cyrl` blue zones
618 ID Blue zone Characters
619 ---- ----------- ------------
620 1 top of capital letters БВЕПЗОСЭ
621 2 bottom of capital letters БВЕШЗОСЭ
622 3 top of small letters хпншезос
623 4 bottom of small letters хпншезос
624 5 bottom of descenders of small letters руф
627 Table: `hebr` blue zones
629 ID Blue zone Characters
630 ---- ----------- ------------
631 1 top of letters בדהחךכםס
632 2 bottom of letters בטכםסצ
633 3 bottom of descenders of letters קךןףץ
636 ![This image shows the relevant glyph terms for vertical blue zone
637 positions.](img/glyph-terms)
643 Aligning outlines along the grid lines is called *grid fitting*. It doesn't
644 necessarily mean that the outlines are positioned *exactly* on the grid,
645 however, especially if you want a smooth appearance at different sizes.
646 This is the central routine of the auto-hinter; its actions are highly
647 dependent on the used script. Currently, only support for scripts that work
648 similarly to Latin (e.g. Greek or Cyrillic) is available.
650 * Align edges linked to blue zones.
652 * Fit edges to the pixel grid.
656 * Handle remaining 'strong' points. Such points are not part of an edge
657 but are still important for defining the shape. This roughly
658 corresponds to the `IP` TrueType instruction.
660 * Everything else (the 'weak' points) is handled with an `IUP`
663 The following images illustrate the hinting process, using glyph 'a' from
664 the freely available font ['Ubuntu Book'](http://font.ubuntu.com). The
665 manual hints were added by [Dalton Maag Ltd], the used application to create
666 the hinting debug snapshots was [FontForge].
668 ![Before hinting.](img/a-before-hinting.png)
670 ![After hinting, using manual hints.](img/a-after-hinting.png)
672 ![After hinting, using ttfautohint. Note that the hinting process
673 doesn't change horizontal positions.](img/a-after-autohinting.png)
679 In ttfautohint terminology, a *hint set* is the *optimal* configuration for
680 a given PPEM (pixel per EM) value.
682 In the range given by the `--hinting-range-min` and `--hinting-range-max`
683 options, ttfautohint creates hint sets for every PPEM value. For each
684 glyph, ttfautohint automatically determines if a new set should be emitted
685 for a PPEM value if it finds that it differs from a previous one. For some
686 glyphs it is possible that one set covers, say, the range 8px-1000px, while
687 other glyphs need 10 or more such sets.
689 In the PPEM range below `--hinting-range-min`, ttfautohint always uses just
690 one set, in the PPEM range between `--hinting-range-max` and
691 `--hinting-limit`, it also uses just one set.
693 One of the hinting configuration parameters is the decision which segments
694 form an edge. For example, let us assume that two segments get aligned on a
695 single horizontal edge at 11px, while two edges are used at 12px.
696 This change makes ttfautohint emit a new hint set to accomodate this
699 The next images illustrate this, using a Cyrillic letter (glyph 'afii10108')
700 from the 'Ubuntu book' font, processed with ttfautohint.
702 ![Before hinting, size 11px.](img/afii10108-11px-before-hinting.png)
704 ![After hinting, size 11px. Segments 43-27-28 and 14-15 are aligned on a
705 single edge, as are segments 26-0-1 and
706 20-21.](img/afii10108-11px-after-hinting.png)
708 ![Before hinting, size 12px.](img/afii10108-12px-before-hinting.png)
710 ![After hinting, size 12px. The segments are not aligned. While
711 segments 43-27-28 and 20-21 now have almost the same horizontal position,
712 they don't form an edge because the outlines passing through the segments
713 point into different directions.](img/afii10108-12px-after-hinting.png)
715 Obviously, the more hint sets get emitted, the larger the bytecode
716 ttfautohint adds to the output font. To find a good value\ *n* for
717 `--hinting-range-max`, some experimentation is necessary since *n* depends
718 on the glyph shapes in the input font. If the value is too low, the hint
719 set created for the PPEM value\ *n* (this hint set gets used for all larger
720 PPEM values) might distort the outlines too much in the PPEM range given
721 by\ *n* and the value set by `--hinting-limit` (at which hinting gets
722 switched off). If the value is too high, the font size increases due to
723 more hint sets without any noticeable hinting effects.
725 Similar arguments hold for `--hinting-range-min` except that there is no
726 lower limit at which hinting is switched off.
728 An example. Let's assume that we have a hinting range 10\ <= ppem <=\ 100,
729 and the hinting limit is set to 250. For a given glyph, ttfautohint finds
730 out that four hint sets must be computed to exactly cover this hinting
731 range: 10-15, 16-40, 41-80, and 81-100. For ppem values below 10ppem, the
732 hint set covering 10-15ppem is used, for ppem values larger than 100 the
733 hint set covering 81-100ppem is used. For ppem values larger than 250, no
734 hinting gets applied.
737 The '\.ttfautohint' Glyph
738 -------------------------
740 If [option `--composites`](#hint-composites) is used, ttfautohint doesn't
741 hint subglyphs of composite glyphs separately. Instead, it hints the whole
742 glyph, this is, composites get recursively expanded internally so that they
743 form simple glyphs, then hints are applied -- this is the normal working
744 mode of FreeType's auto-hinter.
746 One problem, however, must be solved: Hinting for subglyphs (which usually
747 are used as normal glyphs also) must be deactivated so that nothing but the
748 final bytecode of the composite gets executed.
750 The trick used by ttfautohint is to prepend a composite element called
751 '\.ttfautohint', a dummy glyph with a single point, and which has a single
752 job: Its bytecode increases a variable (to be more precise, it is a CVT
753 register called `cvtl_is_subglyph` in the source code), indicating that we
754 are within a composite glyph. The final bytecode of the composite glyph
755 eventually decrements this variable again.
757 As an example, let's consider composite glyph 'Agrave' ('À'), which has the
758 subglyph 'A' as the base and 'grave' as its accent. After processing with
759 ttfautohint it consists of three components: '\.ttfautohint', 'A', and
760 'grave' (in this order).
763 ------------- --------
764 .ttfautohint increase `cvtl_is_subglyph` (now: 1)
765 A do nothing because `cvtl_is_subglyph` > 0
766 grave do nothing because `cvtl_is_subglyph` > 0
767 Agrave decrease `cvtl_is_subglyph` (now: 0)\
768 apply hints because `cvtl_is_subglyph` == 0
770 Some technical details (which you might skip): All glyph point indices get
771 adjusted since each '\.ttfautohint' subglyph shifts all following indices by
772 one. This must be done for both the bytecode and one subformat of
773 OpenType's `GPOS` anchor tables.
775 While this approach works fine on all tested platforms, there is one single
776 drawback: Direct rendering of the '\.ttfautohint' subglyph (this is,
777 rendering as a stand-alone glyph) disables proper hinting of all glyphs in
778 the font! Under normal circumstances this never happens because
779 '\.ttfautohint' doesn't have an entry in the font's `cmap` table. (However,
780 some test and demo programs like FreeType's `ftview` application or other
781 glyph viewers that are able to bypass the `cmap` table might be affected.)
787 ttfautohint checks which auto-hinting module should be used to hint a
788 specific glyph. To do so, it checks a glyph's Unicode character code
789 whether it belongs to a given script. Currently, only FreeType's 'latin'
790 autohinting module is implemented, but more are expected to come. Note,
791 however, that this module is capable to hint other scripts too.
793 Here is the hardcoded list of character ranges that are hinted by this
794 'latin' module. As you can see, this also covers some non-latin scripts (in
795 the Unicode sense) that have similar typographical properties.
797 In ttfautohint, scripts are identified by four-character tags. The value
798 `dflt` indicates 'no script', which gets hinted by 'dummy' auto-hinting
802 Table: `latn` character ranges
804 Character range Description
805 --------------------- -------------
806 `0x0020` - `0x007F` Basic Latin (no control characters)
807 `0x00A0` - `0x00FF` Latin-1 Supplement (no control characters)
808 `0x0100` - `0x017F` Latin Extended-A
809 `0x0180` - `0x024F` Latin Extended-B
810 `0x0250` - `0x02AF` IPA Extensions
811 `0x02B0` - `0x02FF` Spacing Modifier Letters
812 `0x0300` - `0x036F` Combining Diacritical Marks
813 `0x1D00` - `0x1D7F` Phonetic Extensions
814 `0x1D80` - `0x1DBF` Phonetic Extensions Supplement
815 `0x1DC0` - `0x1DFF` Combining Diacritical Marks Supplement
816 `0x1E00` - `0x1EFF` Latin Extended Additional
817 `0x2000` - `0x206F` General Punctuation
818 `0x2070` - `0x209F` Superscripts and Subscripts
819 `0x20A0` - `0x20CF` Currency Symbols
820 `0x2150` - `0x218F` Number Forms
821 `0x2460` - `0x24FF` Enclosed Alphanumerics
822 `0x2C60` - `0x2C7F` Latin Extended-C
823 `0x2E00` - `0x2E7F` Supplemental Punctuation
824 `0xA720` - `0xA7FF` Latin Extended-D
825 `0xFB00` - `0xFB06` Alphabetical Presentation Forms (Latin Ligatures)
826 `0x1D400` - `0x1D7FF` Mathematical Alphanumeric Symbols
827 `0x1F100` - `0x1F1FF` Enclosed Alphanumeric Supplement
830 Table: `grek` character ranges
832 Character range Description
833 --------------------- -------------
834 `0x0370` - `0x03FF` Greek and Coptic
835 `0x1F00` - `0x1FFF` Greek Extended
838 Table: `cyrl` character ranges
840 Character range Description
841 --------------------- -------------
842 `0x0400` - `0x04FF` Cyrillic
843 `0x0500` - `0x052F` Cyrillic Supplement
844 `0x2DE0` - `0x2DFF` Cyrillic Extended-A
845 `0xA640` - `0xA69F` Cyrillic Extended-B
848 Table: `hebr` character ranges
850 Character range Description
851 --------------------- -------------
852 `0x0590` - `0x05FF` Hebrew
853 `0xFB1D` - `0xFB4F` Alphabetic Presentation Forms (Hebrew)
856 If a glyph's character code is not covered by a script range, it is not
857 hinted (or rather, it gets hinted by the 'dummy' auto-hinting module that
858 essentially does nothing). This can be changed by specifying a *fallback
859 script* with [option `--fallback-script`](#fallback-script).
861 It is planned to extend ttfautohint so that the `GSUB` OpenType table gets
862 analyzed, mapping character codes to all glyph indices that can be reached
863 by switching on or off various OpenType features.
869 ttfautohint touches almost all SFNT tables within a TrueType or OpenType
870 font. Note that only OpenType fonts with TrueType outlines are supported.
871 OpenType fonts with a `CFF` table (this is, with PostScript outlines) won't
874 * `glyf`: All hints in the table are replaced with new ones. If option
875 [`--composites`](#hint-composites) is used, one glyph gets added (namely
876 the '\.ttfautohint' glyph) and all composites get an additional
879 * `cvt`, `prep`, and `fpgm`: These tables get replaced with data
880 necessary for the new hinting bytecode.
882 * `gasp`: Set up to always use grayscale rendering with grid-fitting
883 for standard hinting, and symmetric grid-fitting and symmetric
884 smoothing for horizontal subpixel hinting (ClearType).
886 * `DSIG`: If it exists, it gets replaced with a dummy version.
887 ttfautohint can't digitally sign a font; you have to do that afterwards.
889 * `name`: The 'version' entries are modified to add information about the
890 parameters that have been used for calling ttfautohint. This can be
891 controlled with the [`--no-info`](#add-ttfautohint-info) option.
893 * `GPOS`, `hmtx`, `loca`, `head`, `maxp`, `post`: Updated to fit the
894 additional '\.ttfautohint' glyph, the additional subglyphs in
895 composites, and the new hinting bytecode.
897 * `LTSH`, `hdmx`: Since ttfautohint doesn't do any horizontal hinting,
898 those tables are superfluous and thus removed.
900 * `VDMX`: Removed, since it depends on the original bytecode, which
901 ttfautohint removes. A font editor might recompute the necessary data