glGetCompressedTexImage - OpenGL 4 Reference Pages

## Name

glGetCompressedTexImage — return a compressed texture image

## C Specification

`void glGetCompressedTexImage(` | GLenum target,
| GLint level,
| GLvoid * pixels`)`;

`void glGetnCompressedTexImage(` | GLenum target,
| GLint level,
| GLsizei bufSize,
| void *pixels`)`;

`void glGetCompressedTextureImage(` | GLuint texture,
| GLint level,
| GLsizei bufSize,
| void *pixels`)`;

## Parameters

`target`

  Specifies the target to which the texture is bound for `glGetCompressedTexImage` and `glGetnCompressedTexImage` functions. `GL_TEXTURE_1D`, `GL_TEXTURE_1D_ARRAY`, `GL_TEXTURE_2D`, `GL_TEXTURE_2D_ARRAY`, `GL_TEXTURE_3D`, `GL_TEXTURE_CUBE_MAP_ARRAY`, `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`, and `GL_TEXTURE_CUBE_MAP_NEGATIVE_Z`, `GL_TEXTURE_RECTANGLE` are accepted.

`texture`

  Specifies the texture object name for `glGetCompressedTextureImage` function.

`level`

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

`bufSize`

  Specifies the size of the buffer `pixels` for `glGetCompressedTextureImage` and `glGetnCompressedTexImage` functions.

`pixels`

  Returns the compressed texture image.

## Description

`glGetCompressedTexImage` and `glGetnCompressedTexImage` return the compressed texture image associated with `target` and `lod` into `pixels`. `glGetCompressedTextureImage` serves the same purpose, but instead of taking a texture target, it takes the ID of the texture object. `pixels` should be an array of `bufSize` bytes for `glGetnCompresedTexImage` and `glGetCompressedTextureImage` functions, and of `GL_TEXTURE_COMPRESSED_IMAGE_SIZE` bytes in case of `glGetCompressedTexImage`. If the actual data takes less space than `bufSize`, the remaining bytes will not be touched. `target` specifies the texture target, to which the texture the data the function should extract the data from is bound to. `lod` specifies the level-of-detail number of the desired image.

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

To minimize errors, first verify that the texture is compressed by calling glGetTexLevelParameter with argument `GL_TEXTURE_COMPRESSED`. If the texture is compressed, you can determine the amount of memory required to store the compressed texture by calling glGetTexLevelParameter with argument `GL_TEXTURE_COMPRESSED_IMAGE_SIZE`. Finally, retrieve the internal format of the texture by calling glGetTexLevelParameter with argument `GL_TEXTURE_INTERNAL_FORMAT`. To store the texture for later use, associate the internal format and size with the retrieved texture image. These data can be used by the respective texture or subtexture loading routine used for loading `target` textures.

## Errors

`GL_INVALID_OPERATION` is generated by `glGetCompressedTextureImage` if `texture` is not the name of an existing texture object.

`GL_INVALID_VALUE` is generated if `level` is less than zero or greater than the maximum number of LODs permitted by the implementation.

`GL_INVALID_OPERATION` is generated if `glGetCompressedTexImage`, `glGetnCompressedTexImage`, and `glGetCompressedTextureImage` is used to retrieve a texture that is in an uncompressed internal format.

`GL_INVALID_OPERATION` is generated if a non-zero buffer object name is bound to the `GL_PIXEL_PACK_BUFFER` target, the buffer storage was not initialized with `glBufferStorage` using `GL_MAP_PERSISTENT_BIT` flag, 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_PACK_BUFFER` target and the data would be packed to the buffer object such that the memory writes required would exceed the data store size.

## Associated Gets

glGetTexLevelParameter with argument `GL_TEXTURE_COMPRESSED`

glGetTexLevelParameter with argument `GL_TEXTURE_COMPRESSED_IMAGE_SIZE`

glGetTexLevelParameter with argument `GL_TEXTURE_INTERNAL_FORMAT`

glGet with argument `GL_PIXEL_PACK_BUFFER_BINDING`

## 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
`glGetCompressedTexImage` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔
`glGetCompressedTextureImage` | - | - | - | - | - | - | - | - | - | - | - | ✔
`glGetnCompressedTexImage` | - | - | - | - | - | - | - | - | - | - | - | ✔

## See Also

glActiveTexture, glCompressedTexImage1D, glCompressedTexImage2D, glCompressedTexImage3D, glCompressedTexSubImage1D, glCompressedTexSubImage2D, glCompressedTexSubImage3D, glReadPixels, glTexImage1D, glTexImage2D, glTexImage3D, glTexParameter, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D

## Copyright

Copyright © 1991-2006 Silicon Graphics, Inc. Copyright © 2010-2014 Khronos Group. This document is licensed under the SGI Free Software B License. For details, see http://opencontent.org/openpub/.