SDF Fonts: Appendix

1 Feb 2026

These are topics that didn’t fit on the main page.

1 Layout#

In msdf-atlas-gen, the JSON file contains information about the size and layout of each character (“glyph”):

jq '.glyphs[] | select(.unicode == 65)' \
          assets/FiraSans-Regular.json

{
  "unicode": 65,
  "advance": 0.57300000000000006,
  "planeBounds": {
    "left": -0.055197810998398253,
    "bottom": -0.051254671649759741,
    "right": 0.62819781099839844,
    "top": 0.76882007474639624
  },
  "atlasBounds": {
    "left": 0.5,
    "bottom": 34.5,
    "right": 20.5,
    "top": 58.5
  }
}

What do these fields mean? From msdf-atlas-gen’s documentation^[1]:

unicode is the integer codepoint for the character "A".
advance is the horizontal advance in abstract “em” units.
planeBounds represents the glyph quad’s bounds in “em” units relative to the baseline and horizontal cursor position.
atlasBounds represents the glyph’s bounds in the atlas in pixels.

The JSON also contains general information about the font in the metrics field, but I won’t be using them for the examples on this page:

jq '.metrics' assets/FiraSans-Regular.json

{
  "emSize": 1,
  "lineHeight": 1.2,
  "ascender": 0.93500000000000005,
  "descender": -0.26500000000000001,
  "underlineY": -0.10000000000000001,
  "underlineThickness": 0.050000000000000003
}

I will need to use information about the atlas from the atlas field:

jq '.atlas' assets/FiraSans-Regular.json

{
  "type": "sdf",
  "distanceRange": 2.9265625000000002,
  "distanceRangeMiddle": 0,
  "size": 29.265625,
  "width": 192,
  "height": 192,
  "yOrigin": "bottom"
}

We’ll multiply the abstract “em” units by the font size to get sizes in pixels. The first step is to determine where to draw the character relative to the cursor position:

Use planeBounds (multiplied by font size) to determine the area to draw on the screen (blue shaded area). This will be larger than the character itself to leave room for outline effects.
The cursor location is at x. Note that parts of the letter may be drawn to the left of x, especially once outlines and glow effects are included.
The text baseline is at y. Some characters like g will extend below the baseline.

Visually:

The second step is to generate rectangles where the characters will be drawn. Let’s construct a layout for the word dig which gets turned into three glyphs, d, i, g. Use advance (multiplied by font size) to increment x to draw the next character, i. There will be overlap between the drawing areas for d and i. Visually:

Suppose we have a string and a starting x,y position. We can calculate the rectangles needed for each character, as well as the corresponding atlas locations:

Let’s calculate the layout boxes for each character:

Text to lay out: (interactive!)

There can be overlap, and it will be more the larger your distance range (aemrange in msdfgen, differently named in each SDF library). The extra space is where the outlines, glow effects, and drop shadows go. Most characters extend slightly below the baseline but descenders like g extend well below the baseline.

I didn’t explore these topics:

Kerning adjusts spacing between specific pairs of characters. There are multiple formats of kerning data, and msdf-atlas-gen only supports some^[2].
If drawing on multiple lines, set x back to 0 and increment y by metrics.lineHeight, plus some spacing. FreeType’s documentation^[3] is worth a look.
Text layout may also include ligatures, stylistic variants, word break, hyphenation, justification, multiple fonts, and bidirectional text handling.
Anything other than Western left-to-right writing systems may require more complex layout, called “text shaping”. Libraries include HarfBuzz^[4] and KB^[5].

2 SDF vs MSDF#

One downside of SDF fonts is mentioned in the original papers from 2006 and 2007: the corners of shapes end up rounded instead of sharp. The 2006 paper uses a relatively complex data structure to calculate the SDF in a way that keeps corners sharp. The 2007 paper suggests using multiple channels but say “As it stands, we like the rounded style of this text” so they didn’t go into details about how to keep corners sharp. The 2016 paper goes into extensive detail about how to use multiple channels.

Screenshot showing how corners of an SDF rendered font can be round — 256✕256 SDF font atlas, showing rounded corners

To get sharper corners, we can either:

Use a higher resolution SDF:

1✕ texture size

4✕ texture size

16✕ texture size

SDF font atlas, increasing resolution from 256 to 1024
Use a multi channel distance field (MSDF, 4 channels instead of 1):

SDF 1 byte/pixel

MSDF 4 byte/pixel

SDF vs MSDF at 256x256

It’s not surprising that using more texture memory increases the quality, but for a given amount of texture memory, which approach is better? Let’s compare 256✕256 MSDF (4 bytes per pixel) with 512✕512 SDF (1 byte per pixel):

Screenshot of SDF with 512x512 atlas — SDF vs MSF with same texture memory

Screenshot of MSDF with 256x256 atlas — SDF vs MSF with same texture memory

The SDF has smoother curves, especially noticeable on the dot of the “i”. The MSDF has sharper corners. Neither one is a clear win. At a higher resolution, the MSDF looks better:

Screenshot of SDF with 768x768 atlas — SDF vs MSDF with same texture memory

Screenshot of MSDF with 384x384 atlas — SDF vs MSDF with same texture memory

Screenshot of SDF with 1024x1024 atlas — SDF vs MSDF with same texture memory

Screenshot of MSDF with 512x512 atlas — SDF vs MSDF with same texture memory

Rounded corners look better for some of the effects like glow and shadow.

3 Asymmetric range#

For outline/glow effects we need distances farther away from the font. In the above examples I’ve been using --aemrange -0.05 +0.05. The range depends on what effects we want:

The low value (-0.05) depends on the maximum range we want outside the font for outline, halo, and other special effects. For example if we want an outline to be drawn between distance_em 0.0 and 0.2, then we need the low value to be -0.2 or lower. Setting it lower than necessary (e.g. -1.0) is safe but we lose quality because we’re wasting precision on values we don’t need. Since we’re defining the outlines and other effects in terms of em distances, we know what range we need.
The high value (+0.05) depends on the maximum distance inside the font, as calculated by msdfgen. It should be higher for thicker fonts. Setting it too low (e.g. 0.01) may reduce quality because of truncation. Setting it too high (e.g. +0.4) may reduce quality because we’re wasting precision on values we don’t need. In my experiments, 0.05 was plenty for most fonts, and there isn’t that much more to be gained by trying to make it smaller.

A larger range uses more of the “value space” for outlines and less for the main font, which reduces its quality:

Screenshot of SDF with -0.25 to +0.25 aemrange — SDF with thick (0.5) vs thin (0.1) distance range

Screenshot of SDF with -0.05 to +0.05 aemrange — SDF with thick (0.5) vs thin (0.1) distance range

If the font looks bad, make sure 2/scale < atlas.distanceRange < 128 (see issue 11 on msdf-atlas-gen^[6]), where atlas.distanceRange = (aemrange[1] - aemrange[0]) * atlas.size and scale is the ratio of the on-screen size to the size in the atlas. For example, if the letter A in the atlas is 32px tall, and you want to render at 16px, then scale is 0.5 and distanceRange needs to be at least 4.

The best range depends on what effects you want. Plan to experiment to find a good range for your needs. I explored this topic more on my blog.

4 Antialiasing#

Clément Bœsch’s blog post^[7] is the best reference I’ve found, with diagrams how we should construct the antialiasing ramp. It covers L1 vs L2 norm (linearstep vs smoothstep), antialias width, 2D vs 3D, linear vs srgb space.
Some sample code will smooth from the threshold outwards (threshold to threshold+width) and other code will smooth from the threshold in both directions (threshold-width/2 to threshold+width/2). My gut feeling is that both directions is more correct, but outwards may look better sometimes by making small fonts thicker.
Some shaders smoothstep instead of linear step. My gut feeling is that linear step is more correct, but smooothstep may be emulating the effect of gamma correction.
Some SDF shaders use dFdx, dFdy instead of fwidth. In my tests I did not see any meaningful difference, especially with precision highp float.
Dark on light text vs light on dark text may require adjusting the thickness slightly, especially for small fonts.
If using gamma correction, several articles suggest a gamma of 1.4–1.5 may work better than the “true” gamma of 2.2–2.3.
I’ve read in multiple places that gamma correction is important. However, when I tried it myself, I had a hard time telling an improvement. Maybe my code or math was buggy.
https://acko.net/blog/subpixel-distance-transform/^[8] says

The “blurry text” that some people associate with anti-aliasing is usually just text blended with the wrong gamma curve, and without an appropriate bleed for the font in question.

In Use.GPU I prefer to use gamma correct, linear RGB color, even for 2D. What surprised me the most is just how unquestionably superior this looks. Text looks rock solid and readable even at small sizes on low-DPI.
https://news.ycombinator.com/item?id=42191709#42192825^[9] says don’t worry about fonts being tuned for non-gamma-correction, and make sure antialiasing is linear not smoothstep
https://blog.johnnovak.net/2016/09/21/what-every-coder-should-know-about-gamma/#antialiasing^[10] says Photoshop uses gamma 1.42 instead of 2.2
https://www.puredevsoftware.com/blog/2019/01/22/sub-pixel-gamma-correct-font-rendering/^[11] recommends gamma 1.43 instead of 2.2
https://hikogui.org/2022/10/24/the-trouble-with-anti-aliasing.html^[12] says something different. It says to blend in linear space, but compensate for lightness, not by changing gamma but using something different:

I will show why a pixel wide white line and a black background will visual look like a pixel wide line after anti-aliasing in linear-RGB color space

At this point you may think, okay… anti-alias instead in the sRGB color space. The sRGB’s transfer function (gamma), by design, already approximates the perceived lightness.

This will actually work, up to a point. Many font rendering engines do this, probably after having experimented with linear anti-aliasing and not getting the desired results. And even image editors used to compose in a similar non-linear color spaces in the past.

However instead of a uniform gradient between the foreground and the background the colors may get seriously distorted.

However I think the code is just converting back to something close to srgb.

https://github.com/kovidgoyal/kitty/pull/5969#issuecomment-1426707968^[13] the Kitty terminal also has a thickness adjustment based on the contrast between the background luminance (underL) and foreground luminance (overL):

// Apply additional gamma-adjustment scaled by the luminance difference, the darker the foreground the more adjustment we apply.
// A multiplicative contrast is also available to increase sasturation.
over.a = clamp(mix(over.a, pow(over.a, text_gamma_adjustment), (1 - overL + underL) * text_gamma_scaling) * text_contrast);

Patrick Walton @pcwalton says on Twitter^[14] <2017-10-13 Fri> :

For posterity: Seems that default glyph dilation on macOS is min(vec2(0.3px), vec2(0.015125, 0.0121) * S) where S is the font size in px
https://www.reddit.com/r/gamedev/comments/2879jd/comment/cicatot/^[15] says to use supersampling for small font sizes; I have not had good luck yet, and probably need to change my shader more
I had a lot of trouble getting things to look right, and I am not the only one https://x.com/rygorous/status/512371399542202368^[16]

I tried various supersampling and gamma settings here:

Enter text: (interactive!)

Size: MSDF: Gamma: Supersample:

5 Using msdfgen#

I’m using msdfgen^[17], a c++ command line tool. It generates both SDF and MSDF output. The companion project msdf-atlas-gen^[18] generates a font atlas and a JSON file with the layout information. On Windows, get a binary from msdf-atlas-gen/releases^[19]. On Linux or Mac, compile it from source. First install cmake and vcpkg:

On Mac,

cd ~/Projects/src
   
brew install cmake vcpkg
export VCPKG_ROOT="$HOME/vcpkg"
git clone https://github.com/microsoft/vcpkg $VCPKG_ROOT

On Ubuntu Linux,

sudo apt update
sudo apt -y install curl git cmake zip build-essential pkg-config libfreetype-dev
export VCPKG_ROOT="$HOME/vcpkg"
git clone https://github.com/microsoft/vcpkg.git $VCPKG_ROOT
(cd $VCPKG_ROOT; ./bootstrap-vcpkg.sh)

On Fedora Linux,

sudo yum install -y git vcpkg zip cmake
source /etc/profile
git clone https://github.com/microsoft/vcpkg.git $VCPKG_ROOT

On Amazon Linux,

sudo yum install -y git vcpkg zip cmake
export VCPKG_ROOT="$HOME/vcpkg"
git clone https://github.com/microsoft/vcpkg.git $VCPKG_ROOT
(cd $VCPKG_ROOT; ./bootstrap-vcpkg.sh)

Then build the binary with:

git clone https://github.com/Chlumsky/msdf-atlas-gen.git
cd msdf-atlas-gen
git submodule update --init
cmake .
make

If that fails with a skia error, try:

cmake -DMSDF_ATLAS_USE_SKIA=OFF .
make

To update the software later:

cd msdf-atlas-gen
git pull
git submodule update
cmake . --fresh
make

I used this command to generate the texture atlas (.png file) and the layout data (.json file):

mkdir -p assets
~/Projects/src/msdf-atlas-gen/bin/msdf-atlas-gen \
    --font fonts/FiraSans-Regular.otf \
    --type sdf --aemrange -0.05 +0.05 --dimensions 192 192 \
    --imageout  assets/FiraSans-Regular.png \
    --json      assets/FiraSans-Regular.json

I used a low resolution SDF for the diagrams on this page. Depending on what sizes you render at and what effects you want, you will want a higher resolution and/or MSDF instead of SDF. See the section on rounded fonts for a comparison.

6 My pages#

The goal of my project was to increase the contrast between the text and the map https://somethingaboutmaps.wordpress.com/2021/06/01/on-edges/^[20]

Cartography community calls several of these “halos”:

outline
fade/feather
blur https://somethingaboutmaps.wordpress.com/2021/05/19/blurring-backgrounds-to-improve-text-legibility/^[21]
median filter https://ica-proc.copernicus.org/articles/6/4/2024/ica-proc-6-4-2024.pdf^[22] - didn’t implement
selectively applying https://somethingaboutmaps.wordpress.com/2018/10/28/smart-type-halos-in-photoshop-and-illustrator/^[23]
drop shadow
knockout - remove other high contrast edges (requires these to be in a separate layer so we can mask them)

While I was learning and experiment, I wrote several pages and blog posts:

7 TODO Other pages#

{TODO need to organize and prune this list}

https://github.com/Blatko1/awesome-msdf^[24] - is indeed awesome as its name suggests - lots of resources, including shaders with thickness, outlines, glow, drop shadow, gamma correction, plus links to discussions

wrappers around msdfgen:

- msdf-atlas-gen^[25]

msdf-bmfont-xml^[26]
glyb^[27]
glyph-gen^[28]
msdf-bmfont^[29]

other implementations

https://github.com/solenum/msdf-c^[30] - msdf in c, “this is in an unstable state”, uses stb_truetype underneath
- https://github.com/pjako/msdf_c^[31] - fork, also says “this is in an unstable state”
https://github.com/Blatko1/msdfont^[32] - msdf in rust, incomplete
https://github.com/nyyManni/msdfgl^[33] - msdf runs on the gpu! much faster than msdfgen, may not handle all features of truetype