glGetCompressedTextureSubImage - OpenGL 4 Reference Pages

## Name

glGetCompressedTextureSubImage — retrieve a sub-region of a compressed texture image from a compressed texture object

## C Specification

`void glGetCompressedTextureSubImage(` | GLuint texture,
| GLint level,
| GLint xoffset,
| GLint yoffset,
| GLint zoffset,
| GLsizei width,
| GLsizei height,
| GLsizei depth,
| 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. Must be a multiple of the compressed block's width, unless the `offset` is zero and the size equals the texture image size.

`height`

  Specifies the height of the texture subimage. Must be a multiple of the compressed block's height, unless the `offset` is zero and the size equals the texture image size.

`depth`

  Specifies the depth of the texture subimage. Must be a multiple of the compressed block's depth, unless the `offset` is zero and the size equals the texture image size.

`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

`glGetCompressedTextureSubImage` can be used to obtain a sub-region of a compressed texture image instead of the whole image, as long as the compressed data are arranged into fixed-size blocks of texels. `texture` is the name of the texture object, and must not be a buffer or multisample texture. The effective `target` is the value of `GL_TEXTURE_TARGET` for texture. `level` and `pixels` have the same meaning as the corresponding arguments of `glCompressedTexSubImage3D`. `bufSize` indicates the size of the buffer to receive the retrieved pixel data.

For cube map textures, the behavior is as though `glGetCompressedTexImage` were called once for each requested face (selected by `zoffset` and `depth`, as described below) with target corresponding to the requested texture cube map face as indicated by the table presented below. `pixels` is offset appropriately for each successive image.

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`

`xoffset`, `yoffset` and `zoffset` indicate the position of the subregion to return. `width`, `height` and `depth` indicate the size of the region to return. These arguments have the same meaning as for `glCompressedTexSubImage3D`, though there are extra restrictions, described in the errors section below.

The mapping between the `xoffset`, `yoffset`, `zoffset`, `width`, `height` and `depth` parameters and the faces, layers, and layer-faces for cube map, array, and cube map array textures is the same as for glGetTextureSubImage.

The `xoffset`, `yoffset`, `zoffset` offsets and `width`, `height` and `depth` sizes must be multiples of the values of `GL_PACK_COMPRESSED_BLOCK_WIDTH`, `GL_PACK_COMPRESSED_BLOCK_HEIGHT`, and `GL_PACK_COMPRESSED_BLOCK_DEPTH` respectively, unless `offset` is zero and the corresponding `size` is the same as the texture size in that dimension.

Pixel storage modes are treated as for `glGetCompressedTexSubImage`. The texel at (`xoffset`, `yoffset`, `zoffset`) will be stored at the location indicated by `pixels` and the current pixel packing parameters.

## Errors

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

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

`GL_INVALID_OPERATION` error is generated if the texture compression format is not based on fixed-size blocks.

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

`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_VALUE` error is generated if `xoffset`, `yoffset` or `zoffset` is not a multiple of the compressed block width, height or depth respectively.

`GL_INVALID_VALUE` error is generated if `width`, `height` or `depth` is not a multiple of the compressed block width, height or depth respectively, unless the `offset` is zero and the `size` equals the texture image size.

## 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
`glGetCompressedTextureSubImage` | - | - | - | - | - | - | - | - | - | - | - | ✔

## See Also

glCompressedTexImage1D, glCompressedTexImage2D, glCompressedTexImage3D, glCompressedTexSubImage1D, glCompressedTexSubImage2D, glCompressedTexSubImage3D, glGetCompressedTexImage, `glGetCompressedTextureImage`, glReadPixels

## 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/.