XCB Image Functions

These are functions used to create and manipulate X images. More...

Data Structures
struct	xcb_image_t
	A structure that describes an xcb_image_t. More...
struct	xcb_shm_segment_info_t
	A structure that stores the informations needed by the MIT Shm Extension. More...
Functions
void	xcb_image_annotate (xcb_image_t *image)
	Update the cached data of an image.
xcb_image_t *	xcb_image_create (uint16_t width, uint16_t height, xcb_image_format_t format, uint8_t xpad, uint8_t depth, uint8_t bpp, uint8_t unit, xcb_image_order_t byte_order, xcb_image_order_t bit_order, void *base, uint32_t bytes, uint8_t *data)
	Create a new image.
xcb_image_t *	xcb_image_create_native (xcb_connection_t *c, uint16_t width, uint16_t height, xcb_image_format_t format, uint8_t depth, void *base, uint32_t bytes, uint8_t *data)
	Create a new image in connection-native format.
void	xcb_image_destroy (xcb_image_t *image)
	Destroy an image.
xcb_image_t *	xcb_image_get (xcb_connection_t *conn, xcb_drawable_t draw, int16_t x, int16_t y, uint16_t width, uint16_t height, uint32_t plane_mask, xcb_image_format_t format)
	Get an image from the X server.
xcb_void_cookie_t	xcb_image_put (xcb_connection_t *conn, xcb_drawable_t draw, xcb_gcontext_t gc, xcb_image_t *image, int16_t x, int16_t y, uint8_t left_pad)
	Put an image onto the X server.
xcb_image_t *	xcb_image_native (xcb_connection_t *c, xcb_image_t *image, int convert)
	Check image for or convert image to native format.
void	xcb_image_put_pixel (xcb_image_t *image, uint32_t x, uint32_t y, uint32_t pixel)
	Put a pixel to an image.
uint32_t	xcb_image_get_pixel (xcb_image_t *image, uint32_t x, uint32_t y)
	Get a pixel from an image.
xcb_image_t *	xcb_image_convert (xcb_image_t *src, xcb_image_t *dst)
	Convert an image to a new format.
xcb_image_t *	xcb_image_subimage (xcb_image_t *image, uint32_t x, uint32_t y, uint32_t width, uint32_t height, void *base, uint32_t bytes, uint8_t *data)
	Extract a subimage of an image.
xcb_image_t *	xcb_image_shm_put (xcb_connection_t *conn, xcb_drawable_t draw, xcb_gcontext_t gc, xcb_image_t *image, xcb_shm_segment_info_t shminfo, int16_t src_x, int16_t src_y, int16_t dest_x, int16_t dest_y, uint16_t src_width, uint16_t src_height, uint8_t send_event)
	Put the data of an xcb_image_t onto a drawable using the MIT Shm Extension.
int	xcb_image_shm_get (xcb_connection_t *conn, xcb_drawable_t draw, xcb_image_t *image, xcb_shm_segment_info_t shminfo, int16_t x, int16_t y, uint32_t plane_mask)
	Read image data into a shared memory xcb_image_t.
xcb_image_t *	xcb_image_create_from_bitmap_data (uint8_t *data, uint32_t width, uint32_t height)
	Create an image from user-supplied bitmap data.
xcb_pixmap_t	xcb_create_pixmap_from_bitmap_data (xcb_connection_t *display, xcb_drawable_t d, uint8_t *data, uint32_t width, uint32_t height, uint32_t depth, uint32_t fg, uint32_t bg, xcb_gcontext_t *gcp)
	Create a pixmap from user-supplied bitmap data.

---

Detailed Description

These are functions used to create and manipulate X images.

The X image format we use is specific to this software, which is probably a bug; it represents an intermediate position between the wire format used by the X GetImage and PutImage requests and standard formats like PBM. An image consists of a header of type xcb_image_t describing the properties of the image, together with a pointer to the image data itself.

X wire images come in three formats. An xy-bitmap is a bit-packed format that will be expanded to a two-color pixmap using a GC when sent over the wire by PutImage. An xy-pixmap is one or more bit-planes, each in the same format as xy-bitmap. A z-pixmap is a more conventional pixmap representation, with each pixel packed into a word. Pixmaps are sent and received over the wire only to/from drawables of their depth.

Each X server defines, for each depth and format, properties of images in that format that are sent and received on the wire. We refer to this as a "native" image for a given X server. It is not uncommon to want to work with non-native images on the client side, or to convert between the native images of different servers.

This library provides several things. Facilities for creating and destroying images are, of course, provided. Wrappers for xcb_get_image() and xcb_put_image() are provided; these utilize the image header to simplify the interface. Routines for getting and putting image pixels are provided: both a generic form that works with arbitrary images, and fastpath forms for some common cases. Conversion routines are provided for X images; these routines have been fairly well optimized for the common cases, and should run fast even on older hardware. A routine analogous to Xlib's XCreate*FromBitmapData() is provided for creating X images from xbm-format data; this routine is in this library only because it is a trivial use case for the library.

---

Function Documentation

xcb_pixmap_t xcb_create_pixmap_from_bitmap_data	(	xcb_connection_t *	display,
		xcb_drawable_t	d,
		uint8_t *	data,
		uint32_t	width,
		uint32_t	height,
		uint32_t	depth,
		uint32_t	fg,
		uint32_t	bg,
		xcb_gcontext_t *	gcp
	)

Create a pixmap from user-supplied bitmap data.

Parameters:

	display	The connection to the X server.
	d	The parent drawable for the pixmap.
	data	Image data in packed bitmap format.
	width	Width in bits of image data.
	height	Height in bits of image data.
	depth	Depth of the desired pixmap.
	fg	Pixel for one-bits of pixmaps with depth larger than one.
	bg	Pixel for zero-bits of pixmaps with depth larger than one.
	gcp	If this pointer is non-null, the GC created to fill in the pixmap is stored here; it will have its foreground and background set to the supplied value. Otherwise, the GC will be freed.

Returns:

The pixmap constructed from the image data, or 0 on error.

This function creates a pixmap from the user-supplied bitmap data. The bitmap data is assumed to be in xbm format (i.e., 8-bit scanline unit, LSB-first, 8-bit pad). If depth is greater than 1, the bitmap will be expanded to a pixmap using the given foreground and background pixels fg and bg.

References xcb_image_t::format, xcb_image_create_from_bitmap_data(), xcb_image_destroy(), xcb_image_native(), and xcb_image_put().

void xcb_image_annotate

(

xcb_image_t *

image

)

Update the cached data of an image.

Parameters:

image

The image.

An image's size and stride, among other things, are cached in its structure. This function recomputes those cached values for the given image.

References xcb_image_t::bpp, xcb_image_t::depth, xcb_image_t::format, xcb_image_t::height, xcb_image_t::scanline_pad, xcb_image_t::size, xcb_image_t::stride, and xcb_image_t::width.

Referenced by xcb_image_create().

xcb_image_t* xcb_image_convert	(	xcb_image_t *	src,
		xcb_image_t *	dst
	)

Convert an image to a new format.

Parameters:

	src	Source image.
	dst	Destination image.

Returns:

The dst image, or null on error.

This function tries to convert the image data of the src image to the format implied by the dst image, overwriting the current destination image data. The source and destination must have the same width, height, and depth. When the source and destination are already the same format, a simple copy is done. Otherwise, when the destination has the same bits-per-pixel/scanline-unit as the source, an optimized copy routine (thanks to Keith Packard) is used for the conversion. Otherwise, the copy is done the slow, slow way with xcb_image_get_pixel() and xcb_image_put_pixel() calls.

References xcb_image_t::bit_order, xcb_image_t::bpp, xcb_image_t::byte_order, xcb_image_t::data, xcb_image_t::depth, xcb_image_t::format, xcb_image_t::height, xcb_image_t::scanline_pad, xcb_image_t::size, xcb_image_t::stride, xcb_image_t::unit, xcb_image_t::width, xcb_image_get_pixel(), and xcb_image_put_pixel().

Referenced by xcb_image_native().

xcb_image_t* xcb_image_create	(	uint16_t	width,
		uint16_t	height,
		xcb_image_format_t	format,
		uint8_t	xpad,
		uint8_t	depth,
		uint8_t	bpp,
		uint8_t	unit,
		xcb_image_order_t	byte_order,
		xcb_image_order_t	bit_order,
		void *	base,
		uint32_t	bytes,
		uint8_t *	data
	)

Create a new image.

Parameters:

	width	The width of the image, in pixels.
	height	The height of the image, in pixels.
	format	The format of the image.
	xpad	The scanline pad of the image.
	depth	The depth of the image.
	bpp	The depth of the image storage.
	unit	The unit of image representation, in bits.
	byte_order	The byte order of the image.
	bit_order	The bit order of the image.
	base	The base address of malloced image data.
	bytes	The size in bytes of the storage pointed to by base. If base == 0 and bytes == ~0 and data == 0 on entry, no storage will be auto-allocated.
	data	The image data. If data is null and bytes != ~0, then an attempt will be made to fill in data; from base if it is non-null (and bytes is large enough), else by mallocing sufficient storage and filling in base.

Returns:

The new image.

This function allocates the memory needed for an xcb_image_t structure with the given properties. See the description of xcb_image_t for details. This function initializes and returns a pointer to the xcb_image_t structure. It may try to allocate or reserve data for the structure, depending on how base, bytes and data are set.

The image must be destroyed with xcb_image_destroy().

References xcb_image_t::base, xcb_image_t::bit_order, xcb_image_t::bpp, xcb_image_t::byte_order, xcb_image_t::data, xcb_image_t::depth, xcb_image_t::format, xcb_image_t::height, xcb_image_t::plane_mask, xcb_image_t::scanline_pad, xcb_image_t::size, xcb_image_t::unit, xcb_image_t::width, and xcb_image_annotate().

Referenced by xcb_image_create_from_bitmap_data(), xcb_image_create_native(), xcb_image_native(), and xcb_image_subimage().

xcb_image_t* xcb_image_create_from_bitmap_data	(	uint8_t *	data,
		uint32_t	width,
		uint32_t	height
	)

Create an image from user-supplied bitmap data.

Parameters:

	data	Image data in packed bitmap format.
	width	Width in bits of image data.
	height	Height in bits of image data.

Returns:

The image constructed from the image data, or 0 on error.

This function creates an image from the user-supplied bitmap data. The bitmap data is assumed to be in xbm format (i.e., 8-bit scanline unit, LSB-first, 8-bit pad).

References xcb_image_create().

Referenced by xcb_create_pixmap_from_bitmap_data().

xcb_image_t* xcb_image_create_native	(	xcb_connection_t *	c,
		uint16_t	width,
		uint16_t	height,
		xcb_image_format_t	format,
		uint8_t	depth,
		void *	base,
		uint32_t	bytes,
		uint8_t *	data
	)

Create a new image in connection-native format.

Parameters:

	c	The connection.
	width	The width of the image, in pixels.
	height	The height of the image, in pixels.
	format	The format of the image.
	depth	The depth of the image.
	base	The base address of malloced image data.
	bytes	The size in bytes of the storage pointed to by base. If base == 0 and bytes == ~0 and data == 0 on entry, no storage will be auto-allocated.
	data	The image data. If data is null and bytes != ~0, then an attempt will be made to fill in data; from base if it is non-null (and bytes is large enough), else by mallocing sufficient storage and filling in base.

Returns:

The new image.

This function calls xcb_image_create() with the given properties, and with the remaining properties chosen according to the "native format" with the given properties on the current connection.

It is usual to use this rather than calling xcb_image_create() directly.

References xcb_image_create().

Referenced by xcb_image_get().

void xcb_image_destroy

(

xcb_image_t *

image

)

Destroy an image.

Parameters:

image

The image to be destroyed.

This function frees the memory associated with the image parameter. If its base pointer is non-null, it frees that also.

References xcb_image_t::base.

Referenced by xcb_create_pixmap_from_bitmap_data(), and xcb_image_native().

xcb_image_t* xcb_image_get	(	xcb_connection_t *	conn,
		xcb_drawable_t	draw,
		int16_t	x,
		int16_t	y,
		uint16_t	width,
		uint16_t	height,
		uint32_t	plane_mask,
		xcb_image_format_t	format
	)

Get an image from the X server.

Parameters:

	conn	The connection to the X server.
	draw	The drawable to get the image from.
	x	The x coordinate in pixels, relative to the origin of the drawable and defining the upper-left corner of the rectangle.
	y	The y coordinate in pixels, relative to the origin of the drawable and defining the upper-left corner of the rectangle.
	width	The width of the subimage in pixels.
	height	The height of the subimage in pixels.
	plane_mask	The plane mask. See the protocol document for details.
	format	The format of the image.

Returns:

The subimage of draw defined by x, y, w, h.

This function returns a new image taken from the given drawable draw. The image will be in connection native format. If the format is xy-bitmap and the plane_mask masks bit planes out, those bit planes will be made part of the returned image anyway, by zero-filling them; this will require a fresh memory allocation and some copying. Otherwise, the resulting image will use the xcb_get_image_reply() record as its backing store.

If a problem occurs, the function returns null.

References xcb_image_t::bit_order, xcb_image_t::data, xcb_image_t::height, xcb_image_t::plane_mask, xcb_image_t::size, xcb_image_t::stride, and xcb_image_create_native().

uint32_t xcb_image_get_pixel	(	xcb_image_t *	image,
		uint32_t	x,
		uint32_t	y
	)

Get a pixel from an image.

Parameters:

	image	The image.
	x	The x coordinate of the pixel.
	y	The y coordinate of the pixel.

Returns:

The pixel value.

This function retrieves a pixel from the given image. The image must contain the x and y coordinates, as no clipping is done. This function honors the plane-mask for xy-pixmap images.

References xcb_image_t::bpp, xcb_image_t::byte_order, xcb_image_t::data, xcb_image_t::format, xcb_image_t::height, xcb_image_t::plane_mask, and xcb_image_t::stride.

Referenced by xcb_image_convert(), and xcb_image_subimage().

xcb_image_t* xcb_image_native	(	xcb_connection_t *	c,
		xcb_image_t *	image,
		int	convert
	)

Check image for or convert image to native format.

Parameters:

	c	The connection to the X server.
	image	The image.
	convert	If 0, just check the image for native format. Otherwise, actually convert it.

Returns:

Null if the image is not in native format and can or will not be converted. Otherwise, the native format image.

Each X display has its own "native format" for images of a given format and depth. This function either checks whether the given image is in native format for the given connection c, or actually tries to convert the image to native format, depending on whether convert is true or false.

When convert is true, and the image is not in native format but can be converted, it will be, and a pointer to the new image will be returned. The image passed in will be unharmed in this case; it is the caller's responsibility to check that the returned pointer is different and to dispose of the old image if desired.

References xcb_image_t::bit_order, xcb_image_t::bpp, xcb_image_t::byte_order, xcb_image_t::depth, xcb_image_t::format, xcb_image_t::height, xcb_image_t::scanline_pad, xcb_image_t::unit, xcb_image_t::width, xcb_image_convert(), xcb_image_create(), and xcb_image_destroy().

Referenced by xcb_create_pixmap_from_bitmap_data(), and xcb_image_shm_put().

xcb_void_cookie_t xcb_image_put	(	xcb_connection_t *	conn,
		xcb_drawable_t	draw,
		xcb_gcontext_t	gc,
		xcb_image_t *	image,
		int16_t	x,
		int16_t	y,
		uint8_t	left_pad
	)

Put an image onto the X server.

Parameters:

	conn	The connection to the X server.
	draw	The draw you get the image from.
	gc	The graphic context.
	image	The image you want to combine with the rectangle.
	x	The x coordinate, which is relative to the origin of the drawable and defines the x coordinate of the upper-left corner of the rectangle.
	y	The y coordinate, which is relative to the origin of the drawable and defines the x coordinate of the upper-left corner of the rectangle.
	left_pad	Notionally shift an xy-bitmap or xy-pixmap image to the right some small amount, for some reason. XXX Not clear this is currently supported correctly.

Returns:

The cookie returned by xcb_put_image().

This function combines an image with a rectangle of the specified drawable draw. The image must be in native format for the connection. The image is drawn at the specified location in the drawable. For the xy-bitmap format, the foreground pixel in gc defines the source for the one bits in the image, and the background pixel defines the source for the zero bits. For xy-pixmap and z-pixmap formats, the depth of the image must match the depth of the drawable; the gc is ignored.

References xcb_image_t::data, xcb_image_t::depth, xcb_image_t::format, xcb_image_t::height, xcb_image_t::size, and xcb_image_t::width.

Referenced by xcb_create_pixmap_from_bitmap_data().

void xcb_image_put_pixel	(	xcb_image_t *	image,
		uint32_t	x,
		uint32_t	y,
		uint32_t	pixel
	)

Put a pixel to an image.

Parameters:

	image	The image.
	x	The x coordinate of the pixel.
	y	The y coordinate of the pixel.
	pixel	The new pixel value.

This function overwrites the pixel in the given image with the specified pixel value (in client format). The image must contain the x and y coordinates, as no clipping is done. This function honors the plane-mask for xy-pixmap images.

References xcb_image_t::bpp, xcb_image_t::byte_order, xcb_image_t::data, xcb_image_t::format, xcb_image_t::height, xcb_image_t::plane_mask, xcb_image_t::stride, and xcb_image_t::width.

Referenced by xcb_image_convert(), and xcb_image_subimage().

int xcb_image_shm_get	(	xcb_connection_t *	conn,
		xcb_drawable_t	draw,
		xcb_image_t *	image,
		xcb_shm_segment_info_t	shminfo,
		int16_t	x,
		int16_t	y,
		uint32_t	plane_mask
	)

Read image data into a shared memory xcb_image_t.

Parameters:

	conn	The connection to the X server.
	draw	The draw you get the image from.
	image	The image you want to combine with the rectangle.
	shminfo	A xcb_shm_segment_info_t structure.
	x	The x coordinate, which are relative to the origin of the drawable and define the upper-left corner of the rectangle.
	y	The y coordinate, which are relative to the origin of the drawable and define the upper-left corner of the rectangle.
	plane_mask	The plane mask.

Returns:

The subimage of draw defined by x, y, w, h.

This function reads image data into a shared memory xcb_image_t where conn is the connection to the X server, draw is the source drawable, image is the destination xcb_image_t, x and y are offsets within the drawable, and plane_mask defines which planes are to be read.

If a problem occurs, the functons returns 0. It returns 1 otherwise.

References xcb_image_t::data, xcb_image_t::format, xcb_image_t::height, xcb_shm_segment_info_t::shmaddr, xcb_shm_segment_info_t::shmseg, and xcb_image_t::width.

xcb_image_t* xcb_image_shm_put	(	xcb_connection_t *	conn,
		xcb_drawable_t	draw,
		xcb_gcontext_t	gc,
		xcb_image_t *	image,
		xcb_shm_segment_info_t	shminfo,
		int16_t	src_x,
		int16_t	src_y,
		int16_t	dest_x,
		int16_t	dest_y,
		uint16_t	src_width,
		uint16_t	src_height,
		uint8_t	send_event
	)

Put the data of an xcb_image_t onto a drawable using the MIT Shm Extension.

Parameters:

	conn	The connection to the X server.
	draw	The draw you get the image from.
	gc	The graphic context.
	image	The image you want to combine with the rectangle.
	shminfo	A xcb_shm_segment_info_t structure.
	src_x	The offset in x from the left edge of the image defined by the xcb_image_t structure.
	src_y	The offset in y from the left edge of the image defined by the xcb_image_t structure.
	dest_x	The x coordinate, which is relative to the origin of the drawable and defines the x coordinate of the upper-left corner of the rectangle.
	dest_y	The y coordinate, which is relative to the origin of the drawable and defines the x coordinate of the upper-left corner of the rectangle.
	src_width	The width of the subimage, in pixels.
	src_height	The height of the subimage, in pixels.
	send_event	Indicates whether or not a completion event should occur when the image write is complete.

Returns:

1 is no problems occurs.

This function combines an image in memory with a shape of the specified drawable. The section of the image defined by the x, y, width, and height arguments is drawn on the specified part of the drawable. If XYBitmap format is used, the depth must be one, or a``BadMatch'' error results. The foreground pixel in the Graphic Context gc defines the source for the one bits in the image, and the background pixel defines the source for the zero bits. For XYPixmap and ZPixmap, the depth must match the depth of the drawable, or a ``BadMatch'' error results.

If a problem occurs, the functons returns 0. Otherwise, it returns 1.

References xcb_image_t::data, xcb_image_t::depth, xcb_image_t::format, xcb_image_t::height, xcb_shm_segment_info_t::shmaddr, xcb_shm_segment_info_t::shmseg, xcb_image_t::width, and xcb_image_native().

xcb_image_t* xcb_image_subimage	(	xcb_image_t *	image,
		uint32_t	x,
		uint32_t	y,
		uint32_t	width,
		uint32_t	height,
		void *	base,
		uint32_t	bytes,
		uint8_t *	data
	)

Extract a subimage of an image.

Parameters:

	image	Source image.
	x	X coordinate of subimage.
	y	Y coordinate of subimage.
	width	Width of subimage.
	height	Height of subimage.
	base	Base of memory allocation.
	bytes	Size of base allocation.
	data	Memory allocation.

Returns:

The subimage, or null on error.

Given an image, this function extracts the subimage at the given coordinates. The requested subimage must be entirely contained in the source image. The resulting image will have the same general image parameters as the source image. The base, bytes, and data arguments are passed to xcb_create_image() unaltered to create the destination image---see its documentation for details.

References xcb_image_t::bit_order, xcb_image_t::bpp, xcb_image_t::byte_order, xcb_image_t::depth, xcb_image_t::format, xcb_image_t::height, xcb_image_t::scanline_pad, xcb_image_t::unit, xcb_image_t::width, xcb_image_create(), xcb_image_get_pixel(), and xcb_image_put_pixel().