====== std.pdf.shading ======

PDF-Verlaufsfüllungen (Shading, WP-PDF-22): Axiale (lineare) und radiale Gradienten direkt im PDF-Content-Stream über ''Type 2''- bzw. ''Type 3''-Shading-Dictionaries. Koordinaten und Farben werden als kompakte ''int64''-Packwerte übergeben.

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

----

===== Packing-Funktionen =====

Koordinaten und Farben werden als gepackte ''int64''-Werte übergeben, um das 6-Argument-Limit von Lyx einzuhalten.

==== PdfPackColor ====

<code lyx>
pub fn PdfPackColor(r100: int64, g100: int64, b100: int64): int64
</code>

Packt RGB-Komponenten (je ×100, Bereich 0–10 000 entspricht 0 %–100 %) in ein ''int64'':

  r100 << 48 | g100 << 32 | b100 << 16

^ Beispiel ^ Farbe ^
| ''PdfPackColor(10000, 0, 0)'' | Reines Rot |
| ''PdfPackColor(0, 0, 10000)'' | Reines Blau |
| ''PdfPackColor(5000, 5000, 5000)'' | Mittelgrau |
| ''PdfPackColor(10000, 10000, 10000)'' | Weiß |
| ''PdfPackColor(0, 0, 0)'' | Schwarz |

==== PdfPackCoords ====

<code lyx>
pub fn PdfPackCoords(x100: int64, y100: int64): int64
</code>

Packt zwei Koordinaten (je ×100, d. h. 100 entspricht 1,00 Punkt) in ein ''int64'':

  x100 << 32 | (y100 & 0xFFFFFFFF)

Wird für Start-/Endpunkte bei ''PdfLinearGradient'' und Mittelpunkt/Radien bei ''PdfRadialGradient'' verwendet.

----

===== Gradient-Funktionen =====

==== PdfLinearGradient ====

<code lyx>
pub fn PdfLinearGradient(doc: int64, page: int64, p0: int64, p1: int64, c0: int64, c1: int64): void
</code>

Füllt den aktuellen Clipping-Bereich mit einem axialen Verlauf von ''c0'' an ''p0'' bis ''c1'' an ''p1''.

^ Parameter ^ Typ ^ Beschreibung ^
| ''p0'' | ''PdfPackCoords(x100, y100)'' | Startpunkt des Verlaufs |
| ''p1'' | ''PdfPackCoords(x100, y100)'' | Endpunkt des Verlaufs |
| ''c0'' | ''PdfPackColor(r100, g100, b100)'' | Farbe am Startpunkt |
| ''c1'' | ''PdfPackColor(r100, g100, b100)'' | Farbe am Endpunkt |

Der Gradient füllt die gesamte Seite, sofern kein Clipping gesetzt ist. Für einen begrenzten Bereich ''PdfSaveState'' → ''PdfClip'' → ''PdfLinearGradient'' → ''PdfRestoreState'' verwenden.

==== PdfRadialGradient ====

<code lyx>
pub fn PdfRadialGradient(doc: int64, page: int64, center: int64, radii: int64, c0: int64, c1: int64): void
</code>

Füllt mit einem radialen Verlauf (konzentrische Kreise) von ''c0'' am inneren Kreis bis ''c1'' am äußeren Kreis. Beide Kreise teilen denselben Mittelpunkt.

^ Parameter ^ Typ ^ Beschreibung ^
| ''center'' | ''PdfPackCoords(cx100, cy100)'' | Gemeinsamer Mittelpunkt |
| ''radii'' | ''PdfPackCoords(r0_100, r1_100)'' | Innenradius (''r0'') und Außenradius (''r1'') |
| ''c0'' | ''PdfPackColor(r100, g100, b100)'' | Farbe am Innenkreis |
| ''c1'' | ''PdfPackColor(r100, g100, b100)'' | Farbe am Außenkreis |

----

===== Verwendung =====

==== Horizontaler Farbverlauf ====

<code lyx>
import std.pdf.shading;

fn HorizontalGradient(doc: int64, page: int64): void {
    // Verlauf von links (Blau) nach rechts (Rot), volle Seitenbreite A4
    var p0 := PdfPackCoords(0,     84200);  // links, Mitte Y = 421 pt
    var p1 := PdfPackCoords(59500, 84200);  // rechts (595 pt)
    var c0 := PdfPackColor(0, 0, 10000);    // Blau
    var c1 := PdfPackColor(10000, 0, 0);    // Rot

    PdfLinearGradient(doc, page, p0, p1, c0, c1);
}
</code>

==== Diagonaler Verlauf mit Clipping ====

<code lyx>
import std.pdf.shading;
import std.pdf.graphics;

fn ClippedGradient(doc: int64, page: int64): void {
    PdfSaveState(doc, page);

    // Rechteck als Clipping setzen (in ×100-Einheiten)
    PdfRect(doc, page, 5000.0, 60000.0, 20000.0, 10000.0);
    PdfClip(doc, page);

    var p0 := PdfPackCoords(5000,  70000);
    var p1 := PdfPackCoords(25000, 60000);
    var c0 := PdfPackColor(10000, 10000, 0);   // Gelb
    var c1 := PdfPackColor(0, 10000, 0);       // Grün

    PdfLinearGradient(doc, page, p0, p1, c0, c1);

    PdfRestoreState(doc, page);
}
</code>

==== Radialer Sonnen-Effekt ====

<code lyx>
import std.pdf.shading;

fn SunEffect(doc: int64, page: int64): void {
    var cx := 29750;  var cy := 42100;  // Seitenmitte A4 (×100)
    var center := PdfPackCoords(cx, cy);
    var radii  := PdfPackCoords(0, 15000);  // innen r=0, außen r=150 pt

    var cInner := PdfPackColor(10000, 10000, 0);  // Gelb
    var cOuter := PdfPackColor(10000, 0,     0);  // Rot

    PdfRadialGradient(doc, page, center, radii, cInner, cOuter);
}
</code>

----

===== Hinweise =====

  * Koordinaten sind in **×100-Einheiten**: 100 entspricht 1,00 PDF-Punkt. A4-Breite = 59 500, A4-Höhe = 84 200.
  * Farben sind in **×100-Einheiten**: 10 000 entspricht 100 %. RGB-Bereich: 0–10 000 pro Kanal.
  * Ein Gradient ohne vorheriges Clipping füllt die gesamte Seite — immer ''PdfSaveState''/''PdfRestoreState'' um den Aufruf legen, wenn nur ein Teilbereich gefüllt werden soll.
  * Jeder ''PdfLinearGradient''- oder ''PdfRadialGradient''-Aufruf erzeugt ein neues Shading-Objekt im PDF; mehrere Aufrufe auf derselben Seite sind möglich.

----

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

  * ''[[lyx_-_programmiersprache:units:pdf:graphics|std.pdf.graphics]]'' — Pfade, Clipping, Farben (PdfSaveState, PdfClip …)
  * ''[[lyx_-_programmiersprache:units:pdf:spot|std.pdf.spot]]'' — Spot-Farben (Separation Color Space)
  * ''[[lyx_-_programmiersprache:units:pdf:builder|std.pdf.builder]]'' — Dokumenterstellung

Letzte Aktualisierung: 2026-06-05