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.

DESCRIPTION
     rectre 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.
     IRIS-4D VGX and VGXT require that both |x2-x1+1| and |y2-y1+1| be less
     than 2048.