1991-2006
Silicon Graphics, Inc.
glTexSubImage2D
3G

# 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 of the active texture unit. 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_ALPHA`, `GL_RGB`, `GL_RGBA`, `GL_LUMINANCE`, and `GL_LUMINANCE_ALPHA`.

`type`

  Specifies the data type of the pixel data. The following symbolic values are accepted: `GL_UNSIGNED_BYTE`, `GL_UNSIGNED_SHORT_5_6_5`, `GL_UNSIGNED_SHORT_4_4_4_4`, and `GL_UNSIGNED_SHORT_5_5_5_1`.

`data`

  Specifies a pointer to the image data in memory.

## Description

Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is active. Texturing is active when the current fragment shader or vertex shader makes use of built-in texture lookup functions.

`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.

## Notes

Storage parameter `GL_UNPACK_ALIGNMENT`, set by glPixelStorei, affects the way that data is read out of client memory. See glPixelStorei for a description.

`glTexSubImage2D` specifies a two-dimensional or cube-map subtexture for 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` or `type` is not an accepted value.

`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 width and h is the 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 glCopyTexImage2D operation whose `internalformat` matches the `format` of `glTexSubImage2D`.

`GL_INVALID_OPERATION` is generated if `type` is `GL_UNSIGNED_SHORT_5_6_5` and `format` is not `GL_RGB`.

`GL_INVALID_OPERATION` is generated if `type` is `GL_UNSIGNED_SHORT_4_4_4_4` or `GL_UNSIGNED_SHORT_5_5_5_1` and `format` is not `GL_RGBA`.

## Associated Gets

glGet with argument `GL_MAX_TEXTURE_SIZE` or `GL_MAX_CUBE_MAP_TEXTURE_SIZE`

## See Also

glActiveTexture, glCompressedTexImage2D, glCompressedTexSubImage2D, glCopyTexImage2D, glCopyTexSubImage2D, glPixelStorei, glTexImage2D, glTexParameter

## Copyright

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