glGetTextureSubImage - OpenGL 4 Reference Pages

## Name

glGetTextureSubImage — retrieve a sub-region of a texture image from a texture object

## C Specification

`void glGetTextureSubImage(` | GLuint texture,
| GLint level,
| GLint xoffset,
| GLint yoffset,
| GLint zoffset,
| GLsizei width,
| GLsizei height,
| GLsizei depth,
| GLenum format,
| GLenum type,
| GLsizei bufSize,
| void *pixels`)`;

## Parameters

`texture`

  Specifies the name of the source texture object. Must be `GL_TEXTURE_1D`, `GL_TEXTURE_1D_ARRAY`, `GL_TEXTURE_2D`, `GL_TEXTURE_2D_ARRAY`, `GL_TEXTURE_3D`, `GL_TEXTURE_CUBE_MAP`, `GL_TEXTURE_CUBE_MAP_ARRAY` or `GL_TEXTURE_RECTANGLE`. In specific, buffer and multisample textures are not permitted.

`level`

  Specifies the level-of-detail number. Level 0 is the base image level. Level $n$ is the $n$th 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_RED`, `GL_RG`, `GL_RGB`, `GL_BGR`, `GL_RGBA`, `GL_BGRA`, `GL_DEPTH_COMPONENT` and `GL_STENCIL_INDEX`.

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

`bufSize`

  Specifies the size of the buffer to receive the retrieved pixel data.

`pixels`

  Returns the texture subimage. Should be a pointer to an array of the type specified by `type`.

## Description

`glGetTextureSubImage` returns a texture subimage into pixels.

`texture` is the name of the source texture object and must not be a buffer or multisample texture. The effective `target` parameter is the value of `GL_TEXTURE_TARGET` for texture. `Level`, `format`, `type` and `pixels` have the same meaning as for `glGetTexImage`. `bufSize` is the size of the buffer to receive the retrieved pixel data.

For cube map textures, the behavior is as though `GetTextureImage` were called, but only texels from the requested cube map faces (selected by `zoffset` and `depth`, as described below) were returned.

`xoffset`, `yoffset` and `zoffset` values indicate the position of the subregion to return. `width`, `height` and `depth` indicate the size of the region to return. These parameters have the same meaning as for `glTexSubImage3D`, though for one- and two-dimensional textures there are extra restrictions, described in the errors section below.

For one-dimensional array textures, `yoffset` is interpreted as the first layer to access and `height` is the number of layers to access.

For two-dimensional array textures, `zoffset` is interpreted as the first layer to access and `depth` is the number of layers to access.

Cube map textures are treated as an array of six slices in the z-dimension, where the value of `zoffset` is interpreted as specifying the cube map face for the corresponding layer (as presented in the table below) and `depth` is the number of faces to access:

Layer number | Cube Map Face
0 | GL_TEXTURE_CUBE_MAP_POSITIVE_X
1 | GL_TEXTURE_CUBE_MAP_NEGATIVE_X
2 | GL_TEXTURE_CUBE_MAP_POSITIVE_Y
3 | GL_TEXTURE_CUBE_MAP_NEGATIVE_Y
4 | GL_TEXTURE_CUBE_MAP_POSITIVE_Z
5 | GL_TEXTURE_CUBE_MAP_NEGATIVE_Z

For cube map array textures, `zoffset` is the first layer-face to access, and `depth` is the number of layer-faces to access. A layer-face described by $k$ is translated into an array layer and face according to $$ layer = \left\lfloor { layer \over 6 } \right\rfloor$$ and $$ face = k \bmod 6. $$

Component groups from the specified sub-region are packed and placed into memory as described for `glGetTextureImage`, starting with the texel at (`xoffset`, `yoffset`, `zoffset`).

## Errors

`GL_INVALID_VALUE` error is generated if `texture` is not the name of an existing texture object.

`GL_INVALID_OPERATION` error is generated if `texture` is the name of a buffer or multisample texture.

`GL_INVALID_VALUE` is generated if `xoffset`, `yoffset` or `zoffset` are negative.

`GL_INVALID_VALUE` is generated if `xoffset` + `width` is greater than the texture's width, `yoffset` + `height` is greater than the texture's height, or `zoffset` + `depth` is greater than the texture's depth.

`GL_INVALID_VALUE` error is generated if the effective target is `GL_TEXTURE_1D` and either `yoffset` is not zero, or `height` is not one.

`GL_INVALID_VALUE` error is generated if the effective target is `GL_TEXTURE_1D`, `GL_TEXTURE_1D_ARRAY`, `GL_TEXTURE_2D` or `GL_TEXTURE_RECTANGLE` and either `zoffset` is not zero, or `depth` is not one.

`GL_INVALID_OPERATION` error is generated if the buffer size required to store the requested data is greater than `bufSize`.

## Version Support

| OpenGL Version
--- | ---
Function / Feature Name | 2.0 | 2.1 | 3.0 | 3.1 | 3.2 | 3.3 | 4.0 | 4.1 | 4.2 | 4.3 | 4.4 | 4.5
`glGetTextureSubImage` | - | - | - | - | - | - | - | - | - | - | - | ✔

## See Also

glGetTexImage, `glGetTextureImage`, glReadPixels, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D

## Copyright

Copyright © 2014 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.