The XBM file (.xbm)

XBM is the bitmap format of the X Window System, the graphics system of most Unix and Linux desktops since the 1980s. It stores a black-and-white image as C source code, so a programmer can #include an icon or a cursor and have it compiled into the program, with no image library and no file to load at run time.

Xlib, the C library for writing X programs, has had functions to read and write the format from the start: XReadBitmapFile, XWriteBitmapFile and XCreateBitmapFromData. X also came with a bitmap editor that saves XBM files. For pictures with colour, X programs moved to XPM, which first appeared in 1989 and keeps the same idea of an image written as C code.

Today you'll meet XBM files:

• In X11 programs and window managers, for cursors, small icons and button images. The Openbox window manager, for example, draws its title-bar buttons from XBM files in its themes.
• In microcontroller projects, where a display library takes a 1-bit image as a C array; XBM is ready to paste in.
• In old websites, from the early web, when browsers displayed XBM and simple hit counters were served as XBM images.

For anything else, use PNG: it can also store 1-bit images, compresses them, and opens everywhere.

The format is defined by what Xlib writes. In the X11 documentation it's five lines, with the hotspot lines optional:

#define name_width width
#define name_height height
#define name_x_hot x
#define name_y_hot y
static unsigned char name_bits[] = { 0xNN,... }

• 1 bit per pixel. 1 is the foreground, normally drawn black; 0 is the background. Many programs show 0 as transparent, so an XBM icon takes on the colour behind it.
• Rows top to bottom, pixels left to right, unlike BMP, which stores rows bottom-up.
• Least significant bit first. The leftmost pixel of a byte is its lowest bit. That's the opposite of PBM, where the leftmost pixel is the highest bit, and a common mistake in hand-written XBM code.
• Each row is padded to whole bytes. A row of 10 pixels takes 2 bytes; the unused bits are ignored.
• No compression and no colour. A 64 × 64 icon is 512 bytes of pixels, written out as about 3 KB of text.

In the early web, XBM was the simplest image format that wasn't owned by anyone, and graphical browsers, especially those on X, displayed it inline. It was used for small symbols and for hit counters, which a server script could write as text without an image library.

Support went away as the web settled on GIF, JPEG and PNG:

• Internet Explorer dropped XBM in version 6.
• Firefox removed its XBM decoder around Firefox 3.6. A side effect of the old decoder: a local text file starting with #define, such as C source code, could be mistaken for an XBM image.
• WebKit removed its open-source XBM decoder in January 2010, noting that Mozilla and Internet Explorer had already done so. Chrome, then built on WebKit, lost XBM with it.

Treat XBM as unsupported on the web. To show a 1-bit image on a page, convert it to PNG or SVG.

XPM is XBM's colour successor. PBM, from the Netpbm family, stores the same 1-bit pixels with the opposite bit order and is the usual go-between when converting. PNG is what to keep or share.

• Look at it: it's text, so any text editor shows the code. To see the picture, open it in GIMP, XnView or IrfanView (Windows).
• Draw one: GIMP opens and exports XBM. Its export dialog can write hotspot values, a comment, a different name prefix and, since XBM has no transparency, a separate mask file made from the alpha channel. On X11 systems, the classic bitmap editor edits XBM files pixel by pixel.
• Convert with ImageMagick: magick arrow.xbm arrow.png, or magick logo.png -resize 32x32 logo.xbm the other way (convert in ImageMagick 6). A colour image is reduced to black and white; add -threshold 50% and adjust the percentage to choose where the cut falls.
• Convert with Netpbm: xbmtopbm arrow.xbm > arrow.pbm and pbmtoxbm arrow.pbm > arrow.xbm.
• In Python: Pillow reads and writes XBM, including the hotspot: Image.open("arrow.xbm").info["hotspot"] gives (0, 3) for the example above.
• Use it in C: #include "arrow.xbm" and pass arrow_bits, arrow_width and arrow_height to XCreateBitmapFromData, or to a display library on a microcontroller. Check the library's bit order first: some expect the most significant bit first.

• The picture looks scrambled in groups of 8 pixels. The bit order is reversed: the reader or the display library expects the most significant bit first. Reverse the bits in each byte, or convert with a tool rather than by hand.
• The image comes out inverted. Some programs draw 1 as white. Invert it (magick in.xbm -negate out.xbm) or swap the colours where it's drawn.
• A C++ compiler rejects the file. ImageMagick and Netpbm write static char, and in C++ a value such as 0xFF doesn't fit a char that is signed, which g++ reports as a narrowing error. Change the type to unsigned char.
• Two XBM files clash when included together. They share a name prefix, often because both were saved under the same file name. Rename the #define constants and the array.
• It doesn't show in a browser. No current major browser decodes XBM. Convert it to PNG.

An image viewer reads an XBM file as text and never runs it, so opening one is as safe as the viewer's parser. Bugs have happened: in 2008 Mozilla fixed a low-severity flaw in Firefox 2's XBM decoder that could reveal small pieces of uninitialised memory.

The real care point is the C compiler. When you #include an XBM file, the compiler doesn't know it's meant to be an image: any C code in it is compiled into your program. Only include XBM files you've read or generated yourself.