hpux man page for xgetimage

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