imagecolorexact — Funktion · PHP-Referenz

Signatur

imagecolorexact(GdImage $image, int $red, int $green, int $blue): int

Beschreibung

imagecolorexact() durchsucht die Farbtabelle (Palette) eines mit einer Palette arbeitenden GD-Bildes nach einem Eintrag, dessen RGB-Werte exakt mit den übergebenen Werten übereinstimmen. Wird eine passende Farbe gefunden, gibt die Funktion deren Index zurück; existiert die Farbe nicht in der Palette, wird -1 zurückgegeben.

Die Funktion ist besonders nützlich, wenn man mit palettenbasierten PNG- oder GIF-Bildern (erstellt mit imagecreate()) arbeitet und sicherstellen möchte, ob eine bestimmte Farbe bereits in der Palette vorhanden ist, bevor man sie neu hinzufügt. So lässt sich das Überschreiben oder Verdoppeln von Paletteneinträgen vermeiden.

Bei Truecolor-Bildern (erstellt mit imagecreatetruecolor()) hat die Funktion kaum praktischen Nutzen, da Truecolor-Bilder keine feste Farbtabelle besitzen. In solchen Fällen liefert sie für eine gewünschte Farbe immer -1.

Als Ergänzung kann imagecolorexactalpha() verwendet werden, wenn zusätzlich ein Alpha-Kanal berücksichtigt werden soll.

Parameter

Name	Typ	Beschreibung
$image Pflicht	GdImage	Das GD-Bildobjekt, das mit einer Bilderzeugungsfunktion wie `imagecreate()` oder `imagecreatefromgif()` erstellt wurde.
$red Pflicht	int	Der Rotanteil der gesuchten Farbe als Ganzzahl im Bereich von `0` bis `255`.
$green Pflicht	int	Der Grünanteil der gesuchten Farbe als Ganzzahl im Bereich von `0` bis `255`.
$blue Pflicht	int	Der Blauanteil der gesuchten Farbe als Ganzzahl im Bereich von `0` bis `255`.

Rückgabewert

Typ

int

Beschreibung

Gibt den Index der exakt übereinstimmenden Farbe in der Palette zurück, oder -1, wenn keine exakte Übereinstimmung gefunden wurde.

Beispiele

Farbe in Palette suchen und ggf. neu hinzufügen

<?php
// Palettenbasiertes Bild erstellen
$image = imagecreate(200, 100);

// Hintergrundfarbe (wird automatisch als erster Paletteneintrag registriert)
$white = imagecolorallocate($image, 255, 255, 255);

// Rote Farbe in die Palette aufnehmen
$red = imagecolorallocate($image, 255, 0, 0);

// Prüfen, ob die exakte Farbe Rot (255, 0, 0) bereits in der Palette ist
$index = imagecolorexact($image, 255, 0, 0);

if ($index !== -1) {
    echo "Rot gefunden an Palettenindex: " . $index;
} else {
    echo "Rot ist nicht in der Palette vorhanden.";
}

imagedestroy($image);

Rot gefunden an Palettenindex: 1

Farbe nur hinzufügen, wenn sie noch nicht existiert

<?php
$image = imagecreate(300, 150);

// Hintergrund setzen
imagecolorallocate($image, 255, 255, 255);

// Prüfen, ob Blau bereits vorhanden ist, bevor wir es hinzufügen
$blueIndex = imagecolorexact($image, 0, 0, 255);

if ($blueIndex === -1) {
    // Blau existiert noch nicht → neu anlegen
    $blueIndex = imagecolorallocate($image, 0, 0, 255);
    echo "Blau neu hinzugefügt an Index: " . $blueIndex;
} else {
    echo "Blau bereits vorhanden an Index: " . $blueIndex;
}

// Rechteck in Blau zeichnen
imagerectangle($image, 10, 10, 290, 140, $blueIndex);

header('Content-Type: image/png');
imagepng($image);
imagedestroy($image);

Blau neu hinzugefügt an Index: 1

// Wichtig · Fallstricke

Nur für Palettenbilder sinnvoll: Bei Truecolor-Bildern (erstellt mit imagecreatetruecolor()) wird stets -1 zurückgegeben, da diese keine feste Palette verwenden.

Palettengrenze: Eine GD-Palette unterstützt maximal 256 Farben. Wenn die Palette voll ist und eine nicht vorhandene Farbe gesucht wird, sollte stattdessen imagecolorclosest() verwendet werden, um den nächstähnlichen Paletteneintrag zu finden.

Ab PHP 8.0 ist der Typ des Parameters $image GdImage statt der früheren Resource.

Siehe auch

imagecolorallocate imagecolorclosest imagecolorexactalpha imagecolorresolve imagecolorat imagecreate