GLGETCOMPRESSEDTEXIM(3G)

📦
version 1.1 · 7 versions
, in centos-stream 9

💖 GLGETCOMPRESSEDTEXIM(3G) — return a compressed texture image 💖

okay so first things first, bestie: this is from the 3G manual, and it's literally the glow-up you need when you wanna pull a compressed texture image out of OpenGL. no cap, it's giving "I know what I'm doing" energy. let's get into it 🫶

✨ C SPECIFICATION ✨

here's the tea, three whole function signatures, copy them exactly because bestie we do not freestyle signatures:

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 — this is the target the texture is bound to for glGetCompressedTexImage and glGetnCompressedTexImage. accepted targets are: 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, GL_TEXTURE_CUBE_MAP_NEGATIVE_Z, and GL_TEXTURE_RECTANGLE. yes bestie, all thirteen of them, I counted 💅
  • texture — specifies the texture object name for the glGetCompressedTextureImage function. like, the actual ID of the texture, not the target. iconic distinction fr fr.
  • level — 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. mipmap math, we love to see it ✨
  • bufSize — specifies the size of the buffer pixels for glGetCompressedTextureImage and glGetnCompressedTexImage functions. it's giving "how much room do I have" energy.
  • pixels — returns the compressed texture image. that's the whole point, bestie 🎀

🦋 DESCRIPTION 🦋

so 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. slay.

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. (yes, that's literally how it's spelled in the original, glGetnCompresedTexImage with no second 's', I'm not fixing it, I'm just delivering it exactly as it is 💀)

if the actual data takes less space than bufSize, the remaining bytes will not be touched. periodt. don't come for me.

target specifies the texture target, to which the texture the data the function should extract the data from is bound to. (that sentence is a lot, but it's the original, okay? it means: the texture you want data from must be bound to target.)

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. like, it's not a pointer anymore, it's an offset. glow-up moment.

to minimize errors, here's the responsible bestie checklist — and I'm quoting the steps exactly because this is important:

  1. first verify that the texture is compressed by calling glGetTexLevelParameter() with argument GL_TEXTURE_COMPRESSED.
  2. 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.
  3. 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. iykyk 🧚

💀 ERRORS 💀

okay so here's where it can go wrong, and we do not want that:

  • 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. (yes, uncompressed = invalid operation, don't do it bestie 😭)
  • 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. oop, buffer overflow vibes, not the good kind.

⭐ ASSOCIATED GETS ⭐

these are the gets that go with it, like accessories but for OpenGL:

  • 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 👑

here's the whole vibe check, exactly as it appears — I'm putting it in a code block so nothing gets lost in translation:

┌─────────────────────────────┬───────────────────────────────────────────────────────────────────────┐
│                             │                OpenGL Version                                         │
├─────────────────────────────┼─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┤
│ Function                    │ 2.0 │ 2.1 │ 3.0 │ 3.1 │ 3.2 │ 3.3 │ 4.0 │ 4.1 │ 4.2 │ 4.3 │ 4.4 │ 4.5 │
│ /                           │     │     │     │     │     │     │     │     │     │     │     │     │
│ Feature                     │     │     │     │     │     │     │     │     │     │     │     │     │
│ Name                        │     │     │     │     │     │     │     │     │     │     │     │     │
├─────────────────────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│ glGetCompressedTexImage     │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │
├─────────────────────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│ glGetCompressedTextureImage │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  ✔  │
├─────────────────────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│ glGetnCompressedTexImage    │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  ✔  │
└─────────────────────────────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘

like, glGetCompressedTexImage has been iconic since OpenGL 2.0, and the other two are 4.5-only. main character energy vs. new girl on the block, no shade 💅

🌈 SEE ALSO 🌈

go check these out, they're all related and honestly kind of a mood:

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

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

Copyright © 1991-2006 Silicon Graphics, Inc. Copyright © 2010-2014 Khronos Group

and that's the whole page, bestie! 💖 source is literally [FIXME: source] and the date is 08/09/2021, so like, this manual is vintage but still valid. go get those compressed textures, you've got this 🎀✨

📦 where this page comes from