'\" t
.\"     Title: glTexSubImage2D
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 01/03/2018
.\"    Manual: [FIXME: manual]
.\"    Source: [FIXME: source]
.\"  Language: English
.\"
.TH "GLTEXSUBIMAGE2D" "3G" "01/03/2018" "[FIXME: source]" "[FIXME: manual]"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
glTexSubImage2D, glTextureSubImage2D \- specify a two\-dimensional texture subimage
.SH "C SPECIFICATION"
.HP \w'void\ glTexSubImage2D('u
.BI "void glTexSubImage2D(GLenum\ " "target" ", GLint\ " "level" ", GLint\ " "xoffset" ", GLint\ " "yoffset" ", GLsizei\ " "width" ", GLsizei\ " "height" ", GLenum\ " "format" ", GLenum\ " "type" ", const\ GLvoid\ *\ " "pixels" ");"
.HP \w'void\ glTextureSubImage2D('u
.BI "void glTextureSubImage2D(GLuint\ " "texture" ", GLint\ " "level" ", GLint\ " "xoffset" ", GLint\ " "yoffset" ", GLsizei\ " "width" ", GLsizei\ " "height" ", GLenum\ " "format" ", GLenum\ " "type" ", const\ void\ *" "pixels" ");"
.SH "PARAMETERS"
.PP
\fItarget\fR
.RS 4
Specifies the target to which the texture is bound for
\fBglTexSubImage2D\fR\&. Must be
\fBGL_TEXTURE_2D\fR,
\fBGL_TEXTURE_CUBE_MAP_POSITIVE_X\fR,
\fBGL_TEXTURE_CUBE_MAP_NEGATIVE_X\fR,
\fBGL_TEXTURE_CUBE_MAP_POSITIVE_Y\fR,
\fBGL_TEXTURE_CUBE_MAP_NEGATIVE_Y\fR,
\fBGL_TEXTURE_CUBE_MAP_POSITIVE_Z\fR,
\fBGL_TEXTURE_CUBE_MAP_NEGATIVE_Z\fR, or
\fBGL_TEXTURE_1D_ARRAY\fR\&.
.RE
.PP
\fItexture\fR
.RS 4
Specifies the texture object name for
\fBglTextureSubImage2D\fR\&. The effective target of
\fItexture\fR
must be one of the valid
\fItarget\fR
values above\&.
.RE
.PP
\fIlevel\fR
.RS 4
Specifies the level\-of\-detail number\&. Level 0 is the base image level\&. Level
\fIn\fR
is the
\fIn\fRth mipmap reduction image\&.
.RE
.PP
\fIxoffset\fR
.RS 4
Specifies a texel offset in the x direction within the texture array\&.
.RE
.PP
\fIyoffset\fR
.RS 4
Specifies a texel offset in the y direction within the texture array\&.
.RE
.PP
\fIwidth\fR
.RS 4
Specifies the width of the texture subimage\&.
.RE
.PP
\fIheight\fR
.RS 4
Specifies the height of the texture subimage\&.
.RE
.PP
\fIformat\fR
.RS 4
Specifies the format of the pixel data\&. The following symbolic values are accepted:
\fBGL_RED\fR,
\fBGL_RG\fR,
\fBGL_RGB\fR,
\fBGL_BGR\fR,
\fBGL_RGBA\fR,
\fBGL_BGRA\fR,
\fBGL_DEPTH_COMPONENT\fR, and
\fBGL_STENCIL_INDEX\fR\&.
.RE
.PP
\fItype\fR
.RS 4
Specifies the data type of the pixel data\&. The following symbolic values are accepted:
\fBGL_UNSIGNED_BYTE\fR,
\fBGL_BYTE\fR,
\fBGL_UNSIGNED_SHORT\fR,
\fBGL_SHORT\fR,
\fBGL_UNSIGNED_INT\fR,
\fBGL_INT\fR,
\fBGL_FLOAT\fR,
\fBGL_UNSIGNED_BYTE_3_3_2\fR,
\fBGL_UNSIGNED_BYTE_2_3_3_REV\fR,
\fBGL_UNSIGNED_SHORT_5_6_5\fR,
\fBGL_UNSIGNED_SHORT_5_6_5_REV\fR,
\fBGL_UNSIGNED_SHORT_4_4_4_4\fR,
\fBGL_UNSIGNED_SHORT_4_4_4_4_REV\fR,
\fBGL_UNSIGNED_SHORT_5_5_5_1\fR,
\fBGL_UNSIGNED_SHORT_1_5_5_5_REV\fR,
\fBGL_UNSIGNED_INT_8_8_8_8\fR,
\fBGL_UNSIGNED_INT_8_8_8_8_REV\fR,
\fBGL_UNSIGNED_INT_10_10_10_2\fR, and
\fBGL_UNSIGNED_INT_2_10_10_10_REV\fR\&.
.RE
.PP
\fIpixels\fR
.RS 4
Specifies a pointer to the image data in memory\&.
.RE
.SH "DESCRIPTION"
.PP
Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled\&.
.PP
\fBglTexSubImage2D\fR
and
\fBglTextureSubImage2D\fR
redefine a contiguous subregion of an existing two\-dimensional or one\-dimensional array texture image\&. The texels referenced by
\fIpixels\fR
replace the portion of the existing texture array with x indices
\fIxoffset\fR
and
xoffset + width \- 1, inclusive, and y indices
\fIyoffset\fR
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\&.
.PP
If a non\-zero named buffer object is bound to the
\fBGL_PIXEL_UNPACK_BUFFER\fR
target (see
\fBglBindBuffer\fR()) while a texture image is specified,
\fIpixels\fR
is treated as a byte offset into the buffer object\*(Aqs data store\&.
.SH "NOTES"
.PP
\fBglPixelStore\fR()
modes affect texture images\&.
.PP
\fBglTexSubImage2D\fR
and
\fBglTextureSubImage3D\fR
specify a two\-dimensional subtexture for the current texture unit, specified with
\fBglActiveTexture\fR()\&.
.PP
\fBGL_STENCIL_INDEX\fR
is accepted for
\fIformat\fR
only if the GL version is 4\&.4 or higher\&.
.SH "ERRORS"
.PP
\fBGL_INVALID_ENUM\fR
is generated if
\fItarget\fR
or the effective target of
\fItexture\fR
is not
\fBGL_TEXTURE_2D\fR,
\fBGL_TEXTURE_CUBE_MAP_POSITIVE_X\fR,
\fBGL_TEXTURE_CUBE_MAP_NEGATIVE_X\fR,
\fBGL_TEXTURE_CUBE_MAP_POSITIVE_Y\fR,
\fBGL_TEXTURE_CUBE_MAP_NEGATIVE_Y\fR,
\fBGL_TEXTURE_CUBE_MAP_POSITIVE_Z\fR,
\fBGL_TEXTURE_CUBE_MAP_NEGATIVE_Z\fR, or
\fBGL_TEXTURE_1D_ARRAY\fR\&.
.PP
\fBGL_INVALID_OPERATION\fR
is generated by
\fBglTextureSubImage2D\fR
if
\fItexture\fR
is not the name of an existing texture object\&.
.PP
\fBGL_INVALID_ENUM\fR
is generated if
\fIformat\fR
is not an accepted format constant\&.
.PP
\fBGL_INVALID_ENUM\fR
is generated if
\fItype\fR
is not a type constant\&.
.PP
\fBGL_INVALID_VALUE\fR
is generated if
\fIlevel\fR
is less than 0\&.
.PP
\fBGL_INVALID_VALUE\fR
may be generated if
\fIlevel\fR
is greater than
log 2
\fImax\fR, where
\fImax\fR
is the returned value of
\fBGL_MAX_TEXTURE_SIZE\fR\&.
.PP
\fBGL_INVALID_VALUE\fR
is generated if
xoffset < \- b,
xoffset + width > w \- b,
yoffset < \- b, or
yoffset + height > h \- b, where
w
is the
\fBGL_TEXTURE_WIDTH\fR,
h
is the
\fBGL_TEXTURE_HEIGHT\fR, and
b
is the border width of the texture image being modified\&. Note that
w
and
h
include twice the border width\&.
.PP
\fBGL_INVALID_VALUE\fR
is generated if
\fIwidth\fR
or
\fIheight\fR
is less than 0\&.
.PP
\fBGL_INVALID_OPERATION\fR
is generated if the texture array has not been defined by a previous
\fBglTexImage2D\fR()
operation\&.
.PP
\fBGL_INVALID_OPERATION\fR
is generated if
\fItype\fR
is one of
\fBGL_UNSIGNED_BYTE_3_3_2\fR,
\fBGL_UNSIGNED_BYTE_2_3_3_REV\fR,
\fBGL_UNSIGNED_SHORT_5_6_5\fR, or
\fBGL_UNSIGNED_SHORT_5_6_5_REV\fR
and
\fIformat\fR
is not
\fBGL_RGB\fR\&.
.PP
\fBGL_INVALID_OPERATION\fR
is generated if
\fItype\fR
is one of
\fBGL_UNSIGNED_SHORT_4_4_4_4\fR,
\fBGL_UNSIGNED_SHORT_4_4_4_4_REV\fR,
\fBGL_UNSIGNED_SHORT_5_5_5_1\fR,
\fBGL_UNSIGNED_SHORT_1_5_5_5_REV\fR,
\fBGL_UNSIGNED_INT_8_8_8_8\fR,
\fBGL_UNSIGNED_INT_8_8_8_8_REV\fR,
\fBGL_UNSIGNED_INT_10_10_10_2\fR, or
\fBGL_UNSIGNED_INT_2_10_10_10_REV\fR
and
\fIformat\fR
is neither
\fBGL_RGBA\fR
nor
\fBGL_BGRA\fR\&.
.PP
\fBGL_INVALID_OPERATION\fR
is generated if
\fIformat\fR
is
\fBGL_STENCIL_INDEX\fR
and the base internal format is not
\fBGL_STENCIL_INDEX\fR\&.
.PP
\fBGL_INVALID_OPERATION\fR
is generated if a non\-zero buffer object name is bound to the
\fBGL_PIXEL_UNPACK_BUFFER\fR
target and the buffer object\*(Aqs data store is currently mapped\&.
.PP
\fBGL_INVALID_OPERATION\fR
is generated if a non\-zero buffer object name is bound to the
\fBGL_PIXEL_UNPACK_BUFFER\fR
target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size\&.
.PP
\fBGL_INVALID_OPERATION\fR
is generated if a non\-zero buffer object name is bound to the
\fBGL_PIXEL_UNPACK_BUFFER\fR
target and
\fIpixels\fR
is not evenly divisible into the number of bytes needed to store in memory a datum indicated by
\fItype\fR\&.
.SH "ASSOCIATED GETS"
.PP
\fBglGetTexImage\fR()
.PP
\fBglGet\fR()
with argument
\fBGL_PIXEL_UNPACK_BUFFER_BINDING\fR
.SH "VERSION SUPPORT"
.TS
allbox tab(:);
lB cB s s s s s s s s s s s
lB cB cB cB cB cB cB cB cB cB cB cB cB.
T{

T}:T{
\fBOpenGL Version\fR
T}
T{
\fBFunction / Feature Name\fR
T}:T{
\fB2\&.0\fR
T}:T{
\fB2\&.1\fR
T}:T{
\fB3\&.0\fR
T}:T{
\fB3\&.1\fR
T}:T{
\fB3\&.2\fR
T}:T{
\fB3\&.3\fR
T}:T{
\fB4\&.0\fR
T}:T{
\fB4\&.1\fR
T}:T{
\fB4\&.2\fR
T}:T{
\fB4\&.3\fR
T}:T{
\fB4\&.4\fR
T}:T{
\fB4\&.5\fR
T}
.T&
l c c c c c c c c c c c c
l c c c c c c c c c c c c.
T{
\fBglTexSubImage2D\fR
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}:T{
✔
T}
T{
\fBglTextureSubImage2D\fR
T}:T{
\-
T}:T{
\-
T}:T{
\-
T}:T{
\-
T}:T{
\-
T}:T{
\-
T}:T{
\-
T}:T{
\-
T}:T{
\-
T}:T{
\-
T}:T{
\-
T}:T{
✔
T}
.TE
.sp 1
.SH "SEE ALSO"
.PP
\fBglActiveTexture\fR(),
\fBglCopyTexImage1D\fR(),
\fBglCopyTexImage2D\fR(),
\fBglCopyTexSubImage1D\fR(),
\fBglCopyTexSubImage2D\fR(),
\fBglCopyTexSubImage3D\fR(),
\fBglPixelStore\fR(),
\fBglTexImage1D\fR(),
\fBglTexImage2D\fR(),
\fBglTexImage3D\fR(),
\fBglTexSubImage1D\fR(),
\fBglTexSubImage3D\fR(),
\fBglTexParameter\fR()
.SH "COPYRIGHT"
.PP
Copyright
\(co
1991\-2006 Silicon Graphics, Inc\&. Copyright
\(co
2010\-2014 Khronos Group\&. This document is licensed under the SGI Free Software B License\&. For details, see
\m[blue]\fBhttp://oss\&.sgi\&.com/projects/FreeB/\fR\m[]\&.
.SH "COPYRIGHT"
.br
Copyright \(co 1991-2006 Silicon Graphics, Inc.
.br
Copyright \(co 2010-2014 Khronos Group
.br