glClearTexSubImage — fills all or part of a texture image with a constant value
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
The format of the data whose address in memory is given by data
.
type
The type of the data whose address in memory is given by data
.
data
The address in memory of the data to be used to clear the specified region.
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
width
, height
, depth
, and the border width, border height, and border
depth of the texel array and taking
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.
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).
glClearTexImage, glTexStorage1D, glTexStorage2D, glTexStorage3D, glTexImage1D, glTexImage2D, glTexImage3D
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/.