GLAPI/glClearTexImage
| Core in version | 4.6 | |
|---|---|---|
| Core since version | 4.4 | |
| Core ARB extension | ARB_clear_texture | |
glClearTexImage: fills all a texture image with a constant value
Function Definition
void glClearTexImage(GLuint texture, GLint level, GLenum format, GLenum type, const void * data);
- texture
- The name of an existing texture object containing the image to be cleared.
- level
- The level of texture containing the region to be cleared.
- format
- Specifies the format of the pixel data. For transfers of depth, stencil, or depth/stencil data, you must use GL_DEPTH_COMPONENT, GL_STENCIL_INDEX, or GL_DEPTH_STENCIL, where appropriate. For transfers of normalized integer or floating-point color image data, you must use one of the following: GL_RED, GL_GREEN, GL_BLUE, GL_RG, GL_RGB, GL_BGR, GL_RGBA, and GL_BGRA. For transfers of non-normalized integer data, you must use one of the following: GL_RED_INTEGER, GL_GREEN_INTEGER, GL_BLUE_INTEGER, GL_RG_INTEGER, GL_RGB_INTEGER, GL_BGR_INTEGER, GL_RGBA_INTEGER, and GL_BGRA_INTEGER.
- type
- Specifies the data type of the pixel data. The following symbolic values are accepted: GL_UNSIGNED_BYTE, GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, GL_FLOAT, GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, and GL_UNSIGNED_INT_2_10_10_10_REV.
- data
- Specifies a pointer to the image data in memory, or if a buffer is bound to GL_PIXEL_UNPACK_BUFFER, this provides an integer offset into the bound buffer object. If a buffer is not bound to GL_PIXEL_UNPACK_BUFFER, and this parameter is NULL, no Pixel Transfer will be performed.
Description
glClearTexImage fills all 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.
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.
Notes
glClearTexImage is available only if the GL version is 4.4 or greater.
Errors
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 is generated if the image array identified by level has not previously been defined by a call to glTexImage* or glTexStorage*.
Associated Gets
glGetTexImage, glGetInternalFormat
See Also
glClearTexSubImage, glTexStorage1D, glTexStorage2D, glTexStorage3D, glTexImage1D, glTexImage2D, glTexImage3D
Copyright
Copyright © 2013 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.