XGetSubImage()XGetSubImage()NameXGetSubImage – copy a rectangle in drawable to a location within the
pre-existing image.
Synopsis
XImage *XGetSubImage(display, drawable, x, y, width, height,
plane_mask, format, dest_image, dest_x, dest_y)
Display *display;
Drawable drawable;
int x, y;
unsigned int width, height;
unsigned long plane_mask;
int format;
XImage *dest_image;
int dest_x, dest_y;
Arguments
display Specifies a connection to an X server; returned from
XOpenDisplay().
drawable Specifies the drawable from which the rectangle is to be
copied.
x Specify the x and y coordinates of the upper-left corner of
y the rectangle, relative to the origin of the drawable.
width Specify the width and height in pixels of the subimage taken.
height
plane_mask
Specifies which planes of the drawable are transferred to the
image.
format Specifies the format for the image. Either XYPixmap or
ZPixmap.
dest_image
Specifies the destination image.
dest_x Specify the x and y coordinates of the destination rectan‐
dest_y gle's upper-left corner, relative to the image's origin.
Returns
The same image specified by dest_image.
DescriptionXGetSubImage() updates the dest_image with the specified subimage in
the same manner as XGetImage(), except that it does not create the
image or necessarily fill the entire image. If format is XYPixmap, the
function transmits only the bit planes you specify in plane_mask. If
format is ZPixmap, the function transmits as zero the bits in all
planes not specified in plane_mask. The function performs no range
checking on the values in plane_mask and ignores extraneous bits.
The depth of the destination XImage structure must be the same as that
of the drawable. Otherwise, a BadMatch error is generated. If the
specified subimage does not fit at the specified location on the desti‐
nation image, the right and bottom edges are clipped. If the drawable
is a window, the window must be mapped or held in backing store, and it
must be the case that, if there were no inferiors or overlapping win‐
dows, the specified rectangle of the window would be fully visible on
the screen. Otherwise, a BadMatch error is generated.
If the window has a backing store, the backing store contents are
returned for regions of the window that are obscured by noninferior
windows. Otherwise, the return contents of such obscured regions are
undefined. Also undefined are the returned contents of visible regions
of inferiors of different depth than the specified window.
XSubImage() extracts a subimage from an image, instead of from a draw‐
able like XGetSubImage().
If a problem occurs, XGetSubImage() returns NULL.
For more information on images, see Volume One, Chapter 6, Drawing
Graphics and Text.
Errors
BadDrawable
BadGC
BadMatch Depth of dest_image is not the same as depth of drawable.
BadValue
See AlsoXImageByteOrder(), XAddPixel(), XCreateImage(), XDestroyImage(), XGe‐
tImage(), XGetPixel(), XPutImage(), XPutPixel(), XSubImage().
Xlib - Images XGetSubImage()