View source for Importing and using MSDFs/en

<languages />

[https://dspace.cvut.cz/bitstream/handle/10467/62770/F8-DP-2015-Chlumsky-Viktor-thesis.pdf 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 [https://en.wikipedia.org/wiki/SVG SVG] support nor a high-resolution texture.

== Creating MSDFs ==

MSDFs can be created with [https://github.com/Chlumsky/msdfgen 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 [https://inkscape.org/ Inkscape] to combine multiple paths into one.

If you find yourself needing a higher quality MSDF (for more complicated shapes), change the <code>dimensions</code> 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 [[Image import|like any other image]]. For best results when rendering the MSDF, it is recommended to:

* Set <code>PreferredProfile</code> to <code>Linear</code>
* Set <code>FilterMode</code> to <code>Anisotropic</code>
* Set either <code>Uncompressed</code> or <code>DirectLoad</code> to true.

== Rendering MSDFs ==

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

You should set the <code>PixelRange</code> field to the same pixel range that was used in <code>msdfgen</code> from the <code>-pxrange</code> 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 ==

[[File:MSDF rendering example.webp|thumb|left|An example of simply rendering an MSDF on a [[Component:QuadMesh|quad]]. Look at how crisp those edges are for only a 128x128 image!]]

=== Simple rendering ===

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

[[File:MSDF rounded corners example.webm|thumb|A video showing rounded corners on UIX panels. The offscreen component is a [[Component:SpriteProvider|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 [[Component:Image|Image]] along with a null-texture [[Component:SpriteProvider|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.

[[Category:Tutorial]]