README.md

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