XReadDisplayQueryExtension(3X11)

     NAME
          XReadDisplayQueryExtension, XReadDisplayQueryVersion,
          XReadDisplay, XShmCreateReadDisplayBuf,
          XShmReadDisplayRects, XShmDestroyReadDisplayBuf - X
          readdisplay functions

     SYNTAX
          #include <X11/extensions/readdisplay.h>

          Bool XReadDisplayQueryExtension (
               Display *dpy,
               int *event_basep,
               int *error_basep);

          Status XReadDisplayQueryVersion (
               Display *dpy,
               int *major_versionp,
               int *minor_versionp);

          XImage *XReadDisplay (
               Display *dpy,
               Window src,
               int x,
               int y,
               unsigned int w,
               unsigned int h,
               unsigned long hints,
               unsigned long *hints_return);

          ShmReadDisplayBuf *XShmCreateReadDisplayBuf (
               Display *dpy,
               char *data,
               XShmSegmentInfo *shminfo,
               int  width,
               int  height);

          Status XShmReadDisplayRects (
               Display *dpy,
               Window src,
               XRectangle *pRects,
               int  nRects,
               ShmReadDisplayBuf *shmbuf,
               int  dstx,
               int  dsty,
               unsigned long  hints,
               unsigned long *hints_return );

          void XShmDestroyReadDisplayBuf (
               ShmReadDisplayBuf *shmbuf);

     ARGUMENTS
          dpy       Specifies the connection to the X server.
          src       Specifies the window from whose screen you want to
                    read data.

          x
          y
          w
          h         Specify the area of the screen you want to read
                    data from.

          hints     Specifies hints used by the server in reading the
                    screen.  The server is free to ignore any and all
                    of these.

          hints_return
                    If non-NULL, returns the hints the server actually
                    used.

          data      Pointer to a shared memory buffer. It can be NULL
                    if the shared memory buffer has not been allocated
                    yet.

          shminfo   Pointer to a shared memory segment. (See MIT X
                    Shared Memory extension)

          height    Specifies the size of the shared memory buffer.

          pRects    Specifies a list of rectangles to identify areas
                    of the screen you want to read from.

          nRects    Specifies the number of rectangles in the list.

          shmbuf    Pointer to a shared memory buffer destination for
                    the data.

          dstx
          dsty      Specify the location in the shared memory buffer
                    where the data is to be copied.


     DESCRIPTION
          This man page describes the X11 Read Display Extension,
          version 1.0 and version 1.1.  Version 1.0 does not support
          the shared memory functions.  This extension allows client
          programs to read device independent image information from
          the screen.

          XReadDisplay returns a pointer to an XImage structure
          containing 32 bit pixel values for the information in the
          specified box on the screen.  The XImage is in ZPixmap
          format, with 8 bits per color component.  The high 8 bits of
          the pixel value are defined to be zero unless otherwise
          specified by the hints.  Any pixels which can not be read
          (either because they are off-screen, or because of layering
          considerations) are defined to be zero.

          To use the shared memory version of ReadDisplay the user
          should create a shared memory buffer using
          XShmCreateReadDisplayBuf().  The returned value is a
          descriptor for the shared memory buffer.  After the buffer
          is created the shared memory segment must be created and
          attached using shmget(2) and shmat(2).  The next step for
          the application is to tell the X Server to attach the shared
          memory segment. To do so, you should use XShmAttach() (from
          the MIT Shared Memory extension).

          To use X ReadDisplay with a shared memory buffer the
          application has to call XShmReadDisplayRects() passing a
          rectangle list of the area on the screen that is to be
          captured.  The data will be returned in the shared memory
          buffer.  The format of the returned data is the same as for
          the non-shared memory version.

          When finished using the shared memory buffer, it should be
          freed by calling XShmDestroyReadDisplayBuf().



     PREDEFINED VALUES
          XRD_READ_ALPHA
               tells the server to read alpha planes into the upper 8
               bits of the pixel value.

          XRD_IGNORE_NORMAL_LAYER
               tells the server to ignore windows in the normal layer.
               This is the layer the root window is in.

          XRD_TRANSPARENT
               tells the server to ignore pixels that are transparent,
               and read the color value of underlying pixels.
               Normally, transparent pixels are returned as if they
               were visible.

          XRD_READ_POINTER
               tells the server to include the mouse pointer in the
               returned image.

          The following hints apply for layered systems.  Pixels from
          windows that are in ignored layers should be treated as if
          they were transparent.  If an underlying pixel is
          nonexistent (as in the case of a window obscuring one in a
          higher layer), the pixel value is defined to be zero.


          XRD_IGNORE_LAYER_0
          XRD_IGNORE_LAYER_1
          XRD_IGNORE_LAYER_2
          XRD_IGNORE_LAYER_3
          XRD_IGNORE_LAYER_4
          XRD_IGNORE_LAYER_5
          XRD_IGNORE_LAYER_6
          XRD_IGNORE_LAYER_7
          XRD_IGNORE_LAYER_MINUS_1
          XRD_IGNORE_LAYER_MINUS_2
          XRD_IGNORE_LAYER_MINUS_3
          XRD_IGNORE_LAYER_MINUS_4
          XRD_IGNORE_LAYER_MINUS_5
          XRD_IGNORE_LAYER_MINUS_6
          XRD_IGNORE_LAYER_MINUS_7
               These hints tell the server to ignore windows in the
               specified layer.

          Note:  the following hints are a superset of the above hints
          in the case where there are layers beyond the range -7 to
          +7.

          XRD_IGNORE_POSITIVE_LAYERS
               tells the server to ignore windows in all layers above
               layer zero.

          XRD_IGNORE_NEGATIVE_LAYERS
               tells the server to ignore windows in all layers below
               layer zero.