msdf-atlas-gen

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 outlines, or simplified shadows.
• Hard effects refers to the support of effects that use perpendicular distance, such as mitered outlines or thickness adjustment.

Getting started

This project can be used either as a library or as a standalone console program. Examples of how to use it as a library are available at the bottom of the page. To start using the program right away, you may download a Windows binary in the "Releases" section. To build the project from source, you may use the included CMake script. In its default configuration, it requires vcpkg as the provider for third-party library dependencies. If you set the environment variable VCPKG_ROOT to the vcpkg directory, the CMake configuration will take care of fetching all required packages from vcpkg.

Command line arguments

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

Input

• -font (required) – sets the input font file.
  • Alternatively, use -varfont to configure a variable font.
• -charset – sets the character set. See the syntax specification of charset.txt.
• -glyphset – sets the set of input glyphs using their indices within the font file. See the syntax specification.
• -chars / -glyphs sets the above character / glyph set in-line. See the syntax specification.
• -allglyphs – sets the set of input glyphs to all glyphs present within the font file.
• -fontscale – 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 – 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.

If no character set or glyph set is provided, and -allglyphs is not used, the ASCII charset will be used.

Bitmap atlas type

-type – see Atlas types

`` 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 signed perpendicular distance field (PSDF)
• 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

`` can be one of:

• png – a compressed PNG image
• bmp – an uncompressed BMP image
• tiff – an uncompressed floating-point TIFF image
• rgba – an uncompressed RGBA file
• fl32 – an uncompressed floating-point FL32 file
• 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 (little endian, binfloatbe for big endian)

If format is not specified, it may be deduced from the extension of the -imageout argument or other clues.

Please note that all color values must be interpreted as if they were linear (not sRGB) like the alpha channel, even if the image format implies otherwise.

Atlas dimensions

-dimensions – sets fixed atlas dimensions

Alternatively, 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 (typically 2:1 aspect ratio)
• -square – any square dimensions
• -square2 – square with even side length
• -square4 (default) – square with side length divisible by four

Uniform grid atlas

By default, glyphs in the atlas have different dimensions and are bin-packed in an irregular fashion to maximize use of space. With the -uniformgrid switch, you can instead force all glyphs to have identical dimensions and be laid out in a grid. In that case, these additional options are available to customize the layout:

• -uniformcols – sets the number of columns
• -uniformcell – sets the dimensions of the grid's cells
• -uniformcellconstraint – sets constraint for cell dimensions (see explanation of options above)
• -uniformorigin – sets whether the glyph's origin point should be fixed at the same position in each cell

Outputs

Any non-empty subset of the following may be specified:

• -imageout – saves the atlas bitmap as a plain image file. Format matches -format

• -json – writes the atlas's layout data as well as other metrics into a structured JSON file JSON fields

  • atlas section includes the settings used to generate the atlas, including its type and dimensions. The size field represents the font size in pixels per em.
  • If there are multiple input fonts (-and parameter), the remaining data are grouped into variants, each representing an input font.
  • metrics section contains useful font metric values retrieved from the font. All values are in em's.
  • glyphs is an array of individual glyphs identified by Unicode character index (unicode) or glyph index (index), depending on whether character set or glyph set mode is used.
    • advance is the horizontal advance in em's.
    • planeBounds represents the glyph quad's bounds in em's relative to the baseline and horizontal cursor position.
    • atlasBounds represents the glyph's bounds in the atlas in pixels.
  • If available, kerning lists all kerning pairs and their advance adjustment (which needs to be added to the base advance of the first glyph in the pair).

• -csv – writes the glyph layout data into a simple CSV file CSV columns

  • If there are multiple input fonts (-and parameter), the first column is the font index, otherwise it is skipped.
  • Character Unicode value or glyph index, depending on whether character set or glyph set mode is used.
  • Horizontal advance in em's.
  • The next 4 columns are the glyph quad's bounds in em's relative to the baseline and cursor. Depending on the -yorigin setting, this is either left, bottom, right, top (bottom-up Y) or left, top, right, bottom (top-down Y).
  • The last 4 columns the the glyph's bounds in the atlas in pixels. Depending on the -yorigin setting, this is either left, bottom, right, top (bottom-up Y) or left, top, right, bottom (top-down Y).

• -arfont – saves the atlas and its layout data as an Artery Font file

• -shadronpreview – generates a Shadron script that uses the generated atlas to draw a sample text as a preview

Glyph configuration

• -size – sets the size of the glyphs in the atlas in pixels per em
• -minsize – sets the minimum size. The largest possible size that fits the same atlas dimensions will be used
• -emrange – sets the distance field range in em's
• -pxrange (default = 2) – sets the distance field range in output pixels
• -aemrange / -apxrange – sets the distance field range asymmetrically by specifying the minimum and maximum representable signed distances (outside distances are negative!)
• -pxalign (default = vertical) – enables or disables alignment of glyph's origin point with the pixel grid
• -empadding / -pxpadding – sets additional padding within each glyph's box (in em's / pixels)
• -outerempadding / -outerpxpadding – sets additional padding around each glyph's box
• -aempadding / -apxpadding / -aouterempadding / -aouterpxpadding – sets additional padding (see above) asymmetrically with a separate width value for each side

Distance field generator settings

• -angle – sets the minimum angle between adjacent edges to be considered a corner. Append D for degrees (msdf / mtsdf only)
• -coloringstrategy – selects the edge coloring heuristic (msdf / mtsdf only)
• -errorcorrection – selects the error correction algorithm. Use help as mode for more information (msdf / mtsdf only)
• -miterlimit – 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 – sets the initial seed for the edge coloring heuristic
• -threads – sets the number of threads for the parallel computation (0 = auto)
• -yorigin – specifies the direction of the Y-axis in output coordinates. The default is bottom-up.

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.

Library usage examples

Here are commented snippets of code that demonstrate how the project can be used as a library.

Generating whole atlas at once

…

Dynamic atlas

The DynamicAtlas class allows you to add glyphs to the atlas "on-the-fly" as they are needed. In this example, the ImmediateAtlasGenerator is used as the underlying atlas generat