2.2.2. Image Format Functions and Macros

Applications are required to present data to the X server in a format that the server demands. To help simplify applications, most of the work required to convert the data is provided by Xlib (see "Transferring Images between Client and Server" and "Manipulating Images").

The XPixmapFormatValues structure provides an interface to the pixmap format information that is returned at the time of a connection setup. It contains: 


typedef struct {
	int depth;
	int bits_per_pixel;
	int scanline_pad;
} XPixmapFormatValues;

XListPixmapFormats

To obtain the pixmap format information for a given display, use XListPixmapFormats() . 
XPixmapFormatValues *XListPixmapFormats(display, count_return)
      Display *display;
      int *count_return;
display Specifies the connection to the X server.
count_return Returns the number of pixmap formats that are supported by the display.

The XListPixmapFormats() function returns an array of XPixmapFormatValues structures that describe the types of Z format images supported by the specified display. If insufficient memory is available, XListPixmapFormats returns NULL. To free the allocated storage for the XPixmapFormatValues structures, use XFree().

The following lists the C language macros, their corresponding function equivalents that are for other language bindings, and what data they both return for the specified server and screen. These are often used by toolkits as well as by simple applications.

ImageByteOrder

ImageByteOrder(display)

int XImageByteOrder(display)
      Display *display;
display Specifies the connection to the X server.

Both specify the required byte order for images for each scanline unit in XY format (bitmap) or for each pixel value in Z format. The macro or function can return either LSBFirst or MSBFirst .

BitmapUnit

BitmapUnit(display)

int XBitmapUnit(display)
      Display *display;
display Specifies the connection to the X server.

Both return the size of a bitmap's scanline unit in bits. The scanline is calculated in multiples of this value.

BitmapBitOrder

BitmapBitOrder(display)

int XBitmapBitOrder(display)
      Display *display;
display Specifies the connection to the X server.

Within each bitmap unit, the left-most bit in the bitmap as displayed on the screen is either the least-significant or most-significant bit in the unit. This macro or function can return LSBFirst or MSBFirst.

BitmapPad

BitmapPad(display)

int XBitmapPad(display)
      Display *display;
display Specifies the connection to the X server.

Each scanline must be padded to a multiple of bits returned by this macro or function.

DisplayHeight

DisplayHeight(display, screen_number)

int XDisplayHeight(display, screen_number)
      Display *display;
      int screen_number;
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.
Both return an integer that describes the height of the screen in pixels.

DisplayHeightMM

DisplayHeightMM(display, screen_number)

int XDisplayHeightMM(display, screen_number)
      Display *display;
      int screen_number;
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.

Both return the height of the specified screen in millimeters.

DisplayWidth

DisplayWidth(display, screen_number)

int XDisplayWidth(display, screen_number)
      Display *display;
      int screen_number;

display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.

Both return the width of the screen in pixels.

DisplayWidthMM

DisplayWidthMM(display, screen_number)

int XDisplayWidthMM(display, screen_number)
      Display *display;
      int screen_number;
display Specifies the connection to the X server.
screen_number Specifies the appropriate screen number on the host server.

Both return the width of the specified screen in millimeters.

Next: Screen Information Macros
Christophe Tronche, ch@tronche.com