16.8 Manipulating Images

Xlib provides several functions that perform basic operations on images. All operations on images are defined using an XImage structure, as defined in X11/Xlib.h. Because the number of different types of image formats can be very large, this hides details of image storage properly from applications.

This section describes the functions for generic operations on images. Manufacturers can provide very fast implementations of these for the formats frequently encountered on their hardware. These functions are neither sufficient nor desirable to use for general image processing. Rather, they are here to provide minimal functions on screen format images. The basic operations for getting and putting images are XGetImage() and XPutImage().

Note that no functions have been defined, as yet, to read and write images to and from disk files.

The XImage structure describes an image as it exists in the client's memory. The user can request that some of the members such as height, width, and xoffset be changed when the image is sent to the server. Note that bytes_per_line in concert with offset can be used to extract a subset of the image. Other members (for example, byte order, bitmap_unit, and so forth) are characteristics of both the image and the server. If these members differ between the image and the server, XPutImage() makes the appropriate conversions. The first byte of the first line of plane n must be located at the address (data + (n * height * bytes_per_line)). For a description of the XImage structure, see "Transferring Images between Client and Server".

To allocate an XImage structure and initialize it with image format values from a display, use XCreateImage().

The basic functions used to get a pixel, set a pixel, create a subimage, and add a constant value to an image are defined in the image object. The functions in this section are really macro invocations of the functions in the image object and are defined in X11/Xutil.h.

To obtain a pixel value in an image, use XGetPixel().

To set a pixel value in an image, use XPutPixel().

To create a subimage, use XSubImage().

To increment each pixel in an image by a constant value, use XAddPixel().

To deallocate the memory allocated in a previous call to XCreateImage(), use XDestroyImage().

Next: Manipulating Bitmaps

Christophe Tronche, ch@tronche.com