readpixels(3G)

NAME
     readpixels - returns values of specific pixels

C SPECIFICATION
     long readpixels(n, colors)
     short n;
     Colorindex colors[];

PARAMETERS
     n        expects the number of pixels to be read by the function.

     colors   expects the array in which the pixel values are to be stored.

FUNCTION RETURN VALUE
     The returned value of this function is the number of pixels actually
     read.  A returned function value of 0 indicates an error, that the
     starting point is not a valid character position.

DESCRIPTION
     readpixels attempts to read up to n pixel values from the bitplanes in
     color map mode.  It reads them into the array colors starting from the
     current character position along a single scan line (constant y) in the
     direction of increasing x.  readpixels returns the number of pixels read,
     which is the number requested if the starting point is a valid character
     position (inside the current viewport).  readpixels returns zero if the
     starting point is not a valid character position. The values of pixels
     read outside the viewport or the screen are undefined.  readpixels
     updates the current character position to one pixel to the right of the
     last one read; the current character position is undefined if the new
     position is outside the viewport.

     In double buffer mode, only the back buffer is read by default. On
     machines that support it, you can use readsource to control which buffer
     is read.

     The system must be in color map mode for readpixels to function
     correctly.

SEE ALSO
     lrectread, readsource

NOTES
     readpixels should not be used in new development.  Rather, pixels should
     be read using the high-performance lrectread command.

     This routine is available only in immediate mode.

     The upper bits of a color value (an element of the colors array) are
     undefined.  You can write this information to the frame buffer without
     problems.  However, if you intend to interpret this data, be sure you
     mask out the upper bits.
BUGS
     On IRIS-4D GT and GTX models, when reading pixels from the PUPMODE
     planes, the returned bits are shifted up by two bits.