Name EXT_clear_texture Name Strings GL_EXT_clear_texture Contact Tobias Hector, Imagination Technologies (tobias.hector 'at' imgtec.com) Contributors Contributors to the original ARB_clear_texture Ian Romanick Daniel Koch Notice Copyright (c) 2013 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Status Draft Version Last Modified Date: September 16, 2016 Revision: 2 Number OpenGL ES Extension #269 Dependencies OpenGL ES 3.1 is required. This extension is written against the OpenGL ES 3.1 API specification. This extension interacts with EXT/OES_texture_buffer or OpenGL ES 3.2. This extension interacts with EXT/OES_texture_cube_map_array or OpenGL ES 3.2. This extension interacts with OES_texture_stencil8 or OpenGL ES 3.2. Overview Texture objects are fundamental to the operation of OpenGL. They are used as a source for texture sampling and destination for rendering as well as being accessed in shaders for image load/store operations It is also possible to invalidate the contents of a texture. It is currently only possible to set texture image data to known values by uploading some or all of a image array from application memory or by attaching it to a framebuffer object and using the Clear or ClearBuffer commands. Both uploading initial texture data and clearing by attaching to a framebuffer have potential disadvantages when one simply wants to initialize texture data to a known value. Uploading initial data requires the application to allocate a (potentially large) chunk of memory and transferring that to the GL. This can be a costly operation both in terms of memory bandwidth and power usage. Alternatively, attaching a texture level to a framebuffer to clear it may not be possible if the texture format isn't supported for rendering, or even if it is, attaching the image to a framebuffer object may cause the texture to be allocated in certain types of memory, which it may otherwise not need to be placed in. This extension solves these problems by providing a mechanism whereby the contents of a texture image array can be set to known values by using the ClearTexImageEXT or ClearTexSubImageEXT commands. These commands can also be useful for initializing an image that will be used for atomic shader operations. IP Status No known IP claims. New Procedures and Functions void ClearTexImageEXT(uint texture, int level, enum format, enum type, const void * data); void ClearTexSubImageEXT(uint texture, int level, int xoffset, int yoffset, int zoffset, sizei width, sizei height, sizei depth, enum format, enum type, const void * data); New Types None New Tokens None Additions to Chapter 7 of the OpenGL ES 3.1 API Specification (Programs and Shaders) In section 7.11.2 (Shader Memory Access Synchronization) edit the description of the TEXTURE_UPDATE_BARRIER_BIT to add ClearTexImageEXT and ClearTexSubImageEXT to the list of commands that can write to texture images. Additions to Chapter 8 of the OpenGL ES 3.1 API Specification (Textures and Samplers) Add a new Section 8.x (Clearing Texture Image Data) after Section 8.17 (Immutable-Format Texture Images): "All or part of a texture image may be filled with a constant value by calling the command void ClearTexSubImageEXT(uint texture, int level, int xoffset, int yoffset, int zoffset, sizei width, sizei height, sizei depth, enum format, enum type, const void * data); with and indicating which texture array image is being cleared. It is an error if is zero or not the name of a texture object, if is a buffer texture, or if the texture image has a compressed internal format. Arguments , , and specify the lower left texel coordinates of a -wide by -high by -deep rectangular subregion of the texel array and are interpreted as they are in TexSubImage3D as described in section 8.6 (Alternate Texture Image Specification Commands). The subregion must lie within the bounds of the texture image, as described in that section. For 2D array textures, is interpreted as the first layer to be cleared and 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 is interpreted as specifying the cube map face for the corresponding in table 8.25 (Layer numbers for cube map texture faces) and is the number of faces to clear. For cube map array textures, is the first layer-face to clear, and is the number of layer-faces to clear. Each layer-face is translated into an array layer and a cube map face as described for layer-face numbers in section 8.5.3 [in OpenGL ES 3.2]. 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, the application would use equal to zero and equal to one. and specify the format and type of the source data and are interpreted as they are for TexImage3D, as described in section 8.4.2 (Transfer of Pixel Rectangles). Textures with a base internal format of DEPTH_COMPONENT, STENCIL_INDEX, or 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 (see table 8.13) require integer 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 are converted by the GL into the of the texture image (that was specified when the level was defined by any of the TexImage, TexStorage or CopyTexImage commands) in the manner described in section 8.4.2 (Transfer of Pixel Rectangles), and then used to fill the specified range of the destination texture level. If is NULL, then the pointer is ignored and the sub-range of the texture image is filled with zeros. If is a multisample texture, all the samples in a texel are cleared to the value specified by . Errors An INVALID_OPERATION error is generated if is zero or not the name of a texture object. An INVALID_OPERATION error is generated if is a buffer texture. An INVALID_OPERATION error is generated if has a compressed internal format. An INVALID_OPERATION error is generated if the base internal format is DEPTH_COMPONENT and is not DEPTH_COMPONENT. An INVALID_OPERATION error is generated if the base internal format is DEPTH_STENCIL and is not DEPTH_STENCIL. An INVALID_OPERATION error is generated if the base internal format is STENCIL_INDEX and is not STENCIL_INDEX. An INVALID_OPERATION error is generated if the base internal format is RGBA and the is DEPTH_COMPONENT, STENCIL_INDEX, or DEPTH_STENCIL. An INVALID_OPERATION error is generated if the internal format is integer and does not specify integer data. An INVALID_OPERATION error is generated if the internal format is not integer and does specify integer data. An INVALID_OPERATION error is generated if the specified subregion does not lie within the bounds of the texture image, as described for TexSubImage3D in section 8.6. The command void ClearTexImageEXT(uint texture, int level, enum format, enum type, const void * data); is equivalent to calling ClearTexSubImageEXT with , , and equal to 0 and , , and equal to the dimensions of the texture image (or zero and one for dimensions the texture doesn't have). Errors In addition to the errors generated by ClearTexSubImageEXT: An INVALID_OPERATION error is generated if the image array identified by has not previously been defined by a TexImage* or TexStorage* command." Interactions with EXT/OES_texture_buffer or OpenGL ES 3.2 If EXT_texture_buffer or equivalent functionality is not supported, ignore all references to buffer textures. Interactions with EXT/OES_texture_cube_map_array or OpenGL ES 3.2 If EXT_texture_cube_map_array or equivalent functionality is not supported, ignore all references to cube map array textures. Interactions with OES_texture_stencil8 or OpenGL ES 3.2 If OES_texture_stencil8 or equivalent functionality is not supported, ignore all references to stencil textures. Errors An INVALID_OPERATION error is generated by ClearTexImageEXT or ClearTexSubImageEXT if is zero or not the name of a texture object. An INVALID_OPERATION error is generated by ClearTexImageEXT or ClearTexSubImageEXT if is a buffer texture. An INVALID_OPERATION error is generated by ClearTexImageEXT or ClearTexSubImageEXT if has a compressed internal format. An INVALID_OPERATION error is generated by ClearTexImageEXT or ClearTexSubImageEXT if the base internal format is DEPTH_COMPONENT and is not DEPTH_COMPONENT. An INVALID_OPERATION error is generated by ClearTexImageEXT or ClearTexSubImageEXT if the base internal format is STENCIL_INDEX and is not STENCIL_INDEX. An INVALID_OPERATION error is generated by ClearTexImageEXT or ClearTexSubImageEXT if the base internal format is DEPTH_STENCIL and is not DEPTH_STENCIL. An INVALID_OPERATION error is generated by ClearTexImageEXT or ClearTexSubImageEXT if the base internal format is RGBA and the is DEPTH_COMPONENT, STENCIL_INDEX, or DEPTH_STENCIL. An INVALID_OPERATION error is generated by ClearTexImageEXT or ClearTexSubImageEXT if the internal format is integer and does not specify integer data. An INVALID_OPERATION error is generated by ClearTexImageEXT or ClearTexSubImageEXT if the internal format is not integer and does specify integer data. An INVALID_OPERATION error is generated if the specified subregion does not lie within the bouds of the texture image, as described for TexSubImage3D in section 8.6. An INVALID_OPERATION error is generated by ClearTexImageEXT if the image array identified by has not previously been defined. New State None. New Implementation Dependent State None. Issues See ARB_clear_texture for relevant issues. 1) How does this differ from ARB_clear_texture? RESOLVED: - Removed interactions with features not present in OpenGL ES: - 1D arrays - border texels - Removed CLEAR_TEXTURE token for GetInternalFormat* which relies on the ARB_internalformat_query2 extension which does not have equivalent functionality in OpenGL ES. - minor language updates to sync with OpenGL 4.5 language. Revision History Revision 1, 2015/08/15, thector - Initial revision Revision 2, 2016/09/16, dgkoch - added interactions with texture cube map arrays and stencil textures - added missing suffixes on commands - removed CLEAR_TEXTURE, which relies on functionality not in ES. - minor language updates to sync with OpenGL 4.5 core language. - updated some section references.