MSDF text rendering for osu!framework.
If you are interested in using the library, install the package and start from the setting up MSDF fonts wiki page, which walks through generating an atlas, registering it and drawing text with it.
dotnet add package kajarlabs.osu.Framework.MsdfTextRendering --prerelease
The library is pre-1.0.0. The public API may change between 0.x releases, so pin an exact version if you depend on it.
The rest of the information on this page is related to working on the library, not using it!
osu!framework renders text from pre-rasterised bitmap atlases. That is fast and predictable, but a glyph baked at one size degrades once it is drawn far beyond it, which shows up in any UI that zooms, animates scale, or shares a typeface across a wide range of sizes.
libmsdf provides a second rendering path built on multi-channel signed distance fields, where glyph coverage is reconstructed in the fragment shader instead of sampled from a fixed-resolution texture.
- Stay a drop-in alternative, not a replacement.
MsdfSpriteTextmirrorsSpriteText, and MSDF glyphs implement the framework's own glyph abstractions so the existing text builder, layout and localisation keep working. - Keep the atlas pipeline external and standard. Atlases are produced by
msdf-atlas-gen, so nothing here is a bespoke font format. - Cover the same text features users already expect: kerning, multiline, truncation, fixed width, fallback glyphs and shadows. MSDF is not a free upgrade for every case. At small, static sizes a hinted bitmap font is cheaper and often looks better; this library is aimed at the cases where one atlas has to serve many sizes.
- A desktop platform with the .NET 10.0 SDK.
msdf-atlas-genfor generating font atlases.- When working with the codebase, we recommend an IDE with intellisense and syntax highlighting, such as Visual Studio, JetBrains Rider, or Visual Studio Code with the EditorConfig and C# extensions installed.
dotnet build
dotnet test
Visual test scenes live in tests, and are the recommended place to develop and debug rendering changes: a distance-field bug is something you see, not something an assertion catches.
Contributions can be made via pull requests to this repository. If you are unsure where to start, check the list of open issues.
When reporting a rendering bug, include a minimal reproduction and the atlas and JSON metadata that trigger it. "The glyph looks wrong" is impossible to act on without the distance range it was generated with.
This library is licensed under the MIT license. Please see the license file for more information. tl;dr you can do whatever you want as long as you include the original copyright and license notice in any copy of the software/source.
The MSDF technique itself comes from msdfgen by Viktor Chlumský, also MIT licensed. Atlases generated with msdf-atlas-gen carry the license of the font they were generated from; check it before shipping one.