This is a utility for generating compact font atlases using MSDFgen.
The atlas generator loads a subset of glyphs from a TTF or OTF font file, generates a distance field for each of them, and tightly packs them into an atlas bitmap (example below). The finished atlas and/or its layout metadata can be exported as an Artery Font file, a plain image file, a CSV sheet or a structured JSON file.
A font atlas is typically stored in texture memory and used to draw text in real-time rendering contexts such as video games.
- See what's new in the changelog.
The atlas generator can generate the following six types of atlases.
| Hard mask | Soft mask | SDF | PSDF | MSDF | MTSDF | |
|---|---|---|---|---|---|---|
 |
 |
 |
 |
 |
 |
|
| Channels: | 1 (1-bit) | 1 | 1 | 1 | 3 | 4 |
| Anti-aliasing: | - | Yes | Yes | Yes | Yes | Yes |
| Scalability: | - | - | Yes | Yes | Yes | Yes |
| Sharp corners: | - | - | - | - | Yes | Yes |
| Soft effects: | - | - | Yes | - | - | Yes |
| Hard effects: | - | - | - | Yes | Yes | Yes |
Notes:
- Sharp corners refers to preservation of corner sharpness when upscaled.
- Soft effects refers to the support of effects that use true distance, such as glows, rounded borders, or simplified shadows.
- Hard effects refers to the support of effects that use pseudo-distance, such as mitered borders or thickness adjustment.
This project can be used either as a library or as a standalone console program. To start using the program immediately, there is a Windows binary available for download in the "Releases" section. To build the project, you may use the included Visual Studio solution or the Unix Makefile.
Use the following command line arguments for the standalone version of the atlas generator.
-font <fontfile.ttf/otf>(required) – sets the input font file.-charset <charset.txt>– sets the character set. The ASCII charset will be used if not specified. See the syntax specification ofcharset.txt.-glyphset <glyphset.txt>– sets the set of input glyphs using their indices within the font file. See the syntax specification.-fontscale <scale>– applies a scaling transformation to the font's glyphs. Mainly to be used to generate multiple sizes in a single atlas, otherwise use-size.-fontname <name>– sets a name for the font that will be stored in certain output files as metadata.-and– separates multiple inputs to be combined into a single atlas.
-type <type> – see Atlas types
<type> can be one of:
hardmask– a non-anti-aliased binary imagesoftmask– an anti-aliased imagesdf– a true signed distance field (SDF)psdf– a pseudo-distance fieldmsdf(default) – a multi-channel signed distance field (MSDF)mtsdf– a combination of MSDF and true SDF in the alpha channel
-format <format>
<format> can be one of:
png– a compressed PNG imagebmp– an uncompressed BMP imagetiff– an uncompressed floating-point TIFF imagetext– a sequence of pixel values in plain texttextfloat– a sequence of floating-point pixel values in plain textbin– a sequence of pixel values encoded as raw bytes of databinfloat– a sequence of pixel values encoded as raw 32-bit floating-point values
-dimensions <width> <height> – sets fixed atlas dimensions
Alternativelly, the minimum possible dimensions may be selected automatically if a dimensions constraint is set instead:
-pots– a power-of-two square-potr– a power-of-two square or rectangle (2:1)-square– any square dimensions-square2– square with even side length-square4(default) – square with side length divisible by four
Any non-empty subset of the following may be specified:
-imageout <filename.*>– saves the atlas bitmap as a plain image file. Format matches-format-json <filename.json>– writes the atlas's layout data as well as other metrics into a structured JSON file-csv <filename.csv>– writes the glyph layout data into a simple CSV file-arfont <filename.arfont>– saves the atlas and its layout data as an Artery Font file-shadronpreview <filename.shadron> <sample text>– generates a Shadron script that uses the generated atlas to draw a sample text as a preview
-size <EM size>– sets the size of the glyphs in the atlas in pixels per EM-minsize <EM size>– sets the minimum size. The largest possible size that fits the same atlas dimensions will be used-emrange <EM range>– sets the distance field range in EM's-pxrange <pixel range>(default = 2) – sets the distance field range in output pixels
-angle <angle>– sets the minimum angle between adjacent edges to be considered a corner. Append D for degrees (msdf/mtsdfonly)-errorcorrection <threshold>– sets the threshold used to detect and correct potential artifacts. 0 disables error correction (msdf/mtsdfonly)-miterlimit <value>– sets the miter limit that limits the extension of each glyph's bounding box due to very sharp corners (psdf/msdf/mtsdfonly)-overlap– switches to distance field generator with support for overlapping contours-nopreprocess– disables path preprocessing which resolves self-intersections and overlapping contours-scanline– performs an additional scanline pass to fix the signs of the distances-seed <N>– sets the initial seed for the edge coloring heuristic-threads <N>– sets the number of threads for the parallel computation (0 = auto)
The character set file is a text file with UTF-8 or ASCII encoding. The characters can be denoted in the following ways:
- Single character:
'A'(UTF-8 encoded),65(decimal Unicode),0x41(hexadecimal Unicode) - Range of characters:
['A', 'Z'],[65, 90],[0x41, 0x5a] - String of characters:
"ABCDEFGHIJKLMNOPQRSTUVWXYZ"(UTF-8 encoded)
The entries should be separated by commas or whitespace.
In between quotation marks, backslash is used as the escape character (e.g. '\'', '\\', "!\"#").
The order in which characters appear is not taken into consideration.
Additionally, the include directive can be used to include other charset files and combine character sets in a hierarchical way. It must be written on a separate line:
@include "base-charset.txt"
The syntax of the glyph set specification is mostly the same as that of a character set, but only numeric values (decimal and hexadecimal) are allowed.