[Copyright status: this file is in the public domain.] When using PutImage and/or GetImage requests (see lx_PutImage and lx_GetImage in core.txt), there is a need for image data - for PutImage, the application produces it and the server consumes it; for GetImage, the other way around. In most of X, the client chooses things such as byte order and the server adapts; images reverse this, with the server choosing and the client adapting. (I don't understand why this was done.) There are some values involved here which are part of the data received by the client at connection setup. They can be retrieved with functions described below. They are: image-byte-order The byte order used for multi-byte pixels, either LX_IBO_LSBFirst or LX_IBO_MSBFirst. These correspond, respectively, to what are usually called little-endian and big-endian. For example, a 16-bit pixel value 0x1234 would be serialized as 0x34 0x12 if the image-byte-order is LSBFirst. bitmap-bit-order Bit order used for bitmap data. This can be LX_BBO_LeastSignificant or LX_BBO_MostSignificant and indicates whether the first bit of a scanline unit is most or least significant within its scanline unit. bitmap-scanline-unit This is 8, 16, or 32. It is the number of bits in each packing unit for bitmap data. bitmap-scanline-pad This is 8, 16, or 32. It is the number of bits to which each row of bitmap data is padded. It is never smaller than bitmap-scanline-unit. Z format images are easier to explain. Conceptually, to generate a Z format image from a rectangle of pixels, the rows are processed top to bottom (in order of increasing Y coordinate), with each row processed left to right (in order of increasing X coordinate). Each pixel is appended to the data. At the end of each row, padding may be appended, depending on the format's scanline pad, the pixel size, and the width of the rectangle. Once all pixels have been appended (including the padding, if any, at the end of the last row), the data is sent. For formats with bpp 16 or 32, each pixel is serialized into 2 or 4 bytes to be appended according to the connection's image-byte-order. If the depth of the data is less than the bpp, the pixel values are in the least-significant bits, with the most-significant bits being unspecified when sending and ignored when receiving. For formats with bpp 4, in the words of the protocol document, "the order of nibbles in the byte is the same as the image byte-order". Padding bits are chosen arbitrarily by the sender, so they contain nothing of use. They typically will contain zeros, but this is not promised. Z format for depth 1 is a special case; it is processed as a bitmap. A bitmap is just like a depth-1 Z format image, as described above, except that some values come from different places. The pixels are processed in the same order, but pixels (which for this case are each a single bit) are packed into units of bitmap-scanline-unit bits each, in the order specified by the bitmap-bit-order, with each row padded to a bitmap-scanline-pad boundary. Each scanline unit is then serialized into bytes (according to the image-byte-order, if it's multi-byte). XYPixmap with depth greater than 1 is just a stack of bitmaps, one per bit-plane, from most to least significant (with nothing inserted between planes). There is never any ambiguity about which pixmap format to use, because, as the protocol document puts it, the table of formats ... contains one entry for each depth value. The entry describes the Z format used to represent images of that depth. An entry for a depth is included if any screen supports that depth, and all screens supporting that depth must support only that Z format for that depth. Relevant calls: lx_bitmap_bit_order ------------------- LX_BITMAP_BIT_ORDER lx_bitmap_bit_order(LX_CONN *c) Returns the bitmap-bit-order value. This can be LX_BBO_LeastSignificant or LX_BBO_MostSignificant. Returns LX_BBO_Error on error. lx_image_byte_order ------------------- LX_IMAGE_BYTE_ORDER lx_image_byte_order(LX_CONN *c) Returns the image-byte-order value. This can be LX_IBO_LSBFirst or LX_IBO_MSBFirst. Returns LX_IBO_Error on error. lx_num_formats -------------- int lx_num_formats(LX_CONN *c) Returns the number of pixmap formats. Each pixmap format is characterized by a depth, a bits-per-pixel value, and a scanline-pad value; see lx_pixmap_depth, lx_pixmap_bpp, and lx_pixmap_pad. Returns -1 on error. lx_pixmap_bpp ------------- int lx_pixmap_bpp(LX_CONN *c, int n) Returns the bits-per-pixel value for pixmap format n. Returns -1 on error. lx_pixmap_depth --------------- int lx_pixmap_depth(LX_CONN *c, int n) Returns the depth for pixmap format n. Returns -1 on error. lx_pixmap_pad ------------- int lx_pixmap_pad(LX_CONN *c, int n) Returns the scanline-pad value for pixmap format n. Returns -1 on error. lx_bitmap_scanline_pad ---------------------- int lx_bitmap_scanline_pad(LX_CONN *c) Returns the bitmap-scanline-pad value. Returns -1 on error. lx_bitmap_scanline_unit ---------------- int lx_bitmap_scanline_unit(LX_CONN *c) Returns the bitmap-scanline-unit value. Returns -1 on error.