Library / SDK
Chlumsky/msdfgen avatar
Chlumsky/msdfgen

msdfgen: generating multi-channel signed distance fields from fonts and SVG

Multi-channel signed distance field generator

4,967 stars519 forksC++MIT

At a glance

What is it?
msdfgen turns vector shapes and font glyphs into distance field textures for real-time rendering. It ships as a C++ library and a console program, and the README is explicit about where it is not the right tool.
Who is it for?
Adopt msdfgen if you need distance field textures generated offline and you are comfortable with a C++ toolchain or a vcpkg dependency. Do not adopt it if you want an online font atlas generator in the browser, or if you need every path in an SVG file rather than the last one.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 4 days ago.
What is it written in?
Mainly C++, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Chlumsky/msdfgen4,967 ★ · +36
Star history
Repository2026-09-232026-11-15
Chlumsky/msdfgen4.9k5k

36 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What msdfgen solves, and who it is for

Rasterized text and icons get blurry when you scale them, and re-rendering vector art per frame is expensive. A signed distance field stores, per pixel, the distance to the nearest shape edge, so a fragment shader can reconstruct the outline at any size from one texture. The README describes msdfgen as a utility for generating signed distance fields from vector shapes and font glyphs, which serve as a texture representation used in real-time graphics to reproduce those shapes efficiently.

The project's stated primary purpose is the multi-channel variant. A conventional monochrome distance field stores one distance value per pixel. The multi-channel field splits the distance across the three color channels, which the README says lets it reproduce sharp corners almost perfectly. That is the difference that matters for typography: a monochrome field rounds off the corners of letters, and the README includes a comparison demonstrating the improvement in image quality.

The intended audience is graphics programmers who own the rendering pipeline. This is not a design tool and not a web service. It is a generator you run ahead of time, plus a C++ library you can link into your own asset pipeline. If you only need a distance field texture once and never again, the Windows binary in the Releases section is the shortest path.

Core and extensions: how the code is split

The repository is divided into two parts, core and ext. The README states that the core module has no dependencies and uses only bare C++. It holds the key data structures and algorithms, reachable through the msdfgen.h header. That is the part you link if you already have your own shape representation and only want the field generation.

The extensions module is where the file I/O lives. According to the README, it provides utilities for loading fonts and SVG files and for saving PNG images, exposed through msdfgen-ext.h. It depends on FreeType, TinyXML2 and libpng, with Skia as an optional dependency. Those are the libraries that make -font and -svg work at all; the core has no idea what a TrueType file is.

At the top of the tree sits main.cpp, which the README describes as wrapping the functionality into a comprehensive standalone console program. So there are three consumption modes with different dependency footprints: core alone, core plus extensions, or the prebuilt console program. Choosing between them is the first real decision, and it is a dependency decision more than a feature decision.

The data flow is linear. A loader produces a Shape: closed contours made of edges. Generation converts that shape into a distance field image. The CLI then optionally writes it out or test-renders it.

Installing msdfgen and generating your first MSDF

The README gives three routes. For a library install, vcpkg is the documented package manager. For a source build, the repository includes a CMake script, and in its default configuration it requires vcpkg as the provider for third-party dependencies. If you set the environment variable VCPKG_ROOT to the vcpkg directory, the CMake configuration fetches the required packages itself. For a quick look without building anything, there is a Windows binary in the Releases section.

The library install is a single command:

bash
vcpkg install msdfgen

For a source build, the README says to set VCPKG_ROOT to the vcpkg directory so that the CMake configuration takes care of fetching the required packages. The repository ships CMakeLists.txt and CMakePresets.json.

The console program takes a mode, an input and options, in that order, and only the input is required. The README's own example generates a 32x32 multi-channel field for a capital M from Arial Bold:

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

After that command you should have msdf.png, the field itself, and render.png, a 1024x1024 reconstruction of the glyph from that field. Open the render first. If it looks wrong, the field is wrong, and you have not yet written a single line of shader code. The -testrendermulti option renders without combining the color channels, which the README suggests as a way to see how the multi-channel field is built.

Modes are sdf, psdf, msdf and mtsdf, with msdf as the default. mtsdf adds a true signed distance in the alpha channel alongside the multi-channel color data. Character codes can be decimal, hexadecimal, or an ASCII character in single quotes, so 'M' and 0x4D mean the same thing.

Where msdfgen is the wrong tool

The SVG loader is the sharpest limitation in the README: only the last vector path in the file will be used. If you hand it an icon exported from a design tool with several paths, only the last path is used. That rules out the naive workflow of exporting a multi-path asset and feeding it straight in. You either split the file yourself or describe the shape another way.

The -autoframe option carries a warning in the README, in bold: do not use it to generate character maps, because it is intended as a quick preview only. It frames the shape to fit the field, which means the alignment of one glyph has no guaranteed relationship to the alignment of the next. For an atlas where glyphs must share a baseline and em box, you position manually with -translate and -scale instead. This is easy to get wrong, because -autoframe produces a perfectly good-looking single glyph.

There is also a scope boundary. msdfgen generates one field for one shape or one glyph. The README points elsewhere for the atlas problem, directing readers to MSDF-Atlas-Gen if they want to generate entire font atlases for text rendering. If your goal is a font atlas, this repository is a component of that pipeline, not the pipeline.

Finally, the toolchain. The default CMake configuration assumes vcpkg is present. If your build environment cannot use vcpkg, you need to provide FreeType, TinyXML2 and libpng yourself.

Modes, ranges and the parameters that decide quality

The mode choice is the first quality decision. sdf gives a conventional monochrome field, the kind described in the Valve paper the README links. psdf gives a perpendicular distance field, also monochrome. msdf gives the multi-channel field the project is built around. mtsdf combines multi-channel color with a true distance in the alpha channel, which is useful when you want both the sharp-corner reconstruction and a scalar distance for effects like outlines or shadows.

The range parameters control how much distance information the texture holds. -range sets the width of the range around the shape between the minimum and maximum representable signed distance, in shape units. -pxrange does the same in distance field pixels. Get this wrong and you get clipping: distances beyond the range saturate, and the reconstruction flattens at the edges. The README's example uses -pxrange 4 on a 32x32 field, which is the kind of ratio worth starting from.

The -angle option sets the maximum angle considered a corner, in radians or in degrees with a D suffix, so 171.9D is valid. This is the knob that decides which vertices the multi-channel method treats as sharp. Set it too high and rounded joins become corners; too low and real corners get smoothed. Expect to tune it against -testrender.

-scale and -translate convert shape units to pixels and position the shape. The README notes that without a translation, the origin (0, 0) lies in the bottom left corner, which is worth remembering when a glyph appears off-center. -printmetrics reports layout information about the shape, which is the cheapest way to check what the loader actually produced before you spend time on a field.

Alternatives and how they differ

The closest alternative in this repository's own orbit is MSDF-Atlas-Gen, which the README names directly. The difference is granularity. msdfgen produces a field for one shape at a time and leaves packing, layout and atlas metadata to you. MSDF-Atlas-Gen is aimed at generating entire font atlases for text rendering, which means it handles the multi-glyph problem that msdfgen deliberately does not. If you are building a text renderer, start there and treat msdfgen as the underlying generator.

The second comparison is FreeType, which msdfgen itself uses as a dependency for font loading. FreeType rasterizes glyphs into bitmaps and also exposes outline data. It does not produce multi-channel distance fields. The two are not competing at the same layer: msdfgen consumes font files through FreeType and then does something FreeType does not do. Reaching for FreeType alone gets you rasterization, not scalable field textures.

For the monochrome case specifically, msdfgen's sdf mode covers the ground that the Valve paper describes, so there is little reason to assemble that pipeline separately if you already have msdfgen built. The honest summary is that msdfgen occupies a narrow slot: offline field generation from a single shape. Tools above it handle atlases, tools below it handle file formats.

Licence and upgrade cost

The repository is MIT licensed, with the licence text in LICENSE.txt. MIT is permissive and imposes no copyleft obligation on your own code. It does require that the copyright notice and permission notice travel with copies or substantial portions of the software. That is a packaging detail, not a legal opinion, and if your product ships in a context where attribution text is regulated, that is a question for your own counsel.

The dependency licences are separate and not covered by msdfgen's MIT terms. The extensions module pulls in FreeType, TinyXML2, libpng and optionally Skia, each with its own licence. If you build with extensions, you are distributing those too.

Upgrade cost is moderate and mostly tied to the console interface. The README documents the option surface in detail, including the -help flag for the complete list, and the changelog is in CHANGELOG.md. The releases are infrequent rather than constant: v1.12 in May 2024, v1.12.1 in May 2025, v1.13 in November 2025. The last push to the repository was on 2026-08-29, so work is ongoing between releases.

Editorial conclusion

Adopt msdfgen if you need distance field textures generated offline and you are comfortable with a C++ toolchain or a vcpkg dependency. Do not adopt it if you want an online font atlas generator in the browser, or if you need every path in an SVG file rather than the last one. Before committing, verify two things on your own machine: that your font and SVG inputs survive the -font and -svg loaders, and that the -range or -pxrange value you pick produces an acceptable -testrender at the resolution you actually ship.

Frequently asked questions

How is MSDF different from SDF in msdfgen?

A conventional SDF stores one distance value per pixel, while an MSDF distributes the distance across the three color channels. The README states that this lets the multi-channel field reproduce sharp corners almost perfectly, which is the difference msdfgen is built around.

How do I use msdfgen from the command line?

The standalone program runs as msdfgen <mode> <input> <options>, where only the input is required. The README's example uses the msdf mode with -font, -o, -dimensions, -pxrange, -autoframe and -testrender to produce both a field and a preview render.

How does msdfgen compare with FreeType?

msdfgen uses FreeType as a dependency for loading fonts, so they are not alternatives at the same layer. FreeType rasterizes glyphs; msdfgen takes a loaded shape and generates a signed distance field, including the multi-channel variant FreeType does not produce.

Official sources

  1. Chlumsky/msdfgen on GitHub
  2. Issues
  3. License: MIT
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/chlumsky-msdfgen.svg)](https://hysenlabs.com/projects/chlumsky-msdfgen)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/chlumsky-msdfgen.svg)](https://hysenlabs.com/projects/chlumsky-msdfgen)

Was this useful?