Light | Dark

# docs.GL

OpenGL 4
OpenGL 3
OpenGL 2
OpenGL ES 3

# glTexSubImage3D

## Name

glTexSubImage3D — specify a three-dimensional texture subimage

## C Specification

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

## Parameters

`target`

  Specifies the target texture. Must be `GL_TEXTURE_3D`.

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

`zoffset`

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

`width`

  Specifies the width of the texture subimage.

`height`

  Specifies the height of the texture subimage.

`depth`

  Specifies the depth of the texture subimage.

`format`

  Specifies the format of the pixel data. The following symbolic values are accepted: `GL_COLOR_INDEX`, `GL_RED`, `GL_GREEN`, `GL_BLUE`, `GL_ALPHA`, `GL_RGB`, `GL_BGR`, `GL_RGBA`, `GL_BGRA`, `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_BYTE`, `GL_BITMAP`, `GL_UNSIGNED_SHORT`, `GL_SHORT`, `GL_UNSIGNED_INT`, `GL_INT`, `GL_FLOAT`, `GL_UNSIGNED_BYTE_3_3_2`, `GL_UNSIGNED_BYTE_2_3_3_REV`, `GL_UNSIGNED_SHORT_5_6_5`, `GL_UNSIGNED_SHORT_5_6_5_REV`, `GL_UNSIGNED_SHORT_4_4_4_4`, `GL_UNSIGNED_SHORT_4_4_4_4_REV`, `GL_UNSIGNED_SHORT_5_5_5_1`, `GL_UNSIGNED_SHORT_1_5_5_5_REV`, `GL_UNSIGNED_INT_8_8_8_8`, `GL_UNSIGNED_INT_8_8_8_8_REV`, `GL_UNSIGNED_INT_10_10_10_2`, and `GL_UNSIGNED_INT_2_10_10_10_REV`.

`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 enabled. To enable and disable three-dimensional texturing, call glEnable and glDisable with argument `GL_TEXTURE_3D`.

`glTexSubImage3D` redefines a contiguous subregion of an existing three-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, y indices `yoffset` and yoffset + height - 1 , inclusive, and z indices `zoffset` and zoffset + depth - 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, height, or depth 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

`glTexSubImage3D` is available only if the GL version is 1.2 or greater.

Texturing has no effect in color index mode.

glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.

Formats `GL_BGR`, and `GL_BGRA` and types `GL_UNSIGNED_BYTE_3_3_2`, `GL_UNSIGNED_BYTE_2_3_3_REV`, `GL_UNSIGNED_SHORT_5_6_5`, `GL_UNSIGNED_SHORT_5_6_5_REV`, `GL_UNSIGNED_SHORT_4_4_4_4`, `GL_UNSIGNED_SHORT_4_4_4_4_REV`, `GL_UNSIGNED_SHORT_5_5_5_1`, `GL_UNSIGNED_SHORT_1_5_5_5_REV`, `GL_UNSIGNED_INT_8_8_8_8`, `GL_UNSIGNED_INT_8_8_8_8_REV`, `GL_UNSIGNED_INT_10_10_10_2`, and `GL_UNSIGNED_INT_2_10_10_10_REV` are available only if the GL version is 1.2 or greater.

For OpenGL versions 1.3 and greater, or when the `ARB_multitexture` extension is supported, `glTexSubImage3D` specifies a three-dimensional subtexture for the current texture unit, specified with glActiveTexture.

When the `ARB_imaging` extension is supported, the RGBA components specified in `data` may be processed by the imaging pipeline. See glTexImage3D for specific details.

## Errors

`GL_INVALID_ENUM` is generated if /`target` is not `GL_TEXTURE_3D`.

`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_ENUM` is generated if `type` is `GL_BITMAP` and `format` is not `GL_COLOR_INDEX`.

`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 < - b , xoffset + width > w - b , yoffset < - b , or yoffset + height > h - b , or zoffset < - b , or zoffset + depth > d - b , where w is the `GL_TEXTURE_WIDTH`, h is the `GL_TEXTURE_HEIGHT`, d is the `GL_TEXTURE_DEPTH` and b is the border width of the texture image being modified. Note that w, h, and d include twice the border width.

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

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

`GL_INVALID_OPERATION` is generated if `type` is one of `GL_UNSIGNED_BYTE_3_3_2`, `GL_UNSIGNED_BYTE_2_3_3_REV`, `GL_UNSIGNED_SHORT_5_6_5`, or `GL_UNSIGNED_SHORT_5_6_5_REV` and `format` is not `GL_RGB`.

`GL_INVALID_OPERATION` is generated if `type` is one of `GL_UNSIGNED_SHORT_4_4_4_4`, `GL_UNSIGNED_SHORT_4_4_4_4_REV`, `GL_UNSIGNED_SHORT_5_5_5_1`, `GL_UNSIGNED_SHORT_1_5_5_5_REV`, `GL_UNSIGNED_INT_8_8_8_8`, `GL_UNSIGNED_INT_8_8_8_8_REV`, `GL_UNSIGNED_INT_10_10_10_2`, or `GL_UNSIGNED_INT_2_10_10_10_REV` and `format` is neither `GL_RGBA` nor `GL_BGRA`.

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

`GL_INVALID_OPERATION` is generated if `glTexSubImage3D` is executed between the execution of glBegin and the corresponding execution of glEnd.

## Associated Gets

glGetTexImage

glIsEnabled with argument `GL_TEXTURE_3D`

glGet with argument `GL_PIXEL_UNPACK_BUFFER_BINDING`

## See Also

glActiveTexture, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexParameter

## Copyright

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

Think you can improve this page? Edit this page on GitHub.