====== std.pdf.xobject ======

PDF Form XObjects (WP-PDF-23): Wiederverwendbare Grafik-Blöcke, die einmal gezeichnet und dann beliebig oft auf beliebigen Seiten platziert werden können. Der XObject-Handle verhält sich wie ein negativer ''page''-Parameter — alle normalen Zeichenfunktionen (''PdfSetFont'', ''PdfTextAt'', ''PdfRect'', ''PdfMoveTo'' …) akzeptieren ihn direkt.

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

----

===== Funktionen =====

^ Signatur ^ Beschreibung ^
| ''PdfBeginXObject(doc: int64, w: f64, h: f64): int64'' | Startet einen neuen Form-XObject-Kontext mit BBox-Abmessungen ''w'' × ''h'' (PDF-Punkte). Gibt einen negativen Handle zurück (erster = −1, zweiter = −2, …), der als ''page''-Argument für alle Zeichenfunktionen verwendet wird. |
| ''PdfEndXObject(doc: int64, xobj: int64): void'' | Schließt den XObject ab (aktuell No-Op; reserviert für künftige Aufräumlogik). |
| ''PdfDrawXObject(doc: int64, page: int64, xobj: int64, x: f64, y: f64): void'' | Platziert den XObject ''xobj'' auf Seite ''page'' an Position (''x'', ''y'') in nativer Größe (1:1 gemäß BBox). |
| ''PdfDrawXObjectScaled(doc: int64, page: int64, xobj: int64, x100: int64, y100: int64, scale100: int64): void'' | Platziert den XObject mit einheitlichem Skalierungsfaktor. ''scale100'': 100 = 100 % (nativ), 200 = doppelte Größe, 50 = halbe Größe. Koordinaten in ×100-Einheiten. |

----

===== Handle-Konvention =====

''PdfBeginXObject'' gibt einen **negativen** ''int64''-Handle zurück:

^ Index ^ Handle ^
| 0 (erster XObject) | −1 |
| 1 (zweiter) | −2 |
| n | −(n+1) |

Dieser Handle wird direkt als ''page''-Argument an alle Zeichenfunktionen übergeben. ''PdfDrawXObject'' und ''PdfDrawXObjectScaled'' validieren ''xobj >= 0'' als Fehler (Schutz gegen versehentliche Verwechslung mit einer echten Seite).

----

===== Verwendung =====

==== Wiederverwendbares Logo ====

<code lyx>
import std.pdf.xobject;
import std.pdf.graphics;
import std.pdf.fonts;

fn CreateLogo(doc: int64): int64 {
    var xobj := PdfBeginXObject(doc, 100.0, 50.0);

    // Roter Hintergrund
    PdfSetFillColor(doc, xobj, 10000, 0, 0);
    PdfRect(doc, xobj, 0.0, 0.0, 100.0, 50.0);
    PdfFill(doc, xobj);

    // Weißer Text
    PdfSetFont(doc, xobj, 0, 14.0);
    PdfSetTextColor(doc, xobj, 10000, 10000, 10000);
    PdfTextAt(doc, xobj, 10.0, 18.0, "MyBrand");

    PdfEndXObject(doc, xobj);
    return xobj;
}

fn AddLogoToAllPages(doc: int64, logo: int64, pageCount: int64): void {
    var i: int64 := 0;
    while (i < pageCount) {
        // Logo oben rechts auf jeder Seite (A4: 595 pt breit)
        PdfDrawXObject(doc, i, logo, 480.0, 800.0);
        i := i + 1;
    }
}
</code>

==== Skalierter XObject ====

<code lyx>
import std.pdf.xobject;

fn PlaceLogoScaled(doc: int64, page: int64, logo: int64): void {
    // 50 % Größe, Position (x=5000, y=75000) in ×100-Einheiten
    PdfDrawXObjectScaled(doc, page, logo, 5000, 75000, 50);

    // 150 % Größe, Position (x=10000, y=70000)
    PdfDrawXObjectScaled(doc, page, logo, 10000, 70000, 150);
}
</code>

==== Kopf- und Fußzeile als XObject ====

<code lyx>
import std.pdf.xobject;
import std.pdf.fonts;

fn MakeHeader(doc: int64, title: pchar): int64 {
    var xobj := PdfBeginXObject(doc, 595.0, 30.0);
    PdfSetFont(doc, xobj, 0, 10.0);
    PdfTextAt(doc, xobj, 10.0, 10.0, title);
    PdfEndXObject(doc, xobj);
    return xobj;
}

fn ApplyHeader(doc: int64, header: int64, pages: int64): void {
    var i: int64 := 0;
    while (i < pages) {
        PdfDrawXObject(doc, i, header, 0.0, 812.0);   // A4: 842 - 30 = 812 pt
        i := i + 1;
    }
}
</code>

----

===== Hinweise =====

  * Der XObject-Handle ist ein **negativer Wert** — niemals als normalen Seitenindex verwenden.
  * Alle Zeichenoperationen auf einem XObject-Handle werden in den XObject-Content-Stream geschrieben, nicht in eine Seite.
  * ''PdfDrawXObject'' verwendet ''scale100 = 100'' (nativ). Für Skalierung ''PdfDrawXObjectScaled'' mit ×100-Koordinaten nutzen.
  * XObjects werden im PDF einmalig eingebettet und per Referenz gezogen — wiederholtes Platzieren erhöht die Dateigröße kaum.
  * ''PdfEndXObject'' ist aktuell ein No-Op, sollte aber immer aufgerufen werden (Kompatibilität mit zukünftigen Versionen).

----

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

  * ''[[lyx_-_programmiersprache:units:pdf:graphics|std.pdf.graphics]]'' — Pfade, Farben, Clipping
  * ''[[lyx_-_programmiersprache:units:pdf:fonts|std.pdf.fonts]]'' — Schriftauswahl
  * ''[[lyx_-_programmiersprache:units:pdf:builder|std.pdf.builder]]'' — Dokument- und Seitenverwaltung

Letzte Aktualisierung: 2026-06-05