Signatur
Beschreibung
ps_clip() aktiviert den aktuellen Pfad als Clipping-Pfad für das PostScript-Dokument. Nach dem Aufruf werden alle nachfolgenden Zeichenoperationen auf den Bereich innerhalb des zuletzt definierten Pfads beschränkt. Alles außerhalb dieses Bereichs wird nicht gezeichnet.
Typischerweise wird zunächst ein Pfad mit Funktionen wie ps_moveto(), ps_lineto(), ps_curveto() oder ps_circle() aufgebaut. Anschließend sorgt ps_clip() dafür, dass dieser Pfad als Beschneide-Maske wirkt. Der Pfad selbst wird dabei weder gefüllt noch gestrokt – er dient nur als Clip-Grenze.
Sinnvoll ist ps_clip() zum Beispiel beim Platzieren von Bildern oder Texten innerhalb einer definierten Form, etwa eines Kreises oder Rechtecks, oder für komplexe grafische Layouts, bei denen Elemente an einer bestimmten Kontur enden sollen.
Um den Clipping-Bereich zurückzusetzen, sollte man zuvor den aktuellen Grafikzustand mit ps_save() gespeichert und nach dem Zeichnen mit ps_restore() wiederhergestellt haben, da PostScript Clipping-Pfade nicht einfach entfernt, sondern nur verkleinern kann.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $psdoc Pflicht | resource | Die Ressource des PostScript-Dokuments, wie sie von ps_new() zurückgegeben wird. |
Rückgabewert
true bei Erfolg zurück, false bei einem Fehler.Beispiele
Text auf einen kreisförmigen Bereich beschneiden
<?php
$ps = ps_new();
ps_open_file($ps, 'clip_example.ps');
ps_begin_page($ps, 595, 842);
// Grafikzustand speichern, damit der Clip nach ps_restore() aufgehoben wird
ps_save($ps);
// Kreis als Clipping-Pfad definieren
ps_moveto($ps, 300 + 100, 500); // Startpunkt auf dem Kreisrand
ps_arc($ps, 300, 500, 100, 0, 360);
// Clipping aktivieren
ps_clip($ps);
// Alles außerhalb des Kreises wird nicht gezeichnet
ps_setcolor($ps, 'fill', 'rgb', 1, 0, 0, 0);
ps_rect($ps, 150, 350, 300, 300);
ps_fill($ps);
// Grafikzustand wiederherstellen (Clipping aufheben)
ps_restore($ps);
ps_end_page($ps);
ps_close($ps);
ps_delete($ps);
?>Bild auf einen rechteckigen Bereich beschneiden
<?php
$ps = ps_new();
ps_open_file($ps, 'clip_rect.ps');
ps_begin_page($ps, 595, 842);
ps_save($ps);
// Rechteck als Clipping-Pfad
ps_rect($ps, 100, 600, 200, 150);
ps_clip($ps);
// Nur der Bereich innerhalb des Rechtecks wird sichtbar sein
$img = ps_open_image_file($ps, 'png', 'bild.png', '', 0);
ps_place_image($ps, $img, 50, 550, 1.0);
ps_close_image($ps, $img);
ps_restore($ps);
ps_end_page($ps);
ps_close($ps);
ps_delete($ps);
?>// Wichtig · Fallstricke
Wichtig: Clipping-Pfade in PostScript sind akkumulativ – jedes weitere ps_clip() schneidet den Clipping-Bereich weiter ein, ohne ihn zu ersetzen. Es ist daher unbedingt empfohlen, vor dem Setzen eines Clipping-Pfads ps_save() aufzurufen und danach ps_restore(), um zum ursprünglichen (unclipped) Zustand zurückzukehren.
Die Funktion gehört zur ps-Erweiterung (pecl/ps), die PostScript-Dokumente erzeugt. Diese Erweiterung ist nicht standardmäßig in PHP enthalten und muss separat installiert werden.