Signatur
Beschreibung
imagecolorallocate() reserviert eine Farbe in der Farbtabelle des angegebenen GD-Bildes und gibt deren Index zurück. Dieser Index kann anschließend in Zeichenfunktionen wie imagesetpixel(), imagefilledrectangle() oder imageline() verwendet werden.
Bei Palettenbildern (erstellt mit imagecreate()) wird die erste Farbe, die imagecolorallocate() zugewiesen wird, gleichzeitig als Hintergrundfarbe des Bildes festgelegt. Bei True-Color-Bildern (erstellt mit imagecreatetruecolor()) ist das Verhalten transparent: Die Farbe wird intern berechnet, ohne eine explizite Palette zu verwalten.
Die Farbpalette eines Palettenbildes ist auf maximal 256 Einträge begrenzt. Wenn alle Einträge vergeben sind, gibt die Funktion false zurück. Es empfiehlt sich daher, den Rückgabewert auf false zu prüfen, bevor der Index weiterverwendet wird.
Die RGB-Werte müssen im Bereich von 0 bis 255 liegen. Werte außerhalb dieses Bereichs führen zu undefiniertem Verhalten, daher sollten Eingaben stets validiert werden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $image Pflicht | GdImage | Ein gültiges GD-Bildobjekt, das z. B. von imagecreate() oder imagecreatetruecolor() zurückgegeben wurde. |
|
| $red Pflicht | int | Rotwert der Farbe im Bereich von 0 bis 255. | |
| $green Pflicht | int | Grünwert der Farbe im Bereich von 0 bis 255. | |
| $blue Pflicht | int | Blauwert der Farbe im Bereich von 0 bis 255. |
Rückgabewert
int zurück, der in Zeichenfunktionen eingesetzt werden kann. Bei einem Fehler (z. B. volle Palette) wird false zurückgegeben.Beispiele
Einfaches Bild mit farbigem Rechteck erstellen
<?php
// Palettenbild erstellen
$image = imagecreate(200, 100);
// Hintergrundfarbe (erste Farbe = Hintergrund bei Palettenbildern)
$hintergrund = imagecolorallocate($image, 255, 255, 255); // Weiß
// Weitere Farben zuweisen
$rot = imagecolorallocate($image, 255, 0, 0);
$blau = imagecolorallocate($image, 0, 0, 255);
// Rotes Rechteck zeichnen
imagefilledrectangle($image, 10, 10, 100, 90, $rot);
// Blauen Rahmen zeichnen
imagerectangle($image, 10, 10, 100, 90, $blau);
// Als PNG ausgeben
header('Content-Type: image/png');
imagepng($image);
imagedestroy($image);Farbe auf True-Color-Bild zuweisen und Text schreiben
<?php
// True-Color-Bild erstellen
$image = imagecreatetruecolor(300, 50);
// Hintergrund mit imagefilledrectangle setzen
$hintergrund = imagecolorallocate($image, 30, 30, 30); // Dunkelgrau
imagefilledrectangle($image, 0, 0, 300, 50, $hintergrund);
// Textfarbe zuweisen
$gelb = imagecolorallocate($image, 255, 220, 0);
// Prüfen, ob Farbe erfolgreich alloziert wurde
if ($gelb === false) {
die('Farbe konnte nicht alloziert werden.');
}
// Text auf das Bild schreiben
imagestring($image, 5, 10, 15, 'Hallo, PHP-GD!', $gelb);
// Als PNG ausgeben
header('Content-Type: image/png');
imagepng($image);
imagedestroy($image);// Wichtig · Fallstricke
Palettengrenze: Bei mit imagecreate() erstellten Bildern sind maximal 256 Farben möglich. Wird diese Grenze überschritten, gibt imagecolorallocate() false zurück. Prüfe den Rückgabewert stets mit === false, da der Index 0 ein gültiger Farbindex ist und bei einem normalen Vergleich mit == false fälschlicherweise als Fehler interpretiert werden könnte.
Erster Aufruf bei Palettenbildern: Die erste mit imagecolorallocate() zugewiesene Farbe wird automatisch als Hintergrundfarbe des Bildes verwendet. Dies gilt ausschließlich für Palettenbilder, nicht für True-Color-Bilder.
Für Farben mit Transparenz steht imagecolorallocatealpha() zur Verfügung, welche zusätzlich einen Alpha-Wert entgegennimmt.