Signatur
Beschreibung
ps_shading definiert eine Schattierung (engl. shading) innerhalb eines PostScript-Dokuments, das über die PHP-PS-Erweiterung (pslib) erstellt wird. Schattierungen beschreiben Farbverläufe, die als eigene Ressource registriert werden und anschließend für Fülloperationen zur Verfügung stehen.
Der Parameter type bestimmt die Art des Verlaufs: radial erzeugt einen kreisförmigen Verlauf, während axial (linear) einen geradlinigen Verlauf erzeugt. Die Koordinatenpaare (x0, y0) und (x1, y1) legen Start- und Endpunkt des Verlaufs fest. Die Farbkomponenten c1 bis c4 definieren die Endfarbe des Verlaufs; die Startfarbe wird durch den aktuellen Zeichenzustand bestimmt.
Die Funktion ist Teil der PECL ps-Erweiterung und erfordert eine installierte libps-Bibliothek. Schattierungen eignen sich für professionell gestaltete PDF-ähnliche PostScript-Dokumente, etwa für Hintergründe, Buttons oder dekorative Elemente.
Die erstellte Schattierung wird als Integer-Handle zurückgegeben und kann mit ps_shfill direkt zum Füllen von Flächen genutzt werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $psdoc Pflicht | resource | Die Ressource des PostScript-Dokuments, wie sie von ps_new zurückgegeben wird. |
|
| $type Pflicht | string | Art der Schattierung: 'radial' für einen kreisförmigen Verlauf oder 'axial' für einen linearen (geradlinigen) Verlauf. |
|
| $x0 Pflicht | float | X-Koordinate des Startpunkts (bzw. Mittelpunkts beim radialen Verlauf) des Farbverlaufs. | |
| $y0 Pflicht | float | Y-Koordinate des Startpunkts (bzw. Mittelpunkts beim radialen Verlauf) des Farbverlaufs. | |
| $x1 Pflicht | float | X-Koordinate des Endpunkts (bzw. des zweiten Kreismittelpunkts beim radialen Verlauf) des Farbverlaufs. | |
| $y1 Pflicht | float | Y-Koordinate des Endpunkts (bzw. des zweiten Kreismittelpunkts beim radialen Verlauf) des Farbverlaufs. | |
| $c1 Pflicht | float | Erste Farbkomponente der Endfarbe des Verlaufs (z. B. Rot-Anteil bei RGB). | |
| $c2 Pflicht | float | Zweite Farbkomponente der Endfarbe des Verlaufs (z. B. Grün-Anteil bei RGB). | |
| $c3 Pflicht | float | Dritte Farbkomponente der Endfarbe des Verlaufs (z. B. Blau-Anteil bei RGB). | |
| $c4 Pflicht | float | Vierte Farbkomponente der Endfarbe (z. B. Alpha-Wert oder Schwarz-Anteil bei CMYK). Bei RGB-Farbräumen wird dieser Wert in der Regel auf 0.0 gesetzt. |
|
| $optlist Pflicht | string | Optionale Zeichenkette mit weiteren Parametern im pslib-Format, z. B. zur Angabe von Radien bei radialen Verläufen ('r0=... r1=...'). Kann als leere Zeichenkette übergeben werden. |
Rückgabewert
ps_shfill oder ps_shading_pattern verwendet wird. Bei einem Fehler wird 0 zurückgegeben.Beispiele
Linearen Farbverlauf erstellen und Rechteck füllen
<?php
$ps = ps_new();
ps_open_file($ps, 'verlauf.ps');
ps_begin_page($ps, 596, 842);
// Startfarbe setzen (Rot)
ps_setcolor($ps, 'fill', 'rgb', 1.0, 0.0, 0.0, 0.0);
// Axialen (linearen) Verlauf von links nach rechts erstellen
// Endfarbe: Blau (0.0, 0.0, 1.0)
$shading = ps_shading($ps, 'axial', 50, 400, 300, 400, 0.0, 0.0, 1.0, 0.0, '');
// Rechteck definieren und mit Verlauf füllen
ps_rect($ps, 50, 350, 250, 100);
ps_clip($ps);
ps_shfill($ps, $shading);
ps_end_page($ps);
ps_close($ps);
ps_delete($ps);
echo 'PostScript-Datei mit linearem Farbverlauf erstellt.';
?>Radialen Farbverlauf erstellen
<?php
$ps = ps_new();
ps_open_file($ps, 'radial_verlauf.ps');
ps_begin_page($ps, 596, 842);
// Startfarbe: Gelb
ps_setcolor($ps, 'fill', 'rgb', 1.0, 1.0, 0.0, 0.0);
// Radialen Verlauf erstellen – gleicher Mittelpunkt, r0=0, r1=100
$shading = ps_shading(
$ps,
'radial',
298, 421, // Startmittelpunkt
298, 421, // Endmittelpunkt (gleich für konzentrischen Kreis)
0.0, 0.0, 1.0, 0.0, // Endfarbe: Blau
'r0=0 r1=100'
);
// Kreis definieren und mit radialem Verlauf füllen
ps_circle($ps, 298, 421, 100);
ps_clip($ps);
ps_shfill($ps, $shading);
ps_end_page($ps);
ps_close($ps);
ps_delete($ps);
echo 'PostScript-Datei mit radialem Farbverlauf erstellt.';
?>// Wichtig · Fallstricke
Erweiterung erforderlich: ps_shading ist Teil der PECL-Erweiterung ps (pslib) und steht nicht standardmäßig in PHP zur Verfügung. Die Erweiterung muss separat installiert werden (pecl install ps).
Farbmodell: Die Farbkomponenten c1–c4 beziehen sich auf den aktuell gesetzten Farbraum. Bei RGB werden nur drei Komponenten genutzt; c4 sollte auf 0.0 gesetzt werden. Bei CMYK werden alle vier Werte verwendet.
Clipping erforderlich: Eine Schattierung füllt grundsätzlich den gesamten definierten Bereich. Um die Füllung auf bestimmte Formen zu begrenzen, muss vor dem Aufruf von ps_shfill ein Clipping-Pfad mit ps_clip gesetzt werden.
Ressourcenverwaltung: Schattierungen werden intern in der pslib-Ressource gespeichert. Der zurückgegebene Handle ist nur innerhalb desselben Dokuments gültig.