250 lines
8.8 KiB
Plaintext
250 lines
8.8 KiB
Plaintext
|
'\" e
|
||
|
'\"! eqn | mmdoc
|
||
|
'\"macro stdmacro
|
||
|
.ds Vn Version 1.2
|
||
|
.ds Dt 24 September 1999
|
||
|
.ds Re Release 1.2.1
|
||
|
.ds Dp Jan 14 18:30
|
||
|
.ds Dm 01 copypixel
|
||
|
.ds Xs 10756 11 copypixels.gl
|
||
|
.TH GLCOPYPIXELS 3G
|
||
|
.SH NAME
|
||
|
.B "glCopyPixels
|
||
|
\- copy pixels in the frame buffer
|
||
|
|
||
|
.SH C SPECIFICATION
|
||
|
void \f3glCopyPixels\fP(
|
||
|
GLint \fIx\fP,
|
||
|
.nf
|
||
|
.ta \w'\f3void \fPglCopyPixels( 'u
|
||
|
GLint \fIy\fP,
|
||
|
GLsizei \fIwidth\fP,
|
||
|
GLsizei \fIheight\fP,
|
||
|
GLenum \fItype\fP )
|
||
|
.fi
|
||
|
|
||
|
.EQ
|
||
|
delim $$
|
||
|
.EN
|
||
|
.SH PARAMETERS
|
||
|
.TP \w'\f2x\fP\ \f2y\fP\ \ 'u
|
||
|
\f2x\fP, \f2y\fP
|
||
|
Specify the window coordinates of the lower left corner
|
||
|
of the rectangular region of pixels to be copied.
|
||
|
.TP
|
||
|
\f2width\fP, \f2height\fP
|
||
|
Specify the dimensions of the rectangular region of pixels to be copied.
|
||
|
Both must be nonnegative.
|
||
|
.TP
|
||
|
\f2type\fP
|
||
|
Specifies whether color values,
|
||
|
depth values,
|
||
|
or stencil values are to be copied.
|
||
|
Symbolic constants
|
||
|
\%\f3GL_COLOR\fP,
|
||
|
\%\f3GL_DEPTH\fP,
|
||
|
and \%\f3GL_STENCIL\fP are accepted.
|
||
|
.SH DESCRIPTION
|
||
|
\%\f3glCopyPixels\fP 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.
|
||
|
.P
|
||
|
\f2x\fP and \f2y\fP specify the window coordinates of
|
||
|
the lower left corner of the rectangular region to be copied.
|
||
|
\f2width\fP and \f2height\fP specify the dimensions of the
|
||
|
rectangular region to be copied.
|
||
|
Both \f2width\fP and \f2height\fP must not be negative.
|
||
|
.P
|
||
|
Several parameters control the processing of the pixel data
|
||
|
while it is being copied.
|
||
|
These parameters are set with three commands:
|
||
|
\%\f3glPixelTransfer\fP,
|
||
|
\%\f3glPixelMap\fP, and
|
||
|
\%\f3glPixelZoom\fP.
|
||
|
This reference page describes the effects on \%\f3glCopyPixels\fP of most,
|
||
|
but not all, of the parameters specified by these three commands.
|
||
|
.P
|
||
|
\%\f3glCopyPixels\fP copies values from each pixel with the lower left-hand corner at
|
||
|
(\f2x\fP + $i$, \f2y\fP + $j$) for 0 \(<= $i$ < \f2width\fP
|
||
|
and 0 \(<= $j$ < \f2height\fP.
|
||
|
This pixel is said to be the $i$th pixel in the $j$th row.
|
||
|
Pixels are copied in row order from the lowest to the highest row,
|
||
|
left to right in each row.
|
||
|
.P
|
||
|
\f2type\fP specifies whether color, depth, or stencil data is to be copied.
|
||
|
The details of the transfer for each data type are as follows:
|
||
|
.TP 15
|
||
|
\%\f3GL_COLOR\fP
|
||
|
Indices or RGBA colors are read from the buffer currently specified as the
|
||
|
read source buffer (see \%\f3glReadBuffer\fP).
|
||
|
If the GL is in color index mode,
|
||
|
each index that is read from this buffer is converted
|
||
|
to a fixed-point with an unspecified
|
||
|
number of bits to the right of the binary point.
|
||
|
Each index is then shifted left by \%\f3GL_INDEX_SHIFT\fP bits,
|
||
|
and added to \%\f3GL_INDEX_OFFSET\fP.
|
||
|
If \%\f3GL_INDEX_SHIFT\fP is negative,
|
||
|
the shift is to the right.
|
||
|
In either case, zero bits fill otherwise unspecified bit locations in the
|
||
|
result.
|
||
|
If \%\f3GL_MAP_COLOR\fP is true,
|
||
|
the index is replaced with the value that it references in lookup table
|
||
|
\%\f3GL_PIXEL_MAP_I_TO_I\fP.
|
||
|
Whether the lookup replacement of the index is done or not,
|
||
|
the integer part of the index is then ANDed with $2 sup b -1$,
|
||
|
where $b$ is the number of bits in a color index buffer.
|
||
|
.IP
|
||
|
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 representable component value to 1.0,
|
||
|
and component value 0 to 0.0.
|
||
|
The resulting floating-point color values are then multiplied
|
||
|
by \%\f3GL_c_SCALE\fP and added to \%\f3GL_c_BIAS\fP,
|
||
|
where \f2c\fP is RED, GREEN, BLUE, and ALPHA
|
||
|
for the respective color components.
|
||
|
The results are clamped to the range [0,1].
|
||
|
If \%\f3GL_MAP_COLOR\fP is true,
|
||
|
each color component is scaled by the size of lookup table
|
||
|
\%\f3GL_PIXEL_MAP_c_TO_c\fP,
|
||
|
then replaced by the value that it references in that table.
|
||
|
\f2c\fP is R, G, B, or A.
|
||
|
.IP
|
||
|
If the \%\f3GL_ARB_imaging\fP extension is supported, the color values may
|
||
|
be
|
||
|
additionally processed by color-table lookups, color-matrix
|
||
|
transformations, and convolution filters.
|
||
|
.IP
|
||
|
The GL then converts the resulting indices or RGBA colors to fragments
|
||
|
by attaching the current raster position \f2z\fP coordinate and
|
||
|
texture coordinates to each pixel,
|
||
|
then assigning window coordinates
|
||
|
($x sub r ~+~ i , y sub r ~+~ j$),
|
||
|
where ($x sub r , y sub r$) is the current raster position,
|
||
|
and the pixel was the $i$th pixel in the $j$th 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.
|
||
|
.TP
|
||
|
\%\f3GL_DEPTH\fP
|
||
|
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 \%\f3GL_DEPTH_SCALE\fP and added to \%\f3GL_DEPTH_BIAS\fP.
|
||
|
The result is clamped to the range [0,1].
|
||
|
.IP
|
||
|
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 sub r ~+~ i , y sub r ~+~ j$),
|
||
|
where ($x sub r , y sub r$) is the current raster position,
|
||
|
and the pixel was the $i$th pixel in the $j$th 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.
|
||
|
.TP
|
||
|
\%\f3GL_STENCIL\fP
|
||
|
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 \%\f3GL_INDEX_SHIFT\fP bits,
|
||
|
and added to \%\f3GL_INDEX_OFFSET\fP.
|
||
|
If \%\f3GL_INDEX_SHIFT\fP is negative,
|
||
|
the shift is to the right.
|
||
|
In either case, zero bits fill otherwise unspecified bit locations in the
|
||
|
result.
|
||
|
If \%\f3GL_MAP_STENCIL\fP is true,
|
||
|
the index is replaced with the value that it references in lookup table
|
||
|
\%\f3GL_PIXEL_MAP_S_TO_S\fP.
|
||
|
Whether the lookup replacement of the index is done or not,
|
||
|
the integer part of the index is then ANDed with $2 sup b -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 $i$th location of the $j$th row
|
||
|
is written to location
|
||
|
($x sub r ~+~ i , y sub r ~+~ j$),
|
||
|
where ($x sub r , y sub r$) is the current raster position.
|
||
|
Only the pixel ownership test,
|
||
|
the scissor test,
|
||
|
and the stencil writemask affect these write operations.
|
||
|
.P
|
||
|
The rasterization described thus far assumes pixel zoom factors of 1.0.
|
||
|
If
|
||
|
.br
|
||
|
\%\f3glPixelZoom\fP is used to change the $x$ and $y$ pixel zoom factors,
|
||
|
pixels are converted to fragments as follows.
|
||
|
If ($x sub r$, $y sub r$) is the current raster position,
|
||
|
and a given pixel is in the $i$th location in the $j$th row of the source
|
||
|
pixel rectangle,
|
||
|
then fragments are generated for pixels whose centers are in the rectangle
|
||
|
with corners at
|
||
|
.P
|
||
|
.ce
|
||
|
($x sub r ~+~ zoom sub x^ i$, $y sub r ~+~ zoom sub y^j$)
|
||
|
.sp .5
|
||
|
.ce
|
||
|
and
|
||
|
.sp .5
|
||
|
.ce
|
||
|
($x sub r ~+~ zoom sub x^ (i ~+~ 1)$, $y sub r ~+~ zoom sub y^ ( j ~+~ 1 )$)
|
||
|
.P
|
||
|
where $zoom sub x$ is the value of \%\f3GL_ZOOM_X\fP and
|
||
|
$zoom sub y$ is the value of \%\f3GL_ZOOM_Y\fP.
|
||
|
.SH EXAMPLES
|
||
|
To copy the color pixel in the lower left corner of the window to the current raster position,
|
||
|
use
|
||
|
.Ex
|
||
|
glCopyPixels(0, 0, 1, 1, \%\f3GL_COLOR\fP);
|
||
|
.En
|
||
|
.SH NOTES
|
||
|
Modes specified by \%\f3glPixelStore\fP have no effect on the operation
|
||
|
of \%\f3glCopyPixels\fP.
|
||
|
.SH ERRORS
|
||
|
\%\f3GL_INVALID_ENUM\fP is generated if \f2type\fP is not an accepted value.
|
||
|
.P
|
||
|
\%\f3GL_INVALID_VALUE\fP is generated if either \f2width\fP or \f2height\fP is negative.
|
||
|
.P
|
||
|
\%\f3GL_INVALID_OPERATION\fP is generated if \f2type\fP is \%\f3GL_DEPTH\fP
|
||
|
and there is no depth buffer.
|
||
|
.P
|
||
|
\%\f3GL_INVALID_OPERATION\fP is generated if \f2type\fP is \%\f3GL_STENCIL\fP
|
||
|
and there is no stencil buffer.
|
||
|
.P
|
||
|
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glCopyPixels\fP
|
||
|
is executed between the execution of \%\f3glBegin\fP
|
||
|
and the corresponding execution of \%\f3glEnd\fP.
|
||
|
.SH ASSOCIATED GETS
|
||
|
\%\f3glGet\fP with argument \%\f3GL_CURRENT_RASTER_POSITION\fP
|
||
|
.br
|
||
|
\%\f3glGet\fP with argument \%\f3GL_CURRENT_RASTER_POSITION_VALID\fP
|
||
|
.SH SEE ALSO
|
||
|
\%\f3glColorTable(3G)\fP,
|
||
|
\%\f3glConvolutionFilter1D(3G)\fP,
|
||
|
\%\f3glConvolutionFilter2D(3G)\fP,
|
||
|
\%\f3glDepthFunc(3G)\fP,
|
||
|
\%\f3glDrawBuffer(3G)\fP,
|
||
|
\%\f3glDrawPixels(3G)\fP,
|
||
|
\%\f3glMatrixMode(3G)\fP,
|
||
|
\%\f3glPixelMap(3G)\fP,
|
||
|
\%\f3glPixelTransfer(3G)\fP,
|
||
|
\%\f3glPixelZoom(3G)\fP,
|
||
|
\%\f3glRasterPos(3G)\fP,
|
||
|
\%\f3glReadBuffer(3G)\fP,
|
||
|
\%\f3glReadPixels(3G)\fP,
|
||
|
\%\f3glSeparableFilter2D(3G)\fP,
|
||
|
\%\f3glStencilFunc(3G)\fP
|