readpi(3G)

NAME
     readpi - returns values of specific pixels

FORTRAN SPECIFICATION
     integer*4 function readpi(n, colors)
     integer*4 n
     integer*2 colors(n)

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
     readpi 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.  readpi returns the number of pixels read, which is the
     number requested if the starting point is a valid character position
     (inside the current viewport).  readpi 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.  readpi 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 readso to control which buffer is
     read.

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

SEE ALSO
     lrectr, readso

NOTES
     readpi should not be used in new development.  Rather, pixels should be
     read using the high-performance lrectr 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.