GLCLEARTEXSUBIMAGE(3G)

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

💅 GLCLEARTEXSUBIMAGE (3G)

okay so bestie, welcome to the glClearTexSubImage page — it's the OpenGL 3G manual, and honestly? it ate. it's giving "paint bucket but make it 3D" and i'm obsessed. let's get into it ✨

🌸 NAME 🌸

glClearTexSubImage — fills all or part of a texture image with a constant value 💖

🎀 C SPECIFICATION 🎀

void glClearTexSubImage(GLuint texture, GLint level, GLint xoffset,
                        GLint yoffset, GLint zoffset, GLsizei width,
                        GLsizei height, GLsizei depth, GLenum format,
                        GLenum type, const void * data);

like, copy that exactly, no cap 🫶

🦋 PARAMETERS 🦋

  • texture — the name of an existing texture object that's holding the image you wanna clear. it has to already exist, mmkay?
  • level — which mip level of the texture has the region you're clearing.
  • xoffset — the coordinate of the left edge of the region to be cleared.
  • yoffset — the coordinate of the lower edge of the region to be cleared.
  • zoffset — the coordinate of the front of the region to be cleared.
  • width — how wide the region to be cleared is.
  • height — how tall the region to be cleared is.
  • depth — how deep the region to be cleared is.
  • format — the format of the data whose address in memory is given by data. iykyk.
  • type — the type of the data whose address in memory is given by data.
  • data — the address in memory of the data that's gonna be used to clear the specified region.

✨ DESCRIPTION ✨

glClearTexSubImage fills all or part of an image inside a texture with a value your app supplies. lowkey iconic behavior 💅

texture must be the name of an existing texture. also — and this is the important part — texture may not be the name of a buffer texture, and its internal format may not be compressed. those are hard no's 🚫

the arguments xoffset, yoffset, and zoffset specify the lower left texel coordinates of a width-wide by height-high by depth-deep rectangular subregion of the texel array. like a little box carved out of the big box 📦

🧚 how offsets work for the funky texture types

  • for one-dimensional array textures, yoffset is interpreted as the first layer to be cleared, and height is the number of layers to clear.
  • for two-dimensional array textures, zoffset is interpreted as the first layer to be cleared, and depth is the number of layers to clear.
  • cube map textures are treated as an array of six slices in the z-dimension — zoffset is interpreted as specifying the cube map face for the corresponding layer, and depth is the number of faces to clear.
  • for cube map array textures, zoffset is the first layer-face to clear, and depth is the number of layer-faces to clear. each layer-face gets translated into an array layer and a cube map face as described in the OpenGL Specification. (go read it, i believe in you 📖)

💀 the border math (brace yourself)

negative values of xoffset, yoffset, and zoffset correspond to the coordinates of border texels. take ws, hs, ds, wb, hb, and db to be the specified width, height, depth, and the border width, border height, and border depth of the texel array, and take x, y, z, w, h, and d to be the xoffset, yoffset, zoffset, width, height, and depth argument values.

any of the following relationships generates a GL_INVALID_OPERATION error 😭:

x < -wb
x + w > ws - wb
y < -hb
y + h > hs - hb
z < -db
z + d > ds - db
bestie please check your math before you call this. that's six separate ways to get a GL_INVALID_OPERATION and none of them are cute 🙈

🌈 dimensions you don't have

for texture types that don't have certain dimensions, this command treats those dimensions as having a size of 1. for example — to clear a portion of a two-dimensional texture, use zoffset equal to zero and depth equal to one. that's the move 👑

🍓 format, type, and the data itself

format and type specify the format and type of the source data, and they're interpreted exactly as they are for glTexImage3D(). keep that in mind, it's the whole vibe.

matchups, and you do have to match:

  • textures with a base internal format of GL_DEPTH_COMPONENT, GL_STENCIL_INDEX, or GL_DEPTH_STENCIL require depth component, stencil, or depth-stencil component data respectively.
  • textures with other base internal formats require RGBA formats.
  • textures with integer internal formats require integer data.

data is a pointer to an array of between one and four components of texel data, and that's what gets used as the source for the constant fill value. the GL converts the elements of data into the internal format of the texture image (the one that was specified when the level was defined by any of the glTexImage*, glTexStorage* or glCopyTexImage* commands), and then uses them to fill the specified range of the destination texture level. slay 💖

  • if data is NULL, the pointer is ignored and the sub-range of the texture image gets filled with zeros. free real estate ✨
  • if texture is a multisample texture, all the samples in a texel get cleared to the value specified by data.

🫶 NOTES 🫶

glClearTexSubImage is available only if the GL version is 4.4 or greater. no 4.4, no function, that's the rule 🎀

🔥 ERRORS 🔥

buckle up, there's a whole list of ways to make the GL mad at you 😤

  • GL_INVALID_OPERATION is generated if texture is zero or not the name of an existing texture object.
  • GL_INVALID_OPERATION is generated if texture is a buffer texture.
  • GL_INVALID_OPERATION is generated if texture has a compressed internal format.
  • GL_INVALID_OPERATION is generated if the base internal format is GL_DEPTH_COMPONENT and format is not GL_DEPTH_COMPONENT.
  • GL_INVALID_OPERATION is generated if the base internal format is GL_DEPTH_STENCIL and format is not GL_DEPTH_STENCIL.
  • GL_INVALID_OPERATION is generated if the base internal format is GL_STENCIL_INDEX and format is not GL_STENCIL_INDEX.
  • GL_INVALID_OPERATION is generated if the base internal format is GL_RGBA and format is GL_DEPTH_COMPONENT, GL_STENCIL_INDEX, or GL_DEPTH_STENCIL.
  • GL_INVALID_OPERATION is generated if the internal format is integer and format does not specify integer data.
  • GL_INVALID_OPERATION is generated if the internal format is not integer and format specifies integer data.
  • GL_INVALID_OPERATION error is generated if the xoffset, yoffset, zoffset, width, height, and depth parameters (or combinations thereof) specify a region that falls outside the defined texture image array (including border, if any).
fr fr, that last one is the sneaky one. stay inside the array, bestie 🫶

💜 ASSOCIATED GETS 💜

glGetTexImage(), glGetInternalformat()

👑 VERSION SUPPORT 👑

the vibe check, version by version:

  • glClearTexSubImage in OpenGL 2.0 — - (nope)
  • in 2.1 — -
  • in 3.0 — -
  • in 3.1 — -
  • in 3.2 — -
  • in 3.3 — -
  • in 4.0 — -
  • in 4.1 — -
  • in 4.2 — -
  • in 4.3 — -
  • in 4.4 — ✔ (finally!! main character energy ⭐)
  • in 4.5 — ✔

🌈 SEE ALSO 🌈

glClearTexImage(), glTexStorage1D(), glTexStorage2D(), glTexStorage3D(), glTexImage1D(), glTexImage2D(), glTexImage3D()

part 2 is coming, don't go anywhere 💅

Okay so the legal bit, and yes we're doing it, because respecting licenses is the most main-character thing you can do 💅

This material is Copyright © 2013-2014 Khronos Group. and it may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. That license lives at http://opencontent.org/openpub/ — go read it if you're curious, it's giving "required reading" energy ✨

Copyright © 2013-2014 Khronos Group

That's it. That's the whole section. Short, sweet, legally binding. Periodt 🎀

And that's a wrap on the whole page, bestie!! 🦋 You made it to the very end, I'm so proud 😭🫶

Cute little sign-off: the source line reads [FIXME: source] (yes, the docs themselves are out here with a TODO, relatable honestly 💀), the version/date stamp is 08/09/2021, and the whole thing is filed under GLCLEARTEXSUBIMAGE(3G). Now go clear some texture sub-images — slay 👑✨

📦 where this page comes from