KWEngine, Teil 30: Eigene Schriftarten verwenden

Seit KWEngine Version 3.0.6 ist es möglich, eigene Schriftarten in Form von MSDF-Atlanten zu importieren und zu verwenden. Dies ersetzt den vorherigen Importmechanismus für TTF-Schriftartdateien komplett. Durch die Verwendung von MSDF-Atlanten können Schriftsätze nun beliebig groß skaliert werden ohne an Kantenschärfe und Klarheit einzubüßen.

Was sind MSDF-Atlanten?

(M)SDF steht für „(multi-channel) signed distance fields“ und basiert auf der 2007 von einem Valve-Mitarbeiter vorgestellten Technik. Die Idee ist, nicht die Buchstaben selbst als simple Bilder zu speichern, da dies für eine große Darstellung auf dem Bildschirm erfordert, dass jeder Buchstabe selbst ebenfalls hochauflösend (und somit speicherfressend) vorliegen muss.

Stattdessen speichert die von Chris Green popularisierte SDF-Technik für jeden Texel die signierte Entfernung zur nächstgelegenen Formkante (positiv/negativ je nach innen/außen) in einer Textur. MSDF erweitert dies, indem es mehrere Distanzfelder in den RGB-Kanälen kodiert, was insbesondere scharfe Ecken deutlich besser reproduziert als ein einzelnes (monochromes) SDF.

Wie erstelle ich MSDF-Atlanten für die KWEngine?

Auf der Downloadseite der Homepage kann der MSDF-Generator für Windows (64-bit) heruntergeladen werden. Die heruntergeladene ZIP-Datei muss in einen beliebigen Ordner entpackt werden.
Nach dem Entpacken der ZIP-Datei finden Sie die folgenden Dateien vor:

Durch einen Rechtsklick in einen freien Bereich unterhalb dieser Dateien und der Auswahl von „In Terminal öffnen“ (siehe folgenden Screenshot), kann ein PowerShell-Fenster im aktuellen Verzeichnis geöffnet werden:

Je nachdem, an welchen Ort die ZIP-Datei entpackt wurde, sieht der Pfad im folgenden Screenshot unterschiedlich aus. In diesem Beispiel wurde die ZIP-Datei auf das Laufwerk E: im Verzeichnis E:\Tools\msdf-atlas-gen\msdf-generator entpackt.

Zum Testen des Generators enthält die ZIP-Datei auch eine Beispiel-TTF-Schriftartdatei (Playwrite.ttf), die jetzt testweise mit dem oben abgebildeten Befehl konvertiert wird.
Das Konvertieren findet über den Aufruf der Batch-Datei generate-msdf.bat statt. Dieses Skript erwartet drei Parameter, die durch Leerstellen voneinander getrennt sind:

.\generate-msdf.bat <Schriftartdatei> <Ausgabename> <Schriftgröße>

---

Aber: Warum wurde für das Erstellen des Atlas ausgerechnet 122 als Schriftgröße verwendet?

Ziel der Konvertierung ist es, zwei Dateien zu erzeugen:

• Der MSDF-Atlas als PNG-Datei, der alle Schriftzeichen (Glyphen) enthält und eine Auflösung von 1024×1024 Pixeln hat.
• Eine gleichnamige JSON-Datei, die alle Metadaten der Schriftart enthält (Glyphen-Abstände/-Größen/-Kerningpaare).

Dabei versucht der Generator, die Zeichen so in den Atlas zu packen, dass sie möglichst wenig Platz verbrauchen, um die 1024×1024 Pixel optimal zu nutzen. Man muss also mit der Schriftgröße experimentieren und die größte Schriftgröße wählen, für die noch ein Atlas der Größe 1024×1024 erzeugt werden kann.
Für die Schriftart Playwrite.ttf ist die optimale Glyphengröße 122. Für eine andere Schriftart kann die Größe aber auch 96 oder 144 sein. Hier muss man das Skript einfach mit mehreren Größen testen. Der Generator gibt während der Konvertierung darüber Auskunft, welche Atlasgröße erzeugt wurde.

Wie sehen die fertigen Dateien dann aus?

{"atlas":{"type":"msdf","distanceRange":8,"distanceRangeMiddle":0,"size":122,"width":1024,"height":1024,"yOrigin":"bottom"},"metrics":{"emSize":1,"lineHeight":1.6500000000000001,"ascender":1.2750000000000001,"descender":-0.375,"underlineY":-0.125,"underlineThickness":0.050000000000000003},"glyphs":[{"unicode":32,"advance":0.29999999999999999},{"unicode":33,"advance":0.34000000000000002,"planeBounds":{"left":0.079367315573770497,"bottom":-0.053278688524590175,"right":0.25969518442622952,"top":0.93032786885245888},"atlasBounds":{"left":466.5,"bottom":724.5,"right":488.5,"top":844.5}},{"unicode":34,"advance":0.32800000000000001,"planeBounds":{"left":0.0086601465474416672,"bottom":0.61065573770491799,"right":0.32833227769498263,"top":0.95491803278688525},"atlasBounds":{"left":976.5,"bottom":401.5,"right":1015.5,"top":443.5}},{"unicode":35,"advance":0.92500000000000004,"planeBounds":{"left":-0.033401639344262331,"bottom":-0.061475409836065573,"right":0.95840163934426215,"top":0.93032786885245877}, ...

Atlas (verkleinert) der Schriftart Playwrite.ttf

Metadaten des Atlas für die Schriftart Playwrite.ttf (Ausschnitt)

---

Wie binde ich jetzt den Atlas und die dazugehörigen Metadaten ein?

• Kopieren Sie die PNG-Datei und die JSON-Datei in einen Ordner innerhalb ihres Spieleprojekts.
• Stellen Sie sicher, dass innerhalb von Visual Studio definiert ist, dass beide Dateien beim Erstellvorgang in das Ausgabeverzeichnis kopiert werden („Kopieren, wenn neuer“).

In der Prepare-Methode Ihrer Welt können Sie nun folgenden Aufruf tätigen:

using KWEngine3;
using KWEngine3.GameObjects;

public class ExampleWorld : World
{
    public override void Act()
    {

    }

    public override void Prepare()
    {
        // Import des MSDF-Atlas für diese Welt:
        KWEngine.LoadFont(
                          "Playwrite", 
                          "./examplePath/Playwrite.png", 
                          "./examplePath/Playwrite.json"
        );

        // HUDObject testweise erzeugen, um die Schriftart anzeigen zu lassen:
        HUDObjectText t = new HUDObjectText("Hello World");
        t.SetFont("Playwrite");              // Setzen der importierten Schriftart
        t.SetScale(48f);                     // Größe eines Buchstaben (in Pixeln)
        t.SetColor(1f, 1f, 1f);              // Weiße Schriftfarbe wählen
        t.SetColorOutline(1f, 0f, 0f, 0.5f); // Rote Umrandungsfarbe und Umrandungsstärke wählen
        AddHUDObject(t);
    }
}