readdisplay(3G) readdisplay(3G)
NAME
readdisplay - reads a rectangular screen region, returning displayed
pixel colors in a packed RGB format.
C SPECIFICATION
long readdisplay(Screencoord x1, Screencoord y1,
Screencoord x2, Screencoord y2,
unsigned long *parray, unsigned long *hints)
PARAMETERS
x1 expects the x screen coordinate of one corner of the rectangle.
y1 expects the y screen coordinate of one corner of the rectangle.
x2 expects the x screen coordinate of the opposite corner of the
rectangle.
y2 expects the y screen coordinate of the opposite corner of the
rectangle.
These coordinates are relative to the lower-left pixel on the
screen, whose coordinates are 0,0. It does not matter whether x1
is greater than or less than x2, nor y1 greater than or less than
y2.
The rectangle specification is inclusive. Thus the rectangle
specified by coordinates 5,10,14,6 is 10 pixels wide and 5 pixels
high.
parray expects the array that is to receive the pixels that are read.
Pixels are returned in packed ABGR format, with red occupying the
lower 8 bits and alpha (if available) occupying the upper 8 bits.
Returned alpha is one (0xff) if the pixel is in color index mode
or if no alpha bitplanes are present. Return order is left-to-
right, then bottom-to-top, i.e.
6 7 8
Page 1
readdisplay(3G) readdisplay(3G)
3 4 5
0 1 2
hints
hints is an unsigned long passed to readdisplay which
serves as a bit mask for enabling the various readdisplay
modifiers delineated in the list of constants below. The
constants are specified by bitwise ORing them, or by
adding them. For example,
readdisplay(0,0,99,99,parray,(RD_FREEZE+RD_ALPHAONE));
blocks graphics while reading the display and returns an
image in which alpha is equal to one.
These modifiers are hints, not directives, and are
therefore ignored by systems that do not support the
requested feature.
The following hints are available:
RD_FREEZE freezes the screen by blocking all graphics
calls until the read is completed. This assures that the
returned data accurately represents what was being
displayed at the time of the call.
If graphics calls are allowed to proceed while readdisplay
is executing, it is possible that the returned data may
not resemble what was displayed at the time of execution,
since drawing commands and commands that affect the
display state ( etc.) can change the displayed data while
it is being read.
RD_ALPHAONE returns all alpha values set to one
(represented as 0xff in the color space of this command).
If not requested, actual alpha values are returned if
alpha planes are installed and the pixel is in RGB mode.
One (0xff) is returned for pixels in color index mode or
if no alpha planes are installed.
RD_IGNORE_PUP ignores the contents of the pop-up
framebuffer.
RD_IGNORE_OVERLAY ignores the contents of the overlay
framebuffer.
Page 2
readdisplay(3G) readdisplay(3G)
RD_IGNORE_UNDERLAY ignores the contents of the underlay
framebuffer.
RD_OFFSCREEN Data read beyond the framebuffer boundary is
returned equal to zero, regardless of the setting of this
hint. Reading beyond the framebuffer boundary may reduce
performance.
DESCRIPTION
readdisplay generates the displayed value of each addressed pixel, taking
into account all display bitplanes and modes except those of the cursor.
The ABGR values returned therefore correspond to the values viewed on the
monitor, with the following exceptions:
1. The returned values are not gamma corrected.
2. The cursor will not appear in the returned data.
3. If either of the hints RD_IGNORE_UNDERLAY, RD_IGNORE_OVERLAY, or
RD_IGNORE_PUP is set, the corresponding framebuffer data will not be
included in the returned data.
FUNCTION RETURN VALUE
readdisplay returns the number of pixels read.
NOTES
This subroutine is available only in immediate mode.
BUGS
On IRIS-4D VGX and VGXT models, readdisplay does not correctly read the
underlay planes when the program is double buffered.
Page 3