Multi-channel signed distance field atlas generator

This is a utility for generating compact font atlases using MSDFgen.

It can read TTF and OTF font files, select a subset of characters, generate distance fields or bitmaps for each, and tightly pack them into an atlas bitmap, which can be e.g. used as a texture in video games. The atlas can be exported as an image file or an Artery Font file, and its layout written into a CSV or structured JSON file.

Getting started

This project can be used either as a library or as a 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.

Atlas types

The utility can generate the atlas bitmap in the following six ways:

	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.

Command line arguments

Input

• -font <fontfile.ttf/otf> – 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.

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 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)
• -errorcorrection <threshold> – sets the threshold used to detect and correct potential artifacts. 0 disables error correction (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)
• -nooverlap – disables resolution of overlapping contours
• -noscanline – disables the scanline pass, which corrects the distance field's signs according to the non-zero fill rule
• -seed <N> – sets the initial seed for the edge coloring heuristic

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"