glTexSubImage2D - OpenGL ES 3.2 Reference Pages

## Name

glTexSubImage2D — specify a two-dimensional texture subimage

## C Specification

`void glTexSubImage2D(` | GLenum target,
| GLint level,
| GLint xoffset,
| GLint yoffset,
| GLsizei width,
| GLsizei height,
| GLenum format,
| GLenum type,
| const GLvoid * data`)`;

## Parameters

`target`

  Specifies the target texture. Must be `GL_TEXTURE_2D`, `GL_TEXTURE_CUBE_MAP_POSITIVE_X`, `GL_TEXTURE_CUBE_MAP_NEGATIVE_X`, `GL_TEXTURE_CUBE_MAP_POSITIVE_Y`, `GL_TEXTURE_CUBE_MAP_NEGATIVE_Y`, `GL_TEXTURE_CUBE_MAP_POSITIVE_Z`, or `GL_TEXTURE_CUBE_MAP_NEGATIVE_Z`.

`level`

  Specifies the level-of-detail number. Level 0 is the base image level. Level n is the nth mipmap reduction image.

`xoffset`

  Specifies a texel offset in the x direction within the texture array.

`yoffset`

  Specifies a texel offset in the y direction within the texture array.

`width`

  Specifies the width of the texture subimage.

`height`

  Specifies the height of the texture subimage.

`format`

  Specifies the format of the pixel data. The following symbolic values are accepted: `GL_RED`, `GL_RED_INTEGER`, `GL_RG`, `GL_RG_INTEGER`, `GL_RGB`, `GL_RGB_INTEGER`, `GL_RGBA`, `GL_RGBA_INTEGER`, `GL_DEPTH_COMPONENT`, `GL_DEPTH_STENCIL`, `GL_LUMINANCE_ALPHA`, `GL_LUMINANCE`, and `GL_ALPHA`.

`type`

  Specifies the data type of the pixel data. The following symbolic values are accepted: `GL_UNSIGNED_BYTE`, `GL_BYTE`, `GL_UNSIGNED_SHORT`, `GL_SHORT`, `GL_UNSIGNED_INT`, `GL_INT`, `GL_HALF_FLOAT`, `GL_FLOAT`, `GL_UNSIGNED_SHORT_5_6_5`, `GL_UNSIGNED_SHORT_4_4_4_4`, `GL_UNSIGNED_SHORT_5_5_5_1`, `GL_UNSIGNED_INT_2_10_10_10_REV`, `GL_UNSIGNED_INT_10F_11F_11F_REV`, `GL_UNSIGNED_INT_5_9_9_9_REV`, `GL_UNSIGNED_INT_24_8`, and `GL_FLOAT_32_UNSIGNED_INT_24_8_REV`.

`data`

  Specifies a pointer to the image data in memory.

## Description

Texturing allows elements of an image array to be read by shaders.

`glTexSubImage2D` redefines a contiguous subregion of an existing two-dimensional texture image. The texels referenced by `data` replace the portion of the existing texture array with x indices `xoffset` and xoffset + width - 1 , inclusive, and y indices `yoffset` 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.

If a non-zero named buffer object is bound to the `GL_PIXEL_UNPACK_BUFFER` target (see glBindBuffer) while a texture image is specified, `data` is treated as a byte offset into the buffer object's data store.

## Notes

glPixelStorei modes affect texture images.

`glTexSubImage2D` specifies a two-dimensional subtexture for the texture object bound to the current texture unit, specified with glActiveTexture.

## Errors

`GL_INVALID_ENUM` is generated if `target` is not `GL_TEXTURE_2D`, `GL_TEXTURE_CUBE_MAP_POSITIVE_X`, `GL_TEXTURE_CUBE_MAP_NEGATIVE_X`, `GL_TEXTURE_CUBE_MAP_POSITIVE_Y`, `GL_TEXTURE_CUBE_MAP_NEGATIVE_Y`, `GL_TEXTURE_CUBE_MAP_POSITIVE_Z`, or `GL_TEXTURE_CUBE_MAP_NEGATIVE_Z`.

`GL_INVALID_ENUM` is generated if `format` is not an accepted format constant.

`GL_INVALID_ENUM` is generated if `type` is not a type constant.

`GL_INVALID_VALUE` is generated if `level` is less than 0.

`GL_INVALID_VALUE` may be generated if `level` is greater than log 2 max, where max is the returned value of `GL_MAX_TEXTURE_SIZE`.

`GL_INVALID_VALUE` is generated if xoffset < 0 , xoffset + width > w , yoffset < 0 , or yoffset + height > h , where w is the `GL_TEXTURE_WIDTH`, and h is the `GL_TEXTURE_HEIGHT` of the texture image being modified.

`GL_INVALID_VALUE` is generated if `width` or `height` is less than 0.

`GL_INVALID_OPERATION` is generated if the texture array has not been defined by a previous glTexImage2D or glTexStorage2D operation.

`GL_INVALID_OPERATION` is generated if the combination of `internalFormat` of the previously specified texture array, `format` and `type` is not valid. See glTexImage2D.

`GL_INVALID_OPERATION` is generated if a non-zero buffer object name is bound to the `GL_PIXEL_UNPACK_BUFFER` target and the buffer object's data store is currently mapped.

`GL_INVALID_OPERATION` is generated if a non-zero buffer object name is bound to the `GL_PIXEL_UNPACK_BUFFER` target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size.

`GL_INVALID_OPERATION` is generated if a non-zero buffer object name is bound to the `GL_PIXEL_UNPACK_BUFFER` target and `data` is not evenly divisible into the number of bytes needed to store in memory a datum indicated by `type`.

## Associated Gets

glGet with argument `GL_PIXEL_UNPACK_BUFFER_BINDING`

## API Version Support

| OpenGL ES API Version
--- | ---
Function Name | 2.0 | 3.0 | 3.1 | 3.2
glTexSubImage2D | ✔ | ✔ | ✔ | ✔

## See Also

glActiveTexture, glCopyTexImage2D, glCopyTexSubImage2D, glCopyTexSubImage3D, glPixelStorei, glTexImage2D, glTexImage3D, glTexStorage2D, glTexStorage3D, glTexSubImage3D, glTexParameter

## Copyright

Copyright © 1991-2006 Silicon Graphics, Inc. Copyright © 2010-2015 Khronos Group. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.