152 lines
5.0 KiB
Plaintext
152 lines
5.0 KiB
Plaintext
'\" te
|
|
'\"! tbl|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 copytexsu
|
|
.ds Xs 21640 7 copytexsubimage2d.gl
|
|
.TH GLCOPYTEXSUBIMAGE2D 3G
|
|
.SH NAME
|
|
.B "glCopyTexSubImage2D
|
|
\- copy a two-dimensional texture subimage
|
|
|
|
.SH C SPECIFICATION
|
|
void \f3glCopyTexSubImage2D\fP(
|
|
GLenum \fItarget\fP,
|
|
.nf
|
|
.ta \w'\f3void \fPglCopyTexSubImage2D( 'u
|
|
GLint \fIlevel\fP,
|
|
GLint \fIxoffset\fP,
|
|
GLint \fIyoffset\fP,
|
|
GLint \fIx\fP,
|
|
GLint \fIy\fP,
|
|
GLsizei \fIwidth\fP,
|
|
GLsizei \fIheight\fP )
|
|
.fi
|
|
|
|
.EQ
|
|
delim $$
|
|
.EN
|
|
.SH PARAMETERS
|
|
.TP \w'\fIxoffset\fP\ \ 'u
|
|
\f2target\fP
|
|
Specifies the target texture.
|
|
Must be \%\f3GL_TEXTURE_2D\fP.
|
|
.TP
|
|
\f2level\fP
|
|
Specifies the level-of-detail number.
|
|
Level 0 is the base image level.
|
|
Level \f2n\fP is the \f2n\fPth mipmap reduction image.
|
|
.TP
|
|
\f2xoffset\fP
|
|
Specifies a texel offset in the x direction within the texture array.
|
|
.TP
|
|
\f2yoffset\fP
|
|
Specifies a texel offset in the y direction within the texture array.
|
|
.TP
|
|
\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
|
|
Specifies the width of the texture subimage.
|
|
.TP
|
|
\f2height\fP
|
|
Specifies the height of the texture subimage.
|
|
.SH DESCRIPTION
|
|
\%\f3glCopyTexSubImage2D\fP replaces a rectangular portion of a two-dimensional
|
|
texture image with pixels from the current \%\f3GL_READ_BUFFER\fP (rather
|
|
than from main memory, as is the case for \%\f3glTexSubImage2D\fP).
|
|
.P
|
|
The screen-aligned pixel rectangle with lower left corner at
|
|
(\f2x\fP,\ \f2y\fP) and with
|
|
width \f2width\fP and height \f2height\fP replaces the portion of the
|
|
texture array with x indices \f2xoffset\fP through \f2xoffset\fP$~+~$\f2width\fP$~-~$1,
|
|
inclusive, and y indices \f2yoffset\fP through \f2yoffset\fP$~+~$\f2height\fP$~-~$1,
|
|
inclusive, at the mipmap level specified by \f2level\fP.
|
|
.P
|
|
The pixels in the rectangle are processed exactly as if
|
|
\%\f3glCopyPixels\fP had been called, but the process stops just before
|
|
final conversion.
|
|
At this point, all pixel component values are clamped to the range [0,\ 1]
|
|
and then converted to the texture's internal for storage in the texel
|
|
array.
|
|
.P
|
|
The destination rectangle in the texture array may not include any texels
|
|
outside the texture array as it was originally specified.
|
|
It is not an error to specify a subtexture with zero width or height, but
|
|
such a specification has no effect.
|
|
.P
|
|
If any of the pixels within the specified rectangle of the current
|
|
\%\f3GL_READ_BUFFER\fP are outside the read window associated with the current
|
|
rendering context, then the values obtained for those pixels are undefined.
|
|
.P
|
|
No change is made to the \f2internalformat\fP, \f2width\fP,
|
|
\f2height\fP, or \f2border\fP parameters of the specified texture
|
|
array or to texel values outside the specified subregion.
|
|
.SH NOTES
|
|
\%\f3glCopyTexSubImage2D\fP is available only if the GL version is 1.1 or greater.
|
|
.P
|
|
Texturing has no effect in color index mode.
|
|
.P
|
|
\%\f3glPixelStore\fP and \%\f3glPixelTransfer\fP modes affect texture images
|
|
in exactly the way they affect \%\f3glDrawPixels\fP.
|
|
.P
|
|
When the \%\f3GL_ARB_imaging\fP extension is supported, the RGBA components
|
|
read from the framebuffer may be processed by the imaging pipeline. See
|
|
\%\f3glTexImage1D\fP for specific details.
|
|
.SH ERRORS
|
|
\%\f3GL_INVALID_ENUM\fP is generated if \f2target\fP is not \%\f3GL_TEXTURE_2D\fP.
|
|
.P
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if the texture array has not
|
|
been defined by a previous \%\f3glTexImage2D\fP or \%\f3glCopyTexImage2D\fP operation.
|
|
.P
|
|
\%\f3GL_INVALID_VALUE\fP is generated if \f2level\fP is less than 0.
|
|
.P
|
|
\%\f3GL_INVALID_VALUE\fP may be generated if \f2level\fP is greater
|
|
than $log sub 2 max$,
|
|
where $max$ is the returned value of \%\f3GL_MAX_TEXTURE_SIZE\fP.
|
|
.P
|
|
\%\f3GL_INVALID_VALUE\fP is generated if \f2x\fP$ ~<~ ~-b$ or if
|
|
\f2y\fP$ ~<~ ~-b$,
|
|
where $b$ is the border width of the texture array.
|
|
.P
|
|
\%\f3GL_INVALID_VALUE\fP is generated if $"xoffset" ~<~ -b$,
|
|
(\f2xoffset\fP$~+~$\f2width\fP)$~>~(w ~-~b)$,
|
|
\f2yoffset\fP$~<~ ~-b$, or
|
|
(\f2yoffset\fP$~+~$\f2height\fP)$~>~(h ~-~b)$,
|
|
where $w$ is the \%\f3GL_TEXTURE_WIDTH\fP,
|
|
$h$ is the \%\f3GL_TEXTURE_HEIGHT\fP,
|
|
and $b$ is the \%\f3GL_TEXTURE_BORDER\fP
|
|
of the texture image being modified.
|
|
Note that $w$ and $h$
|
|
include twice the border width.
|
|
.P
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glCopyTexSubImage2D\fP is executed
|
|
between the execution of \%\f3glBegin\fP and the corresponding
|
|
execution of \%\f3glEnd\fP.
|
|
.SH ASSOCIATED GETS
|
|
\%\f3glGetTexImage\fP
|
|
.br
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_TEXTURE_2D\fP
|
|
.SH SEE ALSO
|
|
\%\f3glCopyPixels(3G)\fP,
|
|
\%\f3glCopyTexImage1D(3G)\fP,
|
|
\%\f3glCopyTexImage2D(3G)\fP,
|
|
\%\f3glCopyTexSubImage1D(3G)\fP,
|
|
\%\f3glCopyTexSubImage3D(3G)\fP,
|
|
\%\f3glPixelStore(3G)\fP,
|
|
\%\f3glPixelTransfer(3G)\fP,
|
|
\%\f3glReadBuffer(3G)\fP,
|
|
\%\f3glTexEnv(3G)\fP,
|
|
\%\f3glTexGen(3G)\fP,
|
|
\%\f3glTexImage1D(3G)\fP,
|
|
\%\f3glTexImage2D(3G)\fP,
|
|
\%\f3glTexImage3D(3G)\fP,
|
|
\%\f3glTexParameter(3G)\fP,
|
|
\%\f3glTexSubImage1D(3G)\fP,
|
|
\%\f3glTexSubImage2D(3G)\fP,
|
|
\%\f3glTexSubImage3D(3G)\fP
|