Signatur
Beschreibung
imagecolorclosestalpha() durchsucht die Farb-Palette eines palettenbasierten Bildes (imagecreate()) nach dem Eintrag, der der gewünschten Farbe (bestehend aus Rot-, Grün-, Blau- und Alpha-Anteil) am nächsten kommt. Der Rückgabewert ist der Palettenindex dieses Eintrags.
Die Ähnlichkeit wird anhand eines internen Distanzmaßes berechnet, das alle vier Komponenten – red, green, blue und alpha – berücksichtigt. Dies unterscheidet die Funktion von imagecolorclosest(), das den Alpha-Kanal ignoriert.
Typische Einsatzsituationen sind Grafiken, bei denen die Palette bereits voll ausgelastet ist und keine neue Farbe mehr hinzugefügt werden kann. In diesen Fällen liefert die Funktion einen brauchbaren Ersatz-Index. Für Truecolor-Bilder (imagecreatetruecolor()) ist die Funktion weniger sinnvoll, da dort Farben ohne Palettenbeschränkung kodiert werden.
Der Alpha-Wert entspricht dem GD-internen Alpha-Format: 0 steht für vollständig opak, 127 für vollständig transparent – dies ist das Gegenteil der üblichen CSS/PNG-Konvention.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $image Pflicht | GdImage | Das GD-Bildobjekt, das zuvor mit einer Bilderzeugungs-Funktion wie imagecreate() erstellt wurde. |
|
| $red Pflicht | int | Der Rotanteil der gesuchten Farbe im Bereich 0–255. |
|
| $green Pflicht | int | Der Grünanteil der gesuchten Farbe im Bereich 0–255. |
|
| $blue Pflicht | int | Der Blauanteil der gesuchten Farbe im Bereich 0–255. |
|
| $alpha Pflicht | int | Der Alpha-Anteil im GD-Format: 0 = vollständig opak, 127 = vollständig transparent. |
Rückgabewert
-1 zurückgegeben.Beispiele
Nächstliegenden Palettenindex für eine halbtransparente Farbe finden
<?php
// Palettenbasiertes Bild erstellen
$image = imagecreate(200, 100);
// Einige Farben zur Palette hinzufügen
imagecolorallocatealpha($image, 255, 0, 0, 0); // Index 0: Rot, opak
imagecolorallocatealpha($image, 0, 255, 0, 63); // Index 1: Grün, 50 % transparent
imagecolorallocatealpha($image, 0, 0, 255, 127); // Index 2: Blau, voll transparent
// Nächstliegende Farbe zu einem halbtransparenten Blau-Grün suchen
$index = imagecolorclosestalpha($image, 0, 200, 220, 60);
echo "Nächstliegender Palettenindex: " . $index;
// Erwartet: 1 (Grün mit alpha=63 ist dem Gesuchten am ähnlichsten)
imagedestroy($image);Palette-Fallback bei voller Palette
<?php
// Palettenbasiertes Bild (max. 256 Farben)
$image = imagecreate(100, 100);
// Palette vollständig füllen
for ($i = 0; $i < 256; $i++) {
imagecolorallocatealpha($image, $i, 0, 0, 0);
}
// Palette ist jetzt voll – imagecolorallocatealpha würde false liefern
// Stattdessen: nächstliegenden vorhandenen Index verwenden
$index = imagecolorclosestalpha($image, 128, 0, 0, 10);
echo "Fallback-Index: " . $index;
// Ergibt den Index mit dem ähnlichsten Rot- und Alpha-Wert
imagedestroy($image);// Wichtig · Fallstricke
Alpha-Konvention beachten: Der Alpha-Parameter folgt der GD-internen Skala (0 = opak, 127 = transparent), die von der üblichen Web-Konvention abweicht. Ein Verwechseln führt zu unerwarteten Ergebnissen bei der Farbsuche.
Nur für Palettenbilder: Bei Truecolor-Bildern (imagecreatetruecolor()) gibt es keine Palette im klassischen Sinne; die Funktion ist dort nicht sinnvoll und kann unerwartetes Verhalten zeigen.
Falls die Palette leer ist, wird -1 zurückgegeben. Prüfe diesen Fall, bevor du den Index weiterverwendest.