fglCopyPixels(3G) OpenGL Reference fglCopyPixels(3G)NAMEfglCopyPixels - copy pixels in the frame buffer
FORTRAN SPECIFICATION
SUBROUTINE fglCopyPixels( INTEGER*4 x,
INTEGER*4 y,
INTEGER*4 width,
INTEGER*4 height,
INTEGER*4 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.
DESCRIPTIONfglCopyPixels 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. Both width and height 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:
fglPixelTransfer, fglPixelMap, and fglPixelZoom. The state of
GL_INTERLACE_SGIX and GL_INTERLACE_READ_INGR, controlled by fglEnable and
fglDisable, also affect the result of fglCopyPixels. This reference page
describes the effects on fglCopyPixels of most, but not all, of these
parameters. In addition the convolution, histogram, and minmax
operations may affect the result of fglCopyPixels. See the reference
pages for fglConvolutionFilter2DEXT, fglHistogramEXT, and fglMinmaxEXT
for more information.
fglCopyPixels 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
Page 1
fglCopyPixels(3G) OpenGL Reference fglCopyPixels(3G)
row order from the lowest to the highest row, left to right in each row.
type specifies whether color, depth, or stencil data is to be copied.
The details of the transfer for each data type are as follows:
GL_COLOR Indices or RGBA colors are read from the buffer currently
specified as the read source buffer (see fglReadBuffer).
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
b
then ANDed with 2 -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 format with unspecified precision.
The conversion maps the largest representable component
value to 1.0, and component value 0 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, 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 supported, the color
values may be additionally processed by color-table
lookups, color-matrix transformations, and convolution
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 (x + i,y + j), where
r r
(x ,y ) is the current raster position, and the pixel was
r r
the ith pixel in the jth row. These pixel fragments are
then 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.
Page 2
fglCopyPixels(3G) OpenGL Reference fglCopyPixels(3G)
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 GL then converts the resulting depth components to
fragments by attaching the current raster position color
or color index and texture coordinates to each pixel, then
assigning window coordinates (x + i,y + j), where
r r
(x ,y ) is the current raster position, and the pixel was
r r
the ith pixel in the jth row. These pixel fragments are
then 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.
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
b
of the index is then ANDed with 2 -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 (x + i,y + j), where (x ,y )
r r r r
is the current raster position. 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
fglPixelZoom is used to change the x and y pixel zoom factors, pixels are
converted to fragments as follows. If (x , y ) is the current raster
r r
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
(x + zoom i, y + zoom j)
r x r y
and
(x + zoom (i + 1), y + zoom (j + 1))
r x r y
Page 3
fglCopyPixels(3G) OpenGL Reference fglCopyPixels(3G)
where zoom is the value of GL_ZOOM_X and zoom is the value of
x y
GL_ZOOM_Y.
When GL_INTERLACE_READ_INGR is enabled, every other row of the source
pixel rectangle is read. The height of the source pixel rectangle is
equivalent to 2xheight. Only rows (y+0,y+2,...) are read and affected by
pixel transfer and copy operations.
When GL_INTERLACE_SGIX is enabled, every other row of the destination
pixel rectangle is modified. The height of the destination pixel
rectangle is equivalent to 2xGL_ZOOM_Yxheight. Only rows (y +0,y +2,...)
r r
of the destination are modified by the copy.
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 fglPixelStore have no effect on the operation of
fglCopyPixels.
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 fglCopyPixels is executed between
the execution of fglBegin and the corresponding execution of fglEnd.
ASSOCIATED GETS
fglGet with argument GL_CURRENT_RASTER_POSITION
fglGet with argument GL_CURRENT_RASTER_POSITION_VALID
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.
Page 4
fglCopyPixels(3G) OpenGL Reference fglCopyPixels(3G)
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, fglDrawPixels and fglCopyPixels report a
GL_INVALID_OPERATION error and do not transfer any pixels.
RealityEngine, RealityEngine2, and VTX systems cannot copy pixels from a
video source (see fglXCreateGLXVideoSourceSGIX) when RGBA scale and bias
are not 1 and 0, respectively, or when any of texturing, alpha or depth
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 fglCopyPixels is executed.
The SGIX_interlace extension is supported only on InfiniteReality
systems, on RealityEngine, RealityEngine2, and VTX systems, on Octane2
VPro systems, and on O2 systems.
The INGR_interlace_read extension is supported only on Octane2 VPro
systems, and on O2 systems.
SEE ALSO
fglColorTable, fglConvolutionFilter1D, fglConvolutionFilter2D,
fglDepthFunc, fglDrawBuffer, fglDrawPixels, fglMatrixMode, fglPixelMap,
fglPixelTransfer, fglPixelZoom, fglRasterPos, fglReadBuffer,
fglReadPixels, fglSeparableFilter2D, fglStencilFunc
Page 5
