msdfgen: three color channels against the rounded corners of monochrome distance fields

Sharp corners from three color channels

A signed distance field is a texture representation of a shape that real-time graphics can use to efficiently reproduce that shape, and the technique behind conventional monochrome fields is best known from the 2007 Valve SIGGRAPH paper on alpha tested magnification. msdfgen can generate those, and perpendicular distance fields as well, but its primary purpose is the multi-channel distance field, a method the author developed and documented in his Master's thesis. The difference is channel count. A monochrome field holds one distance value per pixel, which forces corners to blur under magnification. A multi-channel field spreads distance values across all three color channels, and gains the ability to reproduce sharp corners almost perfectly. The README demonstrates this with a side by side image comparison, and the method has become the tool's identity, enough that the default generation mode is the multi-channel one rather than the conventional one.

A dependency-free core, a laden extension module

The project divides into two parts with sharply different footprints. The core module has no dependencies and uses only bare C++, containing all key data structures and algorithms, accessed through the msdfgen.h header. The extension module holds the utilities for loading fonts and SVG files and for saving PNG images, exposed by msdfgen-ext.h, and it pays for that convenience with four third-party dependencies, FreeType, TinyXML2, libpng, and optionally Skia. This split is the main architectural decision a library user faces, linking only the core keeps a build clean but means constructing shapes manually or feeding them text descriptions, while the extensions buy glyph and SVG loading at the cost of the dependency set. On top of both sits main.cpp, which wraps the functionality into a standalone console program, and a Windows binary is available directly in the Releases section for anyone who wants the program without compiling anything.

Four modes: sdf, psdf, msdf, mtsdf

The console program is invoked as

msdfgen <mode> <input> <options>

and only the input specification is required. Four modes exist. sdf generates a conventional monochrome, true signed distance field. psdf generates a monochrome signed perpendicular distance field. msdf, the default when no mode is given, generates the multi-channel signed distance field using the author's method. mtsdf generates a combined field, multi-channel in the color channels with a true signed distance field in the alpha channel, the format text renderers reach for when they need both sharp corners from the color channels and a monochrome distance for effects like outlines and shadows from the same texture. Choosing among them is choosing what the shader expects, and since msdf is the default, omitting the mode entirely is itself a decision in favor of corner quality.

Three ways to name the input, one round trip

Input can come from a font, an SVG, or a text description. The font path is -font with a file name and a character code, and the code accepts three notations, decimal like 63, hexadecimal like 0x3F, or an ASCII character in single quotes like '?'. The SVG path is -svg with a file name, carrying a sharp caveat, only the last vector path in the file will be used, so multi-path artwork must be prepared accordingly. The text description path is the most flexible trio, -shapedesc reads the syntax from a file, -defineshape takes it as the next argument, and -stdin reads it from standard input. The description syntax is documented further down the README, and -exportshape closes the loop by saving a shape's text description complete with edge coloring to a file, which can be edited and later fed back through -shapedesc.

autoframe is a preview tool, not for character maps

A group of options controls where the shape sits inside the field. -dimensions sets the output size in pixels. -range and -pxrange set the width of the range around the shape between the minimum and maximum representable signed distance, in shape units or in distance field pixels respectively. -scale converts shape units to distance field pixels, and -translate or -pxtranslate move the shape, with the origin otherwise at the bottom left corner. -autoframe automatically frames the shape to fit the distance field, and the README attaches a warning in bold to it, do not use -autoframe to generate character maps, it is intended as a quick preview only, because auto framing varies per glyph and breaks the consistent placement a font atlas needs. When output must be precisely aligned, manual positioning with -translate and -scale is the prescribed substitute, and -printmetrics prints the shape's layout information to inform that manual work.

The Arial Bold capital M, end to end

The README's worked example is one command:

msdfgen msdf -font C:\Windows\Fonts\arialbd.ttf 'M' -o msdf.png -dimensions 32 32 -pxrange 4 -autoframe -testrender render.png 1024 1024

It takes the glyph capital M from the Arial Bold typeface, generates a 32 by 32 multi-channel distance field with a range 4 pixels wide, stores it into msdf.png, and creates a test render of the glyph as render.png at 1024 by 1024. The test render is the tool's built-in verification loop, -testrender uses the generated field to render an image of the original shape, and -testrendermulti renders without combining the color channels, which shows how the multi-channel field actually works channel by channel. Corner detection is tunable too, -angle sets the maximum angle to be considered a corner, expressed in radians like 3.0 or in degrees with a D suffix like 171.9D. Output goes through -o, which specifies the file name, and the desired format is deduced from the extension, with png, bmp, tiff, rgba, fl32, txt and bin all recognized, falling back to the -format option when the extension does not identify one. That format list matters for pipelines, since the textual and binary forms exist for tooling while the image forms exist for inspection.

vcpkg on both ends: install and build

Two installation routes exist for the library, and both route through vcpkg. The direct one is

vcpkg install msdfgen

Building from source uses the included CMake script, and in its default configuration the CMake setup also requires vcpkg as the provider for third-party library dependencies. The mechanism is one environment variable, VCPKG_ROOT pointed at the vcpkg directory, after which the CMake configuration takes care of fetching all required packages. The repository ships CMakePresets.json alongside CMakeLists.txt, a vcpkg.json manifest at the root, and build-release.bat for Windows release builds. The release history shows steady care rather than churn, v1.13 on 2025-11-30, v1.12.1 on 2025-05-31 and v1.12 on 2024-05-18, with changes recorded in CHANGELOG.md and the last push on 2026-08-29.

The Shape object and its Bézier edges

Library users work through a short recipe, with all classes and functions in the msdfgen namespace. First acquire a Shape object, either loaded via loadGlyph or loadSvgShape or constructed manually. A shape consists of closed contours, which in turn consist of edges, and each edge is a LinearEdge, QuadraticEdge or CubicEdge, constructed from two endpoints and zero to two Bézier control points depending on the class. Next normalize the shape using its normalize method, and assign colors to the edges if a multi-channel field is wanted, which can be performed automatically using edgeColoringSimple or its siblings. When the goal scales past single glyphs to entire font atlases for text rendering, the same author's MSDF-Atlas-Gen is the designated companion, built to generate the atlas rather than one field at a time.

Editorial conclusion

Use msdfgen when text or vector shapes must stay crisp under magnification in a real-time renderer and a texture representation of the geometry is the right trade, and reach for the companion MSDF-Atlas-Gen when the goal is entire font atlases rather than single glyphs. Skip it for one-off rasterization, where a plain rasterizer is simpler than a distance field pipeline. Before adopting, verify which half you need, the dependency-free core or the extension module with its FreeType, TinyXML2, libpng and optional Skia requirements, and if you build from source, set VCPKG_ROOT so the CMake configuration can fetch the dependencies.

Frequently asked questions

Official sources

1. Chlumsky/msdfgen on GitHub
2. Issues
3. License: MIT
4. README
5. Releases