====== std.pdf.imagefile — Bilder aus Dateien ins PDF ======

''import std.pdf.imagefile;''

Eine einzige Funktion: ein Bild aus einer **Datei** laden und als XObject im Dokument anmelden. Das Dekodieren übernimmt ''std.image''; die Unit setzt nur beides zusammen und kürzt dabei die Kanäle auf das, was PDF kennt.

→ [[lyx_-_programmiersprache:units:pdf:image|std.pdf.image]] · [[lyx_-_programmiersprache:units:pdf|std.pdf]]

----

===== Funktion =====

^ Signatur ^ Rückgabe ^ Bedeutung ^
| ''PdfAddImageFile(doc: int64, path: pchar): int64'' | Bildindex ab 0, oder ''-1'' | Datei dekodieren und wie ''PdfAddImage'' anmelden. Der Index geht an ''PdfDrawImage'' |

^ Kanäle im Bild ^ Verhalten ^
| 1 (Graustufen) | direkt übernommen |
| 3 (RGB) | direkt übernommen |
| 4 (RGBA) | **auf RGB gekürzt — der Alphakanal wird verworfen** |
| 2 (Grau + Alpha) | ''-1'' |

<box gh>
> **Durchsichtige Bereiche werden deckend.** PDF-DeviceRGB kennt keinen Alphakanal; der richtige Weg wäre eine SMask, und die gibt es hier noch nicht. Ein halb umgesetzter Alphakanal wäre schlechter als eine benannte Grenze — deshalb steht sie hier.
>
> Grau + Alpha fällt aus demselben Grund auf ''-1'' durch: den Alphakanal stillschweigend als Grauwert zu nehmen wäre schlimmer als eine Fehlermeldung.
</box>

===== Beispiel =====

<code lyx>
import std.pdf;
import std.pdf.imagefile;
import std.io;
import std.alloc;

fn main(): int64 {
    var doc:  int64 := PdfNew();
    var page: int64 := PdfAddPage(doc, 595.0, 842.0);   // A4 in Punkten

    // 1. Rohe Pixel: 4x4 Graustufen-Verlauf
    var n:  int64 := 4 * 4;
    var px: int64 := alloc(n);
    var i:  int64 := 0;
    while (i < n) { poke8(px + i, (i * 16) & 255); i := i + 1; }
    var idx1: int64 := PdfAddImage(doc, px, 4, 4, 1);
    Print("PdfAddImage (grau) : "); PrintLn(IntToStr(idx1));

    // 2. Bild aus einer Datei
    var idx2: int64 := PdfAddImageFile(doc, "rot.png");
    Print("PdfAddImageFile    : "); PrintLn(IntToStr(idx2));

    // 3. Datei gibt es nicht
    var idx3: int64 := PdfAddImageFile(doc, "fehlt.png");
    Print("fehlende Datei     : "); PrintLn(IntToStr(idx3));

    if (idx1 >= 0) { PdfDrawImage(doc, page, idx1,  72.0, 700.0, 100.0, 100.0); }
    if (idx2 >= 0) { PdfDrawImage(doc, page, idx2, 200.0, 700.0, 100.0, 100.0); }
    PdfSave(doc, "bild.pdf");
    free(px, n);
    PrintLn("PDF geschrieben");
    return 0;
}
</code>

Mit einem 8×8-PNG als ''rot.png'' im Arbeitsverzeichnis:

<code>
PdfAddImage (grau) : 0
PdfAddImageFile    : 1
fehlende Datei     : -1
PDF geschrieben
</code>

Die Indizes werden fortlaufend vergeben (0, dann 1) — sie sind die Kennung für ''PdfDrawImage''. Die fehlende Datei liefert ''-1'', und das Programm zeichnet sie schlicht nicht: die Abfrage ''idx >= 0'' vor dem Zeichnen ist der ganze Fehlerpfad.

Höchstens **16 Bilder** je Dokument (''PDF_INITIAL_IMAGE_CAP''); darüber gibt ''PdfAddImage'' ebenfalls ''-1'' zurück.

----

Letzte Aktualisierung: 2026-09-01 — Seite neu angelegt aus ''std/pdf/imagefile.lyx''; Beispiel mit ''lyxc 1.1.16A'' gebaut, ausgeführt und das erzeugte PDF geprüft.