| blob | eee714c180913c47217284fe661bdd5ea773907e |
1 % ttfautohint
2 % Werner Lemberg
3 %
5 <!--
6 Copyright (C) 2011-2020 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.
15 -->
18 ---
19 header-includes:
20 - \hyphenation{ttf-auto-hint}
21 ---
24 Introduction
25 ============
27 **ttfautohint** is a library written in\ C that takes a TrueType font as
28 the input, removes its bytecode instructions (if any), and returns a new
29 font where all glyphs are bytecode hinted using the information given by
30 FreeType's auto-hinting module. The idea is to provide the excellent
31 quality of the auto-hinter on platforms that don't use FreeType.
33 The library has a central API function, `TTF_autohint`, which is described
34 [below](#the-ttfautohint-api).
36 Bundled with the library there are two front-end programs, [`ttfautohint`
37 and `ttfautohintGUI`](#ttfautohint-and-ttfautohintgui), being a command line
38 program and an application with a Graphics User Interface (GUI),
39 respectively.
42 What exactly are hints?
43 -----------------------
45 To cite [Wikipedia](https://en.wikipedia.org/wiki/Font_hinting):
47 > **Font hinting** (also known as **instructing**) is the use of
48 > mathematical instructions to adjust the display of an outline font so that
49 > it lines up with a rasterized grid. At low screen resolutions, hinting is
50 > critical for producing a clear, legible text. It can be accompanied by
51 > antialiasing and (on liquid crystal displays) subpixel rendering for
52 > further clarity.
54 and Apple's [TrueType Reference
55 Manual](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM03/Chap3.html#features):
57 > For optimal results, a font instructor should follow these guidelines:
58 >
59 > - At small sizes, chance effects should not be allowed to magnify small
60 > differences in the original outline design of a glyph.
61 >
62 > - At large sizes, the subtlety of the original design should emerge.
64 In general, there are three possible ways to hint a glyph.
66 1. The font contains hints (in the original sense of this word) to guide
67 the rasterizer, telling it which shapes of the glyphs need special
68 consideration. The hinting logic is partly in the font and partly in
69 the rasterizer. More sophisticated rasterizers are able to produce
70 better rendering results.
72 This is how PostScript Type\ 1 and CFF hints work.
74 2. The font contains exact instructions (also called *bytecode*) on how to
75 move the points of its outlines, depending on the resolution of the
76 output device, and which intentionally distort the (outline) shape to
77 produce a well-rasterized result. The hinting logic is in the font;
78 ideally, all rasterizers simply process these instructions to get the
79 same result on all platforms.
81 This is how TrueType hints work.
83 3. The font gets auto-hinted (at run-time). The hinting logic is
84 completely in the rasterizer. No hints in the font are used or needed;
85 instead, the rasterizer scans and analyzes the glyphs to apply
86 corrections by itself.
88 This is how FreeType's auto-hinter works; see
89 [below](#background-and-technical-details) for more.
92 What problems can arise with TrueType hinting?
93 ----------------------------------------------
95 While it is relatively easy to specify PostScript hints (either manually or
96 by an auto-hinter that works at font creation time), creating TrueType
97 hints is far more difficult. There are at least two reasons:
99 - TrueType instructions form a programming language, operating at a very
100 low level. They are comparable to assembler code, thus lacking all
101 high-level concepts to make programming more comfortable.
103 Here an example how such code looks like:
105 ```
106 SVTCA[0]
107 PUSHB[ ] /* 3 values pushed */
108 18 1 0
109 CALL[ ]
110 PUSHB[ ] /* 2 values pushed */
111 15 4
112 MIRP[01001]
113 PUSHB[ ] /* 3 values pushed */
114 7 3 0
115 CALL[ ]
116 ```
118 Another major obstacle is the fact that font designers usually aren't
119 programmers.
121 - It is very time consuming to manually hint glyphs. Given that the
122 number of specialists for TrueType hinting is very limited, hinting a
123 large set of glyphs for a font or font family can become very expensive.
126 Why ttfautohint?
127 ----------------
129 The ttfautohint library brings the excellent quality of FreeType rendering
130 to platforms that don't use FreeType, yet require hinting for text to look
131 good -- like Microsoft Windows. Roughly speaking, it converts the glyph
132 analysis done by FreeType's auto-hinting module to TrueType bytecode.
133 Internally, the auto-hinter's algorithm resembles PostScript hinting
134 methods; it thus combines all three hinting methods discussed
135 [previously](#what-exactly-are-hints).
137 The simple interface of the front-ends (both on the command line and with
138 the GUI) allows quick hinting of a whole font with a few mouse clicks or a
139 single command on the prompt. As a result, you get better rendering results
140 with web browsers, for example.
142 Across Windows rendering environments today, fonts processed with
143 ttfautohint look best with ClearType enabled. This is the default for
144 Windows\ 7 and higher. Good visual results are also seen in recent MacOS\ X
145 versions and GNU/Linux systems (including Android, ChromeOS, and other
146 mobile operating systems) that use FreeType for rendering glyphs.
149 'Smooth' hinting
150 ----------------
152 Fundamentally, there are two approaches to hinting. The older approach,
153 let's call it 'sharp', popular when text was rendered in pure
154 black-and-white, was to make all stems round to full pixels so that in a
155 text line, all stems would be either one pixel or (at a larger point size)
156 two pixels. When grayscale antialiasing came about, this approach actually
157 started harming the rendering rather than helping it, because the horizontal
158 and vertical stems would render very dark but round or diagonal stems would
159 render very light.
161 So a new approach was developed, let's call it 'fuzzy', where all stems and
162 other elements are equalized so that in grayscale (or ClearType) rendering,
163 they all are of roughly equal color. This means that stems are not rounded
164 to full pixels but in fact to fractions of a pixel. However, with
165 black-and-white renderers, this approach yields poor results because in
166 black-and-white you cannot render a fraction of a pixel, so some stems
167 become one pixel and some become two.
169 The TrueType auto-hinters in [FontForge] and [FontLab Studio], to name two
170 well-known font editors, take the 'sharp' approach, while the TrueType
171 auto-hinter in ttfautohint takes the 'fuzzy' approach.
173 In theory, a hybrid approach is possible, using TrueType conditional hints:
174 If the rasterizer is black-and-white, 'sharp' rendering could happen, while
175 if the rasterizer is ClearType, the 'fuzzy' rendering could be used. It is
176 not intended to add black-and-white auto-hinting to ttfautohint. However,
177 it is planned to develop an interface so that ttfautohint can cooperate with
178 font editors, providing this hybrid hinting.
182 `ttfautohint` and `ttfautohintGUI`
183 ==================================
185 On all supported platforms (GNU/Linux, Windows, and Mac OS\ X), the GUI
186 looks quite similar; the used toolkit is [Qt], which in turn uses the
187 platform's native widgets.
189 
191 Both the GUI and console version share the same features, to be discussed in
192 the next subsection.
194 **Warning: ttfautohint cannot always process a font a second time.**
195 If the font contains composite glyphs, and option [`-c`](#hint-composites)
196 is used, reprocessing with ttfautohint will fail. For this reason it is
197 strongly recommended to *not* delete the original, unhinted font so that you
198 can always rerun ttfautohint.
201 Calling `ttfautohint`
202 ---------------------
204 ```
205 ttfautohint [OPTION]... [IN-FILE [OUT-FILE]]
206 ```
208 The command-line binary, `ttfautohint`, works like a Unix filter, this is,
209 it reads data from standard input if no input file name is given, and it
210 sends its output to standard output if no output file name is specified.
212 A typical call looks like the following.
214 ```
215 ttfautohint -v -t -m foo-control.txt foo.ttf foo-autohinted.ttf
216 ```
218 For demonstration purposes, here the same using a pipe and redirection.
219 Note that Windows's default command line interpreter, `cmd.exe`, doesn't
220 support piping with binary files, unfortunately.
222 ```
223 cat foo.ttf | ttfautohint -v -t -m foo-control.txt > foo-autohinted.ttf
224 ```
227 Calling `ttfautohintGUI`
228 ------------------------
230 ```
231 ttfautohintGUI [OPTION]...
232 ```
234 `ttfautohintGUI` doesn't send any output to a console; however, it accepts
235 (almost) the same command line options as `ttfautohint` to provide
236 customized default values of the GUI.
238 The following command line options are not available in `ttfautohintGUI`:
239 [`--control-file`](#control-instructions-file),
240 [`--reference`](#blue-zone-reference-font),
241 [`--reference-index`](#reference-face-index). Note, however, that the
242 corresponding functionality can be selected interactively.
244 Two options, namely `--ttfa-info` and `--debug`, emit information at
245 standard output and standard error, respectively; they are thus not
246 available in `ttfautohintGUI`, too, and there is no corresponding GUI
247 functionality either.
250 Options
251 -------
253 Long options can be given with one or two dashes, and with and without an
254 equal sign between option and argument. This means that the following forms
255 are acceptable: `-foo=`*bar*, `--foo=`*bar*, `-foo`\ *bar*, and
256 `--foo`\ *bar*.
258 Below, the section title refers to the command's label in the GUI (if
259 applicable), then comes the name of the corresponding long command line
260 option and its short equivalent, followed by a description.
262 Background and technical details on the meaning of the various options are
263 given [afterwards](#background-and-technical-details).
265 ### Control Instructions File
267 `--control-file=`*file*, `-m`\ *file*
268 : Specify the name of a control instructions file to manually tweak the
269 hinting process. This feature can be used to correct glitches in
270 ttfautohint's hinting algorithm. The syntax used in a control
271 instructions file is given [below](#control-instructions).
273 `ttfautohintGUI` doesn't have this command line option.
275 ### Blue Zone Reference Font
277 `--reference=`*file*, `-R`\ *file*
278 : Derive all blue zones from the given font, which can either be a normal
279 TrueType font or a TrueType collection – for the latter you can select
280 the face index with a [separate option](#reference-face-index).
282 Use this to harmonize font families, avoiding ugly height differences at
283 small sizes.
285 
290 To make this work the reference font must obviously be similar enough to
291 the font to be hinted; in particular, it must have proper blue zone
292 characters so that ttfautohint can derive blue zones at all.
294 `ttfautohintGUI` doesn't have this command line option.
296 ### Hint Set Range Minimum, Hint Set Range Maximum
298 See '[Hint Sets](#hint-sets)' for a definition and explanation.
300 `--hinting-range-min=`*n*, `-l`\ *n*
301 : The minimum PPEM value (in pixels) at which hint sets are created. The
302 default value for *n* is\ 8.
304 `--hinting-range-max=`*n*, `-r`\ *n*
305 : The maximum PPEM value (in pixels) at which hint sets are created. The
306 default value for *n* is 50.
308 Increasing the range given by `-l` and `-r` normally makes the font's
309 bytecode larger.
311 ### Default Script
313 `--default-script=`*s*, `-D`\ *s*
314 : Set default script to tag *s*, which is a string consisting of four
315 lowercase characters like `latn` or `dflt`. It is needed to specify the
316 OpenType default script: After applying all features that are handled
317 specially (like small caps or superscript), ttfautohint uses this value
318 for the remaining features. The default value is `latn`. See
319 [below](#opentype-features) for more details.
321 ### Fallback Script
323 `--fallback-script=`*s*, `-f`\ *s*
324 : Set fallback script to tag *s*, which is a string consisting of four
325 characters like `latn` or `dflt`. It gets used for all glyphs that
326 can't be assigned to a script automatically. The default value is
327 `none`. See [below](#scripts) for more details.
329 `--fallback-scaling`, `-S`
330 : Use scaling for glyphs covered by the fallback script, not hinting. See
331 [below](#scripts) for more details.
333 ### Hinting Limit
335 `--hinting-limit=`*n*, `-G`\ *n*
336 : The *hinting limit* is the PPEM value (in pixels) where hinting gets
337 switched off (using the `INSTCTRL` bytecode instruction, not the `gasp`
338 table data); it does not influence the file size. The default value for
339 *n* is 200, which means that the font is not hinted for PPEM values
340 larger than 200.
342 Note that hinting in the range 'hinting-range-max' up to 'hinting-limit'
343 uses the hinting configuration for 'hinting-range-max'.
345 To omit a hinting limit, use `--hinting-limit=0` (or check the 'No
346 Hinting Limit' box in the GUI). Since this causes internal math
347 overflow in the rasterizer for large pixel values (>\ 1500px approx.) it
348 is strongly recommended to not use this except for testing purposes.
350 ### x Height Increase Limit
352 `--increase-x-height=`*n*, `-x`\ *n*
353 : Normally, ttfautohint rounds the x\ height to the pixel grid, with a
354 slight preference for rounding up (to use the terminology of TrueType's
355 'Super Round' bytecode instruction, the threshold is 5/8px). If this
356 flag is set, values in the PPEM range 6 to\ *n* are much more often
357 rounded up (setting the threshold to 13/16px). The default value for
358 *n* is 14. Use this flag to increase the legibility of small sizes if
359 necessary; you might get weird rendering results otherwise for glyphs
360 like 'a' or 'e', depending on the font design.
362 To switch off this feature, use `--increase-x-height=0` (or check the
363 'No x\ Height Increase' box in the GUI). To switch off rounding the
364 x\ height to the pixel grid in general, either partially or completely,
365 see '[x Height Snapping Exceptions](#x-height-snapping-exceptions)'.
367 The following FontForge snapshot images use the font '[Mertz
368 Bold](https://github.com/vernnobile/mertzFont/tree/master/FINAL/Mertz-Bold)'
369 from Vernon Adams.
371 
379 
382 ### x Height Snapping Exceptions
384 `--x-height-snapping-exceptions=`*string*, `-X`\ *string*
385 : A list of comma separated PPEM values or value ranges at which no
386 x\ height snapping shall be applied. A value range has the form
387 *value*~1~`-`*value*~2~, meaning *value*~1~\ <= PPEM <=\ *value*~2~.
388 *value*~1~ or *value*~2~ (or both) can be missing; a missing value is
389 replaced by the beginning or end of the whole interval of valid PPEM
390 values, respectively (6\ to 32767). Whitespace is not significant;
391 superfluous commas are ignored, and ranges must be specified in
392 increasing order. For example, the string `"7-9, 11, 13-"` means the
393 values 7, 8, 9, 11, 13, 14, 15, etc. Consequently, if the supplied
394 argument is `"-"`, no x\ height snapping takes place at all. The
395 default is the empty string (`""`), meaning no snapping exceptions.
397 Normally, x\ height snapping means a slight increase in the overall
398 vertical glyph size so that the height of lowercase glyphs gets aligned
399 to the pixel grid (this is a global feature, affecting *all* glyphs of a
400 font). However, having larger vertical glyph sizes is not always
401 desired, especially if it is not possible to adjust the `usWinAscent`
402 and `usWinDescent` values from the font's `OS/2` table so that they are
403 not too tight. See '[Windows Compatibility](#windows-compatibility)'
404 for more details.
406 ### Fallback Stem Width
408 `--fallback-stem-width=`*n*, `-H`\ *n*
409 : Set the horizontal stem width (hinting) value for all scripts that lack
410 proper standard characters in the font. The value is given in font
411 units and must be a positive integer. If not set, ttfautohint uses a
412 hard-coded default (50\ units at 2048 units per EM, and linearly scaled
413 for other UPEM values, for example 24\ units at 1000 UPEM).
415 For symbol fonts, you need option `--fallback-script` too (to set up a
416 script at all).
418 In the GUI, uncheck the 'Default Fallback Stem Width' box to activate
419 this feature.
421 ### Windows Compatibility
423 `--windows-compatibility`, `-W`
424 : This option makes ttfautohint add two artificial blue zones, positioned
425 at the `usWinAscent` and `usWinDescent` values (from the font's `OS/2`
426 table). The idea is to help ttfautohint so that the hinted glyphs stay
427 within this horizontal stripe since older versions of Windows clip
428 everything that lies outside.
430 There is a general problem with tight values for `usWinAscent` and
431 `usWinDescent`; a good description is given in the [Vertical Metrics
432 How-To](http://typophile.com/node/13081). Additionally, there is a
433 special problem with tight values if used in combination with
434 ttfautohint because the auto-hinter tends to slightly increase the
435 vertical glyph dimensions at smaller sizes to improve legibility. This
436 enlargement can make the heights and depths of glyphs exceed the range
437 given by `usWinAscent` and `usWinDescent`.
439 If ttfautohint is part of the font creation tool chain, and the font
440 designer can adjust those two values, a better solution instead of using
441 option `-W` is to reserve some vertical space for 'padding': For the
442 auto-hinter, the difference between a top or bottom outline point before
443 and after hinting is less than 1px, thus a vertical padding of 2px is
444 sufficient. Assuming a minimum hinting size of 6ppem, adding two pixels
445 gives an increase factor of 8÷6 = 1.33. This is near to the default
446 baseline-to-baseline distance used by TeX and other sophisticated text
447 processing applications, namely 1.2×designsize, which gives satisfying
448 results in most cases. It is also near to the factor 1.25 recommended
449 in the abovementioned how-to. For example, if the vertical extension of
450 the largest glyph is 2000 units (assuming that it approximately
451 represents the designsize), the sum of `usWinAscent` and `usWinDescent`
452 could be 1.25×2000 = 2500.
454 In case ttfautohint is used as an auto-hinting tool for fonts that can
455 be no longer modified to change the metrics, option `-W` in combination
456 with '`-X "-"`' to suppress any vertical enlargement should prevent
457 almost all clipping.
459 ### Adjust Subglyphs
461 `--adjust-subglyphs`, `-p`
462 : *Adjusting subglyphs* makes a font's original bytecode be applied to all
463 glyphs before it is replaced with bytecode created by ttfautohint. This
464 makes only sense if your font already has some hints in it that modify
465 the shape even at EM size (normally 2048px); in particular, some CJK
466 fonts need this because the bytecode is used to scale and shift
467 subglyphs (hence the option's long name). For most fonts, however, this
468 is not the case.
470 ### Hint Composites
472 `--composites`, `-c`
473 : By default, the components of a composite glyph get hinted separately.
474 If this flag is set, the composite glyph itself gets hinted (and the
475 hints of the components are ignored). Using this flag increases the
476 bytecode size a lot, however, it *might* yield better hinting results –
477 usually, it doesn't.
479 If this option is used (and a font actually contains composite glyphs),
480 ttfautohint currently cannot reprocess its own output for technical
481 reasons, see [below](#the-.ttfautohint-glyph).
483 ### Symbol Font
485 `--symbol`, `-s`
486 : Process a font that ttfautohint would refuse otherwise because it can't
487 find a single standard character for any of the supported scripts.
489 For all scripts that lack proper standard characters, ttfautohint uses a
490 default (hinting) value for the standard stem width instead of deriving
491 it from a script's set of standard characters (for the latin script, one
492 of them is character 'o').
494 Use this option – usually in combination with the
495 [`--fallback-script`](#fallback-script) and/or
496 [`--fallback-stem-width`](#fallback-stem-width) option – to hint symbol
497 or dingbat fonts or math glyphs, for example.
499 ### Dehint
501 `--dehint`, `-d`
502 : Strip off all hints without generating new hints. Consequently, all
503 other hinting options are ignored. This option is intended for testing
504 purposes.
506 ### ttfautohint Info
508 `--no-info`, `-n`
509 : Don't add ttfautohint version and command line information to the
510 version string or strings (with name ID\ 5) in the font's `name` table.
511 In the GUI, it corresponds to value 'None' in the 'ttfautohint
512 info' combo box.
514 This option is mutually exclusive with option `-I`.
516 `--detailed-info`, `-I`
517 : Add ttfautohint version and command line information to the version
518 string or strings (with name ID\ 5) in the font's `name` table. In the
519 GUI, it corresponds to value 'Version and Parameters' in the
520 'ttfautohint info' combo box.
522 This option is mutually exclusive with option `-n`.
524 If neither `-n` nor `-I` is set, the string '`ttfautohint (vNNN)`' gets
525 added to the `name` table (with *NNN* the current version); this correponds
526 to value 'Version' in the 'ttfautohint info' combo box.
528 ### Add TTFA Info Table
530 `--ttfa-table`, `-t`
531 : Add an SFNT table called `TTFA` to the output font that holds a dump of
532 all parameters; the data resembles the format of the `--debug` option's
533 parameter listing. In particular, it lists all ttfautohint control
534 instructions (which are *not* shown in the `name` table info). This
535 option is mainly for archival purposes so that all information used to
536 create a font is stored in the font itself. Note that such a `TTFA`
537 table gets ignored by all TrueType rendering engines.
539 Forthcoming versions of the ttfautohint front-ends will be able to use
540 this data so that a font can be processed another time with exactly the
541 same parameters, thus providing a means for round-tripping fonts.
543 ### Family Suffix
545 `--family-suffix=`*string*, `-F`\ *string*
546 : A string that gets appended to the family name in entries with IDs 1, 4,
547 6, 16, and\ 21 in the font's `name` table. Allowed input is ASCII in
548 the range 0x20-0x7E except characters `%()/<>[]{}`.
550 Assuming an input family name 'Foo', a full name 'Foo Bold', and a
551 family suffix '\ 1', the output family name will be 'Foo 1' and the
552 full name 'Foo 1 Bold'. For the PostScript name in ID\ 6, ttfautohint
553 uses the suffix with space characters removed (for example 'Foo1Bold').
555 This option is mainly for testing purposes, enabling the operating
556 system to simultaneously display several instances of a font that are
557 processed with different ttfautohint parameters.
559 ### Reference Face Index
561 `--reference-index=`*n*, `-Z`\ *n*
562 : Set the face index for the [blue zone reference
563 font](#blue-zone-reference-font) if the font is a TrueType collection
564 (`.ttc`). For normal TrueType fonts, the value is always zero (which is
565 also the default).
567 `ttfautohintGUI` doesn't have this command line option.
569 ### Stem Width and Positioning Mode
571 `--stem-width-mode=`*string*, `-a`\ *string*
572 : ttfautohint provides three different algorithms for computing horizontal
573 stem widths and the positioning of blue zones.
575 - 'natural': No adjustments to stem widths, discrete blue zone
576 positioning. This is what FreeType uses for its 'light'
577 (auto-)hinting mode. Essentially no glyph shape distortion, low
578 contrast.
580 - 'quantized': Both stem widths and blue zone positions are slightly
581 quantized to take discrete values. For example, stem values 50, 51,
582 72, 76, and 100 would become 50, 74, and 100 (or something similar).
583 More glyph shape distortion but increased contrast.
585 - 'strong: If active, stem widths and blue zones are snapped and
586 positioned to integer pixel values as much as possible. This gives
587 high contrast, but glyph shape distortion can be significant.
589 These three algorithms are mapped onto three possible rendering targets.
591 - Grayscale rendering, with or without optimization for subpixel
592 positioning (e.g., Android).
594 - 'GDI ClearType' rendering: the rasterizer version, as returned by the
595 GETINFO bytecode instruction, is in the range 36\ <= version <=\ 38
596 and ClearType is enabled (e.g., Windows XP).
598 - 'DirectWrite ClearType' rendering: the rasterizer version, as returned
599 by the GETINFO bytecode instruction, is >=\ 39, ClearType is enabled,
600 and subpixel positioning is enabled also (e.g., Internet Explorer\ 9
601 running on Windows\ 7).
603 GDI ClearType uses a mode similar to B/W rendering along the vertical
604 axis, while DW ClearType applies grayscale rendering. Additionally,
605 only DW ClearType provides subpixel positioning along the x\ axis. For
606 what it's worth, the rasterizers version\ 36 and version\ 38 in
607 Microsoft Windows are two completely different rendering engines.
609 [Note that the GDI framework on Windows\ 10 no longer uses B/W rendering
610 along the vertical axis; we consequently treat it as DW ClearType also.
611 We test this by looking at bit\ 11 of the GETINFO instruction, which
612 was introduced in rasterizer version\ 40.]
614 The command line option expects *string* to contain exactly three
615 letters with possible values '`n`' for natural, '`q`' for quantized, and
616 '`s`' for strong stem width and positioning mode. The first, second,
617 and third letter correspond to grayscale, GDI ClearType, and DW
618 ClearType rendering, respectively. The default value is `qsq`, which
619 means that the 'quantized' algorithm gets used for grayscale and DW
620 ClearType, and the 'strong' algorithm for GDI ClearType. For example,
621 to use the 'natural' algorithm for all three rendering targets, use
622 option `-a nnn`.
624 In the GUI, simply select the desired stem width algorithm in the three
625 combo boxes.
627 
629 as displayed with the 'ftgrid' demo program of FreeType. Top left is
630 unhinted, top right is hinted using ttfautohint natural stem width
631 mode. Bottom left and right uses the quantized and strong stem width
632 modes, respectively.](img/Merriweather-Black-g-21px-comparison.png)
634 `--strong-stem-width=`*string*, `-w`\ *string*
636 : This option is deprecated and has been replaced with the more versatile
637 option [`--stem-width-mode`](#stem-width-and-positioning-mode). The
638 table below shows the corresponding arguments.
640 `-w` `-a`
641 ------ ------
642 `""` `qqq`
643 `g` `sqq`
644 `G` `qsq`
645 `D` `qqs`
646 `gG` `ssq`
647 `gD` `sqs`
648 `GD` `qss`
649 `gGD` `sss`
651 ### Miscellaneous
653 Watch input files\ \ \ (`ttfautohintGUI` only)
654 : If this checkbox is set, automatically regenerate the output file as
655 soon as an input file (either the font, the control instructions file,
656 or the reference font) gets modified.
658 Pressing the 'Run' button starts watching. If an error occurs, watching
659 stops and must be restarted with the 'Run' button.
661 `--ignore-restrictions`, `-i`
662 : By default, fonts that have bit\ 1 set in the 'fsType' field of the
663 `OS/2` table are rejected. If you have a permission of the font's legal
664 owner to modify the font, specify this command line option.
666 If this option is not set, `ttfautohintGUI` shows a dialogue to handle
667 such fonts if necessary.
669 `--help`, `-h`
670 : On the console, print a brief documentation on standard output and exit.
671 This doesn't work with `ttfautohintGUI` on MS Windows.
673 `--version`, `-v`
674 : On the console, print version information on standard output and exit.
675 This doesn't work with `ttfautohintGUI` on MS Windows.
677 `--ttfa-info`, `-T`\ \ \ (not in `ttfautohintGUI`)
678 : Print [`TTFA` table](#add-ttfa-info-table) of the input font on standard
679 output if present, then exit.
681 `--debug`\ \ \ (not in `ttfautohintGUI`)
682 : Print *a lot* of debugging information on standard error while
683 processing a font (you should redirect stderr to a file).
685 To reduce the amount of debug data it is recommended to restrict the
686 hinting process to a single PPEM value, e.g.,
688 ```
689 ttfautohint --debug -l 15 -r 15 ... > debug.txt 2>&1
690 ```
694 Background and Technical Details
695 ================================
697 [Real-Time Grid Fitting of Typographic
698 Outlines](https://www.tug.org/TUGboat/tb24-3/lemberg.pdf) is a scholarly
699 paper that describes FreeType's auto-hinter in some detail. Regarding the
700 described data structures it is slightly out of date, but the algorithm
701 itself hasn't changed in general.
703 The next few subsections are mainly based on this article, introducing some
704 important concepts. Note that ttfautohint only does hinting along the
705 vertical direction (modifying y\ coordinates only).
708 Segments and Edges
709 ------------------
711 A glyph consists of one or more *contours* (this is, closed curves). For
712 example, glyph 'O' consists of two contours, while glyph 'I' has only one.
714 
717 A *segment* is a series of consecutive points of a contour (including its
718 Bézier control points) that are approximately aligned along a coordinate
719 axis. A segment has one of three possible directions: left, right, or none
720 (which means neither left nor right), derived from the TrueType outline
721 directions. ttfautohint itself creates segments that contain at least two
722 points. Using control instructions, however, it is possible to create
723 one-point segments, which are useful for fine-tuning the hinting process.
725 
731 An *edge* corresponds to a single coordinate value (allowing for a small
732 threshold) on the main dimension that collects one or more segments, all
733 pointing into the same direction (either left or right, all others are
734 ignored). While finding segments is done on the unscaled outline, finding
735 edges is bound to the device resolution. See [below](#hint-sets) for an
736 example.
738 In general, segments and edges pointing into different directions 'repel'
739 each other, thus preventing alignment on the same vertical coordinate if
740 they are near. Note that this is a simplification, but it should help
741 understand how to manipulate and/or create segments in control instructions
742 files.
744 The analysis to find segments and edges is specific to a writing
745 system, see [below](#writing-systems).
748 Feature Analysis
749 ----------------
751 The auto-hinter analyzes a font in two steps. Right now, everything
752 described here happens for the horizontal axis only, providing vertical
753 hinting.
755 * Global Analysis
757 This affects the hinting of all glyphs, trying to give them a uniform
758 appearance.
760 + Compute standard horizontal stem width of the font. The value
761 is normally taken from glyphs that resemble letter 'o'.
763 If, for a given script, there is no glyph for at least one standard
764 character in the input font, a fallback stem width gets used. See
765 also option [`--fallback-stem-width`](#fallback-stem-width).
767 The stem width(s) found by the algorithm can be overridden with the
768 [`width`](#stem-width-adjustments) control instruction.
770 + Compute blue zones, see [below](#blue-zones).
772 If the stem widths of single glyphs differ by a large value, or if
773 ttfautohint fails to find proper blue zones, hinting becomes quite poor,
774 possibly leading even to severe shape distortions.
777 Table: script-specific standard characters of the 'latin' writing system
779 Script Standard characters
780 -------- ---------------------
781 `adlm` '𞤌', U+1E90C, ADLAM CAPITAL LETTER O
782 '𞤮', U+1E92E, ADLAM SMALL LETTER O
783 `arab` 'ـ', U+0640, ARABIC TATWEEL
784 'ل', U+0644, ARABIC LETTER LAM
785 'ح', U+062D, ARABIC LETTER HAH
786 `armn` 'օ', U+0585, ARMENIAN SMALL LETTER OH
787 'Օ', U+0555, ARMENIAN CAPITAL LETTER OH
788 `avst` '𐬚', U+10B1A, AVESTAN LETTER THE
789 `bamu` 'ꛁ', U+A6C1, BAMUM LETTER YUQ
790 'ꛯ', U+A6EF, BAMUM LETTER KOGHOM
791 `beng` '০', U+09E6, BENGALI DIGIT ZERO
792 '৪', U+09EA, BENGALI DIGIT FOUR
793 `buhd` 'ᝋ', U+174B, BUHID LETTER MA
794 'ᝏ', U+174F, BUHID LETTER WA
795 `cakm` '𑄤', U+11124, CHAKMA LETTER WAA
796 '𑄉', U+11109, CHAKMA LETTER GAA
797 '𑄛', U+1111B, CHAKMA LETTER PAA
798 `cans` 'ᑌ', U+144C, CANADIAN SYLLABICS TE
799 'ᓚ', U+14DA, CANADIAN SYLLABICS LA
800 `cari` '𐊫', U+102AB, CARIAN LETTER O
801 '𐋉', U+102C9, CARIAN LETTER RR
802 `cher` 'Ꭴ', U+13A4, CHEROKEE LETTER U
803 'Ꮕ', U+13C5, CHEROKEE LETTER NV
804 'ꮕ', U+AB95, CHEROKEE SMALL LETTER NV
805 `copt` 'Ⲟ', U+2C9E, COPTIC CAPITAL LETTER O
806 'ⲟ', U+2C9F, COPTIC SMALL LETTER O
807 `cprt` '𐠅', U+10805, CYPRIOT SYLLABLE JA
808 '𐠣', U+10823, CYPRIOT SYLLABLE RA
809 `cyrl` '\Cyrillic{}о\cyrillic{}', U+043E, CYRILLIC SMALL LETTER O
810 '\Cyrillic{}О\cyrillic{}', U+041E, CYRILLIC CAPITAL LETTER O
811 `deva` 'ठ', U+0920, DEVANAGARI LETTER TTHA
812 'व', U+0935, DEVANAGARI LETTER VA
813 'ट', U+091F, DEVANAGARI LETTER TTA
814 `dsrt` '𐐄', U+10404, DESERET CAPITAL LETTER LONG O
815 '𐐬', U+1042C, DESERET SMALL LETTER LONG O
816 `ethi` 'ዐ', U+12D0, ETHIOPIC SYLLABLE PHARYNGEAL A
817 `geor` 'ი', U+10D8, GEORGIAN LETTER IN
818 'ე', U+10D4, GEORGIAN LETTER EN
819 'ა', U+10D0, GEORGIAN LETTER AN
820 'Ი', U+1C98, GEORGIAN MTAVRULI CAPITAL LETTER IN
821 `geok` 'Ⴖ', U+10B6, GEORGIAN CAPITAL LETTER GHAN
822 'Ⴑ', U+10B1, GEORGIAN CAPITAL LETTER SAN
823 'ⴙ', U+2D19, GEORGIAN SMALL LETTER CHIN
824 `glag` 'Ⱅ', U+2C15, GLAGOLITIC CAPITAL LETTER TVRIDO
825 'ⱅ', U+2C45, GLAGOLITIC SMALL LETTER TVRIDO
826 `goth` '𐌴', U+10334, GOTHIC LETTER AIHVUS
827 '𐌾', U+1033E, GOTHIC LETTER JER
828 '𐍃', U+10343, GOTHIC LETTER SAUIL
829 `grek` '\Greek{}ο\greek{}', U+03BF, GREEK SMALL LETTER OMICRON
830 '\Greek{}Ο\greek{}', U+039F, GREEK CAPITAL LETTER OMICRON
831 `gujr` 'ટ', U+0A9F, GUJARATI LETTER TTA
832 '૦', U+0AE6, GUJARATI DIGIT ZERO
833 `guru` 'ਠ', U+0A20, GURMUKHI LETTER TTHA
834 'ਰ', U+0A30, GURMUKHI LETTER RA
835 '੦', U+0A66, GURMUKHI DIGIT ZERO
836 `hebr` 'ם', U+05DD, HEBREW LETTER FINAL MEM
837 `hmnp` '𞄨', U+1E128, NYIAKENG PUACHUE HMONG LETTER O
838 `kali` 'ꤍ', U+A90D, KAYAH LI LETTER NGA
839 '꤀', U+A900, KAYAH LI DIGIT ZERO
840 `knda` '೦', U+0CE6, KANNADA DIGIT ZERO
841 'ಬ', U+0CAC, KANNADA LETTER BA
842 `khmr` '០', U+17E0, KHMER DIGIT ZERO
843 `lao` '໐', U+0ED0, LAO DIGIT ZERO
844 `latn` '\Latin{}o\latin{}', U+006F, LATIN SMALL LETTER O
845 '\Latin{}O\latin{}', U+004F, LATIN CAPITAL LETTER O
846 '\Latin{}0\latin{}', U+0030, DIGIT ZERO
847 `lisu` 'ꓳ', U+A4F3, LISU LETTER
848 `mlym` 'ഠ', U+0D20, MALAYALAM LETTER TTHA
849 'റ', U+0D31, MALAYALAM LETTER RRA
850 `mong` '\Mongolian{}ᡂ\mongolian{}', U+1842, MONGOLIAN LETTER CHI
851 '\Mongolian{}ᠪ\mongolian{}', U+182A, MONGOLIAN LETTER BA
852 `mymr` 'ဝ', U+101D, MYANMAR LETTER WA
853 'င', U+1004, MYANMAR LETTER NGA
854 'ဂ', U+1002, MYANMAR LETTER GA
855 `nkoo` 'ߋ', U+07CB, NKO LETTER EE
856 '߀', U+07C0, NKO DIGIT ZERO
857 `olck` 'ᱛ', U+1C5B, OL CHIKI LETTER AT
858 `orkh` '𐰗', U+10C17, OLD TURKIC LETTER YENISEI AY
859 `osge` '𐓂', U+104C2, OSAGE CAPITAL LETTER O
860 '𐓪', U+104EA, OSAGE SMALL LETTER O
861 `osma` '𐒆', U+10486, OSMANYA LETTER DEEL
862 '𐒠', U+104A0, OSMANYA DIGIT ZERO
863 `rohg` '𐴰', HANIFI ROHINGYA DIGIT ZERO
864 `saur` 'ꢝ', U+A89D, SAURASHTRA LETTER TTHA
865 '꣐', U+A8D0, SAURASHTRA DIGIT ZERO
866 `shaw` '𐑴', U+10474, SHAVIAN LETTER OAK
867 `sinh` 'ට', U+0DA7, SINHALA LETTER ALPAPRAANA TTAYANNA
868 `sund` '᮰', U+1BB0, SUNDANESE DIGIT ZERO
869 `taml` '௦', U+0BE6, TAMIL DIGIT ZERO
870 `tavt` 'ꪒ', U+AA92, TAI VIET LETTER LOW DO
871 'ꪫ', U+AAAB, TAI VIET LETTER HIGH VO
872 `telu` '౦', U+0C66, TELUGU DIGIT ZERO
873 '౧', U+0C67, TELUGU DIGIT ONE
874 `tfng` 'ⵔ', U+2D54, TIFINAGH LETTER YAR
875 `thai` 'า', U+0E32, THAI CHARACTER SARA AA
876 'ๅ', U+0E45, THAI CHARACTER LAKKHANGYAO
877 '๐', U+0E50, THAI DIGIT ZERO
878 `vaii` 'ꘓ', U+A613, VAI SYMBOL FEENG
879 'ꖜ', U+A59C, VAI SYLLABLE BHU
880 'ꖴ', U+A5B4, VAI SYLLABLE KU
883 Table: standard characters of the 'latin' writing system, special scripts
885 Script Standard characters
886 ---------- ---------------------
887 `khms` '᧡', U+19E1, KHMER SYMBOL MUOY KOET
888 '᧪', U+19EA, KHMER SYMBOL DAP KOET
889 `latb` '\Latin{}ₒ\latin{}', U+2092, LATIN SUBSCRIPT SMALL LETTER O
890 '\Latin{}₀\latin{}', U+2080, SUBSCRIPT ZERO
891 `latp` '\Latin{}ᵒ\latin{}', U+1D52, MODIFIER LETTER SMALL O
892 '\Latin{}ᴼ\latin{}', U+1D3C, MODIFIER LETTER CAPITAL O
893 '\Latin{}⁰\latin{}', U+2070, SUPERSCRIPT ZERO
896 * Glyph Analysis
898 This is a per-glyph operation.
900 + Find segments and edges.
902 + Link edges to set up stems and serifs. The abovementioned paper
903 gives more details on what exactly constitutes a stem or a serif and
904 how the algorithm works.
907 Blue Zones
908 ----------
910 
915 Outlines of certain characters are used to determine *blue zones*. This
916 concept is the same as with Type\ 1 fonts: All glyph points that lie in
917 certain small horizontal zones get aligned vertically.
919 The tables below show the blue zone characters of all available scripts of
920 the latin writing system; the values are hard-coded in the source code.
921 Since the auto-hinter takes mean values it is not necessary that all
922 characters of a zone are present.
924 'Round' characters in blue zones (e.g., the top and bottom of 'O' or the
925 bottom of 'g') are used to control overshoot handling.
927 Blue zones marked with an asterisk are x\ height blue zones, which are
928 adjusted to be on the pixel grid (to improve rendering at small sizes) by
929 scaling the remaining blue zones before they are adjusted to the grid. See
930 also option [`--increase-x-height`](#x-height-increase-limit).
933 Table: `adlm` (Adlam) blue zones
935 ID Blue zone Characters
936 ---- ----------- ------------
937 1 top of capital letters 𞤌 𞤅 𞤈 𞤏 𞤔 𞤚
938 2 bottom of capital letters 𞤂 𞤖
939 3* top of small letters 𞤬 𞤮 𞤻 𞤼 𞤾
940 4 bottom of small letters 𞤤 𞤨 𞤩 𞤭 𞤴 𞤸 𞤺 𞥀
943 Table: `arab` (Arabic) blue zones
945 ID Blue zone Characters
946 ---- ----------- ------------
947 1 top of letters with vertical stroke ا إ ل ك ط ظ
948 2 bottom of letters ت ث ط ظ ك
949 3 glyph joining ـ
952 Table: `armn` (Armenian) blue zones
954 ID Blue zone Characters
955 ---- ----------- ------------
956 1 top of capital letters Ա Մ Ւ Փ Բ Գ Դ Օ
957 2 bottom of capital letters Ւ Ո Փ Ճ Շ Ս Տ Օ
958 3 top of ascenders of small letters ե է ի մ վ փ ֆ փ
959 4* top of small letters ա յ ւ ս գ ջ ր օ
960 5 bottom of small letters հ ո ճ ա ե ծ ս օ
961 6 bottom of descenders of small letters բ ը ի լ ղ պ փ ց
964 Table: `avst` (Avestan) blue zones
966 ID Blue zone Characters
967 ---- ----------- ------------
968 1 top of letters 𐬀 𐬁 𐬐 𐬛
969 2 bottom of letters 𐬀 𐬁
972 Table: `bamu` (Bamum) blue zones
974 ID Blue zone Characters
975 ---- ----------- ------------
976 1 top of letters ꚧ ꚨ ꛛ ꛉ ꛁ ꛈ ꛫ ꛯ
977 2 bottom of letters ꚭ ꚳ ꚶ ꛬ ꚢ ꚽ ꛯ ꛲
980 Table: `beng` (Bengali) blue zones
982 ID Blue zone Characters
983 ---- ----------- ------------
984 1 baseline (flat glyphs only) অ ড ত ন ব ভ ল ক
985 2 top of ascenders ই ট ঠ ি ী ৈ ৗ
986 3* top of baseline ও এ ড ত ন ব ল ক
987 4 bottom of base characters অ ড ত ন ব ভ ল ক
989 Contrary to scripts like latin, the baseline in Bengali is on the top, and
990 we hint from top to bottom.
993 Table: `buhd` (Buhid) blue zones
995 ID Blue zone Characters
996 ---- ----------- ------------
997 1 top of letters ᝐ ᝈ
998 2 top of large letters ᝅ ᝊ ᝎ
999 3* top of small letters ᝂ ᝃ ᝉ ᝌ
1000 4 bottom of letters ᝀ ᝃ ᝆ ᝉ ᝋ ᝏ ᝑ
1003 Table: `cakm` (Chakma) blue zones
1005 ID Blue zone Characters
1006 ---- ----------- ------------
1007 1 top of letters 𑄃 𑄅 𑄉 𑄙 𑄗
1008 2 bottom of letters 𑄅 𑄛 𑄝 𑄗 𑄓
1009 3 bottom of descenders of letters 𑄖𑄳𑄢 𑄘𑄳𑄢 𑄙𑄳𑄢 𑄤𑄳𑄢 𑄥𑄳𑄢
1012 Table: `cans` (Canadian Syllabics) blue zones
1014 ID Blue zone Characters
1015 ---- ----------- ------------
1016 1 top of letters ᗜ ᖴ ᐁ ᒣ ᑫ ᑎ ᔑ ᗰ
1017 2 bottom of letters ᗶ ᖵ ᒧ ᐃ ᑌ ᒍ ᔑ ᗢ
1018 3* top of small letters ᓓ ᓕ ᓀ ᓂ ᓄ ᕄ ᕆ ᘣ
1019 4 bottom of small letters ᕃ ᓂ ᓀ ᕂ ᓗ ᓚ ᕆ ᘣ
1020 5 top of superscript letters ᐪ ᙆ ᣘ ᐢ ᒾ ᣗ ᔆ
1021 6 bottom of superscript letters ᙆ ᗮ ᒻ ᐞ ᔆ ᒡ ᒢ ᓑ
1024 Table: `cari` (Carian) blue zones
1026 ID Blue zone Characters
1027 ---- ----------- ------------
1028 1 top of letters 𐊧 𐊫 𐊬 𐊭 𐊱 𐊺 𐊼 𐊿
1029 2 bottom of letters 𐊣 𐊧 𐊷 𐋀 𐊫 𐊸 𐋉
1032 Table: `cher` (Cherokee) blue zones
1034 ID Blue zone Characters
1035 ---- ----------- ------------
1036 1 top of capital letters Ꮖ Ꮋ Ꭼ Ꮓ Ꭴ Ꮳ Ꭶ Ꮥ
1037 2 bottom of capital letters Ꮖ Ꮋ Ꭼ Ꮓ Ꭴ Ꮳ Ꭶ Ꮥ
1038 3 top of ascenders of small letters ꮒ ꮤ ꮶ ꭴ ꭾ ꮗ ꮝ ꮿ
1039 4* top of small letters ꮖ ꭼ ꮓ ꮠ ꮳ ꭶ ꮥ ꮻ
1040 5 bottom of small letters ꮖ ꭼ ꮓ ꮠ ꮳ ꭶ ꮥ ꮻ
1041 6 bottom of descenders of small letters ᏸ ꮐ ꭹ ꭻ
1044 Table: `copt` (Coptic) blue zones
1046 ID Blue zone Characters
1047 ---- ----------- ------------
1048 1 top of capital letters Ⲍ Ⲏ Ⲡ Ⳟ Ⲟ Ⲑ Ⲥ Ⳋ
1049 2 bottom of capital letters Ⳑ Ⳙ Ⳟ Ⲏ Ⲟ Ⲑ Ⳝ Ⲱ
1050 3* top of small letters ⲍ ⲏ ⲡ ⳟ ⲟ ⲑ ⲥ ⳋ
1051 4 bottom of small letters ⳑ ⳙ ⳟ ⲏ ⲟ ⲑ ⳝ Ⳓ
1054 Table: `cprt` (Cypriot) blue zones
1056 ID Blue zone Characters
1057 ---- ----------- ------------
1058 1 top of letters 𐠍 𐠙 𐠳 𐠱 𐠅 𐠓 𐠣 𐠦
1059 2 bottom of letters 𐠃 𐠊 𐠛 𐠣 𐠳 𐠵 𐠐
1060 3 top of small letters 𐠈 𐠏 𐠖
1061 4 bottom of small letters 𐠈 𐠏 𐠖
1064 Table: `cyrl` (Cyrillic) blue zones
1066 ID Blue zone Characters
1067 ---- ----------- ------------
1068 1 top of capital letters \Cyrillic{}Б В Е П З О С Э\cyrillic{}
1069 2 bottom of capital letters \Cyrillic{}Б В Е Ш З О С Э\cyrillic{}
1070 3* top of small letters \Cyrillic{}х п н ш е з о с\cyrillic{}
1071 4 bottom of small letters \Cyrillic{}х п н ш е з о с\cyrillic{}
1072 5 bottom of descenders of small letters \Cyrillic{}р у ф\cyrillic{}
1075 Table: `deva` (Devanagari) blue zones
1077 ID Blue zone Characters
1078 ---- ----------- ------------
1079 1 top of ascenders ई ऐ ओ औ ि ी ो ौ
1080 2 top of baseline क म अ आ थ ध भ श
1081 3* top of baseline (flat glyphs only) क न म उ छ ट ठ ड
1082 4 bottom of base characters क न म उ छ ट ठ ड
1083 5 bottom of descenders ु ृ
1085 Contrary to scripts like latin, the baseline in Devanagari is on the top,
1086 and we hint from top to bottom. Note that some fonts have extreme variation
1087 in the height of the round elements in Zone\ 3; for this reason we also
1088 define Zone\ 1, which must be always present.
1091 Table: `dsrt` (Deseret) blue zones
1093 ID Blue zone Characters
1094 ---- ----------- ------------
1095 1 top of capital letters 𐐂 𐐄 𐐋 𐐗 𐐑
1096 2 bottom of capital letters 𐐀 𐐂 𐐄 𐐗 𐐛
1097 3* top of small letters 𐐪 𐐬 𐐳 𐐿 𐐹
1098 4 bottom of small letters 𐐨 𐐪 𐐬 𐐿 𐑃
1101 Table: `ethi` (Ethiopian) blue zones
1103 ID Blue zone Characters
1104 ---- ----------- ------------
1105 1 top of letters ሀ ሃ ዘ ፐ ማ በ ዋ ዐ
1106 2 bottom of letters ለ ሐ በ ዘ ሀ ሪ ዐ ጨ
1109 Table: `geok` (Georgian Khutsuri) blue zones
1111 ID Blue zone Characters
1112 ---- ----------- ------------
1113 1 top of Asomtavruli letters Ⴑ Ⴇ Ⴙ Ⴜ Ⴄ Ⴅ Ⴓ Ⴚ
1114 2 bottom of Asomtavruli letters Ⴄ Ⴅ Ⴇ Ⴈ Ⴆ Ⴑ Ⴊ Ⴋ
1115 3* top of Nuskhuri letters ⴁ ⴗ ⴂ ⴄ ⴅ ⴇ ⴔ ⴖ
1116 4 bottom of Nuskhuri letters ⴈ ⴌ ⴖ ⴎ ⴃ ⴆ ⴋ ⴢ
1117 5 top of ascender Nuskhuri letters ⴐ ⴑ ⴓ ⴕ ⴙ ⴛ ⴡ ⴣ
1118 6 bottom of Nuskhuri descender letters ⴄ ⴅ ⴔ ⴕ ⴁ ⴂ ⴘ ⴝ
1120 Georgian Asomtavruli and Nuskhuri form the old ecclesiastical script,
1121 Khutsuri. Note that fonts show a great variation in height and depth of
1122 ascender and descender letter forms.
1125 Table: `geor` (Georgian Mkhedruli) blue zones
1127 ID Blue zone Characters
1128 ---- ----------- ------------
1129 1* top of Mkhedruli letters გ დ ე ვ თ ი ო ღ
1130 2 bottom of Mkhedruli letters ა ზ მ ს შ ძ ხ ჰ
1131 3 top of ascender Mkhedruli letters ს ხ ქ ზ მ შ ჩ წ
1132 4 bottom of descender Mkhedruli letters ე ვ ჟ ტ უ ფ ქ ყ
1133 5 top of ascender Mtavruli letters Ნ Ჟ Ჳ Ჸ Გ Ე Ო Ჴ
1134 6 bottom of descender Mtavruli letters Ი Ჲ Ო Ჩ Მ Შ Ჯ Ჽ
1137 Table: `glag` (Glagolitic) blue zones
1139 ID Blue zone Characters
1140 ---- ----------- ------------
1141 1 top of capital letters Ⰵ Ⱄ Ⱚ Ⰴ Ⰲ Ⰺ Ⱛ Ⰻ
1142 2 bottom of capital letters Ⰵ Ⰴ Ⰲ Ⱚ Ⱎ Ⱑ Ⰺ Ⱄ
1143 3* top of small letters ⰵ ⱄ ⱚ ⰴ ⰲ ⰺ ⱛ ⰻ
1144 4 bottom of small letters ⰵ ⰴ ⰲ ⱚ ⱎ ⱑ ⰺ ⱄ
1147 Table: `goth` (Gothic) blue zones
1149 ID Blue zone Characters
1150 ---- ----------- ------------
1151 1 top of letters 𐌲 𐌶 𐍀 𐍄 𐌴 𐍃 𐍈 𐌾
1152 2 bottom of letters 𐌶 𐌴 𐍃 𐍈
1155 Table: `grek` (Greek) blue zones
1157 ID Blue zone Characters
1158 ---- ----------- ------------
1159 1 top of capital letters \Greek{}Γ Β Ε Ζ Θ Ο Ω\greek{}
1160 2 bottom of capital letters \Greek{}Β Δ Ζ Ξ Θ Ο\greek{}
1161 3 top of 'small beta' like letters \Greek{}β θ δ ζ λ ξ\greek{}
1162 4* top of small letters \Greek{}α ε ι ο π σ τ ω\greek{}
1163 5 bottom of small letters \Greek{}α ε ι ο π σ τ ω\greek{}
1164 6 bottom of descenders of small letters \Greek{}β γ η μ ρ φ χ ψ\greek{}
1167 Table: `gujr` (Gujarati) blue zones
1169 ID Blue zone Characters
1170 ---- ----------- ------------
1171 1* top of letters ત ન ઋ ઌ છ ટ ર ૦
1172 2 bottom of letters ખ ગ ઘ ઞ ઇ ઈ ઠ જ
1173 3 top of ascenders ઈ ઊ િ ી લી શ્ચિ જિ સી
1174 4 bottom of descenders ુ ૃ ૄ ખુ છૃ છૄ
1175 5 top of Gujarati digits ૦ ૧ ૨ ૩ ૭
1178 Table: `guru` (Gurmukhi) blue zones
1180 ID Blue zone Characters
1181 ---- ----------- ------------
1182 1 top of ascenders ਇ ਈ ਉ ਏ ਓ ੳ ਿ ੀ
1183 2 top of baseline ਕ ਗ ਙ ਚ ਜ ਤ ਧ ਸ
1184 3* top of baseline (flat glyphs only) ਕ ਗ ਙ ਚ ਜ ਤ ਧ ਸ
1185 4 bottom of characters ਅ ਏ ਓ ਗ ਜ ਠ ਰ ਸ
1186 5 top of Gurmukhi digits ੦ ੧ ੨ ੩ ੭
1189 Table: `hebr` (Hebrew) blue zones
1191 ID Blue zone Characters
1192 ---- ----------- ------------
1193 1 top of letters ב ד ה ח ך כ ם ס
1194 2 bottom of letters ב ט כ ם ס צ
1195 3 bottom of descenders of letters ק ך ן ף ץ
1198 Table: `hmnp` (Nyiakeng Puachue Hmong) blue zones
1200 ID Blue zone Characters
1201 ---- ----------- ------------
1202 1 top of letters 𞄀 𞄁 𞄈 𞄑 𞄧 𞄬
1203 2 bottom of letters 𞄁 𞄜 𞄠 𞄡 𞄤 𞅂
1206 Table: `kali` (Kayah Li) blue zones
1208 ID Blue zone Characters
1209 ---- ----------- ------------
1210 1* top of letters ꤅ ꤏ ꤁ ꤋ ꤀ ꤍ
1211 2 bottom of letters ꤈ ꤘ ꤀ ꤍ ꤢ
1212 3 top of ascending letters ꤖ ꤡ
1213 4 bottom of descending letters ꤑ ꤜ ꤞ
1214 5 bottom of large descending letters ꤑ꤬ ꤜ꤭ ꤔ꤬
1217 Table: `khmr` (Khmer) blue zones
1219 ID Blue zone Characters
1220 ---- ----------- ------------
1221 1* top of letters ខ ទ ន ឧ ឩ ា
1222 2 top of subscript cluster components ក្ក ក្ខ ក្គ ក្ថ
1223 3 bottom of letters ខ ឃ ច ឋ ប ម យ ឲ
1224 4 bottom of descenders ត្រ រៀ ឲ្យ អឿ
1225 5 bottom of large descenders ន្ត្រៃ ង្ខ្យ ក្បៀ ច្រៀ ន្តឿ ល្បឿ
1228 Table: `khms` (Khmer Symbols) blue zones
1230 ID Blue zone Characters
1231 ---- ----------- ------------
1232 1* top of symbols for waxing ᧠ ᧡
1233 2 bottom of symbols for waning ᧶ ᧹
1235 Khmer symbols are used for lunar dates.
1238 Table: `knda` (Kannada) blue zones
1240 ID Blue zone Characters
1241 ---- ----------- ------------
1242 1 top of letters ಇ ಊ ಐ ಣ ಸಾ ನಾ ದಾ ರಾ
1243 2 bottom of letters ಅ ಉ ಎ ಲ ೦ ೨ ೬ ೭
1246 Table: `lao` (Lao) blue zones
1248 ID Blue zone Characters
1249 ---- ----------- ------------
1250 1* top of letters າ ດ ອ ມ ລ ວ ຣ ງ
1251 2 bottom of letters າ ອ ບ ຍ ຣ ຮ ວ ຢ
1252 3 top of ascenders ປ ຢ ຟ ຝ
1253 4 top of large ascenders ໂ ໄ ໃ
1254 5 bottom of descenders ງ ຊ ຖ ຽ ໆ ຯ
1257 Table: `latb` (Latin Subscripts) blue zones
1259 ID Blue zone Characters
1260 ---- ----------- ------------
1261 1 top of capital characters \Latin{}₀ ₃ ₅ ₇ ₈\latin{}
1262 2 bottom of capital characters \Latin{}₀ ₁ ₂ ₃ ₈\latin{}
1263 3 top of 'small f' like characters \Latin{}ᵢ ⱼ ₕ ₖ ₗ\latin{}
1264 4* top of small characters \Latin{}ₐ ₑ ₒ ₓ ₙ ₛ ᵥ ᵤ ᵣ\latin{}
1265 5 bottom of small characters \Latin{}ₐ ₑ ₒ ₓ ₙ ₛ ᵥ ᵤ ᵣ\latin{}
1266 6 bottom of descenders of small characters \Latin{}ᵦ ᵧ ᵨ ᵩ ₚ\latin{}
1268 Subscript latin characters are similar to normal latin characters.
1271 Table: `latn` (Latin) blue zones
1273 ID Blue zone Characters
1274 ---- ----------- ------------
1275 1 top of capital letters \Latin{}T H E Z O C Q S\latin{}
1276 2 bottom of capital letters \Latin{}H E Z L O C U S\latin{}
1277 3 top of 'small f' like letters \Latin{}f i j k d b h\latin{}
1278 4* top of small letters \Latin{}u v x z o e s c\latin{}
1279 5 bottom of small letters \Latin{}n r x z o e s c\latin{}
1280 6 bottom of descenders of small letters \Latin{}p q g j y\latin{}
1283 Table: `latp` (Latin Superscripts) blue zones
1285 ID Blue zone Characters
1286 ---- ----------- ------------
1287 1 top of capital characters \Latin{}⁰ ³ ⁵ ⁷ ᵀ ᴴ ᴱ ᴼ\latin{}
1288 2 bottom of capital characters \Latin{}⁰ ¹ ² ³ ᴱ ᴸ ᴼ ᵁ\latin{}
1289 3 top of 'small f' like characters \Latin{}ᵇ ᵈ ᵏ ʰ ʲ ᶠ ⁱ\latin{}
1290 4* top of small characters \Latin{}ᵉ ᵒ ʳ ˢ ˣ ᶜ ᶻ\latin{}
1291 5 bottom of small characters \Latin{}ᵉ ᵒ ʳ ˢ ˣ ᶜ ᶻ\latin{}
1292 6 bottom of descenders of small characters \Latin{}ᵖ ʸ ᵍ\latin{}
1294 Superscript latin characters are similar to normal latin characters.
1297 Table: `lisu` (Lisu) blue zones
1299 ID Blue zone Characters
1300 ---- ----------- ------------
1301 1 top of letters ꓡ ꓧ ꓱ ꓶ ꓩ ꓚ ꓵ ꓳ
1302 2 bottom of letters ꓕ ꓜ ꓞ ꓡ ꓛ ꓢ ꓳ ꓴ
1305 Table: `mlym` (Malayalam) blue zones
1307 ID Blue zone Characters
1308 ---- ----------- ------------
1309 1 top of letters ഒ ട ഠ റ ച പ ച്ച പ്പ
1310 2 bottom of letters ട ഠ ധ ശ ഘ ച ഥ ല
1313 Table: `mong` (Mongolian) blue zones
1315 ID Blue zone Characters
1316 ---- ----------- ------------
1317 1 top of base stem \Mongolian{}ᠳ ᠴ ᠶ ᠽ ᡂ ᡊ ᡡ ᡳ\mongolian{}
1318 2 bottom of base stem \Mongolian{}ᡃ\mongolian{}
1321 Table: `mymr` (Myanmar) blue zones
1323 ID Blue zone Characters
1324 ---- ----------- ------------
1325 1* top of letters ခ ဂ င ဒ ဝ ၥ ၊ ။
1326 2 bottom of letters င ဎ ဒ ပ ဗ ဝ ၊ ။
1327 3 top of ascenders of characters ဩ ြ ၍ ၏ ၆ ါ ိ
1328 3 bottom of descenders of letters ဉ ည ဥ ဩ ဨ ၂ ၅ ၉
1331 Table: `nkoo` (N'Ko) blue zones
1333 ID Blue zone Characters
1334 ---- ----------- ------------
1335 1 top of letters ߐ ߉ ߒ ߟ ߖ ߜ ߠ ߥ
1336 2 bottom of letters ߀ ߘ ߡ ߠ ߥ
1337 3* top of small letters ߏ ߛ ߋ
1338 4 bottom of small letters ߎ ߏ ߛ ߋ
1341 Table: `olck` (Ol Chiki) blue zones
1343 ID Blue zone Characters
1344 ---- ----------- ------------
1345 1 top of letters ᱛ ᱜ ᱝ ᱡ ᱢ ᱥ
1346 2 bottom of letters ᱛ ᱜ ᱝ ᱡ ᱢ ᱥ
1349 Table: `orkh` (Old Turkic) blue zones
1351 ID Blue zone Characters
1352 ---- ----------- ------------
1353 1 top of letters 𐰗 𐰘 𐰧
1354 2 bottom of letters 𐰉 𐰗 𐰦 𐰧
1357 Table: `osge` (Osage) blue zones
1359 ID Blue zone Characters
1360 ---- ----------- ------------
1361 1 top of capital letters 𐒾 𐓍 𐓒 𐓓 𐒻 𐓂 𐒵 𐓆
1362 2 bottom of capital letters 𐒰 𐓍 𐓂 𐒿 𐓎 𐒹
1363 3 bottom of descenders of capital letters 𐒼 𐒽 𐒾
1364 4* top of small letters 𐓵 𐓶 𐓺 𐓻 𐓝 𐓣 𐓪 𐓮
1365 5 bottom of small letters 𐓘 𐓚 𐓣 𐓵 𐓡 𐓧 𐓪 𐓶
1366 6 top of ascenders of small letters 𐓤 𐓦 𐓸 𐓹 𐓛
1367 7 bottom of descenders of small letters 𐓤 𐓥 𐓦
1370 Table: `osma` (Osmanya) blue zones
1372 ID Blue zone Characters
1373 ---- ----------- ------------
1374 1 top of letters 𐒆 𐒉 𐒐 𐒒 𐒘 𐒛 𐒠 𐒣
1375 2 bottom of letters 𐒀 𐒂 𐒆 𐒈 𐒊 𐒒 𐒠 𐒩
1378 Table: `rohg` (Hanifi Rohingya) blue zones
1380 ID Blue zone Characters
1381 ---- ----------- ------------
1382 1 top of letters with vertical stroke 𐴃 𐴀 𐴆 𐴖 𐴕
1383 2 bottom of letters 𐴔 𐴖 𐴕 𐴑 𐴐
1384 3 glyph joining ـ
1387 Table: `saur` (Saurashtra) blue zones
1389 ID Blue zone Characters
1390 ---- ----------- ------------
1391 1 top of letters ꢜ ꢞ ꢳ ꢂ ꢖ ꢒ ꢝ ꢛ
1392 2 bottom of letters ꢂ ꢨ ꢺ ꢤ ꢎ
1395 Table: `shaw` (Shavian) blue zones
1397 ID Blue zone Characters
1398 ---- ----------- ------------
1399 1 top of letters 𐑕 𐑙
1400 2 bottom of letters 𐑔 𐑖 𐑗 𐑹 𐑻
1401 3 bottom of descenders of letters 𐑟 𐑣
1402 4* top of small letters 𐑱 𐑲 𐑳 𐑴 𐑸 𐑺 𐑼
1403 5 bottom of small letters 𐑴 𐑻 𐑹
1406 Table: `sinh` (Sinhala) blue zones
1408 ID Blue zone Characters
1409 ---- ----------- ------------
1410 1 top of letters ඉ ක ඝ ඳ ප ය ල ෆ
1411 2 bottom of letters එ ඔ ඝ ජ ට ථ ධ ර
1412 3 bottom of descenders of letters ද ඳ උ ල තූ තු බු දු
1415 Table: `sund` (Sundanese) blue zones
1417 ID Blue zone Characters
1418 ---- ----------- ------------
1419 1 top of letters ᮋ ᮞ ᮮ ᮽ ᮰ ᮈ
1420 2 bottom of letters ᮄ ᮔ ᮕ ᮗ ᮰ ᮆ ᮈ ᮉ
1421 3 bottom of descenders of letters ᮼ ᳄
1424 Table: `taml` (Tamil) blue zones
1426 ID Blue zone Characters
1427 ---- ----------- ------------
1428 1 top of letters உ ஒ ஓ ற ஈ க ங ச
1429 2 bottom of letters க ச ல ஶ உ ங ட ப
1432 Table: `tavt` (Tai Viet) blue zones
1434 ID Blue zone Characters
1435 ---- ----------- ------------
1436 1 top of letters ꪆ ꪔ ꪒ ꪖ ꪫ
1437 2 bottom of letters ꪉ ꪫ ꪮ
1440 Table: `telu` (Telugu) blue zones
1442 ID Blue zone Characters
1443 ---- ----------- ------------
1444 1 top of letters ఇ ఌ ఙ ఞ ణ ఱ ౯
1445 2 bottom of letters అ క చ ర ఽ ౨ ౬
1448 Table: `tfng` (Tifinagh) blue zones
1450 ID Blue zone Characters
1451 ---- ----------- ------------
1452 1 top of letters ⵔ ⵙ ⵛ ⵞ ⴵ ⴼ ⴹ ⵎ
1453 2 bottom of letters ⵔ ⵙ ⵛ ⵞ ⴵ ⴼ ⴹ ⵎ
1456 Table: `thai` (Thai) blue zones
1458 ID Blue zone Characters
1459 ---- ----------- ------------
1460 1* top of letters บ เ แ อ ก า
1461 2 bottom of letters บ ป ษ ฯ อ ย ฮ
1462 3 top of ascenders of letters ป ฝ ฟ
1463 4 top of large ascenders of letters โ ใ ไ
1464 5 bottom of descenders of letters ฎ ฏ ฤ ฦ
1465 6 bottom of large descenders of letters ญ ฐ
1466 7 top of Thai digits ๐ ๑ ๓
1469 Table: `vaii` (Vai) blue zones
1471 ID Blue zone Characters
1472 ---- ----------- ------------
1473 1 top of vai letters ꗍ ꘖ ꘙ ꘜ ꖜ ꖝ ꔅ ꕢ
1474 2 bottom of vai letters ꗍ ꘖ ꘙ ꗞ ꔅ ꕢ ꖜ ꔆ
1477 
1481 Grid Fitting
1482 ------------
1484 Aligning outlines along the grid lines is called *grid fitting*. It doesn't
1485 necessarily mean that the outlines are positioned *exactly* on the grid,
1486 however, especially if you want a smooth appearance at different sizes.
1487 This is the central routine of the auto-hinter; its actions are highly
1488 dependent on the used writing system. Currently, only one writing system is
1489 available (latin), providing support for scripts like Latin or Greek.
1491 * Align edges linked to blue zones.
1493 * Fit edges to the pixel grid.
1495 * Align serif edges.
1497 * Handle remaining 'strong' points. Such points are not part of an edge
1498 but are still important for defining the shape. This roughly
1499 corresponds to the `IP` TrueType instruction.
1501 * Everything else (the 'weak' points) is handled with an 'IUP'
1502 instruction.
1504 The following images illustrate the hinting process, using glyph 'a' from
1505 the freely available font '[Ubuntu Book](https://design.ubuntu.com/font/)'. The
1506 manual hints were added by [Dalton Maag Ltd], the used application to create
1507 the hinting debug snapshots was [FontForge].
1509 
1511 
1513 
1517 Hint Sets
1518 ---------
1520 In ttfautohint terminology, a *hint set* is the *optimal* configuration for
1521 a given PPEM (pixel per EM) value.
1523 In the range given by the `--hinting-range-min` and `--hinting-range-max`
1524 options, ttfautohint creates hint sets for every PPEM value. For each
1525 glyph, ttfautohint automatically determines whether a new set should be
1526 emitted for a PPEM value if it finds that it differs from a previous one.
1527 For some glyphs it is possible that one set covers, say, the range
1528 8px-1000px, while other glyphs need 10 or more such sets.
1530 In the PPEM range below `--hinting-range-min`, ttfautohint always uses just
1531 one set, in the PPEM range between `--hinting-range-max` and
1532 `--hinting-limit`, it also uses just one set.
1534 One of the hinting configuration parameters is the decision which segments
1535 form an edge. For example, let us assume that two segments get aligned on a
1536 single horizontal edge at 11px, while two edges are used at 12px. This
1537 change makes ttfautohint emit a new hint set to accomodate this situation.
1538 The next images illustrate this, using a Cyrillic letter (glyph 'afii10108')
1539 from the 'Ubuntu book' font, processed with ttfautohint.
1541 
1543 
1547 
1549 
1554 Obviously, the more hint sets get emitted, the larger the bytecode
1555 ttfautohint adds to the output font. To find a good value\ *n* for
1556 `--hinting-range-max`, some experimentation is necessary since *n* depends
1557 on the glyph shapes in the input font. If the value is too low, the hint
1558 set created for the PPEM value\ *n* (this hint set gets used for all larger
1559 PPEM values) might distort the outlines too much in the PPEM range given
1560 by\ *n* and the value set by `--hinting-limit` (at which hinting gets
1561 switched off). If the value is too high, the font size increases due to
1562 more hint sets without any noticeable hinting effects.
1564 Similar arguments hold for `--hinting-range-min` except that there is no
1565 lower limit at which hinting is switched off.
1567 An example. Let's assume that we have a hinting range 10\ <= ppem <=\ 100,
1568 and the hinting limit is set to 250. For a given glyph, ttfautohint finds
1569 out that four hint sets must be computed to exactly cover this hinting
1570 range: 10-15, 16-40, 41-80, and 81-100. For PPEM values below 10ppem, the
1571 hint set covering 10-15ppem is used, for PPEM values larger than 100 the
1572 hint set covering 81-100ppem is used. For PPEM values larger than 250, no
1573 hinting gets applied.
1576 Composite Glyphs
1577 ----------------
1579 The ttfautohint library (and programs) supports two solutions for handling
1580 composite glyphs, to be controlled with option
1581 [`--composites`](#hint-composites). This section contains some general
1582 information, then covers the case where the option is off, while the next
1583 section describes how ttfautohint behaves if this option is activated.
1585 Regardless of the `--composites` option, ttfautohint performs a scan over
1586 all composite glyphs to assure that components of a composite glyph inherit
1587 its style, as described [later](#opentype-features). However, components
1588 that are shifted vertically will be skipped. For example, if the glyph
1589 'Agrave' uses a shifted 'grave' accent glyph, the accent is ignored. On the
1590 other hand, if there is a glyph 'agrave' that uses the same 'grave' glyph
1591 vertically unshifted, 'grave' does inherit the style.
1593 If `--composites` is off, components are hinted separately, then put
1594 together. Separate hinting implies that the current style's blue zones are
1595 applied to all subglyphs in its original, unshifted positions. In case you
1596 want to shift components vertically, it is *mandatory* to set bit\ 2
1597 (value\ 4), `ROUND_XY_TO_GRID`, in the flag variable of the composite glyph
1598 description to get visually pleasing results, as the images below
1599 demonstrate.
1601 
1608 
1612 
1620 The '\.ttfautohint' Glyph
1621 -------------------------
1623 If option [`--composites`](#hint-composites) is used, ttfautohint doesn't
1624 hint subglyphs of composite glyphs separately. Instead, it hints the whole
1625 glyph, this is, composites get recursively expanded internally so that they
1626 form simple glyphs, then hints are applied -- this is the normal working
1627 mode of FreeType's auto-hinter.
1629 One problem, however, must be solved: Hinting for subglyphs (which usually
1630 are used as normal glyphs also) must be deactivated so that nothing but the
1631 final bytecode of the composite gets executed.
1633 The trick used by ttfautohint is to prepend a composite element called
1634 '\.ttfautohint', a dummy glyph with a single point, and which has a single
1635 job: Its bytecode increases a variable (to be more precise, it is a CVT
1636 register called `cvtl_is_subglyph` in the source code), indicating that we
1637 are within a composite glyph. The final bytecode of the composite glyph
1638 eventually decrements this variable again.
1640 As an example, let's consider composite glyph 'Agrave' ('À'), which has the
1641 subglyph 'A' as the base and 'grave' as its accent. After processing with
1642 ttfautohint it consists of three components: '\.ttfautohint', 'A', and
1643 'grave' (in this order).
1645 Bytecode of Action
1646 ------------- --------
1647 .ttfautohint increase `cvtl_is_subglyph` (now: 1)
1648 A do nothing because `cvtl_is_subglyph` > 0
1649 grave do nothing because `cvtl_is_subglyph` > 0
1650 Agrave decrease `cvtl_is_subglyph` (now: 0)
1651 apply hints because `cvtl_is_subglyph` == 0
1653 Some technical details (which you might skip): All glyph point indices get
1654 adjusted since each '\.ttfautohint' subglyph shifts all following indices by
1655 one. This must be done for both the bytecode and one subformat of
1656 OpenType's `GPOS` anchor tables.
1658 While this approach works fine on all tested platforms, there is one single
1659 drawback: Direct rendering of the '\.ttfautohint' subglyph (this is,
1660 rendering as a stand-alone glyph) disables proper hinting of all glyphs in
1661 the font! Under normal circumstances this never happens because
1662 '\.ttfautohint' doesn't have an entry in the font's `cmap` table. (However,
1663 some test and demo programs like FreeType's `ftview` application or other
1664 glyph viewers that are able to bypass the `cmap` table might be affected.)
1667 Writing Systems
1668 ---------------
1670 In FreeType terminology, a writing system is a set of functions that
1671 provides auto-hinting for certain scripts. Right now, only two writing
1672 systems from FreeType's auto-hinter are available in ttfautohint: 'dummy'
1673 and 'latin'. The former handles the 'no-script' case; details to 'latin'
1674 follow in the next section.
1677 Scripts
1678 -------
1680 ttfautohint needs to know which script should be used to hint a specific
1681 glyph. To do so, it checks a glyph's Unicode character code whether it
1682 belongs to a given script.
1684 See '[Character Ranges](#character-ranges)' for a complete list of all
1685 handled scripts and its ranges. This list is auto-generated from a source
1686 code file, covering the 'latin' writing system. It also covers some
1687 non-latin scripts (in the Unicode sense) that have similar typographical
1688 properties.
1690 In ttfautohint, scripts are identified by four-character tags (if there are
1691 less characters, spaces are appended). The value `none` indicates 'no
1692 script'.
1694 Each script is represented by two tables to handle 'base' and 'non-base'
1695 characters. For ttfautohint, a non-base character is something that should
1696 not be affected by blue zones, regardless of whether this is a spacing or
1697 no-spacing glyph. In other words, non-base characters are hinted using a
1698 script's default stem width without applying blue zones.
1700 Right now, there are two pseudo-scripts that are used as fallbacks: `latb`
1701 and `latp`, used for latin subscript and superscript characters,
1702 respectively. Its main usage is support of phonetic alphabets like the IPA,
1703 which intermix those characters with normal characters sitting on the
1704 baseline, and which are not specially handled in corresponding OpenType
1705 features like `sups`.
1707 If a glyph's character code is not covered by a script range, it is handled
1708 by a *fallback script*. By default, the fallback script is `none`, which
1709 indicates handling by the 'latin' writing system without applying
1710 script-specific blue zones (but aligning stems to the grid if possible).
1711 The fallback script can be changed; see option
1712 [`--fallback-script`](#fallback-script).
1714 The user can also select whether uncovered glyphs are either hinted (which
1715 is the default) or scaled only with the fallback script's scaling
1716 parameters. This can be controlled with option
1717 [`--fallback-scaling`](#fallback-script). Note that fallback scaling only
1718 makes sense if the fallback script has x\ height blue zones, e.g., `cyrl` or
1719 `latn`.
1721 As a special case, specifying `none` as a fallback script and switching on
1722 fallback scaling ('`-f none -S`'), no hinting is applied at all to uncovered
1723 glyphs – using `none` always implies a scaling factor of\ 1.
1726 OpenType Features
1727 -----------------
1729 (Please read the [OpenType specification] for details on *features*, `GSUB`,
1730 and `GPOS` tables, and how they relate to scripts.)
1732 For modern OpenType fonts, character ranges are not sufficient to handle
1733 scripts.
1735 * Due to glyph substitution in the font (as specified in a font's `GSUB`
1736 table), which handles ligatures and similar typographic features, there
1737 is no longer a one-to-one mapping from an input Unicode character to a
1738 glyph index. Some ligatures, like 'fi', actually do have Unicode values
1739 for historical reasons, but most of them don't. While it is possible to
1740 map ligature glyphs into Unicode's Private Use Area (PUA), code values
1741 from this area are arbitrary by definition and thus unusable for
1742 ttfautohint.
1744 * Some features like `sups` (for handling superscript) completely change
1745 the appearance and even vertical position of the affected glyphs.
1746 Obviously, the blue zones for 'normal' glyphs no longer fit, thus the
1747 auto-hinter puts them into a separate group (called *style* in FreeType
1748 speak), having its own set of blue zones.
1751 Table: OpenType features handled specially by ttfautohint
1753 Feature tag Description
1754 --------------- -------------
1755 `c2cp` petite capitals from capitals
1756 `c2sc` small capitals from capitals
1757 `ordn` ordinals
1758 `pcap` petite capitals
1759 `sinf` scientific inferiors
1760 `smcp` small capitals
1761 `subs` subscript
1762 `sups` superscript
1763 `titl` titling
1766 There are two conditions to get a valid style for a feature in a given
1767 script.
1769 1. One of the script's standard characters must be available in the
1770 feature.
1772 2. The feature must provide characters to form at least one blue zone; see
1773 [above](#blue-zones).
1775 An additional complication is that features from the above table might use
1776 data not only from the `GSUB` but also from the `GPOS` table, containing
1777 information for glyph positioning. For example, the `sups` feature for
1778 superscripts might use the same glyphs as the `subs` feature for subscripts,
1779 simply moved up. ttfautohint skips such vertically shifted glyphs (except
1780 for accessing standard characters) because glyph positioning happens after
1781 hinting. Continuing our example, the `sups` feature wouldn't form a style,
1782 contrary to `subs`, which holds the unshifted glyphs.
1784 The remaining OpenType features of a script are not handled specially; the
1785 affected glyphs are simply hinted together with the 'normal' glyphs of the
1786 script.
1788 Note that a font might still contain some features not covered yet: OpenType
1789 has the concept of a *default script*; its data gets used for all scripts
1790 that aren't explicitly handled in a font. By default, ttfautohint unifies
1791 all affected glyphs from default script features with the `latn` script.
1792 This can be changed with option [`--default-script`](#default-script), if
1793 necessary.
1796 ttfautohint uses the [HarfBuzz] library for handling OpenType features.
1799 SFNT Tables
1800 -----------
1802 ttfautohint touches almost all SFNT tables within a TrueType or OpenType
1803 font. Note that only OpenType fonts with TrueType outlines are supported.
1804 OpenType fonts with a `CFF` or `CFF2` table (this is, with PostScript
1805 outlines) won't work.
1807 * `glyf`: All hints in the table are replaced with new ones. If option
1808 [`--composites`](#hint-composites) is used, one glyph gets added (namely
1809 the '\.ttfautohint' glyph) and all composites get an additional
1810 component.
1812 * `cvt`, `prep`, and `fpgm`: These tables get replaced with data
1813 necessary for the new hinting bytecode.
1815 * `gasp`: Set up to always use grayscale rendering, for all sizes, with
1816 grid-fitting for standard hinting, and symmetric grid-fitting and
1817 symmetric smoothing for horizontal subpixel hinting (ClearType).
1819 * `DSIG`: If it exists, it gets replaced with a dummy version.
1820 ttfautohint can't digitally sign a font; you have to do that afterwards.
1822 * `name`: The 'version' entries are modified to add information about the
1823 parameters that have been used for calling ttfautohint. This can be
1824 controlled with the [`--no-info`](#ttfautohint-info) option. Family
1825 name entries might also be affected by option
1826 [`--family-suffix`](#family-suffix).
1828 * `GPOS`, `hmtx`, `loca`, `head`, `maxp`, `post`: Updated to fit the
1829 additional '\.ttfautohint' glyph, the additional subglyphs in
1830 composites, and the new hinting bytecode.
1832 * `LTSH`, `hdmx`: Since ttfautohint doesn't do any horizontal hinting,
1833 those tables are superfluous and thus removed.
1835 * `VDMX`: Removed, since it depends on the original bytecode, which
1836 ttfautohint removes. A font editor might recompute the necessary data
1837 later on.
1840 Problems
1841 --------
1843 ### Interaction With FreeType
1845 Some versions of FreeType have an experimental extension for handling
1846 subpixel hinting; it is off by default and can be activated by setting the
1847 macro `TT_CONFIG_OPTION_SUBPIXEL_HINTING` to value\ 2 or\ 3 at compile time.
1848 This code has been contributed mainly by [Infinality], being a subset of his
1849 original patch. Many GNU/Linux distributions activate this code, or provide
1850 packages to activate it. [Note that starting with FreeType version 2.7 the
1851 Infinality extension is still available but superseded by a less aggressive
1852 subpixel hinting mode, to which the explanations in this section don't
1853 apply.]
1855 This extension changes the behaviour of many bytecode instructions to get
1856 better rendering results. However, not all changes are global; some of them
1857 are specific to certain fonts. For example, it contains font-specific
1858 improvements for the '[DejaVu] Sans' font family. The list of affected
1859 fonts is hard-coded; it can be found in FreeType's source code file
1860 `ttsubpix.c`.
1862 If you are going to process such specially-handled fonts with ttfautohint,
1863 serious rendering problems might show up. Since ttfautohint (intentionally)
1864 doesn't change the font name in the `name` table, the Infinality extension
1865 has no chance to recognize that the hints are different. All such problems
1866 vanish if the font gets renamed in its `name` table (the name of the font
1867 file itself doesn't matter), for example, by using option
1868 [`--family-suffix`](#family-suffix).
1870 ### Incorrect Unicode Character Map
1872 Fonts with an incorrect Unicode `cmap` table will not be properly hinted by
1873 ttfautohint. Especially older fonts do cheat; for example, there exist
1874 Hebrew fonts that map its glyphs to character codes 'A', 'B', etc., to make
1875 them work with non-localized versions of Windows\ 98, say.
1877 Since ttfautohint needs to find both standard and blue zone characters, it
1878 relies on correct Unicode values. If you want to handle such fonts, please
1879 fix their `cmap` tables accordingly before running ttfautohint.
1881 ### Irregular Glyph Heights
1883 The central concept of ttfautohint's hinting algorithm as discussed
1884 [above](#segments-and-edges) is to identify horizontal segments at extremum
1885 positions, especially for blue zones. If such a segment is missing, it
1886 cannot be associated with a blue zone, possibly leading to irregular heights
1887 for the particular glyph.
1889 Normally, a segment has a horizontal length of at least 20\ font units
1890 (assuming 2048 units per EM)^[To be more precise, the sum of the height and
1891 length of a segment must be at least 20 font units, and the height multiplied
1892 by\ 14 must not exceed the length. Thus (19,1) is also a valid minimum
1893 (length,height) pair, while (18,2) isn't. The value\ 20 is heuristic and
1894 hard-coded, as is the value\ 14 (corresponding to a slope of approx.
1895 4.1°).]. Using a [Control Instructions File](#control-instructions-file),
1896 however, it is possible to define additional segments at arbitrary points
1897 that help overcome this restriction, making it possible to fix (most of)
1898 such problems.
1900 ### Diagonals
1902 ttfautohint doesn't handle diagonal lines specially. For thin outlines,
1903 this might lead to strokes that look too thick at smaller sizes. A font
1904 designer might compensate this to a certain amount by slightly reducing the
1905 stroke width of diagonal lines. However, in many cases the sub-optimal
1906 appearance of a stroke with borders that don't exactly fit the pixel grid is
1907 not the outline itself but an incorrect gamma value of the monitor: People
1908 tend to not properly adjust it, and the default values of most operating
1909 systems are too low, causing too much darkening of such strokes. It is thus
1910 of vital importance to compare ttfautohint's results with similar fonts to
1911 exclude any systematic effect not related to the outlines themselves.
1914 Extending ttfautohint with new scripts
1915 --------------------------------------
1917 Right now, adding new scripts to ttfautohint only works on the source code
1918 level, this is, you have to patch the C\ source code.
1920 The process itself isn't very complicated; it is demonstrated best by
1921 example. The following commits in ttfautohint add Ethiopian and Armenian,
1922 respectively.
1924 | [https://repo.or.cz/ttfautohint.git/commitdiff/d14c7c07](https://repo.or.cz/ttfautohint.git/commitdiff/d14c7c07)
1925 | [https://repo.or.cz/ttfautohint.git/commitdiff/b5022cd9](https://repo.or.cz/ttfautohint.git/commitdiff/b5022cd9)
1927 It shows that you have to do the following steps.
1929 * Add blue zone character data to the file `lib/tablue.dat`.
1931 * Add the proper Unicode ranges to `lib/taranges.c`, following the
1932 structure of similar entries.
1934 * Similarly, the files `lib/tastyles.h` and `lib/ttfautohint-script.h`
1935 must be updated. The latter holds the information on the used default
1936 character or characters; it also references the corresponding script tag
1937 `HB_SCRIPT_XXX` as used by the HarfBuzz library.
1939 If there are any questions, please contact the [FreeType mailing
1940 list](https://lists.nongnu.org/mailman/listinfo/freetype) for help. Note
1941 that the script data in ttfautohint are hold in sync with FreeType's
1942 auto-hinter.
1945 Control Instructions
1946 ====================
1948 An entry in a control instructions file has various syntax forms, which are
1949 discussed here. Brackets indicate optional elements.
1952 Common Syntax Elements
1953 ----------------------
1955 *font‑idx* gives the index of the font in a TrueType Collection, starting
1956 with value\ 0. If missing, it is set to zero. For normal TrueType fonts,
1957 only value zero is valid. A font index can be specified in decimal, octal,
1958 or hexadecimal format, the latter two indicated by the prefixes `0` and
1959 `0x`, respectively.
1961 *glyph‑id* is either a glyph's name as listed in the font's `post` SFNT
1962 table or a glyph index. A glyph name consists of characters from the set
1963 '`A-Za-z0-9._`' only and does not start with a digit or period, with the
1964 exceptions of the names '`.notdef`' and '`.null`'. A glyph index starts
1965 with value\ 0 can be specified in decimal, octal, or hexadecimal format, the
1966 latter two indicated by the prefixes `0` and `0x`, respectively. Glyph
1967 names are internally converted to glyph indices.
1969 *points* are number ranges, see '[x Height Snapping
1970 Exceptions](#x-height-snapping-exceptions)' for the syntax.
1972 Similar to the Bourne shell (`sh` or `bash`), a comment starts with
1973 character '`#`'; the rest of the line is ignored. An empty line is ignored
1974 also. Both the newline character and '`;`' can be used as a separator
1975 between exception entries. A trailing '`\`' at the end of a line continues
1976 the current line on the next one.
1978 A control instructions file is parsed line by line; later entries override
1979 earlier entries (in case there is something to override).
1982 Style Adjustments
1983 -----------------
1985 This syntax form makes it possible to override the style assignment
1986 algorithm of ttfautohint; see '[Scripts](#scripts)' and '[OpenType
1987 Features](#opentype-features)' for more details.
1989 > *\[*\ font-idx\ *\]*\ \ script\ \ feature\ \ *`@`*\ \ glyph-ids
1991 *script* is a four-letter name^[The notable exception is the tag 'lao',
1992 which originally has a trailing space as the fourth character. However,
1993 ttfautohint ignores the space.] of one of the scripts supported by
1994 ttfautohint. *feature* is one of the four-letter names of features
1995 supported by ttfautohint.
1997 The elements of *glyph-ids* are a list of comma separated *glyph-id* values
1998 or value ranges. Note that is not necessary that elements are specified in
1999 increasing order.
2001 Assuming that a font contains superscript digits 'zero.sups' to 'nine.sups'
2002 together with the glyphs 'a.sups' and 'o.sups', use a line
2004 ```
2005 cyrl sups @ zero.sups-nine.sups, a.sups, o.sups
2006 ```
2008 to add those glyphs to the style handling Cyrillic superscript glyphs.
2009 However, it is still necessary that the selected script contains proper
2010 [Blue Zone characters](#blue-zones), otherwise those glyphs aren't handled
2011 at all.
2013 Use the `--debug` command line option to see how ttfautohint assigns glyph
2014 indices of a font to styles.
2017 Stem Width Adjustments
2018 ----------------------
2020 Use the following syntax form to adjust stem width values for a given style,
2021 overriding ttfautohint's algorithm; see '[Scripts](#scripts)' and '[OpenType
2022 Features](#opentype-features)' for more details. This adjustment doesn't
2023 change the glyph shapes; it only influences the hinting process.
2025 > *\[*\ font-idx\ *\]*\ \ script\ \ feature\ \ *`w[idth]`*\ \ stem-widths
2027 *script* and *feature* are the same as with style adjustments; see above.
2028 However, *script* can additionally be the wildcard character '`*`', which
2029 indicates 'any script'. Parameter `width` can be abbreviated as '`w`'.
2031 *stem-widths* is an unsorted list of comma separated integer stem width
2032 values (in font units); the first value gives the style's default stem
2033 width.
2035 The effect of this adjustment depends [on the selected stem width
2036 algorithm](#stem-width-and-positioning-mode). For smooth stem width
2037 positioning, only the first (i.e., the default) value is used; it gets a
2038 higher preference than other discrete stem width choices. For strong stem
2039 width positioning, the stem widths are snapped to the provided values (if
2040 not differing too much) before rounding to an integer pixel value. For
2041 natural stem width positioning, this adjustment is ignored.
2043 A typical example is to reduce the default stem width of an extra-bold font,
2044 which gets better hinted if a stem width of, say, 100 is used instead of the
2045 default value 150. Let's also assume that the font further contains latin
2046 subscript and superscript characters that are hinted best with a stem width
2047 set to 80 font units. We can achieve this with the following lines in a
2048 control instructions file.
2051 ```
2052 * dflt width 100
2053 latb dflt width 80
2054 latp dflt width 80
2055 ```
2057 Without the adjustment chances are very high that the 'eyes' in glyphs 'e'
2058 or 'a' of extra-bold fonts are filled at smaller PPEM values.
2060 Use the `--debug` command line option to see how ttfautohint assigns stem
2061 widths to styles by default.
2064 Glyph Adjustments
2065 -----------------
2067 The following syntax forms allows adjustments of a glyph's hinting process.
2069 ### Change Direction of Points, Artificial Segments
2071 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`l`\[`eft`\]|`r`\[`ight`\]*\ \ points\ \ *\[*\ *`(`*\ left‑offset\ *`,`*\ right‑offset\ *`)`*\ *\]*\
2073 The mutually exclusive parameters `left` and `right` (which can be
2074 abbreviated as '`l`' and '`r`', respectively) indicate that the following
2075 points have left or right 'out' direction, respectively, overriding
2076 ttfautohint's algorithm for setting point directions. The 'out direction'
2077 of a point is the direction of the outline *leaving* the point (or passing
2078 the control point). If the specified direction is identical to what
2079 ttfautohint computes, nothing special happens. Otherwise, a one-point
2080 segment with the specified direction gets created, see
2081 [above](#segments-and-edges). By default, its length is zero. Setting
2082 *left‑offset* and *right‑offset*, you can change the segment's horizontal
2083 start and end position relative to the point position. *left‑offset* and
2084 *right‑offset* are integers measured in font units.
2086 The following five images, displaying glyphs 'O' and 'Q' from the font
2087 [Halant-Regular](https://fonts.google.com/specimen/Halant), demonstrate
2088 how to use direction changes.
2090 
2094 ![The same glyphs, shown at 12px before hinting. [Please ignore the outline
2095 distortion in the upper right of glyph 'O'; this is a bug in FontForge
2096 while running the TrueType
2097 debugger.]](img/Halant-Regular-O-Q-unhinted-12px.png)
2099 
2109 
2119 
2131 ### Unset Direction of Points
2133 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`n`\[`odir`\]*\ \ points\
2135 Parameter `nodir` (or '`n`') sets the 'out' direction of the following
2136 points to 'no direction', this is, neither left nor right. If the specified
2137 direction is identical to what ttfautohint computes, nothing special
2138 happens. Otherwise, ttfautohint no longer considers those points as part of
2139 horizontal segments, thus treating them as ['weak'](#grid-fitting) points.
2141 Modifying or adding segments doesn't directly modify the outlines; it only
2142 influences the hinting process.
2144 ### Delta Exceptions
2146 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`t`\[`ouch`\]|`p`\[`oint`\]*\ \ points\ \ *\[*\ *`x`\[`shift`\]*\ x‑shift\ *\]*\ \ *\[*\ *`y`\[`shift`\]*\ y‑shift\ *\]*\ \ *`@`*\ \ ppems\
2148 The mutually exclusive parameters `touch` and `point` (which can be
2149 abbreviated as '`t`' and '`p`', respectively) make ttfautohint apply delta
2150 exceptions for the given points, shifting them by the given values. Delta
2151 exceptions entered with `touch` are applied before the final 'IUP'
2152 (*interpolate untouched points*) instructions in a glyph's bytecode,
2153 exceptions entered with `point` after 'IUP' (please consult Greg Hitchcock's
2154 [ClearType Whitepaper] for more on pre-IUP and post-IUP delta hints).
2155 Additionally, the `touch` parameter makes the bytecode *touch* the affected
2156 points; such points are no longer affected by 'IUP' at all. Note that in
2157 ClearType mode all deltas along the x\ axis are discarded, and deltas along
2158 the y\ axis are only executed for touched points. As a consequence,
2159 vertical delta exceptions entered with `point` should not be used in
2160 ClearType mode.^[Unfortunately, there is a bug in FreeType prior to version
2161 2.5.4 (released in December 2014) that completely disables vertical delta
2162 exceptions if subpixel hinting is activated. For this reason you should
2163 expect that the `touch` parameter fails on older GNU/Linux distributions.]
2165 *ppems*, similar to *points*, are number ranges, see '[x Height Snapping
2166 Exceptions](#x-height-snapping-exceptions)' for the syntax.
2168 *x‑shift* and *y‑shift* represent real numbers that get rounded to multiples
2169 of 1/8 pixels. The entries for `xshift` ('`x`') and `yshift` ('`y`') are
2170 optional; if missing, the corresponding value is set to zero. If both
2171 values are zero, the delta exception entry is ignored as a whole.
2173 Values for *x‑shift* and *y‑shift* must be in the range [−1.0;1.0]. Values
2174 for *ppems* must be in the range [6;53]. Values for *points* are limited by
2175 the number of points in the glyph.
2177 Note that only character '`.`' is recognized as a decimal point, and a
2178 thousands separator is not accepted.
2180 As an example for delta instructions, let's assume that you want to shift
2181 points 2, 3, and\ 4 in glyph 'Aacute' at PPEM sizes 12 and\ 13 by a vertical
2182 amount of 0.25 pixels. This corresponds to the line
2184 ```
2185 Aacute touch 2-4 yshift 0.25 @ 12, 13
2186 ```
2188 in a control instructions file. Since we use `touch` and not `point`,
2189 points 2, 3, and\ 4 are no longer subject to the final 'IUP' instruction,
2190 which interpolates weak, untouched point positions between strong, touched
2191 ones, cf. the description
2192 [here](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM05/Chap5.html#IUP).