readRG(3G)

NAME
     readRG - gets values of specific pixels

FORTRAN 77 SPECIFICATION
     integer*4 function readRG(n, red, green, blue)
     integer*4 n
     character*(*) red, green, blue

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

     red     expects the array in which the pixel red values will be stored.

     green   expects the array in which the pixel green values will be stored.

     blue    expects the array in which the pixel blue values will 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, namely, that
     the starting point is not a valid character position.

DESCRIPTION
     readRG attempts to read up to n pixel values from the bitplanes in RGB
     mode.  It reads them into the red, green, and blue arrays starting from
     the current character position along a single scan line (constant y) in
     the direction of increasing x.  readRG returns the number of pixels read,
     which is the number requested if the starting point is a valid character
     position (inside the current viewport).  readRG returns zero if the
     starting point is not a valid character position.  The values of pixels
     read outside of the viewport or screen are undefined.

     readRG 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.

     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.

     In RGB 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 RGB mode for readRG to function correctly.
SEE ALSO
     lrectr, readso, drawmo

NOTES
     readRG 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.

     RGB pixels are written as 24-bit RGB triples. On systems with less than
     the full bitplane configuration, the least significant bits of each R, G,
     and B value are not used when pixels are read from the framebuffer.  This
     means that on 8-bit systems, the least significant 5 bits of each RGB
     value are not used, and on 12 bitplane systems, the least significant 4
     bits are set not used.

     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.