Signatur
Beschreibung
imagecopymergegray funktioniert ähnlich wie imagecopymerge, mit dem entscheidenden Unterschied, dass der kopierte Quellbereich vor dem Mischen in Graustufen konvertiert wird. Das Zielbild behält dabei seine ursprünglichen Farben, während der eingefügte Bereich als Graustufenbild über das Ziel gelegt wird.
Der Parameter pct (0–100) steuert den Transparenzgrad des Quellbereichs beim Mischen: Bei 0 wird nichts kopiert, bei 100 wird der Quellbereich vollständig als Graustufen-Overlay gezeichnet, ohne dass noch Farben des Zielbildes durchscheinen.
Typische Anwendungsfälle sind kreative Bildeffekte, bei denen Teile eines farbigen Bildes absichtlich entsättigt (grau) dargestellt werden sollen, zum Beispiel um einen "verblassten" oder "ausgegrauten" Fotoeffekt zu erzeugen oder Bildbereiche optisch hervorzuheben, indem der Rest des Bildes in Grau übergeht.
Die Funktion arbeitet mit True-Color-GD-Ressourcen (GdImage-Objekte seit PHP 8.0). Palette-Bilder werden intern möglicherweise nicht korrekt verarbeitet, daher empfiehlt sich die Verwendung mit True-Color-Bildern.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $dst_image Pflicht | GdImage | Das Zielbild, in das der Quellbereich als Graustufen-Overlay gemischt wird. | |
| $src_image Pflicht | GdImage | Das Quellbild, aus dem der Bereich entnommen und in Graustufen umgewandelt wird. | |
| $dst_x Pflicht | int | X-Koordinate des Einfügepunkts im Zielbild. | |
| $dst_y Pflicht | int | Y-Koordinate des Einfügepunkts im Zielbild. | |
| $src_x Pflicht | int | X-Koordinate des zu kopierenden Bereichs im Quellbild. | |
| $src_y Pflicht | int | Y-Koordinate des zu kopierenden Bereichs im Quellbild. | |
| $src_width Pflicht | int | Breite des zu kopierenden Bereichs im Quellbild (in Pixeln). | |
| $src_height Pflicht | int | Höhe des zu kopierenden Bereichs im Quellbild (in Pixeln). | |
| $pct Pflicht | int | Deckkraft des Quellbereichs beim Einfügen, von 0 (komplett transparent, nichts wird übertragen) bis 100 (voll opaker Graustufen-Overlay). Werte zwischen 0 und 100 erzeugen einen teiltransparenten Graustufen-Effekt. |
Rückgabewert
true bei Erfolg zurück, false bei einem Fehler (z. B. ungültige Bildressourcen oder Parameterfehler).Beispiele
Bild teilweise in Graustufen überblenden
<?php
// Quellbild (z. B. ein farbiges JPEG) laden
$src = imagecreatefromjpeg('foto.jpg');
// Zielbild als Kopie des Quellbildes erstellen
$dst = imagecreatefromjpeg('foto.jpg');
$width = imagesx($src);
$height = imagesy($src);
// Die linke Hälfte des Bildes in Graustufen mit 100% Deckkraft überblenden
imagecopymergegray(
$dst, // Zielbild
$src, // Quellbild
0, 0, // Zielposition (oben links)
0, 0, // Quellposition (oben links)
(int)($width / 2), $height, // Nur die linke Hälfte
100 // Vollständige Graustufen-Deckkraft
);
// Ergebnis ausgeben
header('Content-Type: image/jpeg');
imagejpeg($dst);
imagedestroy($src);
imagedestroy($dst);
?>Abgestufter Graustufen-Überblend-Effekt
<?php
// True-Color-Bilder erstellen
$src = imagecreatefromjpeg('farbbild.jpg');
$dst = imagecreatefromjpeg('farbbild.jpg');
$width = imagesx($src);
$height = imagesy($src);
// Das gesamte Bild mit 50% Transparenz in Graustufen überblenden
// Ergebnis: halber Farbton + halbe Graustufe sichtbar
imagecopymergegray(
$dst,
$src,
0, 0,
0, 0,
$width, $height,
50 // 50% Deckkraft => leicht entsättigter Effekt
);
header('Content-Type: image/png');
imagepng($dst);
imagedestroy($src);
imagedestroy($dst);
?>// Wichtig · Fallstricke
True-Color-Bilder empfohlen: imagecopymergegray liefert die besten Ergebnisse mit True-Color-Bildern (erstellt z. B. mit imagecreatetruecolor oder geladen via imagecreatefromjpeg/imagecreatefrompng). Bei Palette-Bildern kann es zu unerwarteten Farbverfälschungen kommen.
Unterschied zu imagecopymerge: Während imagecopymerge den Quellbereich in seiner Originalfarbe einkopiert und mit dem Ziel mischt, konvertiert imagecopymergegray den Quellbereich zuvor in Graustufen. Das Zielbild wird nicht entsättigt.
PHP 8.0: Ab PHP 8.0 werden GD-Bildressourcen als GdImage-Objekte zurückgegeben. Älterer Code, der resource-Typen verwendet, funktioniert möglicherweise nicht mehr ohne Anpassungen.