README.md

   1 # ttf-to-distfield
   2 ## Render a distance field from a TrueType font
   3
   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.
   7
   8 ### Compiling
   9
  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.
  13
  14     $ make
  15
  16 ### Usage
  17
  18     $ ./ttf-to-distfield my-font.ttf
  19
  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`.
  24
  25 For advanced usage,
  26
  27     $ ./ttf-to-distfield my-font.ttf size codepoints
  28
  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.
  31
  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.
  36
  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.
  44
  45 ### Why?
  46
  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,
  50
  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.
  54
  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.
  58
  59 ### Known Issues
  60
  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.
  64
  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.
  68
  69 The packing algorithm isn't smart but it's simple and easy to read the
  70 result.
  71
  72  [FreeType]: http://freetype.org/
  73  [1]: http://www.valvesoftware.com/publications/2007/SIGGRAPH2007_AlphaTestedMagnification.pdf