readpixels(3G)							readpixels(3G)

NAME    [Toc]    [Back]

     readpixels	- returns values of specific pixels

C SPECIFICATION    [Toc]    [Back]

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

PARAMETERS    [Toc]    [Back]

     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    [Toc]    [Back]

     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    [Toc]    [Back]

     lrectread,	readsource

NOTES    [Toc]    [Back]

     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.




									Page 1






readpixels(3G)							readpixels(3G)

BUGS    [Toc]    [Back]

     On	IRIS-4D	GT and GTX models, when	reading	pixels from the	PUPMODE
     planes, the returned bits are shifted up by two bits.


									PPPPaaaaggggeeee 2222