- copy pixels in the frame buffer
C SPECIFICATION
PARAMETERS
_param1, _param2 Specify the window coordinates of the
lower left corner of the rectangular
region of pixels to be copied.
_param3, _param4 Specify the dimensions of the rectangular
region of pixels to be copied. Both must
be nonnegative.
_param5 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 rela-
tive 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.
_param1 and _param2 specify the window coordinates of the
lower left corner of the rectangular region to be copied.
_param3 and _param4 specify the dimensions of the rectan-
gular region to be copied. Both _param3 and _param4 must
not be negative.
Several parameters control the processing of the pixel
data while it is being copied. These parameters are set
with three commands: glPixelTransfer, glPixelMap, and
glPixelZoom. This reference page describes the effects on
glCopyPixels of most, but not all, of the parameters spec-
ified by these three commands.
glCopyPixels copies values from each pixel with the lower
left-hand corner at (_param1 + i, _param2 + j) for 0 <= i
< _param3 and 0 <= j < _param4. 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 in
each row.
_param5 specifies whether color, depth, or stencil data is
to be copied. The details of the transfer for each data
type are as follows:
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.
If the GL is in RGBA mode, the red, green,
blue, and alpha components of each pixel
that is read are converted to an internal
floating-point with unspecified precision.
The conversion maps the largest repre-
sentable component value to 1.0, and compo-
nent value 0 to 0.0. The resulting float-
ing-point color values are then multiplied
by GL_c_SCALE and added to GL_c_BIAS, where
c is RED, GREEN, BLUE, and 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 scaled 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.
If the GL_ARB_imaging extension is sup-
ported, the color values may be addition-
ally processed by color-table lookups,
color-matrix transformations, and convolu-
tion filters.
The GL then converts the resulting indices
or RGBA colors to fragments by attaching
the current raster position z coordinate
and texture coordinates to each pixel, then
assigning window coordinates (xr+i,yr+j),
where (xr,yr) is the current raster posi-
tion, and the pixel was the ith pixel in
the jth row. These pixel fragments are
then treated just like the fragments gener-
ated by rasterizing points, lines, or poly-
gons. Texture mapping, fog, and all the
fragment operations are applied before the
fragments are written to the frame buffer.
GL_DEPTH Depth values are read from the depth buffer
and converted directly to an internal
floating-point 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].
frame buffer.
GL_STENCIL Stencil indices are read from the stencil
buffer and converted to an internal fixed-
point 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 neg-
ative, 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 indices are then
written to the stencil buffer such that the
index read from the ith location of the jth
row is written to location (xr+i,yr+j),
where (xr,yr) is the current raster posi-
tion. Only the pixel ownership test, the
scissor test, and the stencil writemask
affect these write operations.
The rasterization described thus far assumes pixel zoom
factors of 1.0. If
glPixelZoom is used to change the x and y pixel zoom fac-
tors, pixels are converted to fragments as follows. If
(xr, yr) is the current raster position, and a given pixel
is in the ith location in the jth row of the source pixel
rectangle, then fragments are generated for pixels whose
centers are in the rectangle with corners at
(xr+zoomxi, yr+zoomyj)
and
(xr+zoomx(i+1), yr+zoomy(j+1))
where zoomx is the value of GL_ZOOM_X and zoomy is the
value of GL_ZOOM_Y.
EXAMPLES
To copy the color pixel in the lower left corner of the
window to the current raster position, use glCopyPixels(0,
0, 1, 1, GL_COLOR);
NOTES
Modes specified by glPixelStore have no effect on the
operation of glCopyPixels.
GL_INVALID_OPERATION is generated if glCopyPixels is exe-
cuted between the execution of glBegin and the correspond-
ing execution of glEnd.
ASSOCIATED GETS
glGet with argument GL_CURRENT_RASTER_POSITION
glGet with argument GL_CURRENT_RASTER_POSITION_VALID
SEE ALSO
glColorTable, glConvolutionFilter1D,
glConvolutionFilter2D, glDepthFunc, glDrawBuffer,
glDrawPixels, glMatrixMode, glPixelMap, glPixelTransfer,
glPixelZoom, glRasterPos, glReadBuffer, glReadPixels,
glSeparableFilter2D, glStencilFunc
1