217 lines
6.8 KiB
Plaintext
217 lines
6.8 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 texsubima
|
||
|
|
.ds Xs 33804 8 texsubimage2d.gl
|
||
|
|
.TH GLTEXSUBIMAGE2D 3G
|
||
|
|
.SH NAME
|
||
|
|
.B "glTexSubImage2D
|
||
|
|
\- specify a two-dimensional texture subimage
|
||
|
|
|
||
|
|
.SH C SPECIFICATION
|
||
|
|
void \f3glTexSubImage2D\fP(
|
||
|
|
GLenum \fItarget\fP,
|
||
|
|
.nf
|
||
|
|
.ta \w'\f3void \fPglTexSubImage2D( 'u
|
||
|
|
GLint \fIlevel\fP,
|
||
|
|
GLint \fIxoffset\fP,
|
||
|
|
GLint \fIyoffset\fP,
|
||
|
|
GLsizei \fIwidth\fP,
|
||
|
|
GLsizei \fIheight\fP,
|
||
|
|
GLenum \fIformat\fP,
|
||
|
|
GLenum \fItype\fP,
|
||
|
|
const GLvoid \fI*pixels\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
|
||
|
|
\f2width\fP
|
||
|
|
Specifies the width of the texture subimage.
|
||
|
|
.TP
|
||
|
|
\f2height\fP
|
||
|
|
Specifies the height of the texture subimage.
|
||
|
|
.TP
|
||
|
|
\f2format\fP
|
||
|
|
Specifies the of the pixel data.
|
||
|
|
The following symbolic values are accepted:
|
||
|
|
\%\f3GL_COLOR_INDEX\fP,
|
||
|
|
\%\f3GL_RED\fP,
|
||
|
|
\%\f3GL_GREEN\fP,
|
||
|
|
\%\f3GL_BLUE\fP,
|
||
|
|
\%\f3GL_ALPHA\fP,
|
||
|
|
\%\f3GL_RGB\fP,
|
||
|
|
\%\f3GL_BGR\fP,
|
||
|
|
\%\f3GL_RGBA\fP,
|
||
|
|
\%\f3GL_BGRA\fP,
|
||
|
|
\%\f3GL_LUMINANCE\fP, and
|
||
|
|
\%\f3GL_LUMINANCE_ALPHA\fP.
|
||
|
|
.TP
|
||
|
|
\f2type\fP
|
||
|
|
Specifies the data type of the pixel data.
|
||
|
|
The following symbolic values are accepted:
|
||
|
|
\%\f3GL_UNSIGNED_BYTE\fP,
|
||
|
|
\%\f3GL_BYTE\fP,
|
||
|
|
\%\f3GL_BITMAP\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT\fP,
|
||
|
|
\%\f3GL_SHORT\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT\fP,
|
||
|
|
\%\f3GL_INT\fP,
|
||
|
|
\%\f3GL_FLOAT\fP,
|
||
|
|
\%\f3GL_UNSIGNED_BYTE_3_3_2\fP,
|
||
|
|
\%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_6_5\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_8_8_8_8\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_10_10_10_2\fP, and
|
||
|
|
\%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP.
|
||
|
|
.TP
|
||
|
|
\f2pixels\fP
|
||
|
|
Specifies a pointer to the image data in memory.
|
||
|
|
.SH DESCRIPTION
|
||
|
|
Texturing maps a portion of a specified texture image
|
||
|
|
onto each graphical primitive for which texturing is enabled.
|
||
|
|
To enable and disable two-dimensional texturing, call \%\f3glEnable\fP
|
||
|
|
and \%\f3glDisable\fP with argument \%\f3GL_TEXTURE_2D\fP.
|
||
|
|
.P
|
||
|
|
\%\f3glTexSubImage2D\fP redefines a contiguous subregion of an existing two-dimensional
|
||
|
|
texture image.
|
||
|
|
The texels referenced by \f2pixels\fP replace the portion of the
|
||
|
|
existing texture array with x indices \f2xoffset\fP and $"xoffset"~+~"width"~-~1$,
|
||
|
|
inclusive,
|
||
|
|
and y indices \f2yoffset\fP and $"yoffset"~+~"height"~-~1$, inclusive.
|
||
|
|
This region may not include any texels outside the range of 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.
|
||
|
|
.SH NOTES
|
||
|
|
\%\f3glTexSubImage2D\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
|
||
|
|
Formats \%\f3GL_BGR\fP, and \%\f3GL_BGRA\fP and types
|
||
|
|
\%\f3GL_UNSIGNED_BYTE_3_3_2\fP,
|
||
|
|
\%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_6_5\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_8_8_8_8\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_10_10_10_2\fP, and
|
||
|
|
\%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP are available only if the GL version
|
||
|
|
is 1.2 or greater.
|
||
|
|
.P
|
||
|
|
When the \%\f3GL_ARB_multitexture\fP extension is supported, \%\f3glTexSubImage2D\fP
|
||
|
|
specifies a two-dimensional sub texture for the current texture unit,
|
||
|
|
specified with \%\f3glActiveTextureARB\fP.
|
||
|
|
.P
|
||
|
|
When the \%\f3GL_ARB_imaging\fP extension is supported, the RGBA components
|
||
|
|
specified in \f2pixels\fP 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 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$\f2max\fP,
|
||
|
|
where \f2max\fP is the returned value of \%\f3GL_MAX_TEXTURE_SIZE\fP.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_VALUE\fP is generated if $"xoffset" ~<~ ~-b$,
|
||
|
|
$("xoffset"~+~"width") ~>~ (w~-~b)$,
|
||
|
|
$"yoffset" ~<~ ~-b$, or $("yoffset" ~+~ "height") ~>~ (h~-~b)$,
|
||
|
|
where $w$ is the \%\f3GL_TEXTURE_WIDTH\fP,
|
||
|
|
$h$ is the \%\f3GL_TEXTURE_HEIGHT\fP, and $b$ is the border width
|
||
|
|
of the texture image being modified.
|
||
|
|
Note that $w$ and $h$ include twice the border width.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_VALUE\fP is generated if \f2width\fP or \f2height\fP is less than 0.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_ENUM\fP is generated if \f2format\fP is not an accepted
|
||
|
|
constant.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_ENUM\fP is generated if \f2type\fP is not a type constant.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_ENUM\fP is generated if \f2type\fP is \%\f3GL_BITMAP\fP and
|
||
|
|
\f2format\fP is not \%\f3GL_COLOR_INDEX\fP.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glTexSubImage2D\fP is executed
|
||
|
|
between the execution of \%\f3glBegin\fP and the corresponding
|
||
|
|
execution of \%\f3glEnd\fP.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \f2type\fP is one of
|
||
|
|
\%\f3GL_UNSIGNED_BYTE_3_3_2\fP,
|
||
|
|
\%\f3GL_UNSIGNED_BYTE_2_3_3_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_6_5\fP, or
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_6_5_REV\fP
|
||
|
|
and \f2format\fP is not \%\f3GL_RGB\fP.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \f2type\fP is one of
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_4_4_4_4\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_4_4_4_4_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_5_5_5_1\fP,
|
||
|
|
\%\f3GL_UNSIGNED_SHORT_1_5_5_5_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_8_8_8_8\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_8_8_8_8_REV\fP,
|
||
|
|
\%\f3GL_UNSIGNED_INT_10_10_10_2\fP, or
|
||
|
|
\%\f3GL_UNSIGNED_INT_2_10_10_10_REV\fP
|
||
|
|
and \f2format\fP is neither \%\f3GL_RGBA\fP nor \%\f3GL_BGRA\fP.
|
||
|
|
.SH ASSOCIATED GETS
|
||
|
|
\%\f3glGetTexImage\fP
|
||
|
|
.br
|
||
|
|
\%\f3glIsEnabled\fP with argument \%\f3GL_TEXTURE_2D\fP
|
||
|
|
.SH SEE ALSO
|
||
|
|
\%\f3glActiveTextureARB(3G)\fP,
|
||
|
|
\%\f3glCopyTexImage1D(3G)\fP,
|
||
|
|
\%\f3glCopyTexImage2D(3G)\fP,
|
||
|
|
\%\f3glCopyTexSubImage1D(3G)\fP,
|
||
|
|
\%\f3glCopyTexSubImage2D(3G)\fP,
|
||
|
|
\%\f3glCopyTexSubImage3D(3G)\fP,
|
||
|
|
\%\f3glDrawPixels(3G)\fP,
|
||
|
|
\%\f3glPixelStore(3G)\fP,
|
||
|
|
\%\f3glPixelTransfer(3G)\fP,
|
||
|
|
\%\f3glTexEnv(3G)\fP,
|
||
|
|
\%\f3glTexGen(3G)\fP,
|
||
|
|
\%\f3glTexImage1D(3G)\fP,
|
||
|
|
\%\f3glTexImage2D(3G)\fP,
|
||
|
|
\%\f3glTexImage3D(3G)\fP,
|
||
|
|
\%\f3glTexSubImage1D(3G)\fP,
|
||
|
|
\%\f3glTexSubImage3D(3G)\fP,
|
||
|
|
\%\f3glTexParameter(3G)\fP
|
||
|
|
|