xgetimage(3) [hpux man page]
XGetImage() XGetImage() Name XGetImage - place contents of a rectangle from drawable into an image. Synopsis XImage *XGetImage(display, drawable, x, y, width, height, plane_mask, format) Display *display; Drawable drawable; int x, y; unsigned int width, height; unsigned long plane_mask; int format; Arguments display Specifies a connection to an X server; returned from XOpenDisplay(). drawable Specifies the drawable to get the data from. x Specify the x and y coordinates of the upper-left corner of the rectangle, relative to the origin of the drawable. y width Specify the width and height in pixels of the image. height plane_mask Specifies a plane mask that indicates which planes are represented in the image. format Specifies the format for the image. Pass either XYPixmap or ZPixmap. Returns The created image. Description XGetImage() dumps the contents of the specified rectangle, a drawable, into a client-side XImage structure, in the format you specify. Depending on which format you pass to the format argument, the function does the following: o If the format is XYPixmap, the function gets only the bit planes you passed to the plane_mask argument. o If the format is ZPixmap, the function sets to 0 the bits in all planes not specified in the plane_mask argument. The function performs no range checking on the values in plane_mask, and ignores extraneous bits. XGetImage() returns the depth of the image to the depth member of the XImage structure. This depth is as specified when the drawable was created. If the drawable is a pixmap, the specified rectangle must be completely inside the pixmap, or a BadMatch error will occur, and the visual field in the image will be None. If XGetImage() fails, it returns NULL. If the drawable is a window, the window must be viewable, and the specified rectangle must not go off the edge of the screen. Otherwise, a BadMatch error will occur. If the drawable is a window, the vis- ual argument will return the visual specified when the drawable was created. The returned image will include any visible portions of inferiors contained in the rectangle. The image will not include the cursor. The specified area can include the borders. The returned contents of visible regions of inferiors of different depth than the specified window are undefined. If the window has a backing-store, the backing-store contents are returned for regions of the window that are obscured by noninferior win- dows. Otherwise, the return contents of such obscured regions are undefined. The data in the image structure is stored in the server's natural byte- and bit-order. For more information, see Volume One, Chapter 6, Drawing Graphics and Text. Errors BadDrawable BadMatch See the "Description" section above. BadValue See Also XImageByteOrder(), XAddPixel(), XCreateImage(), XDestroyImage(), XGetPixel(), XGetSubImage(), XPutImage(), XPutPixel(), XSubImage(). Xlib - Images XGetImage()
Check Out this Related Man Page
XGetSubImage() XGetSubImage() Name XGetSubImage - 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 the rectangle, relative to the origin of the drawable. y 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 rectangle's upper-left corner, relative to the image's origin. dest_y Returns The same image specified by dest_image. Description XGetSubImage() 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 destination image, the right and bottom edges are clipped. If the draw- able 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 overlap- ping windows, 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 win- dows. 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 drawable 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 Also XImageByteOrder(), XAddPixel(), XCreateImage(), XDestroyImage(), XGetImage(), XGetPixel(), XPutImage(), XPutPixel(), XSubImage(). Xlib - Images XGetSubImage()