glClearTexSubImage

glClearTexSubImage: man4/glClearTexSubImage.xml

glClearTexSubImage fills all or part of an image contained in a texture with an application supplied value. texture must be the name of an existing texture. Further, texture may not be the name of a buffer texture, nor may its internal format be compressed. 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. 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, where the value of 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 is translated into an array layer and a cube map face as described in the OpenGL Specification. Negative values of xoffset, yoffset, and zoffset correspond to the coordinates of border texels. Taking 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 taking 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:

1. x < w b
2. x + w > w s - w b
3. y < - h b
4. y + h > h s - h b
5. z < - d b
6. z + d > d s - d b

For texture types that do not 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. format and type specify the format and type of the source data and are interpreted as they are for glTexImage3D. 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 that will be used as the source for the constant fill value. The elements of data are converted by the GL into the internal format of the texture image (that was specified when the level was defined by any of the glTexImage*, glTexStorage* or glCopyTexImage* commands), and then used to fill the specified range of the destination texture level. If data is null, then the pointer is ignored and the sub-range of the texture image is filled with zeros. If texture is a multisample texture, all the samples in a texel are cleared to the value specified by data.

glClearTexSubImage is available only if the GL version is 4.4 or greater.