glCopyPixels(3G)	       OpenGL Reference		      glCopyPixels(3G)



NAME
     glCopyPixels - copy pixels	in the frame buffer


C SPECIFICATION
     void glCopyPixels(	GLint x,
			GLint y,
			GLsizei	width,
			GLsizei	height,
			GLenum type )


PARAMETERS
     x,	y Specify the window coordinates of the	lower left corner of the
	  rectangular region of	pixels to be copied.

     width, height
	  Specify the dimensions of the	rectangular region of pixels to	be
	  copied.  Both	must be	nonnegative.

     type Specifies whether color values, depth	values,	or stencil values are
	  to be	copied.	 Symbolic constants GL_COLOR, GL_DEPTH,	and GL_STENCIL
	  are accepted.


DESCRIPTION
     glCopyPixels copies a screen-aligned rectangle of pixels from the
     specified frame buffer location to	a region relative to the current
     raster position.  Its operation is	well defined only if the entire	pixel
     source region is within the exposed portion of the	read window associated
     with the current context.	Results	of copies from outside the window, or
     from regions of the window	that are not exposed, are hardware dependent
     and undefined.

     x and y specify the window	coordinates of the lower left corner of	the
     rectangular region	to be copied.  width and height	specify	the dimensions
     of	the rectangular	region to be copied.  width and	height must be non-
     negative.

     Several parameters	control	the processing of the pixel data while it is
     being copied.  These parameters are set with the commands
     glPixelTransfer, glPixelMap, and glPixelZoom.  The	state of
     GL_INTERLACE_SGIX,	controlled by glEnable and glDisable, also affects the
     result of glCopyPixels.  This reference page describes the	effects	on
     glCopyPixels of most, but not all,	of these parameters.  In addition the
     convolution, histogram, and minmax	operations may affect the result of
     glCopyPixels.  See	the reference pages for	glConvolutionFilter2DEXT,
     glHistogramEXT, and glMinmaxEXT for more information.

     glCopyPixels copies values	from each pixel	with lower left-hand corner at
     (x	+ i, y + j) for	0<iglCopyPixels(3G)	       OpenGL Reference		      glCopyPixels(3G)



     lowest to the highest row,	left to	right in each row.

     type specifies whether color, depth, or stencil data is to	be copied.
     The pixels	read from the source buffer are	operated upon in a manner that
     is	dependent on type to generate various fragment values as detailed
     below.  The number	of fragments generated for each	source pixel and the
     assignment	of xdst	and ydst window	coordinates to these fragments are
     common to all types and are as follows.

     If	the current raster position is invalid,	no fragments are generated for
     any of the	source pixels.	Otherwise, let (xr, yr)	be the current raster
     position.	For each source	pixel, fragments with values computed
     according to that pixel are generated for destination pixels whose
     centers are in the	rectangle with corners at
     (xr + i x zoomx, yr + j x interlace x zoomy) and
     (xr + (i +	1) x zoomx,yr +	(j x interlace + 1) x zoomy).  zoomx and zoomy
     are the values of GL_ZOOM_X and GL_ZOOM_Y,	respectively, and interlace is
     1 or 2 depending on whether GL_INTERLACE_SGIX is GL_FALSE or GL_TRUE,
     respectively.  GL_ZOOM_X and GL_ZOOM_Y, initially set to 1.0, are set
     using glPixelZoom;	GL_INTERLACE_SGIX, initially disabled, is controlled
     by	glEnable and glDisable.

     GL_INTERLACE_SGIX is particularly useful when the pixels are copied from
     fields of an interlaced video source.  For	additional discussion of
     GL_INTERLACE_SGIX see the NOTES section of	the reference page for
     glDrawPixels.

     Except for	when type is GL_STENCIL	the generated fragments	are treated
     just like the fragments generated by rasterizing points, lines, or
     polygons.	Texture	mapping, fog, and all the fragment operations are
     applied before the	fragments are written to the frame buffer. When	type
     is	GL_STENCIL then	only the pixel ownership test, the scissor test, and
     the stencil writemask affect the writes to	the stencil buffer.

     GL_COLOR	    Indices or RGBA colors are read from the buffer currently
		    specified as the read source buffer	(see glReadBuffer).
		    If the GL is in color index	mode, each index that is read
		    from this buffer is	converted to a fixed-point format with
		    an unspecified number of bits to the right of the binary
		    point.  Each index is then shifted left by GL_INDEX_SHIFT
		    bits, and added to GL_INDEX_OFFSET.	 If GL_INDEX_SHIFT is
		    negative, the shift	is to the right.  In either case, zero
		    bits fill otherwise	unspecified bit	locations in the
		    result.  If	GL_MAP_COLOR is	true, the index	is replaced
		    with the value that	it references in lookup	table
		    GL_PIXEL_MAP_I_TO_I.  Whether the lookup replacement of
		    the	index is done or not, the integer part of the index is
		    then ANDed with 2b-1, where	b is the number	of bits	in a
		    color index	buffer.






									Page 2






glCopyPixels(3G)	       OpenGL Reference		      glCopyPixels(3G)



		    If the GL is in RGBA mode, each of the red,	green, blue,
		    and	alpha components of each pixel that is read is
		    converted to an internal floating-point format with
		    unspecified	precision.  The	conversion maps	the largest
		    representable component value to 1.0, and component	value
		    zero to 0.0.  The resulting	floating-point color values
		    are	then multiplied	by GL_c_SCALE and added	to GL_c_BIAS,
		    where c is RED, GREEN, BLUE, or ALPHA for the respective
		    color components.  The results are clamped to the range
		    [0,1].  If GL_MAP_COLOR is true, each color	component is
		    multiplied by the size of lookup table
		    GL_PIXEL_MAP_c_TO_c, then replaced by the value that it
		    references in that table.  c is R, G, B, or	A,
		    respectively.

		    The	resulting index	or RGBA	color components, and the
		    current raster position z and texture coordinates are
		    assigned to	each of	the fragments generated	for the	source
		    pixel.

     GL_DEPTH	    Depth values are read from the depth buffer	and converted
		    directly to	an internal floating-point format with
		    unspecified	precision.  The	resulting floating-point depth
		    value is then multiplied by	GL_DEPTH_SCALE and added to
		    GL_DEPTH_BIAS.  The	result is clamped to the range [0,1].

		    The	resulting depth	component, and the current raster
		    position texture coordinates and color or color index are
		    assigned to	each of	the fragments generated	for the	source
		    pixel.

     GL_STENCIL	    Stencil indices are	read from the stencil buffer and
		    converted to an internal fixed-point format	with an
		    unspecified	number of bits to the right of the binary
		    point.  Each fixed-point index is then shifted left	by
		    GL_INDEX_SHIFT bits, and added to GL_INDEX_OFFSET.	If
		    GL_INDEX_SHIFT is negative,	the shift is to	the right.  In
		    either case, zero bits fill	otherwise unspecified bit
		    locations in the result.  If GL_MAP_STENCIL	is true, the
		    index is replaced with the value that it references	in
		    lookup table GL_PIXEL_MAP_S_TO_S.  Whether the lookup
		    replacement	of the index is	done or	not, the integer part
		    of the index is then ANDed with 2b-1, where	b is the
		    number of bits in the stencil buffer.

		    The	resulting stencil value	is assigned to each of the
		    fragments generated	for the	source pixel.

EXAMPLES
     To	copy the color pixel in	the lower left corner of the window to the
     current raster position, use




									Page 3






glCopyPixels(3G)	       OpenGL Reference		      glCopyPixels(3G)



	  glCopyPixels(0, 0, 1,	1, GL_COLOR);


NOTES
     Modes specified by	glPixelStore have no effect on the operation of
     glCopyPixels.

ERRORS
     GL_INVALID_ENUM is	generated if type is not an accepted value.

     GL_INVALID_VALUE is generated if either width or height is	negative.

     GL_INVALID_OPERATION is generated if type is GL_DEPTH and there is	no
     depth buffer.

     GL_INVALID_OPERATION is generated if type is GL_STENCIL and there is no
     stencil buffer.

     GL_INVALID_OPERATION is generated if glCopyPixels is executed between the
     execution of glBegin and the corresponding	execution of glEnd.

ASSOCIATED GETS
     glGet with	argument GL_CURRENT_RASTER_POSITION
     glGet with	argument GL_CURRENT_RASTER_POSITION_VALID
     glGet with	argument GL_INTERLACE_SGIX


MACHINE	DEPENDENCIES
     On	RealityEngine, RealityEngine2, and VTX systems convolution may not be
     used in the following circumstances:

	  1.  When rendering to	pixmaps.

	  2.  When fragment processing (texturing, depth buffering, alpha
	      testing, multisampling, fog) is enabled.

	  3.  When histogramming or minmax is enabled.

	  4.  When either of the pixel zoom factors has	a value	other than 1.0
	      or -1.0.

     In	these cases, glDrawPixels and glCopyPixels report a
     GL_INVALID_OPERATION error	and do not transfer any	pixels.

     Loading a convolution filter with some combinations of pixel transfer
     modes may be unreliable on	InfiniteReality	systems.  Straightforward
     transfers are known to work, though.  The remaining problems will be
     fixed in the next release.

     RealityEngine, RealityEngine2, and	VTX systems cannot copy	pixels from a
     video source (see glXCreateGLXVideoSourceSGIX) when RGBA scale and	bias
     are not 1 and 0, respectively, or when any	of texturing, alpha or depth



									Page 4






glCopyPixels(3G)	       OpenGL Reference		      glCopyPixels(3G)



     testing, pixel mapping, multisampling, convolution, histogram, or minmax
     is	enabled.  A GL_INVALID_OPERATION error will result if any of these
     conditions	is true	when glCopyPixels is executed.

     Performance of glCopyPixels on InfiniteReality systems is expected	to
     increase in a future release.

     The SGIX_interlace	extension is supported only on InfiniteReality systems
     and on RealityEngine, RealityEngine2, and VTX systems.


SEE ALSO
     glConvolutionFilter2DEXT, glDepthFunc, glDrawBuffer, glDrawPixels,
     glEnable, glHistogramEXT, glMinmaxEXT, glPixelMap,	glPixelTransfer,
     glPixelZoom, glRasterPos, glReadBuffer, glReadPixels,
     glSeparableFilter2DEXT, glStencilFunc.







































									Page 5