====== std.pdf.ttfont ======

TrueType-Font-Einbettung mit Unicode-Unterstützung (WP-PDF-24). Lädt eine ''`.ttf`''-Datei, baut beim Speichern automatisch einen Glyph-Subset (nur verwendete Zeichen) und bettet diesen als ''Type0/CIDFontType2'' mit ''Identity-H''-Encoding in das PDF ein. UTF-8-Text wird über eine ToUnicode-CMap korrekt durchsuchbar.

→ [[lyx_-_programmiersprache:units:pdf:builder|std.pdf.builder]] · [[lyx_-_programmiersprache:units:pdf:fonts|std.pdf.fonts]] · [[lyx_-_programmiersprache:units|Standard Library]]

----

===== Funktionen =====

^ Signatur ^ Beschreibung ^
| ''PdfLoadFont(doc: int64, path: pchar): int64'' | Lädt eine TrueType-Datei (''path'') und registriert sie im Dokument. Gibt ''fontId'' (≥ 0) zurück, −1 bei Fehler. |
| ''PdfFinalizeFont(doc: int64, fontId: int64): void'' | Baut optional vorab einen minimalen Subset-TTF aus den bisher markierten Glyphen. Wird vor ''PdfSave'' aufgerufen, um die Dateigröße zu reduzieren. Ohne diesen Aufruf bettet ''PdfSave'' die vollständige TTF ein. |
| ''PdfSetFontTT(doc: int64, page: int64, fontId: int64, size: f64): void'' | Wählt den TrueType-Font ''fontId'' mit Größe ''size'' (in PDF-Punkten) für nachfolgende ''PdfTextAtUTF8''-Aufrufe auf ''page'' aus. Emittiert ''`/TF{fontId} {size} Tf`'' in den Content-Stream. |
| ''PdfTextAtUTF8(doc: int64, page: int64, x: f64, y: f64, text: pchar): void'' | Platziert UTF-8-kodierten Text an Position (''x'', ''y'') (PDF-Koordinatensystem, Ursprung unten links). Dekodiert UTF-8 → Unicode-Codepoint → Glyph-ID, markiert alle verwendeten Glyphen für den Subset und emittiert einen ''`BT … Td <hex> Tj ET`''-Block. |

----

===== Verwendung =====

==== Font laden und Text ausgeben ====

<code lyx>
import std.pdf.builder;
import std.pdf.ttfont;

fn AddTitlePage(doc: int64, page: int64): void {
    var font := PdfLoadFont(doc, "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf");
    if (font < 0) { return; }

    PdfSetFontTT(doc, page, font, 24.0);
    PdfTextAtUTF8(doc, page, 50.0, 750.0, "Überschrift mit Umlauten: ä ö ü");

    PdfSetFontTT(doc, page, font, 12.0);
    PdfTextAtUTF8(doc, page, 50.0, 700.0, "Fließtext mit Unicode: €, →, ©");
}
</code>

==== Subset vorab bauen (kleinere Ausgabedatei) ====

<code lyx>
import std.pdf.builder;
import std.pdf.ttfont;

fn SaveWithSubset(doc: int64, path: pchar): void {
    // Text-Calls zuerst, damit alle Glyphen markiert sind
    // ...

    // Subset optimieren, dann speichern
    var i: int64 := 0;
    while (i < PdfFontCount(doc)) {
        PdfFinalizeFont(doc, i);
        i := i + 1;
    }
    PdfSave(doc, path);
}
</code>

==== Mehrere Fonts auf einer Seite ====

<code lyx>
import std.pdf.ttfont;

fn MixedFonts(doc: int64, page: int64): void {
    var regular := PdfLoadFont(doc, "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf");
    var bold    := PdfLoadFont(doc, "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf");

    PdfSetFontTT(doc, page, regular, 12.0);
    PdfTextAtUTF8(doc, page, 50.0, 700.0, "Normaler Text");

    PdfSetFontTT(doc, page, bold, 12.0);
    PdfTextAtUTF8(doc, page, 50.0, 680.0, "Fetter Text");
}
</code>

----

===== Hinweise =====

  * ''PdfSetFontTT'' muss vor ''PdfTextAtUTF8'' auf derselben Seite aufgerufen werden — andernfalls ist kein aktiver Font gesetzt und der Aufruf ist ein No-Op.
  * Glyph-Subsetting erfolgt automatisch: Nur Glyphen, die in ''PdfTextAtUTF8''-Aufrufen vorkommen, werden eingebettet. ''PdfFinalizeFont'' ist optional, reduziert aber die Ausgabedateigröße erheblich.
  * Zusammengesetzte Glyphen (Composite Glyphs, z. B. Akzentbuchstaben) werden rekursiv mit ihren Komponenten in den Subset aufgenommen.
  * Das Koordinatensystem ist PDF-Standard: Ursprung (0, 0) links unten, Y wächst nach oben. A4 hat die Dimensionen 595 × 842 Punkte.
  * TrueType-Fonts werden als ''Type0'' (CIDFont) eingebettet — volle Unicode-Unterstützung inkl. BMP (U+0000–U+FFFF). Surrogate-Paare (U+10000+) werden auf Glyph 0 (Notdef) gemappt.

----

===== Verwandte Units =====

  * ''[[lyx_-_programmiersprache:units:pdf:fonts|std.pdf.fonts]]'' — einfache Typ-1/Basis-14-Fonts (keine Einbettung)
  * ''[[lyx_-_programmiersprache:units:pdf:builder|std.pdf.builder]]'' — Dokumenterstellung (PdfCreate, PdfSave)
  * ''[[lyx_-_programmiersprache:units:pdf:objects|std.pdf.objects]]'' — interne PDF-Objekt-Layer

Letzte Aktualisierung: 2026-06-05