XPM

Also Known As: X PixMap

Type Bitmap

Colors Unlimited

Compression Uncompressed

Maximum Image Size NA

Multiple Images Per File Yes

Numerical Format NA

Originator Groupe Bull

Platform X Window

Supporting Applications XPM Library

See Also XBM

Usage
Used to store X Window pixmap information to a disk file.

Comments
XPM is a de facto format only. There is no official standard file format for storing X multibit bitmap data.

Code fragments are available for this format.

Sample images are available for this format.

The XPM (X PixMap) format is the current de facto standard for storing X Window pixmap data to a disk file. This format is supported by many image editors, graphics window managers, and image file converters. (See "For Further Information" later in this article.)

Contents:
File Organization
File Details
For Further Information

XPM is capable of storing black-and-white, gray-scale, or color image data. Hotspot information for cursor bitmaps may also be stored. Although small collections of data, such as icons, are typically associated with XPM files, there is no limit to the size of an image or the number of colors that may be stored in an XPM file.

File Organization

XPM stores image data in the form of ASCII text formatted as a Standard C character string array. This type of format allows XPM files to be edited easily with any text editor, to have comments inserted at any point within the file, to be included as data in C and C++ programs, and to be easily transmitted via electronic mail.

Also, because of its human-readable, plain-text format, XPM does not support any native form of data compression. External compression programs, such as the UNIX compress program, must be used to reduce the physical size of an XPM file.

File Details

The basic syntax of an XPM file is:

/* XPM */
static char * <pixmap_name>[] = {
<Values>
<Colors>
<Pixels>
<Extensions>
};

XPM files always start with the string XPM, delimited by Standard C comment tokens. This is an identifier indicating that the file contains an XPM data structure. Following this identification comment is a Standard C array containing the actual pixmap data in the form of character strings. The data in this array is arranged into four sections: Values, Colors, Pixels, and Extensions.

The <Values> section is similar to an image file format header. It contains values indicating the width and height of the pixmap, the number of colors in the image, the number of characters per pixel, the hotspot coordinates in the image, and a marker indicating whether the XPM file contains an optional extension section. The hotspot values and the extension marker are optional values and need not appear if there is no hotspot or extension section.

The expanded syntax of the <Values> section is shown below:

<width><height><numcolors><cpp> [ <x_hotspot><y_hotspot> ] [ XPMEXT ]

The <Colors> section defines the ASCII characters that represent the pixmap data in the <Pixels> section of this array. There is one string in this section per color in the pixmap. Each string in the <Colors> section may be defined using the following expanded syntax:

<character> { <key> <color> } { <key> <color> }

The <character> is the character(s) used to present a single pixel. The actual number of characters in this field equals the <cpp> value in the <Values> section. The <character> is followed by one or more groups of values. These groups define the type of color(s) each <character> represents.

The <key> indicates the type of color or data represented, and may have one of the following values:

m Mono

s Symbolic name

g4 Four-level gray scale

g Gray scale (more than four levels)

c Color

The <color> is any of the following:

A color name
A # followed by the RGB code in hexadecimal
A % followed by the HSV code in hexadecimal
A symbolic name
The string None, indicating that the pixel is transparent and is part of a masking bitmap rather than a pixmap.

The <Pixels> section contains the actual bitmap data. There is <height> number of strings, each containing <width> number of characters. Each character in a pixel string is a character previously defined in the <Colors> section.

The <Extension> section lets additional string information be stored in the XPM file data. If the XPMEXT marker appears in the <Values> section, then an extension block is found after the <Pixels> section. If there is no marker, then the XPM file extension section does not appear and is said to be empty.

An <Extension> section is composed of one or more sub-sections. Each sub-section may have one of two possible formats. The first format is a single extension composed of only one string:

XPMEXT <extension_name> <extension_data_string>

The second format is a single extension sub-section composed of multiple strings:

XPMEXT <extension_name> <extension_data_string1> 
       <extension_data_string2>

The <Extension> section always ends with the XPMENDEXT marker.

The following is an example of an XPM file containing a bitmap, a hotspot, four bitmap character colors, and an extension section with four sub-sections:

/* XPM */
static char * plaid[] =
{
/* plaid pixmap */
/* width height ncolors chars_per_pixel */
"22 22 4 2 0 0 XPMEXT",
/* colors */
"   c red       m white  s light_color",
"Y  c green     m black  s ines_in_mix",
"+  c yellow    m white  s lines_in_dark ",
"x              m black  s dark_color ",
/* pixels */
"x   x   x x x   x   x x x x x x + x x x x x ",
"  x   x   x   x   x   x x x x x x x x x x x ",
"x   x   x x x   x   x x x x x x + x x x x x ",
"  x   x   x   x   x   x x x x x x x x x x x ",
"x   x   x x x   x   x x x x x x + x x x x x ",
"Y Y Y Y Y x Y Y Y Y Y + x + x + x + x + x + ",
"x   x   x x x   x   x x x x x x + x x x x x ",
"  x   x   x   x   x   x x x x x x x x x x x ",
"x   x   x x x   x   x x x x x x + x x x x x ",
"  x   x   x   x   x   x x x x x x x x x x x ",
"x   x   x x x   x   x x x x x x + x x x x x ",
"          x               x x x Y x x x ",
"          x             x   x   Y   x   x   ",
"          x               x x x Y x x x ",
"          x             x   x   Y   x   x   ",
"          x               x x x Y x x x ",
"x x x x x x x x x x x x x x x x x x x x x x ",
"          x               x x x Y x x x ",
"          x             x   x   Y   x   x   ",
"          x               x x x Y x x x ",
"          x             x   x   Y   x   x   ",
"          x               x x x Y x x x ",
"XPMEXT ext1 data1",
"XPMEXT ext2",
"data2_1",
"data2_2",
"XPMEXT ext3",
"data3",
"XPMEXT",
"data4",
"XPMENDEXT"
};

For Further Information

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

The XPM file format was created by Arnaud Le Hors and Colas Nahaboo of the KOALA Project at Groupe Bull Research. If you have questions or comments about XPM, you can contact:

BULL Research
c/o INRIA
2004 route des Lucoiles
06565 Valbonne Cedex
France
lehors@x.org

You can subscribe to the XPM mailing list by sending an email request to:

xpm-talk-request@sophia.inria.fr

The XPM Library is a collection of Xlib-level functions for the X Window System that read, write, and manipulate XPM data in both files and in memory. The latest version of this library may be obtained by anonymous FTP from:

ftp://avahi.inria.fr/contrib/xpm.tar.Z
ftp://export.lcs.mit.edu

The current version of the XPM library is 3.2g (April 1993).

Other applications capable of generating XPM output include xsnap and pixt, both available via anonymous FTP from:

ftp://avahi.inria.fr/
ftp://ftp.x.org/

A number of software packages included on the CD-ROM also support the conversion of XPM files; see the discussion of FBM, ImageMagick, pbmplus, xli, XLoadimage, and xv in Appendix C, Installation and Setup.

A collection of XPM icons also exists in:

ftp://ftp.x.org/contrib/AIcons/

Type	Bitmap
Colors	Unlimited
Compression	Uncompressed
Maximum Image Size	NA
Multiple Images Per File	Yes
Numerical Format	NA
Originator	Groupe Bull
Platform	X Window
Supporting Applications	XPM Library
See Also	XBM

m	Mono
s	Symbolic name
g4	Four-level gray scale
g	Gray scale (more than four levels)
c	Color