XREADDISPLAY(3X11) X Version 11 (Release 6) XREADDISPLAY(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.
Page 1 (printed 7/20/06)
XREADDISPLAY(3X11) X Version 11 (Release 6) XREADDISPLAY(3X11)
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
Page 2 (printed 7/20/06)
XREADDISPLAY(3X11) X Version 11 (Release 6) XREADDISPLAY(3X11)
(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
Page 3 (printed 7/20/06)
XREADDISPLAY(3X11) X Version 11 (Release 6) XREADDISPLAY(3X11)
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.
Page 4 (printed 7/20/06)
