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/TrueType-Reference-Manual/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 command-line binary, `ttfautohint`, works like a Unix filter, this is,
208 it reads data from standard input if no input file name is given, and it
209 sends its 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* (not in `ttfautohintGUI`)
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 (`ttfautohintGUI` 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 `arab` 'ل', U+0644, ARABIC LETTER LAM
819 'ح', U+062D, ARABIC LETTER HAH
820 'ـ', U+0640, ARABIC TATWEEL
821 `cyrl` 'о', U+043E, CYRILLIC SMALL LETTER O
822 'О', U+041E, CYRILLIC CAPITAL LETTER O
823 `deva` 'ठ', U+0920, DEVANAGARI LETTER TTHA
824 'व', U+0935, DEVANAGARI LETTER VA
825 'ट', U+091F, DEVANAGARI LETTER TTA
826 `grek` 'ο', U+03BF, GREEK SMALL LETTER OMICRON
827 'Ο', U+039F, GREEK CAPITAL LETTER OMICRON
828 `hebr` 'ם', U+05DD, HEBREW LETTER FINAL MEM
829 `latn` 'o', U+006F, LATIN SMALL LETTER O
830 'O', U+004F, LATIN CAPITAL LETTER O
831 '0', U+0030, DIGIT ZERO
832 `telu` 'ఙ', U+0C19, TELUGU LETTER NGA
833 'ఒ', U+0C12, TELUGU LETTER O
834 `thai` 'า', U+0E32, THAI CHARACTER SARA AA
835 'ๅ', U+0E45, THAI CHARACTER LAKKHANGYAO
836 '๐', U+0E50, THAI DIGIT ZERO
841 This is a per-glyph operation.
843 + Find segments and edges.
845 + Link edges together to find stems and serifs. The abovementioned
846 paper gives more details on what exactly constitutes a stem or a
847 serif and how the algorithm works.
853 ![Two blue zones relevant to the glyph 'a'. Vertical point coordinates of
854 *all* glyphs within these zones are aligned, provided the blue zone is
855 active (this is, its vertical size is smaller than
856 3/4\ pixels).](img/blue-zones)
858 Outlines of certain characters are used to determine *blue zones*. This
859 concept is the same as with Type\ 1 fonts: All glyph points that lie in
860 certain small horizontal zones get aligned vertically.
862 Here a series of tables that show the blue zone characters of the latin
863 writing system's available scripts; the values are hard-coded in the source
864 code. Since the auto-hinter takes mean values it is not necessary that all
865 characters of a zone are present.
868 Table: `arab` blue zones
870 ID Blue zone Characters
871 ---- ----------- ------------
872 1 top of letters with vertical stroke ا إ ل ك ط ظ
873 2 bottom of letter joining ت ث ط ظ ك
876 Table: `cyrl` blue zones
878 ID Blue zone Characters
879 ---- ----------- ------------
880 1 top of capital letters БВЕПЗОСЭ
881 2 bottom of capital letters БВЕШЗОСЭ
882 3 top of small letters хпншезос
883 4 bottom of small letters хпншезос
884 5 bottom of descenders of small letters руф
887 Table: `deva` blue zones
889 ID Blue zone Characters
890 ---- ----------- ------------
891 1 baseline (flat glyphs only) क न म उ छ ट ठ ड
892 2 top of ascenders ई ऐ ओ औ ि ी ो ौ
893 3 top of baseline क म अ आ थ ध भ श
894 4 bottom of descenders ु ृ
896 Contrary to scripts like latin, the baseline in Devanagari is on the top.
897 Note that some fonts have extreme variation in the height of the round
898 elements in Zone\ 3; for this reason we also define Zone\ 1, which must be
902 Table: `grek` blue zones
904 ID Blue zone Characters
905 ---- ----------- ------------
906 1 top of capital letters ΓΒΕΖΘΟΩ
907 2 bottom of capital letters ΒΔΖΞΘΟ
908 3 top of 'small beta' like letters βθδζλξ
909 4 top of small letters αειοπστω
910 5 bottom of small letters αειοπστω
911 6 bottom of descenders of small letters βγημρφχψ
914 Table: `hebr` blue zones
916 ID Blue zone Characters
917 ---- ----------- ------------
918 1 top of letters בדהחךכםס
919 2 bottom of letters בטכםסצ
920 3 bottom of descenders of letters קךןףץ
923 Table: `latn` blue zones
925 ID Blue zone Characters
926 ---- ----------- ------------
927 1 top of capital letters THEZOCQS
928 2 bottom of capital letters HEZLOCUS
929 3 top of 'small f' like letters fijkdbh
930 4 top of small letters xzroesc
931 5 bottom of small letters xzroesc
932 6 bottom of descenders of small letters pqgjy
934 The 'round' characters (e.g. 'OCQS') from Zones 1, 2, and\ 5 are also used
935 to control the overshoot handling; to improve rendering at small sizes,
936 zone\ 4 gets adjusted to be on the pixel grid; cf. the
937 [`--increase-x-height`](#x-height-increase-limit) option.
940 Table: `telu` blue zones
942 ID Blue zone Characters
943 ---- ----------- ------------
945 2 bottom అ క చ ర ఽ ౨ ౬
948 Table: `thai` blue zones
950 ID Blue zone Characters
951 ---- ----------- ------------
953 2 bottom บ ป ษ ฯ อ ย ฮ
955 4 large ascender โ ใ ไ
957 6 large descender ญ ฐ
958 7 top of Thai digits ๐ ๑ ๓
961 ![This image shows the relevant glyph terms for vertical blue zone
962 positions.](img/glyph-terms)
968 Aligning outlines along the grid lines is called *grid fitting*. It doesn't
969 necessarily mean that the outlines are positioned *exactly* on the grid,
970 however, especially if you want a smooth appearance at different sizes.
971 This is the central routine of the auto-hinter; its actions are highly
972 dependent on the used writing system. Currently, only one writing system is
973 available (latin), providing support for scripts like Latin or Greek.
975 * Align edges linked to blue zones.
977 * Fit edges to the pixel grid.
981 * Handle remaining 'strong' points. Such points are not part of an edge
982 but are still important for defining the shape. This roughly
983 corresponds to the `IP` TrueType instruction.
985 * Everything else (the 'weak' points) is handled with an `IUP`
988 The following images illustrate the hinting process, using glyph 'a' from
989 the freely available font '[Ubuntu Book](http://font.ubuntu.com)'. The
990 manual hints were added by [Dalton Maag Ltd], the used application to create
991 the hinting debug snapshots was [FontForge].
993 ![Before hinting.](img/a-before-hinting.png)
995 ![After hinting, using manual hints.](img/a-after-hinting.png)
997 ![After hinting, using ttfautohint. Note that the hinting process
998 doesn't change horizontal positions.](img/a-after-autohinting.png)
1004 In ttfautohint terminology, a *hint set* is the *optimal* configuration for
1005 a given PPEM (pixel per EM) value.
1007 In the range given by the `--hinting-range-min` and `--hinting-range-max`
1008 options, ttfautohint creates hint sets for every PPEM value. For each
1009 glyph, ttfautohint automatically determines whether a new set should be
1010 emitted for a PPEM value if it finds that it differs from a previous one.
1011 For some glyphs it is possible that one set covers, say, the range
1012 8px-1000px, while other glyphs need 10 or more such sets.
1014 In the PPEM range below `--hinting-range-min`, ttfautohint always uses just
1015 one set, in the PPEM range between `--hinting-range-max` and
1016 `--hinting-limit`, it also uses just one set.
1018 One of the hinting configuration parameters is the decision which segments
1019 form an edge. For example, let us assume that two segments get aligned on a
1020 single horizontal edge at 11px, while two edges are used at 12px. This
1021 change makes ttfautohint emit a new hint set to accomodate this situation.
1022 The next images illustrate this, using a Cyrillic letter (glyph 'afii10108')
1023 from the 'Ubuntu book' font, processed with ttfautohint.
1025 ![Before hinting, size 11px.](img/afii10108-11px-before-hinting.png)
1027 ![After hinting, size 11px. Segments 43-27-28 and 14-15 are aligned on a
1028 single edge, as are segments 26-0-1 and
1029 20-21.](img/afii10108-11px-after-hinting.png)
1031 ![Before hinting, size 12px.](img/afii10108-12px-before-hinting.png)
1033 ![After hinting, size 12px. The segments are not aligned. While
1034 segments 43-27-28 and 20-21 now have almost the same horizontal position,
1035 they don't form an edge because the outlines passing through the segments
1036 point into different directions.](img/afii10108-12px-after-hinting.png)
1038 Obviously, the more hint sets get emitted, the larger the bytecode
1039 ttfautohint adds to the output font. To find a good value\ *n* for
1040 `--hinting-range-max`, some experimentation is necessary since *n* depends
1041 on the glyph shapes in the input font. If the value is too low, the hint
1042 set created for the PPEM value\ *n* (this hint set gets used for all larger
1043 PPEM values) might distort the outlines too much in the PPEM range given
1044 by\ *n* and the value set by `--hinting-limit` (at which hinting gets
1045 switched off). If the value is too high, the font size increases due to
1046 more hint sets without any noticeable hinting effects.
1048 Similar arguments hold for `--hinting-range-min` except that there is no
1049 lower limit at which hinting is switched off.
1051 An example. Let's assume that we have a hinting range 10\ <= ppem <=\ 100,
1052 and the hinting limit is set to 250. For a given glyph, ttfautohint finds
1053 out that four hint sets must be computed to exactly cover this hinting
1054 range: 10-15, 16-40, 41-80, and 81-100. For ppem values below 10ppem, the
1055 hint set covering 10-15ppem is used, for ppem values larger than 100 the
1056 hint set covering 81-100ppem is used. For ppem values larger than 250, no
1057 hinting gets applied.
1063 The ttfautohint library (and programs) supports two solutions for handling
1064 composite glyphs, to be controlled with option
1065 [`--composites`](#hint-composites). This section contains some general
1066 information, then covers the case where the option is off, while the next
1067 section describes how ttfautohint behaves if this option is activated.
1069 Regardless of the `--composites` option, ttfautohint performs a scan over
1070 all composite glyphs to assure that components of a composite glyph inherit
1071 its style, as described [later](#opentype-features). However, components
1072 that are shifted vertically will be skipped. For example, if the glyph
1073 'Agrave' uses a shifted 'grave' accent glyph, the accent is ignored. On the
1074 other hand, if there is a glyph 'agrave' that uses the same 'grave' glyph
1075 vertically unshifted, 'grave' does inherit the style.
1077 If `--composites` is off, components are hinted separately, then put
1078 together. Separate hinting implies that the current style's blue zones are
1079 applied to all subglyphs in its original, unshifted positions. In case you
1080 want to shift components vertically, it is *mandatory* to set bit\ 2
1081 (value\ 4), `ROUND_XY_TO_GRID`, in the flag variable of the composite glyph
1082 description to get visually pleasing results, as the images below
1085 ![Here, the subscript glyphs are composites each having a single element
1086 that is shifted down. If option `--composites` is not used, subglyphs are
1087 hinted before they are glued together (possibly applying scaling and
1088 shifting). Because the `ROUND_XY_TO_GRID` flag isn't set, the vertical
1089 translation doesn't align the subglyph to the pixel grid, causing severe
1090 distortions.](img/composite-no-round-xy-to-grid.png)
1092 ![The same as before, but with `ROUND_XY_TO_GRID` set. Now the subscript
1093 glyphs look identical to the
1094 superscripts.](img/composite-round-xy-to-grid.png)
1096 ![For comparison purposes, here the result *with* option `--composites` (and
1097 no `ROUND_XY_TO_GRID`). The composite glyphs as a whole get hinted;
1098 consequently, the subscript glyphs get separate blue zones. At the
1099 displayed size of 16ppem the vertical positions of the subscript blue
1100 zones are rounded differently if compared to the superscript zones, thus
1101 the smaller glyph height.](img/composite-no-round-xy-to-grid-option-c.png)
1104 The '\.ttfautohint' Glyph
1105 -------------------------
1107 If option [`--composites`](#hint-composites) is used, ttfautohint doesn't
1108 hint subglyphs of composite glyphs separately. Instead, it hints the whole
1109 glyph, this is, composites get recursively expanded internally so that they
1110 form simple glyphs, then hints are applied -- this is the normal working
1111 mode of FreeType's auto-hinter.
1113 One problem, however, must be solved: Hinting for subglyphs (which usually
1114 are used as normal glyphs also) must be deactivated so that nothing but the
1115 final bytecode of the composite gets executed.
1117 The trick used by ttfautohint is to prepend a composite element called
1118 '\.ttfautohint', a dummy glyph with a single point, and which has a single
1119 job: Its bytecode increases a variable (to be more precise, it is a CVT
1120 register called `cvtl_is_subglyph` in the source code), indicating that we
1121 are within a composite glyph. The final bytecode of the composite glyph
1122 eventually decrements this variable again.
1124 As an example, let's consider composite glyph 'Agrave' ('À'), which has the
1125 subglyph 'A' as the base and 'grave' as its accent. After processing with
1126 ttfautohint it consists of three components: '\.ttfautohint', 'A', and
1127 'grave' (in this order).
1130 ------------- --------
1131 .ttfautohint increase `cvtl_is_subglyph` (now: 1)
1132 A do nothing because `cvtl_is_subglyph` > 0
1133 grave do nothing because `cvtl_is_subglyph` > 0
1134 Agrave decrease `cvtl_is_subglyph` (now: 0)\
1135 apply hints because `cvtl_is_subglyph` == 0
1137 Some technical details (which you might skip): All glyph point indices get
1138 adjusted since each '\.ttfautohint' subglyph shifts all following indices by
1139 one. This must be done for both the bytecode and one subformat of
1140 OpenType's `GPOS` anchor tables.
1142 While this approach works fine on all tested platforms, there is one single
1143 drawback: Direct rendering of the '\.ttfautohint' subglyph (this is,
1144 rendering as a stand-alone glyph) disables proper hinting of all glyphs in
1145 the font! Under normal circumstances this never happens because
1146 '\.ttfautohint' doesn't have an entry in the font's `cmap` table. (However,
1147 some test and demo programs like FreeType's `ftview` application or other
1148 glyph viewers that are able to bypass the `cmap` table might be affected.)
1154 In FreeType terminology, a writing system is a set of functions that
1155 provides auto-hinting for certain scripts. Right now, only two writing
1156 systems from FreeType's auto-hinter are available in ttfautohint: 'dummy'
1157 and 'latin'. The former handles the 'no-script' case; details to 'latin'
1158 follow in the next section.
1164 ttfautohint needs to know which script should be used to hint a specific
1165 glyph. To do so, it checks a glyph's Unicode character code whether it
1166 belongs to a given script.
1168 Here is the hardcoded list of character ranges that are used for scripts in
1169 the 'latin' writing system. As you can see, this also covers some non-latin
1170 scripts (in the Unicode sense) that have similar typographical properties.
1172 In ttfautohint, scripts are identified by four-character tags. The value
1173 `none` indicates 'no script'.
1176 Table: `arab` character ranges
1178 Character range Description
1179 --------------------- -------------
1180 `0x0600` - `0x06FF` Arabic
1181 `0x0750` - `0x07FF` Arabic Supplement
1182 `0x08A0` - `0x08FF` Arabic Extended-A
1183 `0xFB50` - `0xFDFF` Arabic Presentation Forms-A
1184 `0xFE70` - `0xFEFF` Arabic Presentation Forms-B
1185 `0x1EE00` - `0x1EEFF` Arabic Mathematical Alphabetic Symbols
1188 Table: `cyrl` character ranges
1190 Character range Description
1191 --------------------- -------------
1192 `0x0400` - `0x04FF` Cyrillic
1193 `0x0500` - `0x052F` Cyrillic Supplement
1194 `0x2DE0` - `0x2DFF` Cyrillic Extended-A
1195 `0xA640` - `0xA69F` Cyrillic Extended-B
1198 Table: `deva` character ranges
1200 Character range Description
1201 --------------------- -------------
1202 `0x0900` - `0x093B` Devanagari
1203 (omitting U+093C nukta)
1204 `0x093D` - `0x0950` Devanagari cont'd
1205 (omitting U+0951 udatta, U+0952 anudatta)
1206 `0x0953` - `0x0963` Devanagari cont'd
1207 (omitting U+0964 danda, U+0965 double danda)
1208 `0x0966` - `0x097F` Devanagari cont'd
1209 `0x20B9` (new) Rupee sign
1211 There are some characters in the Devanagari Unicode block that are generic
1212 to Indic scripts; we omit them so that their presence doesn't trigger
1216 Table: `grek` character ranges
1218 Character range Description
1219 --------------------- -------------
1220 `0x0370` - `0x03FF` Greek and Coptic
1221 `0x1F00` - `0x1FFF` Greek Extended
1224 Table: `hebr` character ranges
1226 Character range Description
1227 --------------------- -------------
1228 `0x0590` - `0x05FF` Hebrew
1229 `0xFB1D` - `0xFB4F` Alphabetic Presentation Forms (Hebrew)
1232 Table: `latn` character ranges
1234 Character range Description
1235 --------------------- -------------
1236 `0x0020` - `0x007F` Basic Latin (no control characters)
1237 `0x00A0` - `0x00FF` Latin-1 Supplement (no control characters)
1238 `0x0100` - `0x017F` Latin Extended-A
1239 `0x0180` - `0x024F` Latin Extended-B
1240 `0x0250` - `0x02AF` IPA Extensions
1241 `0x02B0` - `0x02FF` Spacing Modifier Letters
1242 `0x0300` - `0x036F` Combining Diacritical Marks
1243 `0x1D00` - `0x1D7F` Phonetic Extensions
1244 `0x1D80` - `0x1DBF` Phonetic Extensions Supplement
1245 `0x1DC0` - `0x1DFF` Combining Diacritical Marks Supplement
1246 `0x1E00` - `0x1EFF` Latin Extended Additional
1247 `0x2000` - `0x206F` General Punctuation
1248 `0x2070` - `0x209F` Superscripts and Subscripts
1249 `0x20A0` - `0x20CF` Currency Symbols
1250 `0x2150` - `0x218F` Number Forms
1251 `0x2460` - `0x24FF` Enclosed Alphanumerics
1252 `0x2C60` - `0x2C7F` Latin Extended-C
1253 `0x2E00` - `0x2E7F` Supplemental Punctuation
1254 `0xA720` - `0xA7FF` Latin Extended-D
1255 `0xFB00` - `0xFB06` Alphabetical Presentation Forms (Latin Ligatures)
1256 `0x1D400` - `0x1D7FF` Mathematical Alphanumeric Symbols
1257 `0x1F100` - `0x1F1FF` Enclosed Alphanumeric Supplement
1260 Table: `telu` character ranges
1262 Character range Description
1263 --------------------- -------------
1264 `0x0C00` - `0x0C7F` Telugu
1267 Table: `thai` character ranges
1269 Character range Description
1270 --------------------- -------------
1271 `0x0E00` - `0x0E7F` Thai
1274 If a glyph's character code is not covered by a script range, it is not
1275 hinted (or rather, it gets hinted by the 'dummy' auto-hinting module that
1276 essentially does nothing). This can be changed by specifying a *fallback
1277 script*; see option [`--fallback-script`](#fallback-script).
1283 (Please read the [OpenType specification] for details on *features*, `GSUB`,
1284 and `GPOS` tables, and how they relate to scripts.)
1286 For modern OpenType fonts, character ranges are not sufficient to handle
1289 * Due to glyph substitution in the font (as specified in a font's `GSUB`
1290 table), which handles ligatures and similar typographic features, there
1291 is no longer a one-to-one mapping from an input Unicode character to a
1292 glyph index. Some ligatures, like 'fi', actually do have Unicode values
1293 for historical reasons, but most of them don't. While it is possible to
1294 map ligature glyphs into Unicode's Private Use Area (PUA), code values
1295 from this area are arbitrary by definition and thus unusable for
1298 * Some features like `sups` (for handling superscript) completely change
1299 the appearance and even vertical position of the affected glyphs.
1300 Obviously, the blue zones for 'normal' glyphs no longer fit, thus the
1301 auto-hinter puts them into a separate group (called *style* in FreeType
1302 speak), having its own set of blue zones.
1305 Table: OpenType features handled specially by ttfautohint
1307 Feature tag Description
1308 --------------- -------------
1309 `c2cp` petite capitals from capitals
1310 `c2sc` small capitals from capitals
1312 `pcap` petite capitals
1313 `sinf` scientific inferiors
1314 `smcp` small capitals
1320 There are two conditions to get a valid style for a feature in a given
1323 1. One of the script's standard characters must be available in the
1326 2. The feature must provide characters to form at least one blue zone; see
1327 [above](#blue-zones).
1329 An additional complication is that features from the above table might use
1330 data not only from the `GSUB` but also from the `GPOS` table, containing
1331 information for glyph positioning. For example, the `sups` feature for
1332 superscripts might use the same glyphs as the `subs` feature for subscripts,
1333 simply moved up. ttfautohint skips such vertically shifted glyphs (except
1334 for accessing standard characters) because glyph positioning happens after
1335 hinting. Continuing our example, the `sups` feature wouldn't form a style,
1336 contrary to `subs`, which holds the unshifted glyphs.
1338 The remaining OpenType features of a script are not handled specially; the
1339 affected glyphs are simply hinted together with the 'normal' glyphs of the
1342 Note that a font might still contain some features not covered yet: OpenType
1343 has the concept of a *default script*; its data gets used for all scripts
1344 that aren't explicitly handled in a font. By default, ttfautohint unifies
1345 all affected glyphs from default script features with the `latn` script.
1346 This can be changed with option [`--default-script`](#default-script), if
1350 ttfautohint uses the [HarfBuzz] library for handling OpenType features.
1356 ttfautohint touches almost all SFNT tables within a TrueType or OpenType
1357 font. Note that only OpenType fonts with TrueType outlines are supported.
1358 OpenType fonts with a `CFF` table (this is, with PostScript outlines) won't
1361 * `glyf`: All hints in the table are replaced with new ones. If option
1362 [`--composites`](#hint-composites) is used, one glyph gets added (namely
1363 the '\.ttfautohint' glyph) and all composites get an additional
1366 * `cvt`, `prep`, and `fpgm`: These tables get replaced with data
1367 necessary for the new hinting bytecode.
1369 * `gasp`: Set up to always use grayscale rendering, for all sizes, with
1370 grid-fitting for standard hinting, and symmetric grid-fitting and
1371 symmetric smoothing for horizontal subpixel hinting (ClearType).
1373 * `DSIG`: If it exists, it gets replaced with a dummy version.
1374 ttfautohint can't digitally sign a font; you have to do that afterwards.
1376 * `name`: The 'version' entries are modified to add information about the
1377 parameters that have been used for calling ttfautohint. This can be
1378 controlled with the [`--no-info`](#add-ttfautohint-info) option.
1380 * `GPOS`, `hmtx`, `loca`, `head`, `maxp`, `post`: Updated to fit the
1381 additional '\.ttfautohint' glyph, the additional subglyphs in
1382 composites, and the new hinting bytecode.
1384 * `LTSH`, `hdmx`: Since ttfautohint doesn't do any horizontal hinting,
1385 those tables are superfluous and thus removed.
1387 * `VDMX`: Removed, since it depends on the original bytecode, which
1388 ttfautohint removes. A font editor might recompute the necessary data
1395 ### Interaction With FreeType
1397 Recent versions of FreeType have an experimental extension for handling
1398 subpixel hinting; it is off by default and can be activated by defining the
1399 macro `TT_CONFIG_OPTION_SUBPIXEL_HINTING` at compile time. This code has
1400 been contributed mainly by [Infinality], being a subset of his original
1401 patch. Many GNU/Linux distributions activate this code, or provide packages
1404 This extension changes the behaviour of many bytecode instructions to get
1405 better rendering results. However, not all changes are global; some of them
1406 are specific to certain fonts. For example, it contains font-specific
1407 improvements for the '[DejaVu] Sans' font family. The list of affected
1408 fonts is hard-coded; it can be found in FreeType's source code file
1411 If you are going to process such specially-handled fonts with ttfautohint,
1412 serious rendering problems might show up. Since ttfautohint (intentionally)
1413 doesn't change the font name in the `name` table, the Infinality extension
1414 has no chance to recognize that the hints are different. All such problems
1415 vanish if the font gets renamed in its `name` table (the name of the font
1416 file itself doesn't matter).
1418 ### Incorrect Unicode Character Map
1420 Fonts with an incorrect Unicode `cmap` table will not be properly hinted by
1421 ttfautohint. Especially older fonts do cheat; for example, there exist
1422 Hebrew fonts that map its glyphs to character codes 'A', 'B', etc., to make
1423 them work with non-localized versions of Windows\ 98, say.
1425 Since ttfautohint needs to find both standard and blue zone characters, it
1426 relies on correct Unicode values. If you want to handle such fonts, please
1427 fix their `cmap` tables accordingly.
1429 ### Irregular Glyph Heights
1431 The central concept of ttfautohint's hinting algorithm, as discussed
1432 [above](#segments-and-edges), is to identify horizontal segments at extremum
1433 positions, especially for blue zones. If such a segment is missing, it
1434 cannot be associated with a blue zone, possibly leading to irregular heights
1435 for the particular glyph.
1437 Normally, a segment has a horizontal length of at least 20\ font units
1438 (assuming 2048 units per EM)^[To be more precise, the sum of the height and
1439 length of a segment must be at least 20 font units, and the height multiplied
1440 by\ 14 must not exceed the length. Thus (19,1) is also a valid minimum
1441 (length,height) pair, while (18,2) isn't. The value\ 20 is heuristic and
1442 hard-coded, as is the value\ 14 (corresponding to a slope of approx.
1443 4.1°).]. Using a [Control Instructions File](#control-instructions-file),
1444 however, it is possible to define additional segments at arbitrary points
1445 that help overcome this restriction, making it possible to fix (most of)
1450 ttfautohint doesn't handle diagonal lines specially. For thin outlines,
1451 this might lead to strokes that look too thick at smaller sizes. A font
1452 designer might compensate this to a certain amount by slightly reducing the
1453 stroke width of diagonal lines. However, in many cases the sub-optimal
1454 appearance of a stroke with borders that don't exactly fit the pixel grid is
1455 not the outline itself but an incorrect gamma value of the monitor: People
1456 tend to not properly adjust it, and the default values of most operating
1457 systems are too low, causing too much darkening of such strokes. It is thus
1458 of vital importance to compare ttfautohint's results with similar fonts to
1459 exclude any systematic effect not related to the outlines themselves.