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 non-negative.
type: Specifies the type of source buffer (color, depth, or stencil). Only the symbolic constant GL_COLOR is allowed.

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 window. Results of copies from outside the window, or from regions of the window that are not exposed, are hardware-dependent and undefined.

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

glCopyPixels copies values from each pixel with the lower left-hand corner at (x+i, y+j) for 0<i≤width and 0≤j<height. This pixel is said to be the ith pixel in the jth row. Pixels are copied in row order from the lowest to the highest row, left to right across each row.

The type argument specifies the type of data to be copied. The only currently allowable value for type is GL_COLOR. Details for this data type are as follows:

GL_COLOR

RGBA colors are read from the buffer currently specified as the read source buffer (see glReadBuffer).

The red, green, blue, and alpha components of each pixel that is read are 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.

If convolution is enabled by calling glEnable with GL_CONVOLUTION_2D_EXT, the rectangle of pixel values being copied will be convolved with the current 2D convolution filter kernel. The behavior of the convolution operation is controlled by the convolution parameters set by glConvolutionParameterEXT. As part of the convolution operation, IVL will also apply the post-convolution scale and bias values (set by calling glPixelTransfer).

Next, if image transformation is enabled, IVL will scale, rotate, and translate the pixel rectangle being copied according to the image transformation parameters set by glImageTransformParameterHP.

Following this, if the post-image transform color table is enabled, pixel values will undergo a table lookup operation. The values in this lookup table are established by calling glColorTableEXT.

The resulting RGBA colors are then converted to fragments by assigning window coordinates (xr+i,yr+j), where (xr,yr) is the current raster position, and the pixel was the ith pixel in the jth row. These pixel fragments are subsequently written to the frame buffer. As pixels are written, they are subjected to the pixel ownership test and, if enabled, the scissor test.

Examples

If all of the pixel transfer operations are disabled, the following command will copy the color pixel in the lower left corner of the window to the current raster position:

   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.

Associated Gets

glGet(GL_CURRENT_RASTER_POSITION) glGet(GL_CURRENT_RASTER_POSITION_VALID)

glCopyPixels

Technical documentation

» Table of Contents

» Glossary

» Index