hpux man page for xgetsubimage

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()