rectre(3G)rectre(3G)NAME
rectre, lrectr - reads a rectangular array of pixels into CPU memory
FORTRAN 77 SPECIFICATION
integer*4 rectre(x1, y1, x2, y2, parray)
integer*4 x1, y1, x2, y2
integer*2 parray(*)
integer*4 lrectr(x1, y1, x2, y2, parray)
integer*4 x1, y1, x2, y2
integer*4 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.
Page 1
rectre(3G)rectre(3G)DESCRIPTIONrectre and lrectr 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
drawmo. Thus, to read pixel values from the overlay bitplanes, for
example, simply set drawmo to OVERDR. Use readso to specify the pixel
source within the current framebuffer (backbuffer, frontbuffer, or z-
buffer, for example) from which both rectre and lrectr take pixel values.
rectre fills an array of 16-bit words, and therefore should be used only
to read color index values. lrectr fills an array of 32-bit words.
Based on the current pixmod, lrectr can return pixels of 1, 2, 4, 8, 12,
16, 24, or 32 bits each. Use lrectr to read packed RGB or RGBA values,
color index values, or z values.
pixmod greatly affects the operation of lrectr, and has no effect on the
operation of rectre. By default, lrectr 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 pixmod
rectre and lrectr leave the current character position unpredictable.
SEE ALSO
cpack, drawmo, lrectw, pixmod, readso
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, rectre
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 lrectr 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.
Page 2
rectre(3G)rectre(3G)
IRIS-4D VGX and VGXT require that both |x2-x1+1| and |y2-y1+1| be less
than 2048.
Page 3
