GLAPI/glClearTexSubImage

From OpenGL.org
Jump to: navigation, search
glClearTexSubImage
Core in version 4.4
Core since version 4.4
Core ARB extension ARB_clear_texture

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

Function Definition

 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​);
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.
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
The width of the region to be cleared.
height
The height of the region to be cleared.
depth
The depth of 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

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 , , , , , and to be the specified width​, height​, depth​, and the border width, border height, and border depth of the texel array and taking , , , , , and to be the xoffset​, yoffset​, zoffset​, width​, height​, and depth​ argument values, any of the following relationships generates a GL_INVALID_OPERATION​ error: * * * * * *

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.

Notes

glClearTexSubImage 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​ 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).

Associated Gets

glGetTexImage, glGetInternalFormat

See Also

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