XBM

Also Known As: X BitMap


Type Bitmap
Colors Mono
Compression None
Maximum Image Size Unlimited
Multiple Images Per File Yes
Numerical Format ASCII
Originator X Consortium
Platform Any supporting X Window System
Supporting Applications BRL-CAD
See Also XPM

Usage
Primarily used for the storage of cursor and icon bitmaps for use in the X graphical user interface.

Comments
XBM is a monochrome bitmap format in which data is stored as a C language data array.

Code fragments are available for this format.

Sample images are available for this format.


Normally, we think of images as data being stored as binary information in a file. In many cases, however, it is more convenient to represent smaller bitmapped images as collections of ASCII data rather than binary data. If such a small bitmapped image is being used by a software application, such as the cursors and icons found in all graphical user interfaces, the images may be stored as an array of ASCII characters, or even as an array of data values stored in the actual software source code.

Contents:
File Organization
File Details
For Further Information

Storing small amounts of image data directly as C language source code is the philosophy behind the XBM (X BitMap) format. Small images that will be compiled into a software program are stored as simple arrays of data values, with one array used per stored image. XBM files are therefore nothing more than C language source files that are read by a compiler, rather than by a graphical display program or bitmap editor, as are most other graphical files.

XBM bitmap data is mostly found in C source header files (with a .h file extension) and in separate XBM bitmap files (with no file extension). Multiple XBM image-data arrays may be stored in a single file, but none of the images may have the same name, or a naming conflict will result.

The XPM (X PixMap) format is similar to XBM. XPM is a cousin of XBM and is capable of storing color bitmap image data and a colormap. XPM is also an ASCII format and is described in the XPM article.

File Organization

XBM files have a height and width, and may define an optional hotspot within the image. The hotspot is used for bitmapped cursors and indicates the absolute position of the cursor on the screen. The hotspot on an arrow cursor is the tip of the arrow, which is usually located at position 0,0 in the bitmap.

In place of the usual image file format header, XBM files have two or four #define statements. The first two #defines specify the height and width of the bitmap in pixels. The second two specify the position of the hotspot within the bitmap, and are not present if no hotspot is defined in the image.

The labels of each #define contain the name of the image. Consider an image that is 8x8 pixels in size, named FOO, with a hotspot at pixel 0,7. This image contains the following #define statements:

#define FOO_width 8
#define FOO_height 8
#define FOO_x_hot 0
#define FOO_y_hot 7

The image data itself is a single line of pixel values stored in a static array. Data representing our FOO image appears as follows:

static unsigned char FOO_bits[] = {
    0x3E, 0x80, 0x00, 0x7C, 0x00, 0x82, 0x41, 0x00};

Because each pixel is only one bit in size, each byte in the array contains the information for eight pixels, with the first pixel in the bitmap (at position 0,0) represented by the high bit of the first byte in the array. If the image width is not a multiple of eight, the extra bits in the last byte of each row are not used and are ignored.

XBM files are found in two variations: the older X10 format and the newer (as of 1986) X11 format. The only difference between these formats is how the pixel data is packed. The X11 flavor stores pixel data as 8-bit BYTEs. The older X10 flavor stores pixel data as 16-bit WORDs. There are no markers separating the rows of image data in either of these formats, and the size of an XBM array is limited only by the compiler and machine using the bitmap.

The X10 XBM is considered obsolete. Make sure that any X software you write is able to read both the XBM X10 and X11 formats, but when you write data, use only the X11 XBM format.

File Details

Following is an example of a 16x16 XBM bitmap stored using both its X10 and X11 variations. Note that each array contains exactly the same data, but is stored using different data word types:

/* XBM X10 format */
#define xlogo16_width 16
#define xlogo16_height 16
static unsigned short xlogo16_bits[] = {
    0x0f80, 0x1e80, 0x3c40, 0x7820, 0x7810, 0xf008, 0xe009, 0xc005,
    0xc002, 0x4007, 0x200f, 0x201e, 0x101e, 0x083c, 0x0478,
    0x02f0};
/* XBM X11 format */
#define xlogo16_width 16
#define xlogo16_height 16
static unsigned char xlogo16_bits[] = {
    0x0f, 0x80, 0x1e, 0x80, 0x3c, 0x40, 0x78, 0x20, 0x78, 0x10,
    0xf0, 0x08, 0xe0, 0x09, 0xc0, 0x05, 0xc0, 0x02, 0x40, 0x07,
    0x20, 0x0f, 0x20, 0x1e, 0x10, 0x1e, 0x08, 0x3c, 0x04, 0x78,
    0x02, 0xf0};

For Further Information

For further information about the XBM format, see the code examples included on the CD-ROM.

The XBM format is part of the X Window System created by the X Consortium. The X11 source code distribution contains many XBM files (in the /bitmaps directory) and C language source code functions (such as XCreateBitmapFromData, XCreatePixmapFromBitmapData, XReadBitmapFile, and XWriteBitmapFile), which operate upon XBM data. The central FTP site for X11 distribution is:

ftp://ftp.x.org/

Other references containing information on XBM include the following:

Gettys, James, and Robert W. Scheiffler, X Window System, Digital Press, 1992.

Gettys, James, Robert W. Scheiffler, et al. Xlib-C language X Interface, X Consortium Standard, X Version 11, Release 5, First Revision, August 1991.

Nye, Adrian, Xlib Programming Manual, third edition, O'Reilly & Associates, Inc., Sebastopol, CA, 1992.



Copyright © 1996, 1994 O'Reilly & Associates, Inc. All Rights Reserved.