ownerYukkuri Games (Git)
last changeSun, 9 Jun 2013 22:37:31 +0000 (00:37 +0200)


This tool generates an atlas (spritesheet) of a distance field from glyphs rendered via a TrueType font, along with a JSON file describing the contents of the atlas.


Compiling ttf-to-distfield requires FreeType, Make, and a C++ compiler with minimal C++11 support. Basically, it should work on most desktop OSs.

$ make


$ ./ttf-to-distfield my-font.ttf

This will take a couple seconds and maybe print some warnings for characters it can't find. When it's done it will generate two files in the working directory, the atlas itself my-font.tga and the font positioning data as a JSON blob my-font.font.json.

For advanced usage,

$ ./ttf-to-distfield my-font.ttf size codepoints

size is specified in pixels and can be tuned to adjust the output texture size. Good values for display quality are 32 to 64.

The codepoints can be specified as a comma-separated list or as hyphen-separated range, e.g. 32,48-57,65-90 for only uppercase alphanumerics. Hexadecimal ranges are also supported, e.g. 0x20-0x7E for the printable ASCII set.

The JSON file contains the TrueType positioning information for each character along with the texture coordinates of it within the TGA file. It also contains the pixel height, distance field scale radius, and inter-character distances. Note that the padding is included in the width/height of the characters. This is probably what you want, but it means you need to start from x = -padding and y = padding rather than 0 when drawing a string.


There are methods of rendering text that can take advantage of the information encoded in the distance field to perform high-quality rendering,

For a common example, see Chris Green's paper Improved Alpha-Tested Magnification for Vector Textures and Special Effects from SIGGRAPH 2007.

There are some tools that did this already, but they all had heavy dependencies (e.g. Windows) and/or required GUIs and/or output weird formats.

Known Issues

This tool punts on all the hard stuff in Unicode. It's just a dump of the data from FreeType out to JSON. You still need to handle all the nasty details of composition yourself.

TGA is probably not the most useful format. But even if it did output PNG you'd probably want to run it through a crusher later in your pipeline anyway.

The packing algorithm isn't smart but it's simple and easy to read the result.


This code is released into the public domain via the CC0 Public Domain Dedication.

2013-06-09 Joe WreschnigUse texCoords instead of tex_coords to match standard... master
2013-06-05 Joe WreschnigCC0 license.
2013-06-05 Joe WreschnigAdd .gitignore for generated binary.
2013-06-05 Joe WreschnigInitial import.
8 years ago master