readpixels(3G)readpixels(3G)NAMEreadpixels - 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.
DESCRIPTIONreadpixels 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
NOTESreadpixels 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.
Page 1
readpixels(3G)readpixels(3G)BUGS
On IRIS-4D GT and GTX models, when reading pixels from the PUPMODE
planes, the returned bits are shifted up by two bits.
Page 2
