readRGB(3G)							   readRGB(3G)

NAME    [Toc]    [Back]

     readRGB - gets values of specific pixels

C SPECIFICATION    [Toc]    [Back]

     long readRGB(n, red, green, blue)
     short n;
     RGBvalue red[], green[], blue[];

PARAMETERS    [Toc]    [Back]

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

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

     readRGB 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
     drawmode.

     Thus, to read pixel values	from the overlay bitplanes, for	example,
     simply set	drawmode to OVERDRAW. Use readsource to	specify	the pixel
     source within the current framebuffer (backbuffer,	frontbuffer, or	zbuffer,
 for example) from which both rectread and lrectread take pixel
     values.

     In	RGB 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 RGB mode for	readRGB	to function correctly.





									Page 1






readRGB(3G)							   readRGB(3G)

SEE ALSO    [Toc]    [Back]

     lrectread,	readsource, drawmode

NOTES    [Toc]    [Back]

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

     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.


									PPPPaaaaggggeeee 2222