Multi-channel signed distance field atlas generator

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.

Atlas types

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.

Getting started

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.

Command line arguments

Use the following command line arguments for the standalone version of the atlas generator.

Input

• -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 of charset.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.

Bitmap atlas type

-type <type> – see Atlas types

<type> can be one of:

• hardmask – a non-anti-aliased binary image
• softmask – an anti-aliased image
• sdf – a true signed distance field (SDF)
• psdf – a pseudo-distance field
• msdf (default) – a multi-channel signed distance field (MSDF)
• mtsdf – a combination of MSDF and true SDF in the alpha channel

Atlas image format

-format <format>

<format> can be one of:

• png – a compressed PNG image
• bmp – an uncompressed BMP image
• tiff – an uncompressed floating-point TIFF image
• text – a sequence of pixel values in plain text
• textfloat – a sequence of floating-point pixel values in plain text
• bin – a sequence of pixel values encoded as raw bytes of data
• binfloat – a sequence of pixel values encoded as raw 32-bit floating-point values

Atlas dimensions

-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

Outputs

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

Glyph configuration

• -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

Distance field generator settings

• -angle <angle> – sets the minimum angle between adjacent edges to be considered a corner. Append D for degrees (msdf / mtsdf only)
• -coloringstrategy <simple / inktrap / distance> – selects the edge coloring heuristic (msdf / mtsdf only)
• -errorcorrection <mode> – selects the error correction algorithm. Use help as mode for more information (msdf / mtsdf only)
• -miterlimit <value> – sets the miter limit that limits the extension of each glyph's bounding box due to very sharp corners (psdf / msdf / mtsdf only)
• -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)

Use -help for an exhaustive list of options.

Character set specification syntax

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"

Glyph set specification

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.