| blob | 4fa0304e4d5e39b29490edbdfcd9e3b8744a0741 |
1 % ttfautohint
2 % Werner Lemberg
3 %
5 <!--
6 Copyright (C) 2011-2018 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](http://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 ### Miscellaneous
636 Watch input files\ \ \ (`ttfautohintGUI` only)
637 : If this checkbox is set, automatically regenerate the output file as
638 soon as an input file (either the font, the control instructions file,
639 or the reference font) gets modified.
641 Pressing the 'Run' button starts watching. If an error occurs, watching
642 stops and must be restarted with the 'Run' button.
644 `--ignore-restrictions`, `-i`
645 : By default, fonts that have bit\ 1 set in the 'fsType' field of the
646 `OS/2` table are rejected. If you have a permission of the font's legal
647 owner to modify the font, specify this command line option.
649 If this option is not set, `ttfautohintGUI` shows a dialogue to handle
650 such fonts if necessary.
652 `--help`, `-h`
653 : On the console, print a brief documentation on standard output and exit.
654 This doesn't work with `ttfautohintGUI` on MS Windows.
656 `--version`, `-v`
657 : On the console, print version information on standard output and exit.
658 This doesn't work with `ttfautohintGUI` on MS Windows.
660 `--ttfa-info`, `-T`\ \ \ (not in `ttfautohintGUI`)
661 : Print [`TTFA` table](#add-ttfa-info-table) of the input font on standard
662 output if present, then exit.
664 `--debug`\ \ \ (not in `ttfautohintGUI`)
665 : Print *a lot* of debugging information on standard error while
666 processing a font (you should redirect stderr to a file).
668 To reduce the amount of debug data it is recommended to restrict the
669 hinting process to a single PPEM value, e.g.,
671 ```
672 ttfautohint --debug -l 15 -r 15 ... > debug.txt 2>&1
673 ```
677 Background and Technical Details
678 ================================
680 [Real-Time Grid Fitting of Typographic
681 Outlines](http://www.tug.org/TUGboat/tb24-3/lemberg.pdf) is a scholarly
682 paper that describes FreeType's auto-hinter in some detail. Regarding the
683 described data structures it is slightly out of date, but the algorithm
684 itself hasn't changed in general.
686 The next few subsections are mainly based on this article, introducing some
687 important concepts. Note that ttfautohint only does hinting along the
688 vertical direction (modifying y\ coordinates only).
691 Segments and Edges
692 ------------------
694 A glyph consists of one or more *contours* (this is, closed curves). For
695 example, glyph 'O' consists of two contours, while glyph 'I' has only one.
697 
700 A *segment* is a series of consecutive points of a contour (including its
701 Bézier control points) that are approximately aligned along a coordinate
702 axis. A segment has one of three possible directions: left, right, or none
703 (which means neither left nor right), derived from the TrueType outline
704 directions. ttfautohint itself creates segments that contain at least two
705 points. Using control instructions, however, it is possible to create
706 one-point segments, which are useful for fine-tuning the hinting process.
708 
714 An *edge* corresponds to a single coordinate value (allowing for a small
715 threshold) on the main dimension that collects one or more segments, all
716 pointing into the same direction (either left or right, all others are
717 ignored). While finding segments is done on the unscaled outline, finding
718 edges is bound to the device resolution. See [below](#hint-sets) for an
719 example.
721 In general, segments and edges pointing into different directions 'repel'
722 each other, thus preventing alignment on the same vertical coordinate if
723 they are near. Note that this is a simplification, but it should help
724 understand how to manipulate and/or create segments in control instructions
725 files.
727 The analysis to find segments and edges is specific to a writing
728 system, see [below](#writing-systems).
731 Feature Analysis
732 ----------------
734 The auto-hinter analyzes a font in two steps. Right now, everything
735 described here happens for the horizontal axis only, providing vertical
736 hinting.
738 * Global Analysis
740 This affects the hinting of all glyphs, trying to give them a uniform
741 appearance.
743 + Compute standard horizontal stem width of the font. The value
744 is normally taken from glyphs that resemble letter 'o'.
746 If, for a given script, there is no glyph for at least one standard
747 character in the input font, a fallback stem width gets used. See
748 also option [`--fallback-stem-width`](#fallback-stem-width).
750 The stem width(s) found by the algorithm can be overridden with the
751 [`width`](#stem-width-adjustments) control instruction.
753 + Compute blue zones, see [below](#blue-zones).
755 If the stem widths of single glyphs differ by a large value, or if
756 ttfautohint fails to find proper blue zones, hinting becomes quite poor,
757 possibly leading even to severe shape distortions.
760 Table: script-specific standard characters of the 'latin' writing system
762 Script Standard characters
763 -------- ---------------------
764 `adlm` '𞤌', U+1E90C, ADLAM CAPITAL LETTER O
765 '𞤮', U+1E92E, ADLAM SMALL LETTER O
766 `arab` 'ـ', U+0640, ARABIC TATWEEL
767 'ل', U+0644, ARABIC LETTER LAM
768 'ح', U+062D, ARABIC LETTER HAH
769 `armn` 'օ', U+0585, ARMENIAN SMALL LETTER OH
770 'Օ', U+0555, ARMENIAN CAPITAL LETTER OH
771 `avst` '𐬚', U+10B1A, AVESTAN LETTER THE
772 `bamu` 'ꛁ', U+A6C1, BAMUM LETTER YUQ
773 'ꛯ', U+A6EF, BAMUM LETTER KOGHOM
774 `beng` '০', U+09E6, BENGALI DIGIT ZERO
775 '৪', U+09EA, BENGALI DIGIT FOUR
776 `buhd` 'ᝋ', U+174B, BUHID LETTER MA
777 'ᝏ', U+174F, BUHID LETTER WA
778 `cakm` '𑄤', U+11124, CHAKMA LETTER WAA
779 '𑄉', U+11109, CHAKMA LETTER GAA
780 '𑄛', U+1111B, CHAKMA LETTER PAA
781 `cans` 'ᑌ', U+144C, CANADIAN SYLLABICS TE
782 'ᓚ', U+14DA, CANADIAN SYLLABICS LA
783 `cari` '𐊫', U+102AB, CARIAN LETTER O
784 '𐋉', U+102C9, CARIAN LETTER RR
785 `cher` 'Ꭴ', U+13A4, CHEROKEE LETTER U
786 'Ꮕ', U+13C5, CHEROKEE LETTER NV
787 'ꮕ', U+AB95, CHEROKEE SMALL LETTER NV
788 `copt` 'Ⲟ', U+2C9E, COPTIC CAPITAL LETTER O
789 'ⲟ', U+2C9F, COPTIC SMALL LETTER O
790 `cprt` '𐠅', U+10805, CYPRIOT SYLLABLE JA
791 '𐠣', U+10823, CYPRIOT SYLLABLE RA
792 `cyrl` '\Cyrillic{}о\cyrillic{}', U+043E, CYRILLIC SMALL LETTER O
793 '\Cyrillic{}О\cyrillic{}', U+041E, CYRILLIC CAPITAL LETTER O
794 `deva` 'ठ', U+0920, DEVANAGARI LETTER TTHA
795 'व', U+0935, DEVANAGARI LETTER VA
796 'ट', U+091F, DEVANAGARI LETTER TTA
797 `dsrt` '𐐄', U+10404, DESERET CAPITAL LETTER LONG O
798 '𐐬', U+1042C, DESERET SMALL LETTER LONG O
799 `ethi` 'ዐ', U+12D0, ETHIOPIC SYLLABLE PHARYNGEAL A
800 `geor` 'ი', U+10D8, GEORGIAN LETTER IN
801 'ე', U+10D4, GEORGIAN LETTER EN
802 'ა', U+10D0, GEORGIAN LETTER AN
803 `geok` 'Ⴖ', U+10B6, GEORGIAN CAPITAL LETTER GHAN
804 'Ⴑ', U+10B1, GEORGIAN CAPITAL LETTER SAN
805 'ⴙ', U+2D19, GEORGIAN SMALL LETTER CHIN
806 `glag` 'Ⱅ', U+2C15, GLAGOLITIC CAPITAL LETTER TVRIDO
807 'ⱅ', U+2C45, GLAGOLITIC SMALL LETTER TVRIDO
808 `goth` '𐌴', U+10334, GOTHIC LETTER AIHVUS
809 '𐌾', U+1033E, GOTHIC LETTER JER
810 '𐍃', U+10343, GOTHIC LETTER SAUIL
811 `grek` '\Greek{}ο\greek{}', U+03BF, GREEK SMALL LETTER OMICRON
812 '\Greek{}Ο\greek{}', U+039F, GREEK CAPITAL LETTER OMICRON
813 `gujr` 'ટ', U+0A9F, GUJARATI LETTER TTA
814 '૦', U+0AE6, GUJARATI DIGIT ZERO
815 `guru` 'ਠ', U+0A20, GURMUKHI LETTER TTHA
816 'ਰ', U+0A30, GURMUKHI LETTER RA
817 '੦', U+0A66, GURMUKHI DIGIT ZERO
818 `hebr` 'ם', U+05DD, HEBREW LETTER FINAL MEM
819 `kali` 'ꤍ', U+A90D, KAYAH LI LETTER NGA
820 '꤀', U+A900, KAYAH LI DIGIT ZERO
821 `knda` '೦', U+0CE6, KANNADA DIGIT ZERO
822 'ಬ', U+0CAC, KANNADA LETTER BA
823 `khmr` '០', U+17E0, KHMER DIGIT ZERO
824 `lao` '໐', U+0ED0, LAO DIGIT ZERO
825 `latn` '\Latin{}o\latin{}', U+006F, LATIN SMALL LETTER O
826 '\Latin{}O\latin{}', U+004F, LATIN CAPITAL LETTER O
827 '\Latin{}0\latin{}', U+0030, DIGIT ZERO
828 `lisu` 'ꓳ', U+A4F3, LISU LETTER
829 `mlym` 'ഠ', U+0D20, MALAYALAM LETTER TTHA
830 'റ', U+0D31, MALAYALAM LETTER RRA
831 `mymr` 'ဝ', U+101D, MYANMAR LETTER WA
832 'င', U+1004, MYANMAR LETTER NGA
833 'ဂ', U+1002, MYANMAR LETTER GA
834 `nkoo` 'ߋ', U+07CB, NKO LETTER EE
835 '߀', U+07C0, NKO DIGIT ZERO
836 `olck` 'ᱛ', U+1C5B, OL CHIKI LETTER AT
837 `orkh` '𐰗', U+10C17, OLD TURKIC LETTER YENISEI AY
838 `osge` '𐓂', U+104C2, OSAGE CAPITAL LETTER O
839 '𐓪', U+104EA, OSAGE SMALL LETTER O
840 `osma` '𐒆', U+10486, OSMANYA LETTER DEEL
841 '𐒠', U+104A0, OSMANYA DIGIT ZERO
842 `saur` 'ꢝ', U+A89D, SAURASHTRA LETTER TTHA
843 '꣐', U+A8D0, SAURASHTRA DIGIT ZERO
844 `shaw` '𐑴', U+10474, SHAVIAN LETTER OAK
845 `sinh` 'ට', U+0DA7, SINHALA LETTER ALPAPRAANA TTAYANNA
846 `sund` '᮰', U+1BB0, SUNDANESE DIGIT ZERO
847 `taml` '௦', U+0BE6, TAMIL DIGIT ZERO
848 `tavt` 'ꪒ', U+AA92, TAI VIET LETTER LOW DO
849 'ꪫ', U+AAAB, TAI VIET LETTER HIGH VO
850 `telu` '౦', U+0C66, TELUGU DIGIT ZERO
851 '౧', U+0C67, TELUGU DIGIT ONE
852 `tfng` 'ⵔ', U+2D54, TIFINAGH LETTER YAR
853 `thai` 'า', U+0E32, THAI CHARACTER SARA AA
854 'ๅ', U+0E45, THAI CHARACTER LAKKHANGYAO
855 '๐', U+0E50, THAI DIGIT ZERO
856 `vaii` 'ꘓ', U+A613, VAI SYMBOL FEENG
857 'ꖜ', U+A59C, VAI SYLLABLE BHU
858 'ꖴ', U+A5B4, VAI SYLLABLE KU
861 Table: standard characters of the 'latin' writing system, special scripts
863 Script Standard characters
864 ---------- ---------------------
865 `khms` '᧡', U+19E1, KHMER SYMBOL MUOY KOET
866 '᧪', U+19EA, KHMER SYMBOL DAP KOET
867 `latb` '\Latin{}ₒ\latin{}', U+2092, LATIN SUBSCRIPT SMALL LETTER O
868 '\Latin{}₀\latin{}', U+2080, SUBSCRIPT ZERO
869 `latp` '\Latin{}ᵒ\latin{}', U+1D52, MODIFIER LETTER SMALL O
870 '\Latin{}ᴼ\latin{}', U+1D3C, MODIFIER LETTER CAPITAL O
871 '\Latin{}⁰\latin{}', U+2070, SUPERSCRIPT ZERO
874 * Glyph Analysis
876 This is a per-glyph operation.
878 + Find segments and edges.
880 + Link edges to set up stems and serifs. The abovementioned paper
881 gives more details on what exactly constitutes a stem or a serif and
882 how the algorithm works.
885 Blue Zones
886 ----------
888 
893 Outlines of certain characters are used to determine *blue zones*. This
894 concept is the same as with Type\ 1 fonts: All glyph points that lie in
895 certain small horizontal zones get aligned vertically.
897 The tables below show the blue zone characters of all available scripts of
898 the latin writing system; the values are hard-coded in the source code.
899 Since the auto-hinter takes mean values it is not necessary that all
900 characters of a zone are present.
902 'Round' characters in blue zones (e.g., the top and bottom of 'O' or the
903 bottom of 'g') are used to control overshoot handling.
905 Blue zones marked with an asterisk are x\ height blue zones, which are
906 adjusted to be on the pixel grid (to improve rendering at small sizes) by
907 scaling the remaining blue zones before they are adjusted to the grid. See
908 also option [`--increase-x-height`](#x-height-increase-limit).
911 Table: `adlm` (Adlam) blue zones
913 ID Blue zone Characters
914 ---- ----------- ------------
915 1 top of capital letters 𞤌 𞤅 𞤈 𞤏 𞤔 𞤚
916 2 bottom of capital letters 𞤂 𞤖
917 3* top of small letters 𞤬 𞤮 𞤻 𞤼 𞤾
918 4 bottom of small letters 𞤤 𞤨 𞤩 𞤭 𞤴 𞤸 𞤺 𞥀
921 Table: `arab` (Arabic) blue zones
923 ID Blue zone Characters
924 ---- ----------- ------------
925 1 top of letters with vertical stroke ا إ ل ك ط ظ
926 2 bottom of letters ت ث ط ظ ك
927 3 glyph joining ـ
930 Table: `armn` (Armenian) blue zones
932 ID Blue zone Characters
933 ---- ----------- ------------
934 1 top of capital letters Ա Մ Ւ Փ Բ Գ Դ Օ
935 2 bottom of capital letters Ւ Ո Փ Ճ Շ Ս Տ Օ
936 3 top of ascenders of small letters ե է ի մ վ փ ֆ փ
937 4* top of small letters ա յ ւ ս գ ջ ր օ
938 5 bottom of small letters հ ո ճ ա ե ծ ս օ
939 6 bottom of descenders of small letters բ ը ի լ ղ պ փ ց
942 Table: `avst` (Avestan) blue zones
944 ID Blue zone Characters
945 ---- ----------- ------------
946 1 top of letters 𐬀 𐬁 𐬐 𐬛
947 2 bottom of letters 𐬀 𐬁
950 Table: `bamu` (Bamum) blue zones
952 ID Blue zone Characters
953 ---- ----------- ------------
954 1 top of letters ꚧ ꚨ ꛛ ꛉ ꛁ ꛈ ꛫ ꛯ
955 2 bottom of letters ꚭ ꚳ ꚶ ꛬ ꚢ ꚽ ꛯ ꛲
958 Table: `beng` (Bengali) blue zones
960 ID Blue zone Characters
961 ---- ----------- ------------
962 1 baseline (flat glyphs only) অ ড ত ন ব ভ ল ক
963 2 top of ascenders ই ট ঠ ি ী ৈ ৗ
964 3* top of baseline ও এ ড ত ন ব ল ক
965 4 bottom of base characters অ ড ত ন ব ভ ল ক
967 Contrary to scripts like latin, the baseline in Bengali is on the top, and
968 we hint from top to bottom.
971 Table: `buhd` (Buhid) blue zones
973 ID Blue zone Characters
974 ---- ----------- ------------
975 1 top of letters ᝐ ᝈ
976 2 top of large letters ᝅ ᝊ ᝎ
977 3* top of small letters ᝂ ᝃ ᝉ ᝌ
978 4 bottom of letters ᝀ ᝃ ᝆ ᝉ ᝋ ᝏ ᝑ
981 Table: `cakm` (Chakma) blue zones
983 ID Blue zone Characters
984 ---- ----------- ------------
985 1 top of letters 𑄃 𑄅 𑄉 𑄙 𑄗
986 2 bottom of letters 𑄅 𑄛 𑄝 𑄗 𑄓
987 3 bottom of descenders of letters 𑄖𑄳𑄢 𑄘𑄳𑄢 𑄙𑄳𑄢 𑄤𑄳𑄢 𑄥𑄳𑄢
990 Table: `cans` (Canadian Syllabics) blue zones
992 ID Blue zone Characters
993 ---- ----------- ------------
994 1 top of letters ᗜ ᖴ ᐁ ᒣ ᑫ ᑎ ᔑ ᗰ
995 2 bottom of letters ᗶ ᖵ ᒧ ᐃ ᑌ ᒍ ᔑ ᗢ
996 3* top of small letters ᓓ ᓕ ᓀ ᓂ ᓄ ᕄ ᕆ ᘣ
997 4 bottom of small letters ᕃ ᓂ ᓀ ᕂ ᓗ ᓚ ᕆ ᘣ
998 5 top of superscript letters ᐪ ᙆ ᣘ ᐢ ᒾ ᣗ ᔆ
999 6 bottom of superscript letters ᙆ ᗮ ᒻ ᐞ ᔆ ᒡ ᒢ ᓑ
1002 Table: `cari` (Carian) blue zones
1004 ID Blue zone Characters
1005 ---- ----------- ------------
1006 1 top of letters 𐊧 𐊫 𐊬 𐊭 𐊱 𐊺 𐊼 𐊿
1007 2 bottom of letters 𐊣 𐊧 𐊷 𐋀 𐊫 𐊸 𐋉
1010 Table: `cher` (Cherokee) blue zones
1012 ID Blue zone Characters
1013 ---- ----------- ------------
1014 1 top of capital letters Ꮖ Ꮋ Ꭼ Ꮓ Ꭴ Ꮳ Ꭶ Ꮥ
1015 2 bottom of capital letters Ꮖ Ꮋ Ꭼ Ꮓ Ꭴ Ꮳ Ꭶ Ꮥ
1016 3 top of ascenders of small letters ꮒ ꮤ ꮶ ꭴ ꭾ ꮗ ꮝ ꮿ
1017 4* top of small letters ꮖ ꭼ ꮓ ꮠ ꮳ ꭶ ꮥ ꮻ
1018 5 bottom of small letters ꮖ ꭼ ꮓ ꮠ ꮳ ꭶ ꮥ ꮻ
1019 6 bottom of descenders of small letters ᏸ ꮐ ꭹ ꭻ
1022 Table: `copt` (Coptic) blue zones
1024 ID Blue zone Characters
1025 ---- ----------- ------------
1026 1 top of capital letters Ⲍ Ⲏ Ⲡ Ⳟ Ⲟ Ⲑ Ⲥ Ⳋ
1027 2 bottom of capital letters Ⳑ Ⳙ Ⳟ Ⲏ Ⲟ Ⲑ Ⳝ Ⲱ
1028 3* top of small letters ⲍ ⲏ ⲡ ⳟ ⲟ ⲑ ⲥ ⳋ
1029 4 bottom of small letters ⳑ ⳙ ⳟ ⲏ ⲟ ⲑ ⳝ Ⳓ
1032 Table: `cprt` (Cypriot) blue zones
1034 ID Blue zone Characters
1035 ---- ----------- ------------
1036 1 top of letters 𐠍 𐠙 𐠳 𐠱 𐠅 𐠓 𐠣 𐠦
1037 2 bottom of letters 𐠃 𐠊 𐠛 𐠣 𐠳 𐠵 𐠐
1038 3 top of small letters 𐠈 𐠏 𐠖
1039 4 bottom of small letters 𐠈 𐠏 𐠖
1042 Table: `cyrl` (Cyrillic) blue zones
1044 ID Blue zone Characters
1045 ---- ----------- ------------
1046 1 top of capital letters \Cyrillic{}Б В Е П З О С Э\cyrillic{}
1047 2 bottom of capital letters \Cyrillic{}Б В Е Ш З О С Э\cyrillic{}
1048 3* top of small letters \Cyrillic{}х п н ш е з о с\cyrillic{}
1049 4 bottom of small letters \Cyrillic{}х п н ш е з о с\cyrillic{}
1050 5 bottom of descenders of small letters \Cyrillic{}р у ф\cyrillic{}
1053 Table: `deva` (Devanagari) blue zones
1055 ID Blue zone Characters
1056 ---- ----------- ------------
1057 1 top of ascenders ई ऐ ओ औ ि ी ो ौ
1058 2 top of baseline क म अ आ थ ध भ श
1059 3* top of baseline (flat glyphs only) क न म उ छ ट ठ ड
1060 4 bottom of base characters क न म उ छ ट ठ ड
1061 5 bottom of descenders ु ृ
1063 Contrary to scripts like latin, the baseline in Devanagari is on the top,
1064 and we hint from top to bottom. Note that some fonts have extreme variation
1065 in the height of the round elements in Zone\ 3; for this reason we also
1066 define Zone\ 1, which must be always present.
1069 Table: `dsrt` (Deseret) blue zones
1071 ID Blue zone Characters
1072 ---- ----------- ------------
1073 1 top of capital letters 𐐂 𐐄 𐐋 𐐗 𐐑
1074 2 bottom of capital letters 𐐀 𐐂 𐐄 𐐗 𐐛
1075 3* top of small letters 𐐪 𐐬 𐐳 𐐿 𐐹
1076 4 bottom of small letters 𐐨 𐐪 𐐬 𐐿 𐑃
1079 Table: `ethi` (Ethiopian) blue zones
1081 ID Blue zone Characters
1082 ---- ----------- ------------
1083 1 top of letters ሀ ሃ ዘ ፐ ማ በ ዋ ዐ
1084 2 bottom of letters ለ ሐ በ ዘ ሀ ሪ ዐ ጨ
1087 Table: `geok` (Georgian Khutsuri) blue zones
1089 ID Blue zone Characters
1090 ---- ----------- ------------
1091 1 top of Asomtavruli letters Ⴑ Ⴇ Ⴙ Ⴜ Ⴄ Ⴅ Ⴓ Ⴚ
1092 2 bottom of Asomtavruli letters Ⴄ Ⴅ Ⴇ Ⴈ Ⴆ Ⴑ Ⴊ Ⴋ
1093 3* top of Nuskhuri letters ⴁ ⴗ ⴂ ⴄ ⴅ ⴇ ⴔ ⴖ
1094 4 bottom of Nuskhuri letters ⴈ ⴌ ⴖ ⴎ ⴃ ⴆ ⴋ ⴢ
1095 5 top of ascender Nuskhuri letters ⴐ ⴑ ⴓ ⴕ ⴙ ⴛ ⴡ ⴣ
1096 6 bottom of Nuskhuri descender letters ⴄ ⴅ ⴔ ⴕ ⴁ ⴂ ⴘ ⴝ
1098 Georgian Asomtavruli and Nuskhuri form the old ecclesiastical script,
1099 Khutsuri. Note that fonts show a great variation in height and depth of
1100 ascender and descender letter forms.
1103 Table: `geor` (Georgian Mkhedruli) blue zones
1105 ID Blue zone Characters
1106 ---- ----------- ------------
1107 1* top of Mkhedruli letters გ დ ე ვ თ ი ო ღ
1108 2 bottom of Mkhedruli letters ა ზ მ ს შ ძ ხ ჰ
1109 3 top of ascender Mkhedruli letters ს ხ ქ ზ მ შ ჩ წ
1110 4 bottom of descender Mkhedruli letters ე ვ ჟ ტ უ ფ ქ ყ
1112 Georgian Mkhedruli support is incomplete; it doesn't yet contain characters
1113 for Mtavruli (which are not yet encoded in Unicode), the uppercase glyph
1114 variants of Mkhedruli.
1117 Table: `glag` (Glagolitic) blue zones
1119 ID Blue zone Characters
1120 ---- ----------- ------------
1121 1 top of capital letters Ⰵ Ⱄ Ⱚ Ⰴ Ⰲ Ⰺ Ⱛ Ⰻ
1122 2 bottom of capital letters Ⰵ Ⰴ Ⰲ Ⱚ Ⱎ Ⱑ Ⰺ Ⱄ
1123 3* top of small letters ⰵ ⱄ ⱚ ⰴ ⰲ ⰺ ⱛ ⰻ
1124 4 bottom of small letters ⰵ ⰴ ⰲ ⱚ ⱎ ⱑ ⰺ ⱄ
1127 Table: `goth` (Gothic) blue zones
1129 ID Blue zone Characters
1130 ---- ----------- ------------
1131 1 top of letters 𐌲 𐌶 𐍀 𐍄 𐌴 𐍃 𐍈 𐌾
1132 2 bottom of letters 𐌶 𐌴 𐍃 𐍈
1135 Table: `grek` (Greek) blue zones
1137 ID Blue zone Characters
1138 ---- ----------- ------------
1139 1 top of capital letters \Greek{}Γ Β Ε Ζ Θ Ο Ω\greek{}
1140 2 bottom of capital letters \Greek{}Β Δ Ζ Ξ Θ Ο\greek{}
1141 3 top of 'small beta' like letters \Greek{}β θ δ ζ λ ξ\greek{}
1142 4* top of small letters \Greek{}α ε ι ο π σ τ ω\greek{}
1143 5 bottom of small letters \Greek{}α ε ι ο π σ τ ω\greek{}
1144 6 bottom of descenders of small letters \Greek{}β γ η μ ρ φ χ ψ\greek{}
1147 Table: `gujr` (Gujarati) blue zones
1149 ID Blue zone Characters
1150 ---- ----------- ------------
1151 1* top of letters ત ન ઋ ઌ છ ટ ર ૦
1152 2 bottom of letters ખ ગ ઘ ઞ ઇ ઈ ઠ જ
1153 3 top of ascenders ઈ ઊ િ ી લી શ્ચિ જિ સી
1154 4 bottom of descenders ુ ૃ ૄ ખુ છૃ છૄ
1155 5 top of Gujarati digits ૦ ૧ ૨ ૩ ૭
1158 Table: `guru` (Gurmukhi) blue zones
1160 ID Blue zone Characters
1161 ---- ----------- ------------
1162 1 top of ascenders ਇ ਈ ਉ ਏ ਓ ੳ ਿ ੀ
1163 2 top of baseline ਕ ਗ ਙ ਚ ਜ ਤ ਧ ਸ
1164 3* top of baseline (flat glyphs only) ਕ ਗ ਙ ਚ ਜ ਤ ਧ ਸ
1165 4 bottom of characters ਅ ਏ ਓ ਗ ਜ ਠ ਰ ਸ
1166 5 top of Gurmukhi digits ੦ ੧ ੨ ੩ ੭
1169 Table: `hebr` (Hebrew) blue zones
1171 ID Blue zone Characters
1172 ---- ----------- ------------
1173 1 top of letters ב ד ה ח ך כ ם ס
1174 2 bottom of letters ב ט כ ם ס צ
1175 3 bottom of descenders of letters ק ך ן ף ץ
1178 Table: `kali` (Kayah Li) blue zones
1180 ID Blue zone Characters
1181 ---- ----------- ------------
1182 1* top of letters ꤅ ꤏ ꤁ ꤋ ꤀ ꤍ
1183 2 bottom of letters ꤈ ꤘ ꤀ ꤍ ꤢ
1184 3 top of ascending letters ꤖ ꤡ
1185 4 bottom of descending letters ꤑ ꤜ ꤞ
1186 5 bottom of large descending letters ꤑ꤬ ꤜ꤭ ꤔ꤬
1189 Table: `khmr` (Khmer) blue zones
1191 ID Blue zone Characters
1192 ---- ----------- ------------
1193 1* top of letters ខ ទ ន ឧ ឩ ា
1194 2 top of subscript cluster components ក្ក ក្ខ ក្គ ក្ថ
1195 3 bottom of letters ខ ឃ ច ឋ ប ម យ ឲ
1196 4 bottom of descenders ត្រ រៀ ឲ្យ អឿ
1197 5 bottom of large descenders ន្ត្រៃ ង្ខ្យ ក្បៀ ច្រៀ ន្តឿ ល្បឿ
1200 Table: `khms` (Khmer Symbols) blue zones
1202 ID Blue zone Characters
1203 ---- ----------- ------------
1204 1* top of symbols for waxing ᧠ ᧡
1205 2 bottom of symbols for waning ᧶ ᧹
1207 Khmer symbols are used for lunar dates.
1210 Table: `knda` (Kannada) blue zones
1212 ID Blue zone Characters
1213 ---- ----------- ------------
1214 1 top of letters ಇ ಊ ಐ ಣ ಸಾ ನಾ ದಾ ರಾ
1215 2 bottom of letters ಅ ಉ ಎ ಲ ೦ ೨ ೬ ೭
1218 Table: `lao` (Lao) blue zones
1220 ID Blue zone Characters
1221 ---- ----------- ------------
1222 1* top of letters າ ດ ອ ມ ລ ວ ຣ ງ
1223 2 bottom of letters າ ອ ບ ຍ ຣ ຮ ວ ຢ
1224 3 top of ascenders ປ ຢ ຟ ຝ
1225 4 top of large ascenders ໂ ໄ ໃ
1226 5 bottom of descenders ງ ຊ ຖ ຽ ໆ ຯ
1229 Table: `latb` (Latin Subscripts) blue zones
1231 ID Blue zone Characters
1232 ---- ----------- ------------
1233 1 top of capital characters \Latin{}₀ ₃ ₅ ₇ ₈\latin{}
1234 2 bottom of capital characters \Latin{}₀ ₁ ₂ ₃ ₈\latin{}
1235 3 top of 'small f' like characters \Latin{}ᵢ ⱼ ₕ ₖ ₗ\latin{}
1236 4* top of small characters \Latin{}ₐ ₑ ₒ ₓ ₙ ₛ ᵥ ᵤ ᵣ\latin{}
1237 5 bottom of small characters \Latin{}ₐ ₑ ₒ ₓ ₙ ₛ ᵥ ᵤ ᵣ\latin{}
1238 6 bottom of descenders of small characters \Latin{}ᵦ ᵧ ᵨ ᵩ ₚ\latin{}
1240 Subscript latin characters are similar to normal latin characters.
1243 Table: `latn` (Latin) blue zones
1245 ID Blue zone Characters
1246 ---- ----------- ------------
1247 1 top of capital letters \Latin{}T H E Z O C Q S\latin{}
1248 2 bottom of capital letters \Latin{}H E Z L O C U S\latin{}
1249 3 top of 'small f' like letters \Latin{}f i j k d b h\latin{}
1250 4* top of small letters \Latin{}u v x z o e s c\latin{}
1251 5 bottom of small letters \Latin{}n r x z o e s c\latin{}
1252 6 bottom of descenders of small letters \Latin{}p q g j y\latin{}
1255 Table: `latp` (Latin Superscripts) blue zones
1257 ID Blue zone Characters
1258 ---- ----------- ------------
1259 1 top of capital characters \Latin{}⁰ ³ ⁵ ⁷ ᵀ ᴴ ᴱ ᴼ\latin{}
1260 2 bottom of capital characters \Latin{}⁰ ¹ ² ³ ᴱ ᴸ ᴼ ᵁ\latin{}
1261 3 top of 'small f' like characters \Latin{}ᵇ ᵈ ᵏ ʰ ʲ ᶠ ⁱ\latin{}
1262 4* top of small characters \Latin{}ᵉ ᵒ ʳ ˢ ˣ ᶜ ᶻ\latin{}
1263 5 bottom of small characters \Latin{}ᵉ ᵒ ʳ ˢ ˣ ᶜ ᶻ\latin{}
1264 6 bottom of descenders of small characters \Latin{}ᵖ ʸ ᵍ\latin{}
1266 Superscript latin characters are similar to normal latin characters.
1269 Table: `lisu` (Lisu) blue zones
1271 ID Blue zone Characters
1272 ---- ----------- ------------
1273 1 top of letters ꓡ ꓧ ꓱ ꓶ ꓩ ꓚ ꓵ ꓳ
1274 2 bottom of letters ꓕ ꓜ ꓞ ꓡ ꓛ ꓢ ꓳ ꓴ
1277 Table: `mlym` (Malayalam) blue zones
1279 ID Blue zone Characters
1280 ---- ----------- ------------
1281 1 top of letters ഒ ട ഠ റ ച പ ച്ച പ്പ
1282 2 bottom of letters ട ഠ ധ ശ ഘ ച ഥ ല
1285 Table: `mymr` (Myanmar) blue zones
1287 ID Blue zone Characters
1288 ---- ----------- ------------
1289 1* top of letters ခ ဂ င ဒ ဝ ၥ ၊ ။
1290 2 bottom of letters င ဎ ဒ ပ ဗ ဝ ၊ ။
1291 3 top of ascenders of characters ဩ ြ ၍ ၏ ၆ ါ ိ
1292 3 bottom of descenders of letters ဉ ည ဥ ဩ ဨ ၂ ၅ ၉
1295 Table: `nkoo` (N'Ko) blue zones
1297 ID Blue zone Characters
1298 ---- ----------- ------------
1299 1 top of letters ߐ ߉ ߒ ߟ ߖ ߜ ߠ ߥ
1300 2 bottom of letters ߀ ߘ ߡ ߠ ߥ
1301 3* top of small letters ߏ ߛ ߋ
1302 4 bottom of small letters ߎ ߏ ߛ ߋ
1305 Table: `olck` (Ol Chiki) blue zones
1307 ID Blue zone Characters
1308 ---- ----------- ------------
1309 1 top of letters ᱛ ᱜ ᱝ ᱡ ᱢ ᱥ
1310 2 bottom of letters ᱛ ᱜ ᱝ ᱡ ᱢ ᱥ
1313 Table: `orkh` (Old Turkic) blue zones
1315 ID Blue zone Characters
1316 ---- ----------- ------------
1317 1 top of letters 𐰗 𐰘 𐰧
1318 2 bottom of letters 𐰉 𐰗 𐰦 𐰧
1321 Table: `osge` (Osage) blue zones
1323 ID Blue zone Characters
1324 ---- ----------- ------------
1325 1 top of capital letters 𐒾 𐓍 𐓒 𐓓 𐒻 𐓂 𐒵 𐓆
1326 2 bottom of capital letters 𐒰 𐓍 𐓂 𐒿 𐓎 𐒹
1327 3 bottom of descenders of capital letters 𐒼 𐒽 𐒾
1328 4* top of small letters 𐓵 𐓶 𐓺 𐓻 𐓝 𐓣 𐓪 𐓮
1329 5 bottom of small letters 𐓘 𐓚 𐓣 𐓵 𐓡 𐓧 𐓪 𐓶
1330 6 top of ascenders of small letters 𐓤 𐓦 𐓸 𐓹 𐓛
1331 7 bottom of descenders of small letters 𐓤 𐓥 𐓦
1334 Table: `osma` (Osmanya) blue zones
1336 ID Blue zone Characters
1337 ---- ----------- ------------
1338 1 top of letters 𐒆 𐒉 𐒐 𐒒 𐒘 𐒛 𐒠 𐒣
1339 2 bottom of letters 𐒀 𐒂 𐒆 𐒈 𐒊 𐒒 𐒠 𐒩
1342 Table: `saur` (Saurashtra) blue zones
1344 ID Blue zone Characters
1345 ---- ----------- ------------
1346 1 top of letters ꢜ ꢞ ꢳ ꢂ ꢖ ꢒ ꢝ ꢛ
1347 2 bottom of letters ꢂ ꢨ ꢺ ꢤ ꢎ
1350 Table: `shaw` (Shavian) blue zones
1352 ID Blue zone Characters
1353 ---- ----------- ------------
1354 1 top of letters 𐑕 𐑙
1355 2 bottom of letters 𐑔 𐑖 𐑗 𐑹 𐑻
1356 3 bottom of descenders of letters 𐑟 𐑣
1357 4* top of small letters 𐑱 𐑲 𐑳 𐑴 𐑸 𐑺 𐑼
1358 5 bottom of small letters 𐑴 𐑻 𐑹
1361 Table: `sinh` (Sinhala) blue zones
1363 ID Blue zone Characters
1364 ---- ----------- ------------
1365 1 top of letters ඉ ක ඝ ඳ ප ය ල ෆ
1366 2 bottom of letters එ ඔ ඝ ජ ට ථ ධ ර
1367 3 bottom of descenders of letters ද ඳ උ ල තූ තු බු දු
1370 Table: `sund` (Sundanese) blue zones
1372 ID Blue zone Characters
1373 ---- ----------- ------------
1374 1 top of letters ᮋ ᮞ ᮮ ᮽ ᮰ ᮈ
1375 2 bottom of letters ᮄ ᮔ ᮕ ᮗ ᮰ ᮆ ᮈ ᮉ
1376 3 bottom of descenders of letters ᮼ ᳄
1379 Table: `taml` (Tamil) blue zones
1381 ID Blue zone Characters
1382 ---- ----------- ------------
1383 1 top of letters உ ஒ ஓ ற ஈ க ங ச
1384 2 bottom of letters க ச ல ஶ உ ங ட ப
1387 Table: `tavt` (Tai Viet) blue zones
1389 ID Blue zone Characters
1390 ---- ----------- ------------
1391 1 top of letters ꪆ ꪔ ꪒ ꪖ ꪫ
1392 2 bottom of letters ꪉ ꪫ ꪮ
1395 Table: `telu` (Telugu) blue zones
1397 ID Blue zone Characters
1398 ---- ----------- ------------
1399 1 top of letters ఇ ఌ ఙ ఞ ణ ఱ ౯
1400 2 bottom of letters అ క చ ర ఽ ౨ ౬
1403 Table: `tfng` (Tifinagh) blue zones
1405 ID Blue zone Characters
1406 ---- ----------- ------------
1407 1 top of letters ⵔ ⵙ ⵛ ⵞ ⴵ ⴼ ⴹ ⵎ
1408 2 bottom of letters ⵔ ⵙ ⵛ ⵞ ⴵ ⴼ ⴹ ⵎ
1411 Table: `thai` (Thai) blue zones
1413 ID Blue zone Characters
1414 ---- ----------- ------------
1415 1* top of letters บ เ แ อ ก า
1416 2 bottom of letters บ ป ษ ฯ อ ย ฮ
1417 3 top of ascenders of letters ป ฝ ฟ
1418 4 top of large ascenders of letters โ ใ ไ
1419 5 bottom of descenders of letters ฎ ฏ ฤ ฦ
1420 6 bottom of large descenders of letters ญ ฐ
1421 7 top of Thai digits ๐ ๑ ๓
1424 Table: `vaii` (Vai) blue zones
1426 ID Blue zone Characters
1427 ---- ----------- ------------
1428 1 top of vai letters ꗍ ꘖ ꘙ ꘜ ꖜ ꖝ ꔅ ꕢ
1429 2 bottom of vai letters ꗍ ꘖ ꘙ ꗞ ꔅ ꕢ ꖜ ꔆ
1432 
1436 Grid Fitting
1437 ------------
1439 Aligning outlines along the grid lines is called *grid fitting*. It doesn't
1440 necessarily mean that the outlines are positioned *exactly* on the grid,
1441 however, especially if you want a smooth appearance at different sizes.
1442 This is the central routine of the auto-hinter; its actions are highly
1443 dependent on the used writing system. Currently, only one writing system is
1444 available (latin), providing support for scripts like Latin or Greek.
1446 * Align edges linked to blue zones.
1448 * Fit edges to the pixel grid.
1450 * Align serif edges.
1452 * Handle remaining 'strong' points. Such points are not part of an edge
1453 but are still important for defining the shape. This roughly
1454 corresponds to the `IP` TrueType instruction.
1456 * Everything else (the 'weak' points) is handled with an 'IUP'
1457 instruction.
1459 The following images illustrate the hinting process, using glyph 'a' from
1460 the freely available font '[Ubuntu Book](http://font.ubuntu.com)'. The
1461 manual hints were added by [Dalton Maag Ltd], the used application to create
1462 the hinting debug snapshots was [FontForge].
1464 
1466 
1468 
1472 Hint Sets
1473 ---------
1475 In ttfautohint terminology, a *hint set* is the *optimal* configuration for
1476 a given PPEM (pixel per EM) value.
1478 In the range given by the `--hinting-range-min` and `--hinting-range-max`
1479 options, ttfautohint creates hint sets for every PPEM value. For each
1480 glyph, ttfautohint automatically determines whether a new set should be
1481 emitted for a PPEM value if it finds that it differs from a previous one.
1482 For some glyphs it is possible that one set covers, say, the range
1483 8px-1000px, while other glyphs need 10 or more such sets.
1485 In the PPEM range below `--hinting-range-min`, ttfautohint always uses just
1486 one set, in the PPEM range between `--hinting-range-max` and
1487 `--hinting-limit`, it also uses just one set.
1489 One of the hinting configuration parameters is the decision which segments
1490 form an edge. For example, let us assume that two segments get aligned on a
1491 single horizontal edge at 11px, while two edges are used at 12px. This
1492 change makes ttfautohint emit a new hint set to accomodate this situation.
1493 The next images illustrate this, using a Cyrillic letter (glyph 'afii10108')
1494 from the 'Ubuntu book' font, processed with ttfautohint.
1496 
1498 
1502 
1504 
1509 Obviously, the more hint sets get emitted, the larger the bytecode
1510 ttfautohint adds to the output font. To find a good value\ *n* for
1511 `--hinting-range-max`, some experimentation is necessary since *n* depends
1512 on the glyph shapes in the input font. If the value is too low, the hint
1513 set created for the PPEM value\ *n* (this hint set gets used for all larger
1514 PPEM values) might distort the outlines too much in the PPEM range given
1515 by\ *n* and the value set by `--hinting-limit` (at which hinting gets
1516 switched off). If the value is too high, the font size increases due to
1517 more hint sets without any noticeable hinting effects.
1519 Similar arguments hold for `--hinting-range-min` except that there is no
1520 lower limit at which hinting is switched off.
1522 An example. Let's assume that we have a hinting range 10\ <= ppem <=\ 100,
1523 and the hinting limit is set to 250. For a given glyph, ttfautohint finds
1524 out that four hint sets must be computed to exactly cover this hinting
1525 range: 10-15, 16-40, 41-80, and 81-100. For PPEM values below 10ppem, the
1526 hint set covering 10-15ppem is used, for PPEM values larger than 100 the
1527 hint set covering 81-100ppem is used. For PPEM values larger than 250, no
1528 hinting gets applied.
1531 Composite Glyphs
1532 ----------------
1534 The ttfautohint library (and programs) supports two solutions for handling
1535 composite glyphs, to be controlled with option
1536 [`--composites`](#hint-composites). This section contains some general
1537 information, then covers the case where the option is off, while the next
1538 section describes how ttfautohint behaves if this option is activated.
1540 Regardless of the `--composites` option, ttfautohint performs a scan over
1541 all composite glyphs to assure that components of a composite glyph inherit
1542 its style, as described [later](#opentype-features). However, components
1543 that are shifted vertically will be skipped. For example, if the glyph
1544 'Agrave' uses a shifted 'grave' accent glyph, the accent is ignored. On the
1545 other hand, if there is a glyph 'agrave' that uses the same 'grave' glyph
1546 vertically unshifted, 'grave' does inherit the style.
1548 If `--composites` is off, components are hinted separately, then put
1549 together. Separate hinting implies that the current style's blue zones are
1550 applied to all subglyphs in its original, unshifted positions. In case you
1551 want to shift components vertically, it is *mandatory* to set bit\ 2
1552 (value\ 4), `ROUND_XY_TO_GRID`, in the flag variable of the composite glyph
1553 description to get visually pleasing results, as the images below
1554 demonstrate.
1556 
1563 
1567 
1575 The '\.ttfautohint' Glyph
1576 -------------------------
1578 If option [`--composites`](#hint-composites) is used, ttfautohint doesn't
1579 hint subglyphs of composite glyphs separately. Instead, it hints the whole
1580 glyph, this is, composites get recursively expanded internally so that they
1581 form simple glyphs, then hints are applied -- this is the normal working
1582 mode of FreeType's auto-hinter.
1584 One problem, however, must be solved: Hinting for subglyphs (which usually
1585 are used as normal glyphs also) must be deactivated so that nothing but the
1586 final bytecode of the composite gets executed.
1588 The trick used by ttfautohint is to prepend a composite element called
1589 '\.ttfautohint', a dummy glyph with a single point, and which has a single
1590 job: Its bytecode increases a variable (to be more precise, it is a CVT
1591 register called `cvtl_is_subglyph` in the source code), indicating that we
1592 are within a composite glyph. The final bytecode of the composite glyph
1593 eventually decrements this variable again.
1595 As an example, let's consider composite glyph 'Agrave' ('À'), which has the
1596 subglyph 'A' as the base and 'grave' as its accent. After processing with
1597 ttfautohint it consists of three components: '\.ttfautohint', 'A', and
1598 'grave' (in this order).
1600 Bytecode of Action
1601 ------------- --------
1602 .ttfautohint increase `cvtl_is_subglyph` (now: 1)
1603 A do nothing because `cvtl_is_subglyph` > 0
1604 grave do nothing because `cvtl_is_subglyph` > 0
1605 Agrave decrease `cvtl_is_subglyph` (now: 0)
1606 apply hints because `cvtl_is_subglyph` == 0
1608 Some technical details (which you might skip): All glyph point indices get
1609 adjusted since each '\.ttfautohint' subglyph shifts all following indices by
1610 one. This must be done for both the bytecode and one subformat of
1611 OpenType's `GPOS` anchor tables.
1613 While this approach works fine on all tested platforms, there is one single
1614 drawback: Direct rendering of the '\.ttfautohint' subglyph (this is,
1615 rendering as a stand-alone glyph) disables proper hinting of all glyphs in
1616 the font! Under normal circumstances this never happens because
1617 '\.ttfautohint' doesn't have an entry in the font's `cmap` table. (However,
1618 some test and demo programs like FreeType's `ftview` application or other
1619 glyph viewers that are able to bypass the `cmap` table might be affected.)
1622 Writing Systems
1623 ---------------
1625 In FreeType terminology, a writing system is a set of functions that
1626 provides auto-hinting for certain scripts. Right now, only two writing
1627 systems from FreeType's auto-hinter are available in ttfautohint: 'dummy'
1628 and 'latin'. The former handles the 'no-script' case; details to 'latin'
1629 follow in the next section.
1632 Scripts
1633 -------
1635 ttfautohint needs to know which script should be used to hint a specific
1636 glyph. To do so, it checks a glyph's Unicode character code whether it
1637 belongs to a given script.
1639 See '[Character Ranges](#character-ranges)' for a complete list of all
1640 handled scripts and its ranges. This list is auto-generated from a source
1641 code file, covering the 'latin' writing system. It also covers some
1642 non-latin scripts (in the Unicode sense) that have similar typographical
1643 properties.
1645 In ttfautohint, scripts are identified by four-character tags (if there are
1646 less characters, spaces are appended). The value `none` indicates 'no
1647 script'.
1649 Each script is represented by two tables to handle 'base' and 'non-base'
1650 characters. For ttfautohint, a non-base character is something that should
1651 not be affected by blue zones, regardless of whether this is a spacing or
1652 no-spacing glyph. In other words, non-base characters are hinted using a
1653 script's default stem width without applying blue zones.
1655 Right now, there are two pseudo-scripts that are used as fallbacks: `latb`
1656 and `latp`, used for latin subscript and superscript characters,
1657 respectively. Its main usage is support of phonetic alphabets like the IPA,
1658 which intermix those characters with normal characters sitting on the
1659 baseline, and which are not specially handled in corresponding OpenType
1660 features like `sups`.
1662 If a glyph's character code is not covered by a script range, it is handled
1663 by a *fallback script*. By default, the fallback script is `none`, which
1664 indicates handling by the 'latin' writing system without applying
1665 script-specific blue zones (but aligning stems to the grid if possible).
1666 The fallback script can be changed; see option
1667 [`--fallback-script`](#fallback-script).
1669 The user can also select whether uncovered glyphs are either hinted (which
1670 is the default) or scaled only with the fallback script's scaling
1671 parameters. This can be controlled with option
1672 [`--fallback-scaling`](#fallback-script). Note that fallback scaling only
1673 makes sense if the fallback script has x\ height blue zones, e.g., `cyrl` or
1674 `latn`.
1676 As a special case, specifying `none` as a fallback script and switching on
1677 fallback scaling ('`-f none -S`'), no hinting is applied at all to uncovered
1678 glyphs – using `none` always implies a scaling factor of\ 1.
1681 OpenType Features
1682 -----------------
1684 (Please read the [OpenType specification] for details on *features*, `GSUB`,
1685 and `GPOS` tables, and how they relate to scripts.)
1687 For modern OpenType fonts, character ranges are not sufficient to handle
1688 scripts.
1690 * Due to glyph substitution in the font (as specified in a font's `GSUB`
1691 table), which handles ligatures and similar typographic features, there
1692 is no longer a one-to-one mapping from an input Unicode character to a
1693 glyph index. Some ligatures, like 'fi', actually do have Unicode values
1694 for historical reasons, but most of them don't. While it is possible to
1695 map ligature glyphs into Unicode's Private Use Area (PUA), code values
1696 from this area are arbitrary by definition and thus unusable for
1697 ttfautohint.
1699 * Some features like `sups` (for handling superscript) completely change
1700 the appearance and even vertical position of the affected glyphs.
1701 Obviously, the blue zones for 'normal' glyphs no longer fit, thus the
1702 auto-hinter puts them into a separate group (called *style* in FreeType
1703 speak), having its own set of blue zones.
1706 Table: OpenType features handled specially by ttfautohint
1708 Feature tag Description
1709 --------------- -------------
1710 `c2cp` petite capitals from capitals
1711 `c2sc` small capitals from capitals
1712 `ordn` ordinals
1713 `pcap` petite capitals
1714 `sinf` scientific inferiors
1715 `smcp` small capitals
1716 `subs` subscript
1717 `sups` superscript
1718 `titl` titling
1721 There are two conditions to get a valid style for a feature in a given
1722 script.
1724 1. One of the script's standard characters must be available in the
1725 feature.
1727 2. The feature must provide characters to form at least one blue zone; see
1728 [above](#blue-zones).
1730 An additional complication is that features from the above table might use
1731 data not only from the `GSUB` but also from the `GPOS` table, containing
1732 information for glyph positioning. For example, the `sups` feature for
1733 superscripts might use the same glyphs as the `subs` feature for subscripts,
1734 simply moved up. ttfautohint skips such vertically shifted glyphs (except
1735 for accessing standard characters) because glyph positioning happens after
1736 hinting. Continuing our example, the `sups` feature wouldn't form a style,
1737 contrary to `subs`, which holds the unshifted glyphs.
1739 The remaining OpenType features of a script are not handled specially; the
1740 affected glyphs are simply hinted together with the 'normal' glyphs of the
1741 script.
1743 Note that a font might still contain some features not covered yet: OpenType
1744 has the concept of a *default script*; its data gets used for all scripts
1745 that aren't explicitly handled in a font. By default, ttfautohint unifies
1746 all affected glyphs from default script features with the `latn` script.
1747 This can be changed with option [`--default-script`](#default-script), if
1748 necessary.
1751 ttfautohint uses the [HarfBuzz] library for handling OpenType features.
1754 SFNT Tables
1755 -----------
1757 ttfautohint touches almost all SFNT tables within a TrueType or OpenType
1758 font. Note that only OpenType fonts with TrueType outlines are supported.
1759 OpenType fonts with a `CFF` or `CFF2` table (this is, with PostScript
1760 outlines) won't work.
1762 * `glyf`: All hints in the table are replaced with new ones. If option
1763 [`--composites`](#hint-composites) is used, one glyph gets added (namely
1764 the '\.ttfautohint' glyph) and all composites get an additional
1765 component.
1767 * `cvt`, `prep`, and `fpgm`: These tables get replaced with data
1768 necessary for the new hinting bytecode.
1770 * `gasp`: Set up to always use grayscale rendering, for all sizes, with
1771 grid-fitting for standard hinting, and symmetric grid-fitting and
1772 symmetric smoothing for horizontal subpixel hinting (ClearType).
1774 * `DSIG`: If it exists, it gets replaced with a dummy version.
1775 ttfautohint can't digitally sign a font; you have to do that afterwards.
1777 * `name`: The 'version' entries are modified to add information about the
1778 parameters that have been used for calling ttfautohint. This can be
1779 controlled with the [`--no-info`](#ttfautohint-info) option. Family
1780 name entries might also be affected by option
1781 [`--family-suffix`](#family-suffix).
1783 * `GPOS`, `hmtx`, `loca`, `head`, `maxp`, `post`: Updated to fit the
1784 additional '\.ttfautohint' glyph, the additional subglyphs in
1785 composites, and the new hinting bytecode.
1787 * `LTSH`, `hdmx`: Since ttfautohint doesn't do any horizontal hinting,
1788 those tables are superfluous and thus removed.
1790 * `VDMX`: Removed, since it depends on the original bytecode, which
1791 ttfautohint removes. A font editor might recompute the necessary data
1792 later on.
1795 Problems
1796 --------
1798 ### Interaction With FreeType
1800 Some versions of FreeType have an experimental extension for handling
1801 subpixel hinting; it is off by default and can be activated by setting the
1802 macro `TT_CONFIG_OPTION_SUBPIXEL_HINTING` to value\ 2 or\ 3 at compile time.
1803 This code has been contributed mainly by [Infinality], being a subset of his
1804 original patch. Many GNU/Linux distributions activate this code, or provide
1805 packages to activate it. [Note that starting with FreeType version 2.7 the
1806 Infinality extension is still available but superseded by a less aggressive
1807 subpixel hinting mode, to which the explanations in this section don't
1808 apply.]
1810 This extension changes the behaviour of many bytecode instructions to get
1811 better rendering results. However, not all changes are global; some of them
1812 are specific to certain fonts. For example, it contains font-specific
1813 improvements for the '[DejaVu] Sans' font family. The list of affected
1814 fonts is hard-coded; it can be found in FreeType's source code file
1815 `ttsubpix.c`.
1817 If you are going to process such specially-handled fonts with ttfautohint,
1818 serious rendering problems might show up. Since ttfautohint (intentionally)
1819 doesn't change the font name in the `name` table, the Infinality extension
1820 has no chance to recognize that the hints are different. All such problems
1821 vanish if the font gets renamed in its `name` table (the name of the font
1822 file itself doesn't matter), for example, by using option
1823 [`--family-suffix`](#family-suffix).
1825 ### Incorrect Unicode Character Map
1827 Fonts with an incorrect Unicode `cmap` table will not be properly hinted by
1828 ttfautohint. Especially older fonts do cheat; for example, there exist
1829 Hebrew fonts that map its glyphs to character codes 'A', 'B', etc., to make
1830 them work with non-localized versions of Windows\ 98, say.
1832 Since ttfautohint needs to find both standard and blue zone characters, it
1833 relies on correct Unicode values. If you want to handle such fonts, please
1834 fix their `cmap` tables accordingly before running ttfautohint.
1836 ### Irregular Glyph Heights
1838 The central concept of ttfautohint's hinting algorithm as discussed
1839 [above](#segments-and-edges) is to identify horizontal segments at extremum
1840 positions, especially for blue zones. If such a segment is missing, it
1841 cannot be associated with a blue zone, possibly leading to irregular heights
1842 for the particular glyph.
1844 Normally, a segment has a horizontal length of at least 20\ font units
1845 (assuming 2048 units per EM)^[To be more precise, the sum of the height and
1846 length of a segment must be at least 20 font units, and the height multiplied
1847 by\ 14 must not exceed the length. Thus (19,1) is also a valid minimum
1848 (length,height) pair, while (18,2) isn't. The value\ 20 is heuristic and
1849 hard-coded, as is the value\ 14 (corresponding to a slope of approx.
1850 4.1°).]. Using a [Control Instructions File](#control-instructions-file),
1851 however, it is possible to define additional segments at arbitrary points
1852 that help overcome this restriction, making it possible to fix (most of)
1853 such problems.
1855 ### Diagonals
1857 ttfautohint doesn't handle diagonal lines specially. For thin outlines,
1858 this might lead to strokes that look too thick at smaller sizes. A font
1859 designer might compensate this to a certain amount by slightly reducing the
1860 stroke width of diagonal lines. However, in many cases the sub-optimal
1861 appearance of a stroke with borders that don't exactly fit the pixel grid is
1862 not the outline itself but an incorrect gamma value of the monitor: People
1863 tend to not properly adjust it, and the default values of most operating
1864 systems are too low, causing too much darkening of such strokes. It is thus
1865 of vital importance to compare ttfautohint's results with similar fonts to
1866 exclude any systematic effect not related to the outlines themselves.
1869 Extending ttfautohint with new scripts
1870 --------------------------------------
1872 Right now, adding new scripts to ttfautohint only works on the source code
1873 level, this is, you have to patch the C\ source code.
1875 The process itself isn't very complicated; it is demonstrated best by
1876 example. The following commits in ttfautohint add Ethiopian and Armenian,
1877 respectively.
1879 | [http://repo.or.cz/ttfautohint.git/commitdiff/d14c7c07](http://repo.or.cz/ttfautohint.git/commitdiff/d14c7c07)
1880 | [http://repo.or.cz/ttfautohint.git/commitdiff/b5022cd9](http://repo.or.cz/ttfautohint.git/commitdiff/b5022cd9)
1882 It shows that you have to do the following steps.
1884 * Add blue zone character data to the file `lib/tablue.dat`.
1886 * Add the proper Unicode ranges to `lib/taranges.c`, following the
1887 structure of similar entries.
1889 * Similarly, the files `lib/tastyles.h` and `lib/ttfautohint-script.h`
1890 must be updated. The latter holds the information on the used default
1891 character or characters; it also references the corresponding script tag
1892 `HB_SCRIPT_XXX` as used by the HarfBuzz library.
1894 If there are any questions, please contact the [FreeType mailing
1895 list](https://lists.nongnu.org/mailman/listinfo/freetype) for help. Note
1896 that the script data in ttfautohint are hold in sync with FreeType's
1897 auto-hinter.
1900 Control Instructions
1901 ====================
1903 An entry in a control instructions file has various syntax forms, which are
1904 discussed here. Brackets indicate optional elements.
1907 Common Syntax Elements
1908 ----------------------
1910 *font‑idx* gives the index of the font in a TrueType Collection, starting
1911 with value\ 0. If missing, it is set to zero. For normal TrueType fonts,
1912 only value zero is valid. A font index can be specified in decimal, octal,
1913 or hexadecimal format, the latter two indicated by the prefixes `0` and
1914 `0x`, respectively.
1916 *glyph‑id* is either a glyph's name as listed in the font's `post` SFNT
1917 table or a glyph index. A glyph name consists of characters from the set
1918 '`A-Za-z0-9._`' only and does not start with a digit or period, with the
1919 exceptions of the names '`.notdef`' and '`.null`'. A glyph index starts
1920 with value\ 0 can be specified in decimal, octal, or hexadecimal format, the
1921 latter two indicated by the prefixes `0` and `0x`, respectively. Glyph
1922 names are internally converted to glyph indices.
1924 *points* are number ranges, see '[x Height Snapping
1925 Exceptions](#x-height-snapping-exceptions)' for the syntax.
1927 Similar to the Bourne shell (`sh` or `bash`), a comment starts with
1928 character '`#`'; the rest of the line is ignored. An empty line is ignored
1929 also. Both the newline character and '`;`' can be used as a separator
1930 between exception entries. A trailing '`\`' at the end of a line continues
1931 the current line on the next one.
1933 A control instructions file is parsed line by line; later entries override
1934 earlier entries (in case there is something to override).
1937 Style Adjustments
1938 -----------------
1940 This syntax form makes it possible to override the style assignment
1941 algorithm of ttfautohint; see '[Scripts](#scripts)' and '[OpenType
1942 Features](#opentype-features)' for more details.
1944 > *\[*\ font-idx\ *\]*\ \ script\ \ feature\ \ *`@`*\ \ glyph-ids
1946 *script* is a four-letter name^[The notable exception is the tag 'lao',
1947 which originally has a trailing space as the fourth character. However,
1948 ttfautohint ignores the space.] of one of the scripts supported by
1949 ttfautohint. *feature* is one of the four-letter names of features
1950 supported by ttfautohint.
1952 The elements of *glyph-ids* are a list of comma separated *glyph-id* values
1953 or value ranges. Note that is not necessary that elements are specified in
1954 increasing order.
1956 Assuming that a font contains superscript digits 'zero.sups' to 'nine.sups'
1957 together with the glyphs 'a.sups' and 'o.sups', use a line
1959 ```
1960 cyrl sups @ zero.sups-nine.sups, a.sups, o.sups
1961 ```
1963 to add those glyphs to the style handling Cyrillic superscript glyphs.
1964 However, it is still necessary that the selected script contains proper
1965 [Blue Zone characters](#blue-zones), otherwise those glyphs aren't handled
1966 at all.
1968 Use the `--debug` command line option to see how ttfautohint assigns glyph
1969 indices of a font to styles.
1972 Stem Width Adjustments
1973 ----------------------
1975 Use the following syntax form to adjust stem width values for a given style,
1976 overriding ttfautohint's algorithm; see '[Scripts](#scripts)' and '[OpenType
1977 Features](#opentype-features)' for more details. This adjustment doesn't
1978 change the glyph shapes; it only influences the hinting process.
1980 > *\[*\ font-idx\ *\]*\ \ script\ \ feature\ \ *`w[idth]`*\ \ stem-widths
1982 *script* and *feature* are the same as with style adjustments; see above.
1983 However, *script* can additionally be the wildcard character '`*`', which
1984 indicates 'any script'. Parameter `width` can be abbreviated as '`w`'.
1986 *stem-widths* is an unsorted list of comma separated integer stem width
1987 values (in font units); the first value gives the style's default stem
1988 width.
1990 The effect of this adjustment depends [on the selected stem width
1991 algorithm](#stem-width-and-positioning-mode). For smooth stem width
1992 positioning, only the first (i.e., the default) value is used; it gets a
1993 higher preference than other discrete stem width choices. For strong stem
1994 width positioning, the stem widths are snapped to the provided values (if
1995 not differing too much) before rounding to an integer pixel value. For
1996 natural stem width positioning, this adjustment is ignored.
1998 A typical example is to reduce the default stem width of an extra-bold font,
1999 which gets better hinted if a stem width of, say, 100 is used instead of the
2000 default value 150. Let's also assume that the font further contains latin
2001 subscript and superscript characters that are hinted best with a stem width
2002 set to 80 font units. We can achieve this with the following lines in a
2003 control instructions file.
2006 ```
2007 * dflt width 100
2008 latb dflt width 80
2009 latp dflt width 80
2010 ```
2012 Without the adjustment chances are very high that the 'eyes' in glyphs 'e'
2013 or 'a' of extra-bold fonts are filled at smaller PPEM values.
2015 Use the `--debug` command line option to see how ttfautohint assigns stem
2016 widths to styles by default.
2019 Glyph Adjustments
2020 -----------------
2022 The following syntax forms allows adjustments of a glyph's hinting process.
2024 ### Change Direction of Points, Artificial Segments
2026 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`l`\[`eft`\]|`r`\[`ight`\]*\ \ points\ \ *\[*\ *`(`*\ left‑offset\ *`,`*\ right‑offset\ *`)`*\ *\]*\
2028 The mutually exclusive parameters `left` and `right` (which can be
2029 abbreviated as '`l`' and '`r`', respectively) indicate that the following
2030 points have left or right 'out' direction, respectively, overriding
2031 ttfautohint's algorithm for setting point directions. The 'out direction'
2032 of a point is the direction of the outline *leaving* the point (or passing
2033 the control point). If the specified direction is identical to what
2034 ttfautohint computes, nothing special happens. Otherwise, a one-point
2035 segment with the specified direction gets created, see
2036 [above](#segments-and-edges). By default, its length is zero. Setting
2037 *left‑offset* and *right‑offset*, you can change the segment's horizontal
2038 start and end position relative to the point position. *left‑offset* and
2039 *right‑offset* are integers measured in font units.
2041 The following five images, displaying glyphs 'O' and 'Q' from the font
2042 [Halant-Regular](http://www.google.com/fonts/specimen/Halant), demonstrate
2043 how to use direction changes.
2045 
2049 ![The same glyphs, shown at 12px before hinting. [Please ignore the outline
2050 distortion in the upper right of glyph 'O'; this is a bug in FontForge
2051 while running the TrueType
2052 debugger.]](img/Halant-Regular-O-Q-unhinted-12px.png)
2054 
2064 
2074 
2086 ### Unset Direction of Points
2088 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`n`\[`odir`\]*\ \ points\
2090 Parameter `nodir` (or '`n`') sets the 'out' direction of the following
2091 points to 'no direction', this is, neither left nor right. If the specified
2092 direction is identical to what ttfautohint computes, nothing special
2093 happens. Otherwise, ttfautohint no longer considers those points as part of
2094 horizontal segments, thus treating them as ['weak'](#grid-fitting) points.
2096 Modifying or adding segments doesn't directly modify the outlines; it only
2097 influences the hinting process.
2099 ### Delta Exceptions
2101 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`t`\[`ouch`\]|`p`\[`oint`\]*\ \ points\ \ *\[*\ *`x`\[`shift`\]*\ x‑shift\ *\]*\ \ *\[*\ *`y`\[`shift`\]*\ y‑shift\ *\]*\ \ *`@`*\ \ ppems\
2103 The mutually exclusive parameters `touch` and `point` (which can be
2104 abbreviated as '`t`' and '`p`', respectively) make ttfautohint apply delta
2105 exceptions for the given points, shifting them by the given values. Delta
2106 exceptions entered with `touch` are applied before the final 'IUP'
2107 (*interpolate untouched points*) instructions in a glyph's bytecode,
2108 exceptions entered with `point` after 'IUP' (please consult Greg Hitchcock's
2109 [ClearType Whitepaper] for more on pre-IUP and post-IUP delta hints).
2110 Additionally, the `touch` parameter makes the bytecode *touch* the affected
2111 points; such points are no longer affected by 'IUP' at all. Note that in
2112 ClearType mode all deltas along the x\ axis are discarded, and deltas along
2113 the y\ axis are only executed for touched points. As a consequence,
2114 vertical delta exceptions entered with `point` should not be used in
2115 ClearType mode.^[Unfortunately, there is a bug in FreeType prior to version
2116 2.5.4 (released in December 2014) that completely disables vertical delta
2117 exceptions if subpixel hinting is activated. For this reason you should
2118 expect that the `touch` parameter fails on older GNU/Linux distributions.]
2120 *ppems*, similar to *points*, are number ranges, see '[x Height Snapping
2121 Exceptions](#x-height-snapping-exceptions)' for the syntax.
2123 *x‑shift* and *y‑shift* represent real numbers that get rounded to multiples
2124 of 1/8 pixels. The entries for `xshift` ('`x`') and `yshift` ('`y`') are
2125 optional; if missing, the corresponding value is set to zero. If both
2126 values are zero, the delta exception entry is ignored as a whole.
2128 Values for *x‑shift* and *y‑shift* must be in the range [−1.0;1.0]. Values
2129 for *ppems* must be in the range [6;53]. Values for *points* are limited by
2130 the number of points in the glyph.
2132 Note that only character '`.`' is recognized as a decimal point, and a
2133 thousands separator is not accepted.
2135 As an example for delta instructions, let's assume that you want to shift
2136 points 2, 3, and\ 4 in glyph 'Aacute' at PPEM sizes 12 and\ 13 by a vertical
2137 amount of 0.25 pixels. This corresponds to the line
2139 ```
2140 Aacute touch 2-4 yshift 0.25 @ 12, 13
2141 ```
2143 in a control instructions file. Since we use `touch` and not `point`,
2144 points 2, 3, and\ 4 are no longer subject to the final 'IUP' instruction,
2145 which interpolates weak, untouched point positions between strong, touched
2146 ones, cf. the description
2147 [here](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM05/Chap5.html#IUP).