6 Copyright (C) 2011-2013 by Werner Lemberg.
8 This file is part of the ttfautohint library, and may only be used,
9 modified, and distributed under the terms given in `COPYING'. By
10 continuing to use, modify, or distribute this file you indicate that you
11 have read `COPYING' and understand and accept it fully.
13 The file `COPYING' mentioned in the previous paragraph is distributed
14 with the ttfautohint library.
22 **ttfautohint** is a library written in\ C that takes a TrueType font as
23 the input, removes its bytecode instructions (if any), and returns a new
24 font where all glyphs are bytecode hinted using the information given by
25 FreeType's autohinting module. The idea is to provide the excellent quality
26 of the autohinter on platforms that don't use FreeType.
28 The library has a single API function, `TTF_autohint`, which is described
29 [below](#the-ttfautohint-api).
31 Bundled with the library there are two front-end programs, [`ttfautohint`
32 and `ttfautohintGUI`](#ttfautohint-and-ttfautohintgui), being a command line
33 and an application with a Graphics User Interface (GUI), respectively.
36 What exactly are hints?
37 -----------------------
39 To cite [Wikipedia](http://en.wikipedia.org/wiki/Font_hinting):
41 > **Font hinting** (also known as **instructing**) is the use of
42 > mathematical instructions to adjust the display of an outline font so that
43 > it lines up with a rasterized grid. At low screen resolutions, hinting is
44 > critical for producing a clear, legible text. It can be accompanied by
45 > antialiasing and (on liquid crystal displays) subpixel rendering for
48 and Apple's [TrueType Reference
49 Manual](https://developer.apple.com/fonts/TTRefMan/RM03/Chap3.html#features):
51 > For optimal results, a font instructor should follow these guidelines:
53 > - At small sizes, chance effects should not be allowed to magnify small
54 > differences in the original outline design of a glyph.
56 > - At large sizes, the subtlety of the original design should emerge.
59 In general, there are three possible ways to hint a glyph.
61 1. The font contains hints (in the original sense of this word) to guide
62 the rasterizer, telling it which shapes of the glyphs need special
63 consideration. The hinting logic is partly in the font and partly in
64 the rasterizer. More sophisticated rasterizers are able to produce
65 better rendering results.
67 This is how Type\ 1 and CFF hints work.
69 2. The font contains exact instructions (also called *bytecode*) on how to
70 move the points of its outlines, depending on the resolution of the
71 output device, and which intentionally distort the (outline) shape to
72 produce a well-rasterized result. The hinting logic is in the font;
73 ideally, all rasterizers simply process these instructions to get the
74 same result on all platforms.
76 This is how TrueType hints work.
78 3. The font gets auto-hinted (at run-time). The hinting logic is
79 completely in the rasterizer. No hints in the font are used or needed;
80 instead, the rasterizer scans and analyzes the glyphs to apply
81 corrections by itself.
83 This is how FreeType's auto-hinter works; see
84 [below](#background-and-technical-details) for more.
87 What problems can arise with TrueType hinting?
88 ----------------------------------------------
90 While it is relatively easy to specify PostScript hints (either manually or
91 by an auto-hinter that works at font creation time), creating TrueType
92 hints is far more difficult. There are at least two reasons:
94 - TrueType instructions form a programming language, operating at a very
95 low level. They are comparable to assembler code, thus lacking all
96 high-level concepts to make programming more comfortable.
98 Here an example how such code looks like:
102 PUSHB[ ] /* 3 values pushed */
105 PUSHB[ ] /* 2 values pushed */
108 PUSHB[ ] /* 3 values pushed */
113 Another major obstacle is the fact that font designers usually aren't
116 - It is very time consuming to manually hint glyphs. Given that the
117 number of specialists for TrueType hinting is very limited, hinting a
118 large set of glyphs for a font or font family can become very expensive.
124 The ttfautohint library brings the excellent quality of FreeType rendering
125 to platforms that don't use FreeType, yet require hinting for text to look
126 good -- like Microsoft Windows. Roughly speaking, it converts the glyph
127 analysis done by FreeType's auto-hinting module to TrueType bytecode.
128 Internally, the auto-hinter's algorithm resembles PostScript hinting
129 methods; it thus combines all three hinting methods discussed
130 [previously](#what-exactly-are-hints).
132 The simple interface of the front-ends (both on the command line and with
133 the GUI) allows quick hinting of a whole font with a few mouse clicks or a
134 single command on the prompt. As a result, you get better rendering results
135 with web browsers, for example.
137 Across Windows rendering environments today, fonts processed with
138 ttfautohint look best with ClearType enabled. This is the default for
139 Windows\ 7. Good visual results are also seen in recent MacOS\ X versions
140 and GNU/Linux systems that use FreeType for rendering.
142 The goal of the project is to generate a 'first pass' of hinting that font
143 developers can refine further for ultimate quality.
147 `ttfautohint` and `ttfautohintGUI`
148 ==================================
150 On all supported platforms (GNU/Linux, Windows, and Mac OS\ X), the GUI
151 looks quite similar; the used toolkit is [Qt], which in turn uses the
152 platform's native widgets.
154 ![`ttfautohintGUI` on GNU/Linux running KDE](img/ttfautohintGUI.png)
156 Both the GUI and console version share the same features, to be discussed in
159 **Warning: ttfautohint cannot always process a font a second time.**
160 If the font contains composite glyphs, and option `-c` is used,
161 reprocessing with ttfautohint will fail. For this reason it is strongly
162 recommended to *not* delete the original, unhinted font so that you can
163 always rerun ttfautohint.
166 Calling `ttfautohint`
167 ---------------------
170 ttfautohint [OPTION]... [IN-FILE [OUT-FILE]]
173 The TTY binary, `ttfautohint`, works like a Unix filter, this is, it reads
174 data from standard input if no input file name is given, and it sends its
175 output to standard output if no output file name is specified.
177 A typical call looks like the following.
180 ttfautohint -v -f latn foo.ttf foo-autohinted.ttf
183 For demonstration purposes, here the same using a pipe and redirection.
184 Note that Windows's default command line interpreter, `cmd.exe`, doesn't
185 support piping with binary files, unfortunately.
188 cat foo.ttf | ttfautohint -v -f latn > foo-autohinted.ttf
192 Calling `ttfautohintGUI`
193 ------------------------
196 ttfautohintGUI [OPTION]...
199 `ttfautohintGUI` doesn't send any output to a console; however, it accepts
200 the same command line options as `ttfautohint`, setting default values for
207 Long options can be given with one or two dashes, and with and without an
208 equal sign between option and argument. This means that the following forms
209 are acceptable: `-foo=`*bar*, `--foo=`*bar*, `-foo`\ *bar*, and
212 Below, the section title refers to the command's label in the GUI, then
213 comes the name of the corresponding long command line option and its short
214 equivalent, followed by a description.
216 Background and technical details on the meaning of the various options are
217 given [afterwards](#background-and-technical-details).
219 ### Hint Set Range Minimum, Hint Set Range Maximum
221 See ['Hint Sets'](#hint-sets) for a definition and explanation.
223 `--hinting-range-min=`*n*, `-l`\ *n*
224 : The minimum PPEM value (in pixels) at which hint sets are created. The
225 default value for *n* is\ 8.
227 `--hinting-range-max=`*n*, `-r`\ *n*
228 : The maximum PPEM value (in pixels) at which hint sets are created. The
229 default value for *n* is 50.
233 `--fallback-script=`*s*, `-f`\ *s*
234 : Set fallback script to tag *s*, which is a string consisting of four
235 characters like `latn` or `dflt`. It gets used for for all glyphs that
236 can't be assigned to a script automatically. See [below](#scripts) for
241 `--hinting-limit=`*n*, `-G`\ *n*
242 : The *hinting limit* is the PPEM value (in pixels) where hinting gets
243 switched off (using the `INSTCTRL` bytecode instruction); it has zero
244 impact on the file size. The default value for *n* is 200, which means
245 that the font is not hinted for PPEM values larger than 200.
247 Note that hinting in the range 'hinting-range-max' up to 'hinting-limit'
248 uses the hinting configuration for 'hinting-range-max'.
250 To omit a hinting limit, use `--hinting-limit=0` (or check the 'No
251 Hinting Limit' box in the GUI). Since this will cause internal math
252 overflow in the rasterizer for large pixel values (>\ 1500px approx.) it
253 is strongly recommended to not use this except for testing purposes.
255 ### x Height Increase Limit
257 `--increase-x-height=`*n*, `-x`\ *n*
258 : Normally, ttfautohint rounds the x\ height to the pixel grid, with a
259 slight preference for rounding up. If this flag is set, values in the
260 range 6\ PPEM to *n*\ PPEM are much more often rounded up. The default
261 value for *n* is 14. Use this flag to increase the legibility of small
262 sizes if necessary; you might get weird rendering results otherwise for
263 glyphs like 'a' or 'e', depending on the font design.
265 To switch off this feature, use `--increase-x-height=0` (or check the
266 'No x\ Height Increase' box in the GUI). To switch off rounding the
267 x\ height to the pixel grid in general, either partially or completely,
268 see ['x Height Snapping Exceptions'](#x-height-snapping-exceptions).
270 The following images again use the font 'Mertz Bold'.
272 ![At 17px, without option `-x` and '`-w ""`', the hole in glyph 'e'
273 looks very grey in the FontForge snapshot, and the GDI ClearType
274 rendering (which is the default on older Windows versions) fills it
275 completely with black because it uses B/W rendering along the y\ axis.
276 FreeType's 'light' autohint mode (which corresponds to ttfautohint's
277 'smooth' stem width algorithm) intentionally aligns horizontal lines
278 to non-integer (but still discrete) values to avoid large glyph shape
279 distortions.](img/e-17px-x14.png)
281 ![The same, this time with option `-x 17` (and
282 '`-w ""`').](img/e-17px-x17.png)
284 ### x Height Snapping Exceptions
286 `--x-height-snapping-exceptions=`*string*, `-X`\ *string*
287 : A list of comma separated PPEM values or value ranges at which no
288 x-height snapping shall be applied. A value range has the form
289 *value1*`-`*value2*, meaning *value1*\ <= PPEM <=\ *value2*. *value1*
290 or *value2* (or both) can be missing; a missing value is replaced by the
291 beginning or end of the whole interval of valid PPEM values,
292 respectively (6\ to 32767). Whitespace is not significant; superfluous
293 commas are ignored, and ranges must be specified in increasing order.
294 For example, the string `"7-9, 11, 13-"` means the values 7, 8, 9, 11,
295 13, 14, 15, etc. Consequently, if the supplied argument is `"-"`, no
296 x-height snapping takes place at all. The default is the empty string
297 (`""`), meaning no snapping exceptions.
299 Normally, x-height snapping means a slight increase in the overall
300 vertical glyph size so that the height of lowercase glyphs gets aligned
301 to the pixel grid (this is a global feature, affecting *all* glyphs of a
302 font). However, having larger vertical glyph sizes is not always
303 desired, especially if it is not possible to adjust the `usWinAscent`
304 and `usWinDescent` values from the font's `OS/2` table so that they are
305 not too tight. See ['Windows Compatibility'](#windows-compatibility)
308 ### Windows Compatibility
310 `--windows-compatibility`, `-W`
311 : This option makes ttfautohint add two artificial blue zones, positioned
312 at the `usWinAscent` and `usWinDescent` values (from the font's `OS/2`
313 table). The idea is to help ttfautohint so that the hinted glyphs stay
314 within this horizontal stripe since Windows clips everything falling
317 There is a general problem with tight values for `usWinAscent` and
318 `usWinDescent`; a good description is given in the [Vertical Metrics
319 How-To](http://typophile.com/node/13081). Additionally, there is a
320 special problem with tight values if used in combination with
321 ttfautohint because the auto-hinter tends to slightly increase the
322 vertical glyph dimensions at smaller sizes to improve legibility. This
323 enlargement can make the heights and depths of glyphs exceed the range
324 given by `usWinAscent` and `usWinDescent`.
326 If ttfautohint is part of the font creation tool chain, and the font
327 designer can adjust those two values, a better solution instead of using
328 option `-W` is to reserve some vertical space for 'padding': For the
329 auto-hinter, the difference between a top or bottom outline point before
330 and after hinting is less than 1px, thus a vertical padding of 2px is
331 sufficient. Assuming a minimum hinting size of 6ppem, adding two pixels
332 gives an increase factor of 8÷6 = 1.33. This is near to the default
333 baseline-to-baseline distance used by TeX and other sophisticated text
334 processing applications, namely 1.2×designsize, which gives satisfying
335 results in most cases. It is also near to the factor 1.25 recommended
336 in the abovementioned how-to. For example, if the vertical extension of
337 the largest glyph is 2000 units (assuming that it approximately
338 represents the designsize), the sum of `usWinAscent` and `usWinDescent`
339 could be 1.25×2000 = 2500.
341 In case ttfautohint is used as an auto-hinting tool for fonts that can
342 be no longer modified to change the metrics, option `-W` in combination
343 with '`-X "-"`' to suppress any vertical enlargement should prevent
348 `--pre-hinting`, `-p`
349 : *Pre-hinting* means that a font's original bytecode is applied to all
350 glyphs before it is replaced with bytecode created by ttfautohint.
351 This makes only sense if your font already has some hints in it that
352 modify the shape even at EM size (normally 2048px); for example, some
353 CJK fonts need this because the bytecode is used to scale and shift
354 subglyphs. For most fonts, however, this is not the case.
359 : By default, the components of a composite glyph get hinted separately.
360 If this flag is set, the composite glyph itself gets hinted (and the
361 hints of the components are ignored). Using this flag increases the
362 bytecode size a lot, however, it might yield better hinting results.
364 If this option is used (and a font actually contains composite glyphs),
365 ttfautohint currently cannot reprocess its own output for technical
366 reasons, see [below](#the-.ttfautohint-glyph).
371 : Apply default values for standard (horizontal) stem width and height
372 instead of deriving them from a script-specific, hard-coded default
373 character (which usually resembles the shape of a lowercase 'o'). Use
374 this option (usually in combination with option `--fallback-script`) to
375 hint symbol or dingbat fonts or math glyphs, for example, that lack a
376 default character, at the expense of possibly poor hinting results at
382 : Strip off all hints without generating new hints. Consequently, all
383 other hinting options are ignored. This option is intended for testing
386 ### Add ttfautohint Info
389 : Don't add ttfautohint version and command line information to the
390 version string or strings (with name ID\ 5) in the font's `name` table.
391 In the GUI it is similar: If you uncheck the 'Add ttfautohint info' box,
392 information is not added to the `name` table. Except for testing and
393 development purposes it is strongly recommended to not use this option.
395 ### Strong Stem Width and Positioning
397 `--strong-stem-width=`*string*, `-w`\ *string*
398 : ttfautohint offers two different routines to handle (horizontal) stem
399 widths and stem positions: 'smooth' and 'strong'. The former uses
400 discrete values that slightly increase the stem contrast with almost no
401 distortion of the outlines, while the latter snaps both stem widths and
402 stem positions to integer pixel values as much as possible, yielding a
403 crisper appearance at the cost of much more distortion.
405 These two routines are mapped onto three possible rendering targets:
407 - grayscale rendering, with or without optimization for subpixel
408 positioning (e.g. Mac OS\ X)
410 - 'GDI ClearType' rendering: the rasterizer version, as returned by the
411 GETINFO bytecode instruction, is in the range 36\ <= version <\ 38 and
412 ClearType is enabled (e.g. Windows XP)
414 - 'DirectWrite ClearType' rendering: the rasterizer version, as returned
415 by the GETINFO bytecode instruction, is >=\ 38, ClearType is enabled,
416 and subpixel positioning is enabled also (e.g. Internet Explorer\ 9
417 running on Windows\ 7)
419 GDI ClearType uses a mode similar to B/W rendering along the vertical
420 axis, while DW ClearType applies grayscale rendering. Additionally,
421 only DW ClearType provides subpixel positioning along the x\ axis. For
422 what it's worth, the rasterizers version\ 36 and version\ 38 in
423 Microsoft Windows are two completely different rendering engines.
425 The command line option expects *string* to contain up to three letters
426 with possible values '`g`' for grayscale, '`G`' for GDI ClearType, and
427 '`D`' for DW ClearType. If a letter is found in *string*, the strong
428 stem width routine is used for the corresponding rendering target (and
429 smooth stem width handling otherwise). The default value is '`G`', which
430 means that strong stem width handling is activated for GDI ClearType
431 only. To use smooth stem width handling for all three rendering
432 targets, use the empty string as an argument, usually connoted with
435 In the GUI, simply set the corresponding check box to select the strong
436 width routine for a given rendering target. If you unset the check box,
437 the smooth width routine gets used.
439 The following FontForge snapshot images use the font ['Mertz
440 Bold'](http://code.newtypography.co.uk/mertz-sans/) (still under
441 development) from [Vernon Adams].
443 ![The left part shows the glyph 'g' unhinted at 26px, the right part
444 with hints, using the 'smooth' stem algorithm.](img/ff-g-26px.png)
446 ![The same, but this time using the 'strong'
447 algorithm. Note how the stems are aligned to the pixel
448 grid.](img/ff-g-26px-wD.png)
450 ### Font License Restrictions
452 `--ignore-restrictions`, `-i`
453 : By default, fonts that have bit\ 1 set in the 'fsType' field of the
454 `OS/2` table are rejected. If you have a permission of the font's legal
455 owner to modify the font, specify this command line option.
457 If this option is not set, `ttfautohintGUI` shows a dialogue to handle
458 such fonts if necessary.
463 : On the console, print a brief documentation on standard output and exit.
464 This doesn't work with `ttfautohintGUI` on MS Windows.
467 : On the console, print version information on standard output and exit.
468 This doesn't work with `ttfautohintGUI` on MS Windows.
471 : Print *a lot* of debugging information on standard error while
472 processing a font (you should redirect stderr to a file). This
473 doesn't work with `ttfautohintGUI` on MS Windows.
477 Background and Technical Details
478 ================================
480 [Real-Time Grid Fitting of Typographic
481 Outlines](http://www.tug.org/TUGboat/tb24-3/lemberg.pdf) is a scholarly
482 paper that describes FreeType's auto-hinter in some detail. Regarding the
483 described data structures it is slightly out of date, but the algorithm
484 itself hasn't changed.
486 The next few subsections are mainly based on this article, introducing some
487 important concepts. Note that ttfautohint only does hinting along the
488 vertical direction (this is, modifying y\ coordinates).
494 A glyph consists of one or more *contours* (this is, closed curves). For
495 example, glyph 'O' consists of two contours, while glyph 'I' has only one.
497 ![The letter 'O' has two contours, an inner and an outer one, while letter
498 'I' has only an outer contour.](img/o-and-i)
500 A *segment* is a series of consecutive points of a contour (including its
501 Bézier control points) that are approximately aligned along a coordinate
504 ![A serif. Contour and control points are represented by squares and
505 circles, respectively. The bottom 'line' DE is approximately aligned
506 along the horizontal axis, thus it forms a segment of 7\ points. Together
507 with the two other horizontal segments, BC and FG, they form two edges
508 (BC+FG, DE).](img/segment-edge)
510 An *edge* corresponds to a single coordinate value on the main dimension
511 that collects one or more segments (allowing for a small threshold). While
512 finding segments is done on the unscaled outline, finding edges is bound to
513 the device resolution. See [below](#hint-sets) for an example.
515 The analysis to find segments and edges is specific to a script.
521 The auto-hinter analyzes a font in two steps. Right now, everything
522 described below happens for the horizontal axis only, providing vertical
527 This affects the hinting of all glyphs, trying to give them a uniform
530 + Compute standard stem widths and heights of the font. The values
531 are normally taken from a glyph that resembles letter 'o'.
533 + Compute blue zones, see [below](#blue-zones).
535 If stem widths and heights of single glyphs differ by a large value, or
536 if ttfautohint fails to find proper blue zones, hinting becomes quite
537 poor, leading even to severe shape distortions.
540 Table: script-specific standard characters of the 'latin' module
542 script standard character
543 -------- --------------------
544 `cyrl` 'о', U+043E, CYRILLIC SMALL LETTER O
545 `grek` 'ο', U+03BF, GREEK SMALL LETTER OMICRON
546 `hebr` 'ם', U+05DD, HEBREW LETTER FINAL MEM
547 `latn` 'o', U+006F, LATIN SMALL LETTER O
552 This is a per-glyph operation.
554 + Find segments and edges.
556 + Link edges together to find stems and serifs. The abovementioned
557 paper gives more details on what exactly constitutes a stem or a
558 serif and how the algorithm works.
564 ![Two blue zones relevant to the glyph 'a'. Vertical point coordinates of
565 *all* glyphs within these zones are aligned, provided the blue zone is
566 active (this is, its vertical size is smaller than
567 3/4\ pixels).](img/blue-zones)
569 Outlines of certain characters are used to determine *blue zones*. This
570 concept is the same as with Type\ 1 fonts: All glyph points that lie in
571 certain small horizontal zones get aligned vertically.
573 Here a series of tables that show the blue zone characters of the latin
574 module's available scripts; the values are hard-coded in the source code.
577 Table: `latn` blue zones
579 ID Blue zone Characters
580 ---- ----------- ------------
581 1 top of capital letters THEZOCQS
582 2 bottom of capital letters HEZLOCUS
583 3 top of 'small f' like letters fijkdbh
584 4 top of small letters xzroesc
585 5 bottom of small letters xzroesc
586 6 bottom of descenders of small letters pqgjy
589 The 'round' characters (e.g. 'OCQS') from Zones 1, 2, and 5 are also used to
590 control the overshoot handling; to improve rendering at small sizes, zone\ 4
591 gets adjusted to be on the pixel grid; cf. the [`--increase-x-height`
592 option](#x-height-increase-limit).
595 Table: `grek` blue zones
597 ID Blue zone Characters
598 ---- ----------- ------------
599 1 top of capital letters ΓΒΕΖΘΟΩ
600 2 bottom of capital letters ΒΔΖΞΘΟ
601 3 top of 'small beta' like letters βθδζλξ
602 4 top of small letters αειοπστω
603 5 bottom of small letters αειοπστω
604 6 bottom of descenders of small letters βγημρφχψ
607 Table: `cyrl` blue zones
609 ID Blue zone Characters
610 ---- ----------- ------------
611 1 top of capital letters БВЕПЗОСЭ
612 2 bottom of capital letters БВЕШЗОСЭ
613 3 top of small letters хпншезос
614 4 bottom of small letters хпншезос
615 5 bottom of descenders of small letters руф
618 Table: `hebr` blue zones
620 ID Blue zone Characters
621 ---- ----------- ------------
622 1 top of letters בדהחךכםס
623 2 bottom of letters בטכםסצ
624 3 bottom of descenders of letters קךןףץ
627 ![This image shows the relevant glyph terms for vertical blue zone
628 positions.](img/glyph-terms)
634 Aligning outlines along the grid lines is called *grid fitting*. It doesn't
635 necessarily mean that the outlines are positioned *exactly* on the grid,
636 however, especially if you want a smooth appearance at different sizes.
637 This is the central routine of the auto-hinter; its actions are highly
638 dependent on the used script. Currently, only support for scripts that work
639 similarly to Latin (e.g. Greek or Cyrillic) is available.
641 * Align edges linked to blue zones.
643 * Fit edges to the pixel grid.
647 * Handle remaining 'strong' points. Such points are not part of an edge
648 but are still important for defining the shape. This roughly
649 corresponds to the `IP` TrueType instruction.
651 * Everything else (the 'weak' points) is handled with an `IUP`
654 The following images illustrate the hinting process, using glyph 'a' from
655 the freely available font ['Ubuntu Book'](http://font.ubuntu.com). The
656 manual hints were added by [Dalton Maag Ltd], the used application to create
657 the hinting debug snapshots was [FontForge].
659 ![Before hinting.](img/a-before-hinting.png)
661 ![After hinting, using manual hints.](img/a-after-hinting.png)
663 ![After hinting, using ttfautohint. Note that the hinting process
664 doesn't change horizontal positions.](img/a-after-autohinting.png)
670 In ttfautohint terminology, a *hint set* is the *optimal* configuration for
671 a given PPEM (pixel per EM) value.
673 In the range given by the `--hinting-range-min` and `--hinting-range-max`
674 options, ttfautohint creates hint sets for every PPEM value. For each
675 glyph, ttfautohint automatically determines if a new set should be emitted
676 for a PPEM value if it finds that it differs from a previous one. For some
677 glyphs it is possible that one set covers, say, the range 8px-1000px, while
678 other glyphs need 10 or more such sets.
680 In the PPEM range below `--hinting-range-min`, ttfautohint always uses just
681 one set, in the PPEM range between `--hinting-range-max` and
682 `--hinting-limit`, it also uses just one set.
684 One of the hinting configuration parameters is the decision which segments
685 form an edge. For example, let us assume that two segments get aligned on a
686 single horizontal edge at 11px, while two edges are used at 12px.
687 This change makes ttfautohint emit a new hint set to accomodate this
690 The next images illustrate this, using a Cyrillic letter (glyph 'afii10108')
691 from the 'Ubuntu book' font, processed with ttfautohint.
693 ![Before hinting, size 11px.](img/afii10108-11px-before-hinting.png)
695 ![After hinting, size 11px. Segments 43-27-28 and 14-15 are aligned on a
696 single edge, as are segments 26-0-1 and
697 20-21.](img/afii10108-11px-after-hinting.png)
699 ![Before hinting, size 12px.](img/afii10108-12px-before-hinting.png)
701 ![After hinting, size 12px. The segments are not aligned. While
702 segments 43-27-28 and 20-21 now have almost the same horizontal position,
703 they don't form an edge because the outlines passing through the segments
704 point into different directions.](img/afii10108-12px-after-hinting.png)
706 Obviously, the more hint sets get emitted, the larger the bytecode
707 ttfautohint adds to the output font. To find a good value\ *n* for
708 `--hinting-range-max`, some experimentation is necessary since *n* depends
709 on the glyph shapes in the input font. If the value is too low, the hint
710 set created for the PPEM value\ *n* (this hint set gets used for all larger
711 PPEM values) might distort the outlines too much in the PPEM range given
712 by\ *n* and the value set by `--hinting-limit` (at which hinting gets
713 switched off). If the value is too high, the font size increases due to
714 more hint sets without any noticeable hinting effects.
716 Similar arguments hold for `--hinting-range-min` except that there is no
717 lower limit at which hinting is switched off.
719 An example. Let's assume that we have a hinting range 10\ <= ppem <=\ 100,
720 and the hinting limit is set to 250. For a given glyph, ttfautohint finds
721 out that four hint sets must be computed to exactly cover this hinting
722 range: 10-15, 16-40, 41-80, and 81-100. For ppem values below 10ppem, the
723 hint set covering 10-15ppem is used, for ppem values larger than 100 the
724 hint set covering 81-100ppem is used. For ppem values larger than 250, no
725 hinting gets applied.
728 The '\.ttfautohint' Glyph
729 -------------------------
731 If [option `--composites`](#hint-composites) is used, ttfautohint doesn't
732 hint subglyphs of composite glyphs separately. Instead, it hints the whole
733 glyph, this is, composites get recursively expanded internally so that they
734 form simple glyphs, then hints are applied -- this is the normal working
735 mode of FreeType's auto-hinter.
737 One problem, however, must be solved: Hinting for subglyphs (which usually
738 are used as normal glyphs also) must be deactivated so that nothing but the
739 final bytecode of the composite gets executed.
741 The trick used by ttfautohint is to prepend a composite element called
742 '\.ttfautohint', a dummy glyph with a single point, and which has a single
743 job: Its bytecode increases a variable (to be more precise, it is a CVT
744 register called `cvtl_is_subglyph` in the source code), indicating that we
745 are within a composite glyph. The final bytecode of the composite glyph
746 eventually decrements this variable again.
748 As an example, let's consider composite glyph 'Agrave' ('À'), which has the
749 subglyph 'A' as the base and 'grave' as its accent. After processing with
750 ttfautohint it consists of three components: '\.ttfautohint', 'A', and
751 'grave' (in this order).
754 ------------- --------
755 .ttfautohint increase `cvtl_is_subglyph` (now: 1)
756 A do nothing because `cvtl_is_subglyph` > 0
757 grave do nothing because `cvtl_is_subglyph` > 0
758 Agrave decrease `cvtl_is_subglyph` (now: 0)\
759 apply hints because `cvtl_is_subglyph` == 0
761 Some technical details (which you might skip): All glyph point indices get
762 adjusted since each '\.ttfautohint' subglyph shifts all following indices by
763 one. This must be done for both the bytecode and one subformat of
764 OpenType's `GPOS` anchor tables.
766 While this approach works fine on all tested platforms, there is one single
767 drawback: Direct rendering of the '\.ttfautohint' subglyph (this is,
768 rendering as a stand-alone glyph) disables proper hinting of all glyphs in
769 the font! Under normal circumstances this never happens because
770 '\.ttfautohint' doesn't have an entry in the font's `cmap` table. (However,
771 some test and demo programs like FreeType's `ftview` application or other
772 glyph viewers that are able to bypass the `cmap` table might be affected.)
778 ttfautohint checks which auto-hinting module should be used to hint a
779 specific glyph. To do so, it checks a glyph's Unicode character code
780 whether it belongs to a given script. Currently, only FreeType's 'latin'
781 autohinting module is implemented, but more are expected to come. Note,
782 however, that this module is capable to hint other scripts too.
784 Here is the hardcoded list of character ranges that are hinted by this
785 'latin' module. As you can see, this also covers some non-latin scripts (in
786 the Unicode sense) that have similar typographical properties.
788 In ttfautohint, scripts are identified by four-character tags. The value
789 `dflt` indicates 'no script', which gets hinted by 'dummy' auto-hinting
793 Table: `latn` character ranges
795 Character range Description
796 --------------------- -------------
797 `0x0020` - `0x007F` Basic Latin (no control characters)
798 `0x00A0` - `0x00FF` Latin-1 Supplement (no control characters)
799 `0x0100` - `0x017F` Latin Extended-A
800 `0x0180` - `0x024F` Latin Extended-B
801 `0x0250` - `0x02AF` IPA Extensions
802 `0x02B0` - `0x02FF` Spacing Modifier Letters
803 `0x0300` - `0x036F` Combining Diacritical Marks
804 `0x1D00` - `0x1D7F` Phonetic Extensions
805 `0x1D80` - `0x1DBF` Phonetic Extensions Supplement
806 `0x1DC0` - `0x1DFF` Combining Diacritical Marks Supplement
807 `0x1E00` - `0x1EFF` Latin Extended Additional
808 `0x2000` - `0x206F` General Punctuation
809 `0x2070` - `0x209F` Superscripts and Subscripts
810 `0x20A0` - `0x20CF` Currency Symbols
811 `0x2150` - `0x218F` Number Forms
812 `0x2460` - `0x24FF` Enclosed Alphanumerics
813 `0x2C60` - `0x2C7F` Latin Extended-C
814 `0x2E00` - `0x2E7F` Supplemental Punctuation
815 `0xA720` - `0xA7FF` Latin Extended-D
816 `0xFB00` - `0xFB06` Alphabetical Presentation Forms (Latin Ligatures)
817 `0x1D400` - `0x1D7FF` Mathematical Alphanumeric Symbols
818 `0x1F100` - `0x1F1FF` Enclosed Alphanumeric Supplement
821 Table: `grek` character ranges
823 Character range Description
824 --------------------- -------------
825 `0x0370` - `0x03FF` Greek and Coptic
826 `0x1F00` - `0x1FFF` Greek Extended
829 Table: `cyrl` character ranges
831 Character range Description
832 --------------------- -------------
833 `0x0400` - `0x04FF` Cyrillic
834 `0x0500` - `0x052F` Cyrillic Supplement
835 `0x2DE0` - `0x2DFF` Cyrillic Extended-A
836 `0xA640` - `0xA69F` Cyrillic Extended-B
839 Table: `hebr` character ranges
841 Character range Description
842 --------------------- -------------
843 `0x0590` - `0x05FF` Hebrew
844 `0xFB1D` - `0xFB4F` Alphabetic Presentation Forms (Hebrew)
847 If a glyph's character code is not covered by a script range, it is not
848 hinted (or rather, it gets hinted by the 'dummy' auto-hinting module that
849 essentially does nothing). This can be changed by specifying a *fallback
850 script* with [option `--fallback-script`](#fallback-script).
852 It is planned to extend ttfautohint so that the `GSUB` OpenType table gets
853 analyzed, mapping character codes to all glyph indices that can be reached
854 by switching on or off various OpenType features.
860 ttfautohint touches almost all SFNT tables within a TrueType or OpenType
861 font. Note that only OpenType fonts with TrueType outlines are supported.
862 OpenType fonts with a `CFF` table (this is, with PostScript outlines) won't
865 * `glyf`: All hints in the table are replaced with new ones. If option
866 [`--composites`](#hint-composites) is used, one glyph gets added (namely
867 the '\.ttfautohint' glyph) and all composites get an additional
870 * `cvt`, `prep`, and `fpgm`: These tables get replaced with data
871 necessary for the new hinting bytecode.
873 * `gasp`: Set up to always use grayscale rendering with grid-fitting
874 for standard hinting, and symmetric grid-fitting and symmetric
875 smoothing for horizontal subpixel hinting (ClearType).
877 * `DSIG`: If it exists, it gets replaced with a dummy version.
878 ttfautohint can't digitally sign a font; you have to do that afterwards.
880 * `name`: The 'version' entries are modified to add information about the
881 parameters that have been used for calling ttfautohint. This can be
882 controlled with the [`--no-info`](#add-ttfautohint-info) option.
884 * `GPOS`, `hmtx`, `loca`, `head`, `maxp`, `post`: Updated to fit the
885 additional '\.ttfautohint' glyph, the additional subglyphs in
886 composites, and the new hinting bytecode.
888 * `LTSH`, `hdmx`: Since ttfautohint doesn't do any horizontal hinting,
889 those tables are superfluous and thus removed.
891 * `VDMX`: Removed, since it depends on the original bytecode, which
892 ttfautohint removes. A font editor might recompute the necessary data