GLAPI/glGetCompressedTexImage: Difference between revisions

From OpenGL Wiki
Jump to navigation Jump to search
← Older edit
m Renaming category: 'API Reference 4' to 'Core API Reference'.
 
(5 intermediate revisions by one other user not shown)
Line 8: Line 8:
== Function Definition ==
== Function Definition ==


   void '''glGetCompressedTexImage'''(GLenum ''target'', GLint ''lod'', GLvoid * ''img'');
   void '''glGetCompressedTexImage'''(GLenum {{param|target}}, GLint {{param|lod}}, GLvoid * {{param|img}});


; target
; target
: Specifies which texture is to be obtained. {{code|GL_TEXTURE_1D}}, {{code|GL_TEXTURE_2D}}, {{code|GL_TEXTURE_3D}}, {{code|GL_TEXTURE_CUBE_MAP_POSITIVE_X}}, {{code|GL_TEXTURE_CUBE_MAP_NEGATIVE_X}}, {{code|GL_TEXTURE_CUBE_MAP_POSITIVE_Y}}, {{code|GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}}, {{code|GL_TEXTURE_CUBE_MAP_POSITIVE_Z}}, and {{code|GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}} are accepted.
: Specifies which texture is to be obtained. {{enum|GL_TEXTURE_1D}}, {{enum|GL_TEXTURE_2D}}, {{enum|GL_TEXTURE_3D}}, {{enum|GL_TEXTURE_CUBE_MAP_POSITIVE_X}}, {{enum|GL_TEXTURE_CUBE_MAP_NEGATIVE_X}}, {{enum|GL_TEXTURE_CUBE_MAP_POSITIVE_Y}}, {{enum|GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}}, {{enum|GL_TEXTURE_CUBE_MAP_POSITIVE_Z}}, and {{enum|GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}} are accepted.
; lod
; lod
: 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.
: 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.
Line 19: Line 19:
== Description ==
== Description ==


'''glGetCompressedTexImage''' returns the compressed texture image associated with ''target'' and ''lod'' into ''img''. ''img'' should be an array of {{code|GL_TEXTURE_COMPRESSED_IMAGE_SIZE}} bytes. ''target'' specifies whether the desired texture image was one specified by [[GLAPI/glTexImage1D|glTexImage1D]] ({{code|GL_TEXTURE_1D}}), [[GLAPI/glTexImage2D|glTexImage2D]] ({{code|GL_TEXTURE_2D}} or any of {{code|GL_TEXTURE_CUBE_MAP_*}}), or [[GLAPI/glTexImage3D|glTexImage3D]] ({{code|GL_TEXTURE_3D}}). ''lod'' specifies the level-of-detail number of the desired image.
'''glGetCompressedTexImage''' returns the compressed texture image associated with {{param|target}} and {{param|lod}} into {{param|img}}. {{param|img}} should be an array of {{enum|GL_TEXTURE_COMPRESSED_IMAGE_SIZE}} bytes. {{param|target}} specifies whether the desired texture image was one specified by {{apifunc|glTexImage1D}} ({{enum|GL_TEXTURE_1D}}), {{apifunc|glTexImage2D}} ({{enum|GL_TEXTURE_2D}} or any of {{enum|GL_TEXTURE_CUBE_MAP_*}}), or {{apifunc|glTexImage3D}} ({{enum|GL_TEXTURE_3D}}). {{param|lod}} specifies the level-of-detail number of the desired image.


If a non-zero named buffer object is bound to the {{code|GL_PIXEL_PACK_BUFFER}} target (see [[GLAPI/glBindBuffer|glBindBuffer]]) while a texture image is requested, ''img'' is treated as a byte offset into the buffer object's data store.
If a non-zero named buffer object is bound to the {{enum|GL_PIXEL_PACK_BUFFER}} target (see {{apifunc|glBindBuffer}}) while a texture image is requested, {{param|img}} 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 [[GLAPI/glGetTexLevelParameter|glGetTexLevelParameter]] with argument {{code|GL_TEXTURE_COMPRESSED}}. If the texture is compressed, then determine the amount of memory required to store the compressed texture by calling [[GLAPI/glGetTexLevelParameter|glGetTexLevelParameter]] with argument {{code|GL_TEXTURE_COMPRESSED_IMAGE_SIZE}}. Finally, retrieve the internal format of the texture by calling [[GLAPI/glGetTexLevelParameter|glGetTexLevelParameter]] with argument {{code|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.
To minimize errors, first verify that the texture is compressed by calling {{apifunc|glGetTexLevelParameter}} with argument {{enum|GL_TEXTURE_COMPRESSED}}. If the texture is compressed, then determine the amount of memory required to store the compressed texture by calling {{apifunc|glGetTexLevelParameter}} with argument {{enum|GL_TEXTURE_COMPRESSED_IMAGE_SIZE}}. Finally, retrieve the internal format of the texture by calling {{apifunc|glGetTexLevelParameter}} with argument {{enum|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 {{param|target}} textures.


== Errors ==
== Errors ==


{{code|GL_INVALID_VALUE}} is generated if ''lod'' is less than zero or greater than the maximum number of LODs permitted by the implementation.
{{enum|GL_INVALID_VALUE}} is generated if {{param|lod}} is less than zero or greater than the maximum number of LODs permitted by the implementation.


{{code|GL_INVALID_OPERATION}} is generated if '''glGetCompressedTexImage''' is used to retrieve a texture that is in an uncompressed internal format.
{{enum|GL_INVALID_OPERATION}} is generated if '''glGetCompressedTexImage''' is used to retrieve a texture that is in an uncompressed internal format.


{{code|GL_INVALID_OPERATION}} is generated if a non-zero buffer object name is bound to the {{code|GL_PIXEL_PACK_BUFFER}} target and the buffer object's data store is currently mapped.
{{enum|GL_INVALID_OPERATION}} is generated if a non-zero buffer object name is bound to the {{enum|GL_PIXEL_PACK_BUFFER}} target and the buffer object's data store is currently mapped.


{{code|GL_INVALID_OPERATION}} is generated if a non-zero buffer object name is bound to the {{code|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.
{{enum|GL_INVALID_OPERATION}} is generated if a non-zero buffer object name is bound to the {{enum|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 ==
== Associated Gets ==


[[GLAPI/glGetTexLevelParameter|glGetTexLevelParameter]] with argument {{code|GL_TEXTURE_COMPRESSED}}
{{apifunc|glGetTexLevelParameter}} with argument {{enum|GL_TEXTURE_COMPRESSED}}


[[GLAPI/glGetTexLevelParameter|glGetTexLevelParameter]] with argument {{code|GL_TEXTURE_COMPRESSED_IMAGE_SIZE}}
{{apifunc|glGetTexLevelParameter}} with argument {{enum|GL_TEXTURE_COMPRESSED_IMAGE_SIZE}}


[[GLAPI/glGetTexLevelParameter|glGetTexLevelParameter]] with argument {{code|GL_TEXTURE_INTERNAL_FORMAT}}
{{apifunc|glGetTexLevelParameter}} with argument {{enum|GL_TEXTURE_INTERNAL_FORMAT}}


[[GLAPI/glGet|glGet]] with argument {{code|GL_PIXEL_PACK_BUFFER_BINDING}}
{{apifunc|glGet}} with argument {{enum|GL_PIXEL_PACK_BUFFER_BINDING}}


== See Also ==
== See Also ==


[[GLAPI/glActiveTexture|glActiveTexture]], [[GLAPI/glCompressedTexImage1D|glCompressedTexImage1D]], [[GLAPI/glCompressedTexImage2D|glCompressedTexImage2D]], [[GLAPI/glCompressedTexImage3D|glCompressedTexImage3D]], [[GLAPI/glCompressedTexSubImage1D|glCompressedTexSubImage1D]], [[GLAPI/glCompressedTexSubImage2D|glCompressedTexSubImage2D]], [[GLAPI/glCompressedTexSubImage3D|glCompressedTexSubImage3D]], [[GLAPI/glReadPixels|glReadPixels]], [[GLAPI/glTexImage1D|glTexImage1D]], [[GLAPI/glTexImage2D|glTexImage2D]], [[GLAPI/glTexImage3D|glTexImage3D]], [[GLAPI/glTexParameter|glTexParameter]], [[GLAPI/glTexSubImage1D|glTexSubImage1D]], [[GLAPI/glTexSubImage2D|glTexSubImage2D]], [[GLAPI/glTexSubImage3D|glTexSubImage3D]]
{{apifunc|glActiveTexture}}, {{apifunc|glBindTexture}}, {{apifunc|glPixelStore}}


== Copyright ==
== 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/ http://oss.sgi.com/projects/FreeB/].
Copyright © 1991-2006 Silicon Graphics, Inc. This document is licensed under the SGI Free Software B License. For details, see [https://khronos.org/registry/OpenGL-Refpages/LICENSES/LicenseRef-FreeB.txt LicenseRef-FreeB].


[[Category:GL 4 API Texturing|GetCompressedTexImage]]
[[Category:Core API Reference|GetCompressedTexImage]]
[[Category:Core API Reference|GetCompressedTexImage]]
[[Category:Core API Ref Texturing|GetCompressedTexImage]]
[[Category:Texture Object API State Functions|GetCompressedTexImage]]

Latest revision as of 22:00, 5 February 2021

glGetCompressedTexImage
Core in version 4.6
Core since version 1.3

glGetCompressedTexImage: return a compressed texture image

Function Definition

 void glGetCompressedTexImage(GLenum target​, GLint lod​, GLvoid * img​);
target
Specifies which texture is to be obtained. GL_TEXTURE_1D, GL_TEXTURE_2D, GL_TEXTURE_3D, 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 are accepted.
lod
Specifies the level-of-detail number of the desired image. Level 0 is the base image level. Level n is the nth mipmap reduction image.
img
Returns the compressed texture image.

Description

glGetCompressedTexImage returns the compressed texture image associated with target​ and lod​ into img​. img​ should be an array of GL_TEXTURE_COMPRESSED_IMAGE_SIZE bytes. target​ specifies whether the desired texture image was one specified by glTexImage1D (GL_TEXTURE_1D), glTexImage2D (GL_TEXTURE_2D or any of GL_TEXTURE_CUBE_MAP_*), or glTexImage3D (GL_TEXTURE_3D). 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, img​ 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, then 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_VALUE is generated if lod​ is less than zero or greater than the maximum number of LODs permitted by the implementation.

GL_INVALID_OPERATION is generated if glGetCompressedTexImage 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 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

See Also

glActiveTexture, glBindTexture, glPixelStore

Copyright

Copyright © 1991-2006 Silicon Graphics, Inc. This document is licensed under the SGI Free Software B License. For details, see LicenseRef-FreeB.

Retrieved from "https://wikis.khronos.org/opengl/index.php?title=GLAPI/glGetCompressedTexImage&oldid=14792"