readdi(3G)readdi(3G)NAMEreaddi - reads a rectangular screen region, returning displayed pixel
colors in a packed RGB format.
FORTRAN 77 SPECIFICATION
subroutine readdi(x1, y1, x2, y2, newx,
integer*4 x1, y1, x2, y2, hints
integer*4 parray(*)
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
readdi(3G)readdi(3G)
3 4 5
0 1 2
hints
hints is an unsigned long passed to readdi which serves as
a bit mask for enabling the various readdi modifiers
delineated in the list of constants below. The constants
are specified by bitwise ORing them, or by adding them.
For example,
readdi(0,0,99,99,parray,(RDFREZ + RDALPH))
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:
RDFREZ 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 readdi 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.
RDALPH 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.
RDIGPU ignores the contents of the pop-up framebuffer.
RDIGOV ignores the contents of the overlay framebuffer.
RDIGOV ignores the contents of the underlay framebuffer.
Page 2
readdi(3G)readdi(3G)
RDOFFS 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.
DESCRIPTIONreaddi 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 RDIGUN, RDIGOV, or RDIGPU is set, the
corresponding framebuffer data will not be included in the returned
data.
FUNCTION RETURN VALUEreaddi returns the number of pixels read.
NOTES
This subroutine is available only in immediate mode.
BUGS
On IRIS-4D VGX and VGXT models, readdi does not correctly read the
underlay planes when the program is double buffered.
Page 3
