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.

→ std.pdf.builder · std.pdf.graphics · 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

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;
    }
}

Skalierter XObject

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);
}

Kopf- und Fußzeile als XObject

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;
    }
}

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).

Inhaltsverzeichnis