[ttf-to-distfield.git] / README.md
1 # ttf-to-distfield
2 ## Render a distance field from a TrueType font
4 This tool generates an atlas (spritesheet) of a distance field from
5 codepoints rendered in a 2D font, along with a JSON file describing
6 the contents of the atlas.
8 ### Compiling
10 Compiling `ttf-to-distfield` requires [FreeType], Make, and a C++
11 compiler with minimal C++11 support. Basically, it should work on most
12 desktop OSs.
14 $ make
16 ### Usage
18 $ ./ttf-to-distfield my-font.ttf
20 This will take a couple seconds and maybe print some warnings for
21 characters it can't find. When it's done it will generate two files in
22 the working directory, the atlas itself `my-font.tga` and the font
23 positioning data as a JSON blob `my-font.font.json`.
25 For advanced usage,
27 $ ./ttf-to-distfield my-font.ttf size codepoints
29 `size` is specified in pixels and can be tuned to adjust the output
30 texture size. Good values for display quality are 32 to 64.
32 The codepoints can be specified as a comma-separated list or as
33 hyphen-separated range, e.g. `32,48-57,65-90` for only uppercase
34 alphanumerics. Hexadecimal ranges are also supported, e.g. `0x20-0x7E`
35 for the printable ASCII set.
37 The JSON file contains the TrueType positioning information for each
38 character along with the texture coordinates of it within the TGA
39 file. It also contains the pixel height, distance field scale radius,
40 and inter-character distances. Note that the padding is included in
41 the width/height of the characters. This is probably what you want,
42 but it means you need to start from `x = -padding` and `y = padding`
43 rather than 0 when drawing a string.
45 ### Why?
47 There are methods of rendering text that can take advantage of the
48 information encoded in the distance field to perform high-quality
49 rendering,
51 For a common example, see Chris Green's paper [_Improved Alpha-Tested
52 Magnification for Vector Textures and Special Effects_][1] from
53 SIGGRAPH 2007.
55 There are some tools that did this already, but they all had heavy
56 dependencies (e.g. Windows) and/or required GUIs and/or output weird
57 formats.
59 ### Known Issues
61 This tool punts on all the hard stuff in Unicode. It's just a dump of
62 the data from FreeType out to JSON. You still need to handle all the
63 nasty details of composition yourself.
65 TGA is probably not the most useful format. But even if it did output
66 PNG you'd probably want to run it through a crusher later in your
67 pipeline anyway.
69 The packing algorithm isn't smart but it's simple and easy to read the
70 result.
72 [FreeType]: http://freetype.org/
73 [1]: http://www.valvesoftware.com/publications/2007/SIGGRAPH2007_AlphaTestedMagnification.pdf