imagesetclip — Funktion · PHP-Referenz

Signatur

imagesetclip(GdImage $image, int $x1, int $y1, int $x2, int $y2): bool

Beschreibung

imagesetclip() definiert ein achsenparalleles Rechteck innerhalb eines GD-Bildes, auf das alle folgenden Zeichenoperationen (Linien, Formen, Text usw.) beschränkt werden. Pixel, die außerhalb dieses Rechtecks liegen, werden nicht verändert. Das Rechteck wird durch seine obere linke Ecke (x1, y1) und seine untere rechte Ecke (x2, y2) in Pixel-Koordinaten definiert.

Diese Funktion ist nützlich, wenn man nur einen bestimmten Bereich eines Bildes verändern möchte, ohne andere Bereiche zu beeinflussen — zum Beispiel beim Einfügen von Text oder grafischen Elementen innerhalb eines definierten Rahmens. So lassen sich komplexe Masken-Operationen ohne aufwendige manuelle Überprüfungen realisieren.

Das aktuell gesetzte Clipping-Rechteck kann mit imagegetclip() abgefragt werden. Um das Clipping aufzuheben und wieder das gesamte Bild zu nutzen, setzt man das Rechteck auf die vollen Bildabmessungen zurück.

Zu beachten ist, dass das Clipping-Rechteck bildspezifisch ist und sich nicht auf andere GD-Ressourcen auswirkt. Die Funktion steht ab PHP 7.2.0 zur Verfügung und erwartet seit PHP 8.0 ein GdImage-Objekt statt einer Ressource.

Parameter

Name	Typ	Beschreibung
$image Pflicht	GdImage	Ein GD-Bildobjekt, das z. B. mit `imagecreatetruecolor()` oder `imagecreatefromjpeg()` erzeugt wurde.
$x1 Pflicht	int	Die X-Koordinate der oberen linken Ecke des Clipping-Rechtecks (in Pixel).
$y1 Pflicht	int	Die Y-Koordinate der oberen linken Ecke des Clipping-Rechtecks (in Pixel).
$x2 Pflicht	int	Die X-Koordinate der unteren rechten Ecke des Clipping-Rechtecks (in Pixel).
$y2 Pflicht	int	Die Y-Koordinate der unteren rechten Ecke des Clipping-Rechtecks (in Pixel).

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültiges Bildobjekt).

Beispiele

Text nur innerhalb eines definierten Bereichs zeichnen

<?php
// Bild erstellen (400x200 Pixel)
$image = imagecreatetruecolor(400, 200);

// Hintergrundfarbe: Weiß
$white = imagecolorallocate($image, 255, 255, 255);
imagefill($image, 0, 0, $white);

// Einen grauen Rahmen zur Orientierung zeichnen
$gray = imagecolorallocate($image, 180, 180, 180);
imagerectangle($image, 50, 50, 350, 150, $gray);

// Clipping-Rechteck setzen: nur innerhalb des Rahmens zeichnen
imagesetclip($image, 50, 50, 350, 150);

// Rote Linie, die über den Rahmen hinausgeht — wird aber geclipt
$red = imagecolorallocate($image, 255, 0, 0);
imageline($image, 0, 100, 400, 100, $red);

// Clipping aufheben (gesamtes Bild)
imagesetclip($image, 0, 0, imagesx($image) - 1, imagesy($image) - 1);

// Bild ausgeben
header('Content-Type: image/png');
imagepng($image);
imagedestroy($image);
?>

Clipping-Bereich setzen und anschließend auslesen

<?php
$image = imagecreatetruecolor(800, 600);

// Clipping-Rechteck auf eine bestimmte Region setzen
imagesetclip($image, 100, 100, 700, 500);

// Aktuell gesetztes Clipping-Rechteck auslesen
$clip = imagegetclip($image);
echo "Clipping-Rechteck: ";
echo "x1={$clip['x1']}, y1={$clip['y1']}, x2={$clip['x2']}, y2={$clip['y2']}";

imagedestroy($image);
?>

Clipping-Rechteck: x1=100, y1=100, x2=700, y2=500

// Wichtig · Fallstricke

Wenn das Clipping-Rechteck außerhalb der Bildgrenzen gesetzt wird, werden Zeichenoperationen trotzdem nur auf den gültigen Bildbereich angewendet — es kommt zu keinem Speicherzugriff außerhalb des Bildes.

Vor PHP 8.0 wurde statt GdImage eine resource verwendet. Code, der mit imagecreate*()-Ressourcen arbeitet, muss für PHP 8+ ggf. angepasst werden.

Das Clipping-Rechteck wird nicht zurückgesetzt, wenn das Bild skaliert oder kopiert wird. Soll das gesamte Bild wieder beschreibbar sein, muss imagesetclip() explizit mit den vollen Bildabmessungen aufgerufen werden.

Siehe auch

imagegetclip imagecreatetruecolor imageline imagerectangle