Signatur
Beschreibung
imagepalettecopy() überträgt die gesamte Farbpalette eines Quell-GdImage-Objekts auf ein Ziel-GdImage-Objekt. Dies ist ausschließlich für Paletten-basierte Bilder relevant, also Bilder, die mit imagecreate() (nicht imagecreatetruecolor()) erstellt wurden oder aus GIF- bzw. 8-Bit-PNG-Quellen stammen.
Wenn zwei Paletten-Bilder zusammengeführt oder auf ein gemeinsames Farbschema gebracht werden sollen – etwa beim Kopieren von Bildbereichen mit imagecopy() – kann es zu Farbverfälschungen kommen, weil jedes Bild eine eigene Paletten-Zuordnung besitzt. Mit imagepalettecopy() lässt sich sicherstellen, dass Quell- und Ziel-Bild dieselbe Palette verwenden, sodass Pixelwerte korrekt interpretiert werden.
Die Funktion kopiert bis zu 256 Farben (die maximale Palette für Paletten-Bilder in GD). Farben, die im Quellbild nicht belegt sind, werden im Zielbild entsprechend freigelassen oder auf Schwarz gesetzt. Truecolor-Bilder haben keine Palette im eigentlichen Sinne; der Einsatz dieser Funktion auf solche Bilder ergibt keinen sinnvollen Effekt.
Typische Anwendungsfälle sind die Manipulation von GIF-Animationen, die Vereinheitlichung von Paletten vor dem Zusammenführen von Bildregionen oder das Exportieren optimierter Paletten-Grafiken für Webanwendungen mit eingeschränkter Farbanzahl.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $destination Pflicht | GdImage | Das Ziel-Bild-Objekt, in das die Palette kopiert wird. Muss ein gültiges GdImage-Objekt sein, typischerweise ein Paletten-Bild (erstellt mit imagecreate()). |
|
| $source Pflicht | GdImage | Das Quell-Bild-Objekt, dessen Palette übernommen wird. Muss ein gültiges GdImage-Objekt sein, das eine Farbpalette enthält. |
Rückgabewert
Beispiele
Palette von einem GIF-Bild auf ein neues Bild übertragen
<?php
// Quellbild aus einer GIF-Datei laden (Paletten-Bild)
$source = imagecreatefromgif('original.gif');
// Neues leeres Paletten-Bild in gleicher Größe erstellen
$destination = imagecreate(imagesx($source), imagesy($source));
// Palette vom Quellbild auf das Zielbild übertragen
imagepalettecopy($destination, $source);
// Jetzt können Bildbereiche korrekt kopiert werden
imagecopy($destination, $source, 0, 0, 0, 0, imagesx($source), imagesy($source));
// Ergebnis als GIF speichern
imagegif($destination, 'kopie.gif');
imagedestroy($source);
imagedestroy($destination);
echo "Bild mit kopierter Palette wurde gespeichert.";
Zwei Paletten-Bilder mit gleicher Palette zusammenfügen
<?php
// Zwei Paletten-Bilder laden
$img1 = imagecreatefromgif('hintergrund.gif');
$img2 = imagecreatefromgif('vordergrund.gif');
// Breite und Höhe ermitteln
$breite = imagesx($img1);
$hoehe = imagesy($img1);
// Neues Ziel-Palettenbild erstellen
$result = imagecreate($breite, $hoehe);
// Palette von img1 als Basis übernehmen
imagepalettecopy($result, $img1);
// Hintergrund in das Ergebnis kopieren
imagecopy($result, $img1, 0, 0, 0, 0, $breite, $hoehe);
// Vordergrund oben links einblenden (obere Hälfte)
$halfH = intdiv($hoehe, 2);
imagepalettecopy($result, $img2); // Palette aktualisieren falls nötig
imagecopy($result, $img2, 0, 0, 0, 0, $breite, $halfH);
// Speichern
imagegif($result, 'zusammengefuegt.gif');
imagedestroy($img1);
imagedestroy($img2);
imagedestroy($result);
echo "Zusammengefügtes Bild gespeichert.";
// Wichtig · Fallstricke
Nur für Paletten-Bilder: imagepalettecopy() hat keine sinnvolle Wirkung auf Truecolor-Bilder, die mit imagecreatetruecolor() erstellt wurden. Der Einsatz auf solche Bilder kann zu unerwartetem Verhalten führen.
Maximale Palettenanzahl: GD unterstützt maximal 256 Farben in einer Palette (Indizes 0–255). Beim Kopieren werden alle belegten Einträge übernommen; überschüssige Einträge des Quellbildes werden ignoriert, wenn das Zielbild bereits eine volle Palette hat.
Farbverfälschung ohne Palettenkopie: Wenn man Bildinhalte per imagecopy() zwischen zwei Paletten-Bildern mit unterschiedlichen Paletten überträgt, werden Pixelwerte (Indizes) beibehalten, aber als andere Farben interpretiert. imagepalettecopy() löst dieses Problem, indem es die Paletten synchronisiert.
Ab PHP 8.0 werden GdImage-Objekte anstelle von resource-Handles verwendet. Älterer Code, der resource-Variablen übergab, muss entsprechend angepasst werden.