rectread(3G)rectread(3G)NAME
rectread, lrectread - reads a rectangular array of pixels into CPU memory
C SPECIFICATION
long rectread(x1, y1, x2, y2, parray)
Screencoord x1, y1, x2, y2;
Colorindex parray[];
long lrectread(x1, y1, x2, y2, parray)
Screencoord x1, y1, x2, y2;
unsigned long parray[];
PARAMETERS
x1 expects the x coordinate of the lower-left corner of the
rectangle that you want to read.
y1 expects the y coordinate of the lower-left corner of the
rectangle that you want to read.
x2 expects the x coordinate of the upper-right corner of the
rectangle that you want to read.
y2 expects the y coordinate of the upper-right corner of the
rectangle that you want to read.
parray expects the array to receive the pixels that you want to read.
FUNCTION RETURN VALUE
The returned value of this function is the number of pixels specified in
the rectangular region, regardless of whether the pixels were actually
readable (i.e. on-screen) or not.
DESCRIPTIONrectread and lrectread read the pixel values of a rectangular region of
the screen and write them to the array, parray. The system fills the
elements of parray from left-to-right, then bottom-to-top. All
coordinates are relative to the lower-left corner of the window, not the
screen or viewport.
Pixels are read from the currently active framebuffer, as specified by
drawmode. Thus, to read pixel values from the overlay bitplanes, for
example, simply set drawmode to OVERDRAW. Use readsource to specify the
pixel source within the current framebuffer (backbuffer, frontbuffer, or
z-buffer, for example) from which both rectread and lrectread take pixel
values.
rectread fills an array of 16-bit words, and therefore should be used
only to read color index values. lrectread fills an array of 32-bit
words. Based on the current pixmode, lrectread can return pixels of 1,
2, 4, 8, 12, 16, 24, or 32 bits each. Use lrectread to read packed RGB
or RGBA values, color index values, or z values.
Page 1
rectread(3G)rectread(3G)
pixmode greatly affects the operation of lrectread, and has no effect on
the operation of rectread. By default, lrectread returns 32-bit pixels
in the format used by cpack. Different pixel sizes, framebuffer shifts,
scan patterns through the framebuffer, and offsets through memory, can
all be specified using pixmode
rectread and lrectread leave the current character position
unpredictable.
SEE ALSO
cpack, drawmode, lrectwrite, pixmode, readsource
NOTES
These routines are available only in immediate mode.
On IRIS-4D GT and GTX models, returned bits that do not correspond to
valid bitplanes are undefined. Other models return zero in these bits.
On IRIS-4D GT, GTX, XS, XS24, XZ, Elan, Extreme and VGX models, rectread
performance will suffer if x2 - x1 + 1 is odd, or if parray is not 32-bit
word aligned.
Due to the write-back nature of the R4000 cache, sproc/m_fork processes
should avoid accesses to cache lines (128 Bytes) to which a pixel read is
currently in progress.
The size of the array passed to lrectread is limited to the size of the
screen.
BUGS
On IRIS-4D GT and GTX models, when reading pixels from the PUPMODE
planes, the returned bits are shifted up by two bits.
IRIS-4D VGX and VGXT require that both |x2-x1+1| and |y2-y1+1| be less
than 2048.
Page 2
