6 Copyright (C) 2011-2015 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 auto-hinting module. The idea is to provide the excellent
26 quality of the auto-hinter 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 program and an application with a Graphics User Interface (GUI),
37 What exactly are hints?
38 -----------------------
40 To cite [Wikipedia](http://en.wikipedia.org/wiki/Font_hinting):
42 > **Font hinting** (also known as **instructing**) is the use of
43 > mathematical instructions to adjust the display of an outline font so that
44 > it lines up with a rasterized grid. At low screen resolutions, hinting is
45 > critical for producing a clear, legible text. It can be accompanied by
46 > antialiasing and (on liquid crystal displays) subpixel rendering for
49 and Apple's [TrueType Reference
50 Manual](https://developer.apple.com/fonts/TTRefMan/RM03/Chap3.html#features):
52 > For optimal results, a font instructor should follow these guidelines:
54 > - At small sizes, chance effects should not be allowed to magnify small
55 > differences in the original outline design of a glyph.
57 > - At large sizes, the subtlety of the original design should emerge.
60 In general, there are three possible ways to hint a glyph.
62 1. The font contains hints (in the original sense of this word) to guide
63 the rasterizer, telling it which shapes of the glyphs need special
64 consideration. The hinting logic is partly in the font and partly in
65 the rasterizer. More sophisticated rasterizers are able to produce
66 better rendering results.
68 This is how Type\ 1 and CFF hints work.
70 2. The font contains exact instructions (also called *bytecode*) on how to
71 move the points of its outlines, depending on the resolution of the
72 output device, and which intentionally distort the (outline) shape to
73 produce a well-rasterized result. The hinting logic is in the font;
74 ideally, all rasterizers simply process these instructions to get the
75 same result on all platforms.
77 This is how TrueType hints work.
79 3. The font gets auto-hinted (at run-time). The hinting logic is
80 completely in the rasterizer. No hints in the font are used or needed;
81 instead, the rasterizer scans and analyzes the glyphs to apply
82 corrections by itself.
84 This is how FreeType's auto-hinter works; see
85 [below](#background-and-technical-details) for more.
88 What problems can arise with TrueType hinting?
89 ----------------------------------------------
91 While it is relatively easy to specify PostScript hints (either manually or
92 by an auto-hinter that works at font creation time), creating TrueType
93 hints is far more difficult. There are at least two reasons:
95 - TrueType instructions form a programming language, operating at a very
96 low level. They are comparable to assembler code, thus lacking all
97 high-level concepts to make programming more comfortable.
99 Here an example how such code looks like:
103 PUSHB[ ] /* 3 values pushed */
106 PUSHB[ ] /* 2 values pushed */
109 PUSHB[ ] /* 3 values pushed */
114 Another major obstacle is the fact that font designers usually aren't
117 - It is very time consuming to manually hint glyphs. Given that the
118 number of specialists for TrueType hinting is very limited, hinting a
119 large set of glyphs for a font or font family can become very expensive.
125 The ttfautohint library brings the excellent quality of FreeType rendering
126 to platforms that don't use FreeType, yet require hinting for text to look
127 good -- like Microsoft Windows. Roughly speaking, it converts the glyph
128 analysis done by FreeType's auto-hinting module to TrueType bytecode.
129 Internally, the auto-hinter's algorithm resembles PostScript hinting
130 methods; it thus combines all three hinting methods discussed
131 [previously](#what-exactly-are-hints).
133 The simple interface of the front-ends (both on the command line and with
134 the GUI) allows quick hinting of a whole font with a few mouse clicks or a
135 single command on the prompt. As a result, you get better rendering results
136 with web browsers, for example.
138 Across Windows rendering environments today, fonts processed with
139 ttfautohint look best with ClearType enabled. This is the default for
140 Windows\ 7. Good visual results are also seen in recent MacOS\ X versions
141 and GNU/Linux systems (including Android, ChromeOS, and other mobile
142 operating systems) that use FreeType for rendering glyphs.
144 The goal of the project is to generate a 'first pass' of hinting that font
145 developers can refine further for ultimate quality.
151 Fundamentally, there are two approaches to hinting. The older approach,
152 let's call it 'sharp', popular when text was rendered in pure
153 black-and-white, was to make all stems round to full pixels so that in a
154 text line, all stems would be either one pixel or (at a larger point size)
155 two pixels. When grayscale antialiasing came about, this approach actually
156 started harming the rendering rather than helping it, because the horizontal
157 and vertical stems would render very dark but round or diagonal stems would
160 So a new approach was developed, let's call it 'fuzzy', where all stems and
161 other elements are equalized so that in grayscale (or ClearType) rendering,
162 they all are of roughly equal color. This means that stems are not rounded
163 to full pixels but in fact to fractions of a pixel. However, with
164 black-and-white renderers, this approach yields poor results because in
165 black-and-white you cannot render a fraction of a pixel, so some stems
166 become one pixel and some become two.
168 The TrueType autohinters in [FontForge] and [FontLab Studio], to name two
169 well-known font editors, take the 'sharp' approach, while the TrueType
170 autohinter in ttfautohint takes the 'fuzzy' approach.
172 In theory, a hybrid approach is possible, using TrueType conditional hints:
173 If the rasterizer is black-and-white, 'sharp' rendering could happen, while
174 if the rasterizer is ClearType, the 'fuzzy' rendering could be used. It is
175 not intended to add black-and-white auto-hinting to ttfautohint. However,
176 it is planned to develop an interface so that ttfautohint can cooperate with
177 font editors, providing this hybrid hinting.
181 `ttfautohint` and `ttfautohintGUI`
182 ==================================
184 On all supported platforms (GNU/Linux, Windows, and Mac OS\ X), the GUI
185 looks quite similar; the used toolkit is [Qt], which in turn uses the
186 platform's native widgets.
188 ![`ttfautohintGUI` on GNU/Linux running KDE](img/ttfautohintGUI.png)
190 Both the GUI and console version share the same features, to be discussed in
193 **Warning: ttfautohint cannot always process a font a second time.**
194 If the font contains composite glyphs, and option [`-c`](#hint-composites)
195 is used, reprocessing with ttfautohint will fail. For this reason it is
196 strongly recommended to *not* delete the original, unhinted font so that you
197 can always rerun ttfautohint.
200 Calling `ttfautohint`
201 ---------------------
204 ttfautohint [OPTION]... [IN-FILE [OUT-FILE]]
207 The TTY binary, `ttfautohint`, works like a Unix filter, this is, it reads
208 data from standard input if no input file name is given, and it sends its
209 output to standard output if no output file name is specified.
211 A typical call looks like the following.
214 ttfautohint -v -f latn foo.ttf foo-autohinted.ttf
217 For demonstration purposes, here the same using a pipe and redirection.
218 Note that Windows's default command line interpreter, `cmd.exe`, doesn't
219 support piping with binary files, unfortunately.
222 cat foo.ttf | ttfautohint -v -f latn > foo-autohinted.ttf
226 Calling `ttfautohintGUI`
227 ------------------------
230 ttfautohintGUI [OPTION]...
233 `ttfautohintGUI` doesn't send any output to a console; however, it accepts
234 the same command line options as `ttfautohint`, setting default values for
241 Long options can be given with one or two dashes, and with and without an
242 equal sign between option and argument. This means that the following forms
243 are acceptable: `-foo=`*bar*, `--foo=`*bar*, `-foo`\ *bar*, and
246 Below, the section title refers to the command's label in the GUI (if
247 applicable), then comes the name of the corresponding long command line
248 option and its short equivalent, followed by a description.
250 Background and technical details on the meaning of the various options are
251 given [afterwards](#background-and-technical-details).
253 ### Hint Set Range Minimum, Hint Set Range Maximum
255 See '[Hint Sets](#hint-sets)' for a definition and explanation.
257 `--hinting-range-min=`*n*, `-l`\ *n*
258 : The minimum PPEM value (in pixels) at which hint sets are created. The
259 default value for *n* is\ 8.
261 `--hinting-range-max=`*n*, `-r`\ *n*
262 : The maximum PPEM value (in pixels) at which hint sets are created. The
263 default value for *n* is 50.
265 Increasing the range given by `-l` and `-r` normally makes the font's
270 `--default-script=`*s*, `-D`\ *s*
271 : Set default script to tag *s*, which is a string consisting of four
272 lowercase characters like `latn` or `dflt`. It is needed to specify the
273 OpenType default script: After applying all features that are handled
274 specially (like small caps or superscript), ttfautohint uses this value
275 for the remaining features. The default value is `latn`. See
276 [below](#opentype-features) for more details.
280 `--fallback-script=`*s*, `-f`\ *s*
281 : Set fallback script to tag *s*, which is a string consisting of four
282 characters like `latn` or `dflt`. It gets used for for all glyphs that
283 can't be assigned to a script automatically. The default value is
284 `none`. See [below](#scripts) for more details.
288 `--hinting-limit=`*n*, `-G`\ *n*
289 : The *hinting limit* is the PPEM value (in pixels) where hinting gets
290 switched off (using the `INSTCTRL` bytecode instruction, not the `gasp`
291 table data); it does not influence the file size. The default value for
292 *n* is 200, which means that the font is not hinted for PPEM values
295 Note that hinting in the range 'hinting-range-max' up to 'hinting-limit'
296 uses the hinting configuration for 'hinting-range-max'.
298 To omit a hinting limit, use `--hinting-limit=0` (or check the 'No
299 Hinting Limit' box in the GUI). Since this causes internal math
300 overflow in the rasterizer for large pixel values (>\ 1500px approx.) it
301 is strongly recommended to not use this except for testing purposes.
303 ### x Height Increase Limit
305 `--increase-x-height=`*n*, `-x`\ *n*
306 : Normally, ttfautohint rounds the x\ height to the pixel grid, with a
307 slight preference for rounding up (to use the terminology of TrueType's
308 'Super Round' bytecode instruction, the threshold is 5/8px). If this
309 flag is set, values in the range 6\ PPEM to *n*\ PPEM are much more
310 often rounded up (setting the threshold to 13/16px). The default value
311 for *n* is 14. Use this flag to increase the legibility of small sizes
312 if necessary; you might get weird rendering results otherwise for glyphs
313 like 'a' or 'e', depending on the font design.
315 To switch off this feature, use `--increase-x-height=0` (or check the
316 'No x\ Height Increase' box in the GUI). To switch off rounding the
317 x\ height to the pixel grid in general, either partially or completely,
318 see '[x Height Snapping Exceptions](#x-height-snapping-exceptions)'.
320 The following FontForge snapshot images use the font '[Mertz
321 Bold](http://code.newtypography.co.uk/mertz-sans/)' (still under
322 development) from [Vernon Adams].
324 ![At 17px, without option `-x` and '`-w ""`', the hole in glyph 'e'
325 looks very grey in the FontForge snapshot, and the GDI ClearType
326 rendering (which is the default on older Windows versions) fills it
327 completely with black because it uses B/W rendering along the y\ axis.
328 FreeType's 'light' autohint mode (which corresponds to ttfautohint's
329 'smooth' stem width algorithm) intentionally aligns horizontal lines
330 to non-integer (but still discrete) values to avoid large glyph shape
331 distortions.](img/e-17px-x14.png)
333 ![The same, this time with option `-x 17` (and
334 '`-w ""`').](img/e-17px-x17.png)
336 ### x Height Snapping Exceptions
338 `--x-height-snapping-exceptions=`*string*, `-X`\ *string*
339 : A list of comma separated PPEM values or value ranges at which no
340 x\ height snapping shall be applied. A value range has the form
341 *value*~1~`-`*value*~2~, meaning *value*~1~\ <= PPEM <=\ *value*~2~.
342 *value*~1~ or *value*~2~ (or both) can be missing; a missing value is
343 replaced by the beginning or end of the whole interval of valid PPEM
344 values, respectively (6\ to 32767). Whitespace is not significant;
345 superfluous commas are ignored, and ranges must be specified in
346 increasing order. For example, the string `"7-9, 11, 13-"` means the
347 values 7, 8, 9, 11, 13, 14, 15, etc. Consequently, if the supplied
348 argument is `"-"`, no x\ height snapping takes place at all. The
349 default is the empty string (`""`), meaning no snapping exceptions.
351 Normally, x\ height snapping means a slight increase in the overall
352 vertical glyph size so that the height of lowercase glyphs gets aligned
353 to the pixel grid (this is a global feature, affecting *all* glyphs of a
354 font). However, having larger vertical glyph sizes is not always
355 desired, especially if it is not possible to adjust the `usWinAscent`
356 and `usWinDescent` values from the font's `OS/2` table so that they are
357 not too tight. See '[Windows Compatibility](#windows-compatibility)'
360 ### Fallback Stem Width
362 `--fallback-stem-width=`*n*, `-H`\ *n*
363 : Set the horizontal stem width (hinting) value for all scripts that lack
364 proper standard characters in the font. The value is given in font
365 units and must be a positive integer. If not set, ttfautohint uses a
366 hard-coded default (50\ units at 2048 units per EM, and linearly scaled
367 for other UPEM values, for example 24\ units at 1000 UPEM).
369 For symbol fonts, you need option `--fallback-script` too (to set up a
372 In the GUI, uncheck the 'Default Fallback Stem Width' box to activate
375 ### Windows Compatibility
377 `--windows-compatibility`, `-W`
378 : This option makes ttfautohint add two artificial blue zones, positioned
379 at the `usWinAscent` and `usWinDescent` values (from the font's `OS/2`
380 table). The idea is to help ttfautohint so that the hinted glyphs stay
381 within this horizontal stripe since Windows clips everything falling
384 There is a general problem with tight values for `usWinAscent` and
385 `usWinDescent`; a good description is given in the [Vertical Metrics
386 How-To](http://typophile.com/node/13081). Additionally, there is a
387 special problem with tight values if used in combination with
388 ttfautohint because the auto-hinter tends to slightly increase the
389 vertical glyph dimensions at smaller sizes to improve legibility. This
390 enlargement can make the heights and depths of glyphs exceed the range
391 given by `usWinAscent` and `usWinDescent`.
393 If ttfautohint is part of the font creation tool chain, and the font
394 designer can adjust those two values, a better solution instead of using
395 option `-W` is to reserve some vertical space for 'padding': For the
396 auto-hinter, the difference between a top or bottom outline point before
397 and after hinting is less than 1px, thus a vertical padding of 2px is
398 sufficient. Assuming a minimum hinting size of 6ppem, adding two pixels
399 gives an increase factor of 8÷6 = 1.33. This is near to the default
400 baseline-to-baseline distance used by TeX and other sophisticated text
401 processing applications, namely 1.2×designsize, which gives satisfying
402 results in most cases. It is also near to the factor 1.25 recommended
403 in the abovementioned how-to. For example, if the vertical extension of
404 the largest glyph is 2000 units (assuming that it approximately
405 represents the designsize), the sum of `usWinAscent` and `usWinDescent`
406 could be 1.25×2000 = 2500.
408 In case ttfautohint is used as an auto-hinting tool for fonts that can
409 be no longer modified to change the metrics, option `-W` in combination
410 with '`-X "-"`' to suppress any vertical enlargement should prevent
415 `--adjust-subglyphs`, `-p`
416 : *Adjusting subglyphs* makes a font's original bytecode be applied to all
417 glyphs before it is replaced with bytecode created by ttfautohint. This
418 makes only sense if your font already has some hints in it that modify
419 the shape even at EM size (normally 2048px); in particular, some CJK
420 fonts need this because the bytecode is used to scale and shift
421 subglyphs (hence the option's long name). For most fonts, however, this
427 : By default, the components of a composite glyph get hinted separately.
428 If this flag is set, the composite glyph itself gets hinted (and the
429 hints of the components are ignored). Using this flag increases the
430 bytecode size a lot, however, it might yield better hinting results.
432 If this option is used (and a font actually contains composite glyphs),
433 ttfautohint currently cannot reprocess its own output for technical
434 reasons, see [below](#the-.ttfautohint-glyph).
439 : Process a font that ttfautohint would refuse otherwise because it can't
440 find a single standard character for any of the supported scripts.
442 For all scripts that lack proper standard characters, ttfautohint uses a
443 default (hinting) value for the standard stem width instead of deriving
444 it from a script's set of standard characters (for the latin script, one
445 of them is character 'o').
447 Use this option (usually in combination with the
448 [`--fallback-script`](#fallback-script) and/or
449 [`--fallback-stem-width`](#fallback-stem-width) option) to hint symbol
450 or dingbat fonts or math glyphs, for example, at the expense of possibly
451 poor hinting results at small sizes.
456 : Strip off all hints without generating new hints. Consequently, all
457 other hinting options are ignored. This option is intended for testing
463 : Don't add ttfautohint version and command line information to the
464 version string or strings (with name ID\ 5) in the font's `name` table.
465 In the GUI, it corresponds to value 'None' in the 'ttfautohint
468 This option is mutually exclusive with option `-I`.
470 `--detailed-info`, `-I`
471 : Add ttfautohint version and command line information to the version
472 string or strings (with name ID\ 5) in the font's `name` table. In the
473 GUI, it corresponds to value 'Version and Parameters' in the
474 'ttfautohint info' combo box.
476 This option is mutually exclusive with option `-n`.
478 If neither `-n` nor `-I` is set, the string '`ttfautohint (vNNN)`' gets
479 added to the `name` table (with *NNN* the current version); this correponds
480 to value 'Version' in the 'ttfautohint info' combo box.
482 ### Add TTFA Info Table
485 : Add an SFNT table called `TTFA` to the output font that holds a dump of
486 all parameters; the data resembles the format of the `--debug` option's
487 parameter listing. In particular, it lists all ttfautohint control
488 instructions (which are *not* shown in the `name` table info). This
489 option is mainly for archival purposes so that all information used to
490 create a font is stored in the font itself. Note that such a `TTFA`
491 table gets ignored by all TrueType rendering engines.
493 Forthcoming versions of the ttfautohint front-ends will be able to use
494 this data so that a font can be processed another time with exactly the
495 same parameters, thus providing a means for round-tripping fonts.
499 `--family-suffix=`*string*, `-F`\ *string*
500 : A string that gets appended to the family name in entries with IDs 1, 4,
501 6, 16, and\ 21 in the font's `name` table. Allowed input is ASCII in
502 the range 0x20-0x7E except characters `%()/<>[]{}`.
504 Assuming an input family name 'Foo', a full name 'Foo Bold', and a
505 family suffix '\ 1', the output family name will be 'Foo 1' and the
506 full name 'Foo 1 Bold'. For the PostScript name in ID\ 6, ttfautohint
507 uses the suffix with space characters removed (for example 'Foo1Bold').
509 This option is mainly for testing purposes, enabling the operating
510 system to simultaneously display several instances of a font that are
511 processed with different ttfautohint parameters.
513 ### Strong Stem Width and Positioning
515 `--strong-stem-width=`*string*, `-w`\ *string*
516 : ttfautohint offers two different routines to handle (horizontal) stem
517 widths and stem positions: 'smooth' and 'strong'. The former uses
518 discrete values that slightly increase the stem contrast with almost no
519 distortion of the outlines, while the latter snaps both stem widths and
520 stem positions to integer pixel values as much as possible, yielding a
521 crisper appearance at the cost of much more distortion.
523 These two routines are mapped onto three possible rendering targets:
525 - grayscale rendering, with or without optimization for subpixel
526 positioning (e.g. Android)
528 - 'GDI ClearType' rendering: the rasterizer version, as returned by the
529 GETINFO bytecode instruction, is in the range 36\ <= version <\ 38 and
530 ClearType is enabled (e.g. Windows XP)
532 - 'DirectWrite ClearType' rendering: the rasterizer version, as returned
533 by the GETINFO bytecode instruction, is >=\ 38, ClearType is enabled,
534 and subpixel positioning is enabled also (e.g. Internet Explorer\ 9
535 running on Windows\ 7)
537 GDI ClearType uses a mode similar to B/W rendering along the vertical
538 axis, while DW ClearType applies grayscale rendering. Additionally,
539 only DW ClearType provides subpixel positioning along the x\ axis. For
540 what it's worth, the rasterizers version\ 36 and version\ 38 in
541 Microsoft Windows are two completely different rendering engines.
543 The command line option expects *string* to contain up to three letters
544 with possible values '`g`' for grayscale, '`G`' for GDI ClearType, and
545 '`D`' for DW ClearType. If a letter is found in *string*, the strong
546 stem width routine is used for the corresponding rendering target (and
547 smooth stem width handling otherwise). The default value is '`G`', which
548 means that strong stem width handling is activated for GDI ClearType
549 only. To use smooth stem width handling for all three rendering
550 targets, use the empty string as an argument, usually connoted with
553 In the GUI, simply set the corresponding check box to select the strong
554 width routine for a given rendering target. If you unset the check box,
555 the smooth width routine gets used.
557 The following images again use the font 'Mertz Bold'.
559 ![The left part shows the glyph 'g' unhinted at 26px, the right part
560 with hints, using the 'smooth' stem algorithm.](img/ff-g-26px.png)
562 ![The same, but this time using the 'strong'
563 algorithm. Note how the stems are aligned to the pixel
564 grid.](img/ff-g-26px-wD.png)
566 ### Control Instructions File
567 `--control-file=`*file*, `-m`\ *file* (TTY only)
568 : Specify the name of a control instructions file to manually tweak the
569 hinting process. This feature can be used to correct glitches in
570 ttfautohint's hinting algorithm.
572 An entry in a control instructions file has one of the following syntax
573 forms (with brackets showing optional elements):
575 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`l`\[`eft`\]|`r`\[`ight`\]*\ points\ \ *\[*\ *`(`*\ left‑offset\ *`,`*\ right‑offset\ *`)`*\ *\]*\
576 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`n`\[`odir`\]*\ points\
577 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`t`\[`ouch`\]|`p`\[`oint`\]*\ points\ \ *\[*\ *`x`\[`shift`\]*\ x‑shift\ *\]*\ \ *\[*\ *`y`\[`shift`\]*\ y‑shift\ *\]*\ \ *`@`*\ ppems
579 *font‑idx* gives the index of the font in a TrueType Collection. If
580 missing, it is set to zero. For normal TrueType fonts, only value zero
581 is valid. If starting with `0x` the number is interpreted as
582 hexadecimal. If starting with `0` it gets interpreted as an octal
583 value, and as a decimal value otherwise.
585 *glyph‑id* is a glyph's name as listed in the `post` SFNT table or a
586 glyph index. A glyph name consists of characters from the set
587 '`A-Za-z0-9._`' only and does not start with a digit or period, with the
588 exceptions of the names '`.notdef`' and '`.null`'. A glyph index can be
589 specified in decimal, octal, or hexadecimal format, the latter two
590 indicated by the prefixes `0` and `0x`, respectively.
592 The mutually exclusive parameters `left` and `right` (which can be
593 abbreviated as '`l`' and '`r`', respectively) indicate that the
594 following points have left or right 'out' direction, respectively,
595 overriding ttfautohint's algorithm for setting point directions. The
596 'out direction' of a point is the direction of the outline *leaving* the
597 point (or passing the control point). If the specified direction is
598 identical to what ttfautohint computes, nothing special happens.
599 Otherwise, a one-point segment with the specified direction gets
600 created. By default, its length is zero. Setting *left‑offset* and
601 *right‑offset*, you can change the segment's horizontal start and end
602 position relative to the point position. *left‑offset* and
603 *right‑offset* are integers measured in font units.
605 Parameter `nodir` (or '`n`') sets the 'out' direction of the following
606 points to 'no direction'. If the specified direction is identical to
607 what ttfautohint computes, nothing special happens. Otherwise,
608 ttfautohint no longer considers those points as part of horizontal
609 segments, thus treating them as 'weak' points.
611 Modifying or adding segments doesn't directly modify the outlines; it
612 only influences the hinting process.
614 The mutually exclusive parameters `touch` and `point` (which can be
615 abbreviated as '`t`' and '`p`', respectively) make ttfautohint apply
616 delta exceptions for the given points, shifting them by the given
617 values. Delta exceptions entered with `touch` are applied before the
618 final `IUP` instructions in a glyph's bytecode, exceptions entered with
619 `point` after `IUP`. Additionally, the `touch` parameter makes the
620 bytecode *touch* the affected points; such points are no longer affected
621 by `IUP` at all. Note that in ClearType mode all deltas along the
622 x\ axis are discarded, and deltas along the y\ axis are only executed
623 for touched points. As a consequence, vertical delta exceptions entered
624 with `point` should not be used in ClearType mode.^[Unfortunately, there
625 is a bug in FreeType prior to version 2.5.4 (released in December 2014)
626 that completely disables vertical delta exceptions if subpixel hinting
627 is activated. For this reason you should expect that the `touch`
628 parameter fails on older GNU/Linux distributions.]
630 Both *points* and *ppems* are number ranges, see '[x Height Snapping
631 Exceptions](#x-height-snapping-exceptions)' for the syntax.
633 *x‑shift* and *y‑shift* represent real numbers that get rounded to
634 multiples of 1/8 pixels. The entries for `xshift` ('`x`') and `yshift`
635 ('`y`') are optional; if missing, the corresponding value is set to
636 zero. If both values are zero, the delta exception entry is ignored as
639 Values for *x‑shift* and *y‑shift* must be in the range [−1.0;1.0].
640 Values for *ppems* must be in the range [6;53]. Values for *points* are
641 limited by the number of points in the glyph.
643 Similar to the Bourne shell (`sh` or `bash`), a comment starts with
644 character '`#`'; the rest of the line is ignored. An empty line is
645 ignored also. Both the newline character and '`;`' can be used as a
646 separator between exception entries. A trailing '`\`' at the end of a
647 line continues the current line on the next one.
649 In case there are multiple shift entries for the same (*font‑idx*,
650 *glyph‑id*, *point‑idx*, *ppem‑value*) quadruplet, the first entry in
651 the control instructions file wins.
653 Note that only character '`.`' is recognized as a decimal point, and a
654 thousands separator is not accepted.
656 As an example for delta instructions, let's assume that you want to
657 shift points 2, 3, and\ 4 in glyph `Aacute' at ppem sizes 12 and\ 13 by
658 a vertical amount of 0.25 pixels. This corresponds to the line
661 Aacute touch 2-4 yshift 0.25 @ 12, 13
664 in a control instructions file. Since we use `touch` and not `point`,
665 points 2, 3, and\ 4 are no longer subject to the final `IUP` instruction
666 (`IUP` interpolates weak, untouched point positions between strong,
669 The following images display glyphs from the font
670 [Halant-Regular](http://www.google.com/fonts/specimen/Halant).
672 ![The outlines of glyphs 'O' and 'Q', as displayed in
673 FontForge. They are sufficiently similar to expect that ttfautohint
674 hints them equally. However, this is not the
675 case.](img/Halant-Regular-O-Q.png)
677 ![The same glyphs, shown at 12px before hinting. [Please ignore the
678 outline distortion in the upper right of glyph 'O'; this is a bug in
679 FontForge while running the TrueType
680 debugger.]](img/Halant-Regular-O-Q-unhinted-12px.png)
682 ![Using only ttfautohint's '`-w gGD`' parameter to force strong stem
683 width and positioning, the hinting of glyph 'Q' is really bad, making
684 the glyph vertically two pixels larger! Reason is that this glyph
685 doesn't contain a horizontal segment at the baseline blue zone
686 (*y*\ =\ 1; this corresponds to the segment 13-14 in the 'O' glyph).
687 Normally, segment 1-2 would form a 'stem' with the baseline segment
688 (as segment 7-8 does in glyph 'O'). Instead, it forms a stem with
689 segment 19-20, which gets moved down (*y*\ =\ −1) because the whole
691 stretched.](img/Halant-Regular-O-good-Q-badly-hinted-12px.png)
693 ![To fix the problem, we change the direction of point\ 38 to 'left' by
694 writing a line '`Q left 38`' (without the quotes) to a control
695 description file `Halant-Regular.txt`. Adding option '`-m
696 Halant-Regular.txt`' to ttfautohint, we get the shown image as a
697 result, which is much better: Segment 1-2 now properly forms a stem
698 with our artificial one-point segment\ 38, and the 'O'-like shape is
699 properly positioned. However, there is still room for improvement:
700 Segment 19-20 is also positioned at the baseline, making the
701 connection between the 'O' shape and the tail too
702 thin.](img/Halant-Regular-O-good-Q-better-hinted-12px.png)
704 ![By giving the one-point segment\ 38 a horizontal width, we can prevent
705 that segment 19-20 gets positioned at the baseline: Replace the line
706 in the previous image description with '`Q left 38 (−70,20)`', making
707 the segment extend 70 font units to the left and 20 to the right of
708 point\ 38. The exact offset values don't matter; it's only important
709 to start left of point\ 19. Another solution to the problem is to
710 artificially change the direction of segment 19-20 by adding a second
711 line '`Q right 19-20`' to the control instructions file; for our 'Q'
712 glyph, this produces almost exactly the same hinting results. Note
713 that such direction changes only influence the hinting process; an
714 outline's direction won't be changed at
715 all.](img/Halant-Regular-O-good-Q-well-hinted-12px.png)
719 Watch input files (GUI only)
720 : If this checkbox is set, automatically regenerate the output file as
721 soon as an input file (either the font or the control instructions file)
724 Pressing the 'Run' button starts watching. If an error occurs, watching
725 stops and must be restarted with the 'Run' button.
727 `--ignore-restrictions`, `-i`
728 : By default, fonts that have bit\ 1 set in the 'fsType' field of the
729 `OS/2` table are rejected. If you have a permission of the font's legal
730 owner to modify the font, specify this command line option.
732 If this option is not set, `ttfautohintGUI` shows a dialogue to handle
733 such fonts if necessary.
736 : On the console, print a brief documentation on standard output and exit.
737 This doesn't work with `ttfautohintGUI` on MS Windows.
740 : On the console, print version information on standard output and exit.
741 This doesn't work with `ttfautohintGUI` on MS Windows.
744 : Print *a lot* of debugging information on standard error while
745 processing a font (you should redirect stderr to a file). This
746 doesn't work with `ttfautohintGUI` on MS Windows.
750 Background and Technical Details
751 ================================
753 [Real-Time Grid Fitting of Typographic
754 Outlines](http://www.tug.org/TUGboat/tb24-3/lemberg.pdf) is a scholarly
755 paper that describes FreeType's auto-hinter in some detail. Regarding the
756 described data structures it is slightly out of date, but the algorithm
757 itself hasn't changed in general.
759 The next few subsections are mainly based on this article, introducing some
760 important concepts. Note that ttfautohint only does hinting along the
761 vertical direction (modifying y\ coordinates only).
767 A glyph consists of one or more *contours* (this is, closed curves). For
768 example, glyph 'O' consists of two contours, while glyph 'I' has only one.
770 ![The letter 'O' has two contours, an inner and an outer one, while letter
771 'I' has only an outer contour.](img/o-and-i)
773 A *segment* is a series of consecutive points of a contour (including its
774 Bézier control points) that are approximately aligned along a coordinate
777 ![A serif. Contour and control points are represented by squares and
778 circles, respectively. The bottom 'line' DE is approximately aligned
779 along the horizontal axis, thus it forms a segment of 7\ points. Together
780 with the two other horizontal segments, BC and FG, they form two edges
781 (BC+FG, DE).](img/segment-edge)
783 An *edge* corresponds to a single coordinate value on the main dimension
784 that collects one or more segments (allowing for a small threshold). While
785 finding segments is done on the unscaled outline, finding edges is bound to
786 the device resolution. See [below](#hint-sets) for an example.
788 The analysis to find segments and edges is specific to a writing
789 system, see [below](#writing-systems).
795 The auto-hinter analyzes a font in two steps. Right now, everything
796 described here happens for the horizontal axis only, providing vertical
801 This affects the hinting of all glyphs, trying to give them a uniform
804 + Compute standard horizontal stem width of the font. The value
805 is normally taken from glyphs that resemble letter 'o'.
807 + Compute blue zones, see [below](#blue-zones).
809 If the stem widths of single glyphs differ by a large value, or if
810 ttfautohint fails to find proper blue zones, hinting becomes quite poor,
811 possibly leading even to severe shape distortions.
814 Table: script-specific standard characters of the 'latin' writing system
816 Script Standard characters
817 ---------- ---------------------
818 `cyrl` 'о', U+043E, CYRILLIC SMALL LETTER O
819 'О', U+041E, CYRILLIC CAPITAL LETTER O
820 `deva` 'ठ', U+0920, DEVANAGARI LETTER TTHA
821 'व', U+0935, DEVANAGARI LETTER VA
822 'ट', U+091F, DEVANAGARI LETTER TTA
823 `grek` 'ο', U+03BF, GREEK SMALL LETTER OMICRON
824 'Ο', U+039F, GREEK CAPITAL LETTER OMICRON
825 `hebr` 'ם', U+05DD, HEBREW LETTER FINAL MEM
826 `latn` 'o', U+006F, LATIN SMALL LETTER O
827 'O', U+004F, LATIN CAPITAL LETTER O
828 '0', U+0030, DIGIT ZERO
829 `telu` 'ఙ', U+0C19, TELUGU LETTER NGA
830 'ఒ', U+0C12, TELUGU LETTER O
831 `thai` 'า', U+0E32, THAI CHARACTER SARA AA
832 'ๅ', U+0E45, THAI CHARACTER LAKKHANGYAO
833 '๐', U+0E50, THAI DIGIT ZERO
838 This is a per-glyph operation.
840 + Find segments and edges.
842 + Link edges together to find stems and serifs. The abovementioned
843 paper gives more details on what exactly constitutes a stem or a
844 serif and how the algorithm works.
850 ![Two blue zones relevant to the glyph 'a'. Vertical point coordinates of
851 *all* glyphs within these zones are aligned, provided the blue zone is
852 active (this is, its vertical size is smaller than
853 3/4\ pixels).](img/blue-zones)
855 Outlines of certain characters are used to determine *blue zones*. This
856 concept is the same as with Type\ 1 fonts: All glyph points that lie in
857 certain small horizontal zones get aligned vertically.
859 Here a series of tables that show the blue zone characters of the latin
860 writing system's available scripts; the values are hard-coded in the source
861 code. Since the auto-hinter takes mean values it is not necessary that all
862 characters of a zone are present.
865 Table: `cyrl` blue zones
867 ID Blue zone Characters
868 ---- ----------- ------------
869 1 top of capital letters БВЕПЗОСЭ
870 2 bottom of capital letters БВЕШЗОСЭ
871 3 top of small letters хпншезос
872 4 bottom of small letters хпншезос
873 5 bottom of descenders of small letters руф
876 Table: `deva` blue zones
878 ID Blue zone Characters
879 ---- ----------- ------------
880 1 baseline (flat glyphs only) क न म उ छ ट ठ ड
881 2 top of ascenders ई ऐ ओ औ ि ी ो ौ
882 3 top of baseline क म अ आ थ ध भ श
883 4 bottom of descenders ु ृ
885 Contrary to scripts like latin, the baseline in Devanagari is on the top.
886 Note that some fonts have extreme variation in the height of the round
887 elements in Zone\ 3; for this reason we also define Zone\ 1, which must be
891 Table: `grek` blue zones
893 ID Blue zone Characters
894 ---- ----------- ------------
895 1 top of capital letters ΓΒΕΖΘΟΩ
896 2 bottom of capital letters ΒΔΖΞΘΟ
897 3 top of 'small beta' like letters βθδζλξ
898 4 top of small letters αειοπστω
899 5 bottom of small letters αειοπστω
900 6 bottom of descenders of small letters βγημρφχψ
903 Table: `hebr` blue zones
905 ID Blue zone Characters
906 ---- ----------- ------------
907 1 top of letters בדהחךכםס
908 2 bottom of letters בטכםסצ
909 3 bottom of descenders of letters קךןףץ
912 Table: `latn` blue zones
914 ID Blue zone Characters
915 ---- ----------- ------------
916 1 top of capital letters THEZOCQS
917 2 bottom of capital letters HEZLOCUS
918 3 top of 'small f' like letters fijkdbh
919 4 top of small letters xzroesc
920 5 bottom of small letters xzroesc
921 6 bottom of descenders of small letters pqgjy
923 The 'round' characters (e.g. 'OCQS') from Zones 1, 2, and\ 5 are also used
924 to control the overshoot handling; to improve rendering at small sizes,
925 zone\ 4 gets adjusted to be on the pixel grid; cf. the
926 [`--increase-x-height`](#x-height-increase-limit) option.
929 Table: `telu` blue zones
931 ID Blue zone Characters
932 ---- ----------- ------------
934 2 bottom అ క చ ర ఽ ౨ ౬
937 Table: `thai` blue zones
939 ID Blue zone Characters
940 ---- ----------- ------------
942 2 bottom บ ป ษ ฯ อ ย ฮ
944 4 large ascender โ ใ ไ
946 6 large descender ญ ฐ
947 7 top of Thai digits ๐ ๑ ๓
950 ![This image shows the relevant glyph terms for vertical blue zone
951 positions.](img/glyph-terms)
957 Aligning outlines along the grid lines is called *grid fitting*. It doesn't
958 necessarily mean that the outlines are positioned *exactly* on the grid,
959 however, especially if you want a smooth appearance at different sizes.
960 This is the central routine of the auto-hinter; its actions are highly
961 dependent on the used writing system. Currently, only one writing system is
962 available (latin), providing support for scripts like Latin or Greek.
964 * Align edges linked to blue zones.
966 * Fit edges to the pixel grid.
970 * Handle remaining 'strong' points. Such points are not part of an edge
971 but are still important for defining the shape. This roughly
972 corresponds to the `IP` TrueType instruction.
974 * Everything else (the 'weak' points) is handled with an `IUP`
977 The following images illustrate the hinting process, using glyph 'a' from
978 the freely available font '[Ubuntu Book](http://font.ubuntu.com)'. The
979 manual hints were added by [Dalton Maag Ltd], the used application to create
980 the hinting debug snapshots was [FontForge].
982 ![Before hinting.](img/a-before-hinting.png)
984 ![After hinting, using manual hints.](img/a-after-hinting.png)
986 ![After hinting, using ttfautohint. Note that the hinting process
987 doesn't change horizontal positions.](img/a-after-autohinting.png)
993 In ttfautohint terminology, a *hint set* is the *optimal* configuration for
994 a given PPEM (pixel per EM) value.
996 In the range given by the `--hinting-range-min` and `--hinting-range-max`
997 options, ttfautohint creates hint sets for every PPEM value. For each
998 glyph, ttfautohint automatically determines whether a new set should be
999 emitted for a PPEM value if it finds that it differs from a previous one.
1000 For some glyphs it is possible that one set covers, say, the range
1001 8px-1000px, while other glyphs need 10 or more such sets.
1003 In the PPEM range below `--hinting-range-min`, ttfautohint always uses just
1004 one set, in the PPEM range between `--hinting-range-max` and
1005 `--hinting-limit`, it also uses just one set.
1007 One of the hinting configuration parameters is the decision which segments
1008 form an edge. For example, let us assume that two segments get aligned on a
1009 single horizontal edge at 11px, while two edges are used at 12px. This
1010 change makes ttfautohint emit a new hint set to accomodate this situation.
1011 The next images illustrate this, using a Cyrillic letter (glyph 'afii10108')
1012 from the 'Ubuntu book' font, processed with ttfautohint.
1014 ![Before hinting, size 11px.](img/afii10108-11px-before-hinting.png)
1016 ![After hinting, size 11px. Segments 43-27-28 and 14-15 are aligned on a
1017 single edge, as are segments 26-0-1 and
1018 20-21.](img/afii10108-11px-after-hinting.png)
1020 ![Before hinting, size 12px.](img/afii10108-12px-before-hinting.png)
1022 ![After hinting, size 12px. The segments are not aligned. While
1023 segments 43-27-28 and 20-21 now have almost the same horizontal position,
1024 they don't form an edge because the outlines passing through the segments
1025 point into different directions.](img/afii10108-12px-after-hinting.png)
1027 Obviously, the more hint sets get emitted, the larger the bytecode
1028 ttfautohint adds to the output font. To find a good value\ *n* for
1029 `--hinting-range-max`, some experimentation is necessary since *n* depends
1030 on the glyph shapes in the input font. If the value is too low, the hint
1031 set created for the PPEM value\ *n* (this hint set gets used for all larger
1032 PPEM values) might distort the outlines too much in the PPEM range given
1033 by\ *n* and the value set by `--hinting-limit` (at which hinting gets
1034 switched off). If the value is too high, the font size increases due to
1035 more hint sets without any noticeable hinting effects.
1037 Similar arguments hold for `--hinting-range-min` except that there is no
1038 lower limit at which hinting is switched off.
1040 An example. Let's assume that we have a hinting range 10\ <= ppem <=\ 100,
1041 and the hinting limit is set to 250. For a given glyph, ttfautohint finds
1042 out that four hint sets must be computed to exactly cover this hinting
1043 range: 10-15, 16-40, 41-80, and 81-100. For ppem values below 10ppem, the
1044 hint set covering 10-15ppem is used, for ppem values larger than 100 the
1045 hint set covering 81-100ppem is used. For ppem values larger than 250, no
1046 hinting gets applied.
1052 The ttfautohint library (and programs) supports two solutions for handling
1053 composite glyphs, to be controlled with option
1054 [`--composites`](#hint-composites). This section contains some general
1055 information, then covers the case where the option if off, while the next
1056 section describes how ttfautohint behaves if this option is activated.
1058 Regardless of the `--composites` option, ttfautohint performs a scan over
1059 all composite glyphs to assure that components of a composite glyph inherit
1060 its style, as described [later](#opentype-features). However, components
1061 that are shifted vertically will be skipped. For example, if the glyph
1062 'Agrave' uses a shifted 'grave' accent glyph, the accent is ignored. On the
1063 other hand, if there is a glyph 'agrave' that uses the same 'grave' glyph
1064 vertically unshifted, 'grave' does inherit the style.
1066 If `--composites` is off, components are hinted separately, then put
1067 together. Separate hinting implies that the current style's blue zones are
1068 applied to all subglyphs in its original, unshifted positions.
1071 The '\.ttfautohint' Glyph
1072 -------------------------
1074 If option [`--composites`](#hint-composites) is used, ttfautohint doesn't
1075 hint subglyphs of composite glyphs separately. Instead, it hints the whole
1076 glyph, this is, composites get recursively expanded internally so that they
1077 form simple glyphs, then hints are applied -- this is the normal working
1078 mode of FreeType's auto-hinter.
1080 One problem, however, must be solved: Hinting for subglyphs (which usually
1081 are used as normal glyphs also) must be deactivated so that nothing but the
1082 final bytecode of the composite gets executed.
1084 The trick used by ttfautohint is to prepend a composite element called
1085 '\.ttfautohint', a dummy glyph with a single point, and which has a single
1086 job: Its bytecode increases a variable (to be more precise, it is a CVT
1087 register called `cvtl_is_subglyph` in the source code), indicating that we
1088 are within a composite glyph. The final bytecode of the composite glyph
1089 eventually decrements this variable again.
1091 As an example, let's consider composite glyph 'Agrave' ('À'), which has the
1092 subglyph 'A' as the base and 'grave' as its accent. After processing with
1093 ttfautohint it consists of three components: '\.ttfautohint', 'A', and
1094 'grave' (in this order).
1097 ------------- --------
1098 .ttfautohint increase `cvtl_is_subglyph` (now: 1)
1099 A do nothing because `cvtl_is_subglyph` > 0
1100 grave do nothing because `cvtl_is_subglyph` > 0
1101 Agrave decrease `cvtl_is_subglyph` (now: 0)\
1102 apply hints because `cvtl_is_subglyph` == 0
1104 Some technical details (which you might skip): All glyph point indices get
1105 adjusted since each '\.ttfautohint' subglyph shifts all following indices by
1106 one. This must be done for both the bytecode and one subformat of
1107 OpenType's `GPOS` anchor tables.
1109 While this approach works fine on all tested platforms, there is one single
1110 drawback: Direct rendering of the '\.ttfautohint' subglyph (this is,
1111 rendering as a stand-alone glyph) disables proper hinting of all glyphs in
1112 the font! Under normal circumstances this never happens because
1113 '\.ttfautohint' doesn't have an entry in the font's `cmap` table. (However,
1114 some test and demo programs like FreeType's `ftview` application or other
1115 glyph viewers that are able to bypass the `cmap` table might be affected.)
1121 In FreeType terminology, a writing system is a set of functions that
1122 provides auto-hinting for certain scripts. Right now, only two writing
1123 systems from FreeType's auto-hinter are available in ttfautohint: 'dummy'
1124 and 'latin'. The former handles the 'no-script' case; details to 'latin'
1125 follow in the next section.
1131 ttfautohint needs to know which script should be used to hint a specific
1132 glyph. To do so, it checks a glyph's Unicode character code whether it
1133 belongs to a given script.
1135 Here is the hardcoded list of character ranges that are used for scripts in
1136 the 'latin' writing system. As you can see, this also covers some non-latin
1137 scripts (in the Unicode sense) that have similar typographical properties.
1139 In ttfautohint, scripts are identified by four-character tags. The value
1140 `none` indicates 'no script'.
1143 Table: `cyrl` character ranges
1145 Character range Description
1146 --------------------- -------------
1147 `0x0400` - `0x04FF` Cyrillic
1148 `0x0500` - `0x052F` Cyrillic Supplement
1149 `0x2DE0` - `0x2DFF` Cyrillic Extended-A
1150 `0xA640` - `0xA69F` Cyrillic Extended-B
1153 Table: `deva` character ranges
1155 Character range Description
1156 --------------------- -------------
1157 `0x0900` - `0x097F` Devanagari
1158 `0x20B9` (new) Rupee sign
1161 Table: `grek` character ranges
1163 Character range Description
1164 --------------------- -------------
1165 `0x0370` - `0x03FF` Greek and Coptic
1166 `0x1F00` - `0x1FFF` Greek Extended
1169 Table: `hebr` character ranges
1171 Character range Description
1172 --------------------- -------------
1173 `0x0590` - `0x05FF` Hebrew
1174 `0xFB1D` - `0xFB4F` Alphabetic Presentation Forms (Hebrew)
1177 Table: `latn` character ranges
1179 Character range Description
1180 --------------------- -------------
1181 `0x0020` - `0x007F` Basic Latin (no control characters)
1182 `0x00A0` - `0x00FF` Latin-1 Supplement (no control characters)
1183 `0x0100` - `0x017F` Latin Extended-A
1184 `0x0180` - `0x024F` Latin Extended-B
1185 `0x0250` - `0x02AF` IPA Extensions
1186 `0x02B0` - `0x02FF` Spacing Modifier Letters
1187 `0x0300` - `0x036F` Combining Diacritical Marks
1188 `0x1D00` - `0x1D7F` Phonetic Extensions
1189 `0x1D80` - `0x1DBF` Phonetic Extensions Supplement
1190 `0x1DC0` - `0x1DFF` Combining Diacritical Marks Supplement
1191 `0x1E00` - `0x1EFF` Latin Extended Additional
1192 `0x2000` - `0x206F` General Punctuation
1193 `0x2070` - `0x209F` Superscripts and Subscripts
1194 `0x20A0` - `0x20CF` Currency Symbols
1195 `0x2150` - `0x218F` Number Forms
1196 `0x2460` - `0x24FF` Enclosed Alphanumerics
1197 `0x2C60` - `0x2C7F` Latin Extended-C
1198 `0x2E00` - `0x2E7F` Supplemental Punctuation
1199 `0xA720` - `0xA7FF` Latin Extended-D
1200 `0xFB00` - `0xFB06` Alphabetical Presentation Forms (Latin Ligatures)
1201 `0x1D400` - `0x1D7FF` Mathematical Alphanumeric Symbols
1202 `0x1F100` - `0x1F1FF` Enclosed Alphanumeric Supplement
1205 Table: `telu` character ranges
1207 Character range Description
1208 --------------------- -------------
1209 `0x0C00` - `0x0C7F` Telugu
1212 Table: `thai` character ranges
1214 Character range Description
1215 --------------------- -------------
1216 `0x0E00` - `0x0E7F` Thai
1219 If a glyph's character code is not covered by a script range, it is not
1220 hinted (or rather, it gets hinted by the 'dummy' auto-hinting module that
1221 essentially does nothing). This can be changed by specifying a *fallback
1222 script*; see option [`--fallback-script`](#fallback-script).
1228 (Please read the [OpenType specification] for details on *features*, `GSUB`,
1229 and `GPOS` tables, and how they relate to scripts.)
1231 For modern OpenType fonts, character ranges are not sufficient to handle
1234 * Due to glyph substitution in the font (as specified in a font's `GSUB`
1235 table), which handles ligatures and similar typographic features, there
1236 is no longer a one-to-one mapping from an input Unicode character to a
1237 glyph index. Some ligatures, like 'fi', actually do have Unicode values
1238 for historical reasons, but most of them don't. While it is possible to
1239 map ligature glyphs into Unicode's Private Use Area (PUA), code values
1240 from this area are arbitrary by definition and thus unusable for
1243 * Some features like `sups` (for handling superscript) completely change
1244 the appearance and even vertical position of the affected glyphs.
1245 Obviously, the blue zones for 'normal' glyphs no longer fit, thus the
1246 auto-hinter puts them into a separate group (called *style* in FreeType
1247 speak), having its own set of blue zones.
1250 Table: OpenType features handled specially by ttfautohint
1252 Feature tag Description
1253 --------------- -------------
1254 `c2cp` petite capitals from capitals
1255 `c2sc` small capitals from capitals
1257 `pcap` petite capitals
1258 `sinf` scientific inferiors
1259 `smcp` small capitals
1265 There are two conditions to get a valid style for a feature in a given
1268 1. One of the script's standard characters must be available in the
1271 2. The feature must provide characters to form at least one blue zone; see
1272 [above](#blue-zones).
1274 An additional complication is that features from the above table might use
1275 data not only from the `GSUB` but also from the `GPOS` table, containing
1276 information for glyph positioning. For example, the `sups` feature for
1277 superscripts might use the same glyphs as the `subs` feature for subscripts,
1278 simply moved up. ttfautohint skips such vertically shifted glyphs (except
1279 for accessing standard characters) because glyph positioning happens after
1280 hinting. Continuing our example, the `sups` feature wouldn't form a style,
1281 contrary to `subs`, which holds the unshifted glyphs.
1283 The remaining OpenType features of a script are not handled specially; the
1284 affected glyphs are simply hinted together with the 'normal' glyphs of the
1287 Note that a font might still contain some features not covered yet: OpenType
1288 has the concept of a *default script*; its data gets used for all scripts
1289 that aren't explicitly handled in a font. By default, ttfautohint unifies
1290 all affected glyphs from default script features with the `latn` script.
1291 This can be changed with option [`--default-script`](#default-script), if
1295 ttfautohint uses the [HarfBuzz] library for handling OpenType features.
1301 ttfautohint touches almost all SFNT tables within a TrueType or OpenType
1302 font. Note that only OpenType fonts with TrueType outlines are supported.
1303 OpenType fonts with a `CFF` table (this is, with PostScript outlines) won't
1306 * `glyf`: All hints in the table are replaced with new ones. If option
1307 [`--composites`](#hint-composites) is used, one glyph gets added (namely
1308 the '\.ttfautohint' glyph) and all composites get an additional
1311 * `cvt`, `prep`, and `fpgm`: These tables get replaced with data
1312 necessary for the new hinting bytecode.
1314 * `gasp`: Set up to always use grayscale rendering, for all sizes, with
1315 grid-fitting for standard hinting, and symmetric grid-fitting and
1316 symmetric smoothing for horizontal subpixel hinting (ClearType).
1318 * `DSIG`: If it exists, it gets replaced with a dummy version.
1319 ttfautohint can't digitally sign a font; you have to do that afterwards.
1321 * `name`: The 'version' entries are modified to add information about the
1322 parameters that have been used for calling ttfautohint. This can be
1323 controlled with the [`--no-info`](#add-ttfautohint-info) option.
1325 * `GPOS`, `hmtx`, `loca`, `head`, `maxp`, `post`: Updated to fit the
1326 additional '\.ttfautohint' glyph, the additional subglyphs in
1327 composites, and the new hinting bytecode.
1329 * `LTSH`, `hdmx`: Since ttfautohint doesn't do any horizontal hinting,
1330 those tables are superfluous and thus removed.
1332 * `VDMX`: Removed, since it depends on the original bytecode, which
1333 ttfautohint removes. A font editor might recompute the necessary data
1340 ### Interaction With FreeType
1342 Recent versions of FreeType have an experimental extension for handling
1343 subpixel hinting; it is off by default and can be activated by defining the
1344 macro `TT_CONFIG_OPTION_SUBPIXEL_HINTING` at compile time. This code has
1345 been contributed mainly by [Infinality], being a subset of his original
1346 patch. Many GNU/Linux distributions activate this code, or provide packages
1349 This extension changes the behaviour of many bytecode instructions to get
1350 better rendering results. However, not all changes are global; some of them
1351 are specific to certain fonts. For example, it contains font-specific
1352 improvements for the '[DejaVu] Sans' font family. The list of affected
1353 fonts is hard-coded; it can be found in FreeType's source code file
1356 If you are going to process such specially-handled fonts with ttfautohint,
1357 serious rendering problems might show up. Since ttfautohint (intentionally)
1358 doesn't change the font name in the `name` table, the Infinality extension
1359 has no chance to recognize that the hints are different. All such problems
1360 vanish if the font gets renamed in its `name` table (the name of the font
1361 file itself doesn't matter).
1363 ### Incorrect Unicode Character Map
1365 Fonts with an incorrect Unicode `cmap` table will not be properly hinted by
1366 ttfautohint. Especially older fonts do cheat; for example, there exist
1367 Hebrew fonts that map its glyphs to character codes 'A', 'B', etc., to make
1368 them work with non-localized versions of Windows\ 98, say.
1370 Since ttfautohint needs to find both standard and blue zone characters, it
1371 relies on correct Unicode values. If you want to handle such fonts, please
1372 fix their `cmap` tables accordingly.
1374 ### Irregular Glyph Heights
1376 The central concept of ttfautohint's hinting algorithm, as discussed
1377 [above](#segments-and-edges), is to identify horizontal segments at extremum
1378 positions, especially for blue zones. If such a segment is missing, it
1379 cannot be associated with a blue zone, possibly leading to irregular heights
1380 for the particular glyph.
1382 Normally, a segment has a horizontal length of at least 20\ font units
1383 (assuming 2048 units per EM)^[To be more precise, the sum of the height and
1384 length of a segment must be at least 20 font units, and the height multiplied
1385 by\ 14 must not exceed the length. Thus (19,1) is also a valid minimum
1386 (length,height) pair, while (18,2) isn't. The value\ 20 is heuristic and
1387 hard-coded, as is the value\ 14 (corresponding to a slope of approx.
1388 4.1°).]. Using a [Control Instructions File](#control-instructions-file),
1389 however, it is possible to define additional segments at arbitrary points
1390 that help overcome this restriction, making it possible to fix (most of)
1395 ttfautohint doesn't handle diagonal lines specially. For thin outlines,
1396 this might lead to strokes that look too thick at smaller sizes. A font
1397 designer might compensate this to a certain amount by slightly reducing the
1398 stroke width of diagonal lines. However, in many cases the sub-optimal
1399 appearance of a stroke with borders that don't exactly fit the pixel grid is
1400 not the outline itself but an incorrect gamma value of the monitor: People
1401 tend to not properly adjust it, and the default values of most operating
1402 systems are too low, causing too much darkening of such strokes. It is thus
1403 of vital importance to compare ttfautohint's results with similar fonts to
1404 exclude any systematic effect not related to the outlines themselves.