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.

DESCRIPTION
     rectread 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.
     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.