Importing and using MSDFs

Multi-channel signed distance fields are how Resonite conventionally renders text. They are essentially a big lookup table of how far away a sampled point must be to be a part of some 2d object. When combined with normal image interpolation, this can result in vector-like graphics without the need for something like SVG support nor a high-resolution texture.

Creating MSDFs

MSDFs can be created with the reference implementation of the format. This is a command line program to convert vector graphic paths (most notably, SVGs) into MSDFs.

For most purposes, the following command should generate a good MSDF from an SVG for rendering:

msdfgen -svg input.svg -dimensions 128 128 -autoframe

The SVG must contain only one path that defines the object. The program will warn you if there is more than one path in the SVG. You can use a program like Inkscape to combine multiple paths into one.

If you find yourself needing a higher quality MSDF (for more complicated shapes), change the dimensions to 256, 512, whatever you need. If you find that 64 or even smaller works just as well for your shape, by all means, try to optimize! You really don't need a lot of resolution for most symbols, and 128x128 is generally good enough.

Importing MSDFs

An MSDF is just like any other texture, so importing is done like any other image. For best results when rendering the MSDF, it is recommended to:

Set PreferredProfile to Linear
Set FilterMode to Anisotropic
Set either Uncompressed or DirectLoad to true.

Rendering MSDFs

To render MSDFs in Resonite, use the TextUnlitMaterial or UI_TextUnlitMaterial materials. The MSDF can be placed in the FontAtlas field of the material. TintColor is used to color the actual object the MSDF represents, while BackgroundColor can be used to color the background of the MSDF, so long as AutoBackgroundColor is unchecked. OutlineColor can be used to give an outline color to the object. FaceDilate dilates the boundary of the MSDF, OutlineThickness controls the thickness of the outline, and FaceSoftness controls how soft the object looks.

You should set the PixelRange field to the same pixel range that was used in msdfgen from the -pxrange parameter. The default is 2. Pixel ranges of 4 or 8 might yield better quality renders for your use case, so long as you make sure to re-generate the MSDF with a matching pixel range.

Examples

Simple rendering

As with any other material, the two materials that support MSDF rendering can be used in a MeshRenderer. This can be used to create simple symbols or renders of the MSDF.

A video showing rounded corners on UIX panels. The offscreen component is a SpriteProvider with a null texture. The MSDF used is File:MSDF circle for corners.webp

UIX effects

By using one of the aforementioned materials in an Image along with a null-texture SpriteProvider, MSDFs can be used in UIX. For example, using MSDFs in conjunction with 9-slice scaling can provide little effects on borders when messing with various values on the material or image component.