plucky (3) glClearTexSubImage.3G.gz

Provided by: opengl-4-man-doc_1.0~svn33624-3_all bug

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);

PARAMETERS

       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.

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
       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:

       •

                                               x
                                               <

                                                       w
                                                       b

                                   .RE

           •

                                               x
                                               +
                                               w
                                               >

                                                   w
                                                   s

                                               -

                                                   w
                                                   b

                                       .RE

               •

                                                   y
                                                   <
                                                   -

                                                       h
                                                       b

                                           .RE

                   •

                                                       y
                                                       +
                                                       h
                                                       >

                                                           h
                                                           s

                                                       -

                                                           h
                                                           b

                                               .RE

                       •

                                                           z
                                                           <
                                                           -

                                                               d
                                                               b

                                                   .RE

                           •

                                                               z
                                                               +
                                                               d
                                                               >

                                                                   d
                                                                   s

                                                               -

                                                                   d
                                                                   b

                                                       .RE

                               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()

VERSION SUPPORT

       ┌───────────────────┬───────────────────────────────────────────────────────────────────────┐
       │                   │                OpenGL Version                                         │
       ├───────────────────┼─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┤
       │Function2.02.13.03.13.23.34.04.14.24.34.44.5 │
       │/                  │     │     │     │     │     │     │     │     │     │     │     │     │
       │Feature            │     │     │     │     │     │     │     │     │     │     │     │     │
       │Name               │     │     │     │     │     │     │     │     │     │     │     │     │
       ├───────────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
       │glClearTexSubImage │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  ✔  │  ✔  │
       └───────────────────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘

SEE ALSO

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

       Copyright © 2013-2014 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/.

       Copyright © 2013-2014 Khronos Group

[FIXME: source]                                    11/18/2024                             GLCLEARTEXSUBIMAGE(3G)