Signatur
Beschreibung
imagexbm() exportiert ein GD-Bildobjekt im XBM-Format, einem textbasierten Bitmap-Format, das ursprünglich im X Window System verwendet wurde. Das Bild wird entweder direkt an den Browser (Standard-Output) gesendet oder in eine Datei geschrieben, wenn ein Dateiname übergeben wird.
XBM ist ein monochromes Format – das heißt, das Bild wird in Schwarz-Weiß dargestellt. Mit dem optionalen Parameter foreground_color kann festgelegt werden, welche Farbe als Vordergrundfarbe (schwarz / gesetzt) gilt. Pixel, die dieser Farbe entsprechen, werden als gesetzte Bits dargestellt; alle anderen Pixel gelten als Hintergrund (weiß / nicht gesetzt).
Für die Ausgabe an den Browser sollte zuvor der korrekte Content-Type-Header gesendet werden: header('Content-Type: image/x-xbitmap');. Das XBM-Format ist heute kaum noch in modernen Anwendungen anzutreffen und eignet sich allenfalls für spezialisierte Anwendungsfälle oder Kompatibilität mit Legacy-Systemen.
Das erzeugte XBM besteht aus einem C-ähnlichen Header mit #define-Anweisungen sowie einem Array mit den Bitmap-Daten. Der Name des Arrays leitet sich aus dem Dateinamen ab.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $image Pflicht | GdImage | Das GD-Bildobjekt, das ausgegeben werden soll. Wird z. B. mit imagecreate() oder imagecreatefromxbm() erzeugt. |
|
| $filename Pflicht | ?string | null | Pfad zur Zieldatei, in die das Bild geschrieben wird. Wird null übergeben, wird das Bild direkt an den Standard-Output (Browser) gesendet. |
| $foreground_color | ?int | null | Ein Farbbezeichner (wie er von imagecolorallocate() zurückgegeben wird), der als Vordergrundfarbe (gesetzte Bits) verwendet wird. Wird null übergeben oder weggelassen, wird Schwarz als Standard-Vordergrundfarbe genutzt. |
Rückgabewert
true bei Erfolg zurück, false bei einem Fehler (z. B. wenn die Datei nicht geschrieben werden konnte).Beispiele
XBM-Bild an den Browser ausgeben
<?php
// Einfaches 32x32-Bild erzeugen
$image = imagecreate(32, 32);
// Hintergrundfarbe (weiß)
$white = imagecolorallocate($image, 255, 255, 255);
// Vordergrundfarbe (schwarz)
$black = imagecolorallocate($image, 0, 0, 0);
// Ein Kreuz in die Mitte zeichnen
imageline($image, 0, 16, 31, 16, $black);
imageline($image, 16, 0, 16, 31, $black);
// Korrekte HTTP-Header setzen
header('Content-Type: image/x-xbitmap');
// Als XBM ausgeben – Vordergrundfarbe: Schwarz
imagexbm($image, null, $black);
// Speicher freigeben
imagedestroy($image);XBM-Bild in eine Datei speichern
<?php
// 16x16-Bild erstellen
$image = imagecreate(16, 16);
$white = imagecolorallocate($image, 255, 255, 255);
$black = imagecolorallocate($image, 0, 0, 0);
// Rahmen zeichnen
imagerectangle($image, 0, 0, 15, 15, $black);
// In eine Datei exportieren
$result = imagexbm($image, '/tmp/rahmen.xbm', $black);
if ($result) {
echo "XBM-Datei erfolgreich gespeichert.";
} else {
echo "Fehler beim Speichern der XBM-Datei.";
}
imagedestroy($image);// Wichtig · Fallstricke
Monochromes Format: XBM unterstützt nur zwei Farben (Vordergrund und Hintergrund). Alle Farbinformationen eines Truecolor- oder Paletten-Bildes werden beim Export auf Schwarz/Weiß reduziert.
Dateiname und Array-Name: Der Name des internen C-Arrays im erzeugten XBM wird aus dem Dateinamen abgeleitet. Sonderzeichen im Dateinamen können dabei zu ungültigem XBM-Output führen. Bei der Ausgabe an den Browser (null als Dateiname) verwendet PHP intern einen leeren String, was zu einem Array-Namen _bits führt.
Verbreitung: XBM ist ein sehr altes Format und wird von modernen Browsern und Anwendungen kaum noch unterstützt. Für die meisten Web-Anwendungen sind imagepng(), imagejpeg() oder imagewebp() die bessere Wahl.