1Name
2
3    EXT_clear_texture
4
5Name Strings
6
7    GL_EXT_clear_texture
8
9Contact
10
11    Tobias Hector, Imagination Technologies (tobias.hector 'at' imgtec.com)
12
13Contributors
14
15    Contributors to the original ARB_clear_texture
16    Ian Romanick
17    Daniel Koch
18
19Notice
20
21    Copyright (c) 2013 The Khronos Group Inc. Copyright terms at
22        http://www.khronos.org/registry/speccopyright.html
23
24Status
25
26    Draft
27
28Version
29
30    Last Modified Date: September 16, 2016
31    Revision: 2
32
33Number
34
35    OpenGL ES Extension #269
36
37Dependencies
38
39    OpenGL ES 3.1 is required.
40
41    This extension is written against the OpenGL ES 3.1 API specification.
42
43    This extension interacts with EXT/OES_texture_buffer or OpenGL ES 3.2.
44
45    This extension interacts with EXT/OES_texture_cube_map_array or
46    OpenGL ES 3.2.
47
48    This extension interacts with OES_texture_stencil8 or OpenGL ES 3.2.
49
50Overview
51
52    Texture objects are fundamental to the operation of OpenGL. They are
53    used as a source for texture sampling and destination for rendering
54    as well as being accessed in shaders for image load/store operations
55    It is also possible to invalidate the contents of a texture. It is
56    currently only possible to set texture image data to known values by
57    uploading some or all of a image array from application memory or by
58    attaching it to a framebuffer object and using the Clear or ClearBuffer
59    commands.
60
61    Both uploading initial texture data and clearing by attaching to a
62    framebuffer have potential disadvantages when one simply wants to
63    initialize texture data to a known value. Uploading initial data
64    requires the application to allocate a (potentially large) chunk
65    of memory and transferring that to the GL.  This can be a costly
66    operation both in terms of memory bandwidth and power usage.
67    Alternatively, attaching a texture level to a framebuffer to clear it
68    may not be possible if the texture format isn't supported for
69    rendering, or even if it is, attaching the image to a framebuffer object
70    may cause the texture to be allocated in certain types of memory, which
71    it may otherwise not need to be placed in.
72
73    This extension solves these problems by providing a mechanism whereby
74    the contents of a texture image array can be set to known values by
75    using the ClearTexImageEXT or ClearTexSubImageEXT commands.  These commands
76    can also be useful for initializing an image that will be used for
77    atomic shader operations.
78
79IP Status
80
81    No known IP claims.
82
83New Procedures and Functions
84
85    void ClearTexImageEXT(uint texture, int level,
86                          enum format, enum type,
87                          const void * data);
88
89    void ClearTexSubImageEXT(uint texture, int level,
90                             int xoffset, int yoffset, int zoffset,
91                             sizei width, sizei height, sizei depth,
92                             enum format, enum type,
93                             const void * data);
94
95New Types
96
97    None
98
99New Tokens
100
101    None
102
103Additions to Chapter 7 of the OpenGL ES 3.1 API Specification (Programs and
104Shaders)
105
106    In section 7.11.2 (Shader Memory Access Synchronization) edit the
107    description of the TEXTURE_UPDATE_BARRIER_BIT to add ClearTexImageEXT
108    and ClearTexSubImageEXT to the list of commands that can write to
109    texture images.
110
111Additions to Chapter 8 of the OpenGL ES 3.1 API Specification (Textures and
112Samplers)
113
114    Add a new Section 8.x (Clearing Texture Image Data) after
115    Section 8.17 (Immutable-Format Texture Images):
116
117    "All or part of a texture image may be filled with a constant value
118    by calling the command
119
120      void ClearTexSubImageEXT(uint texture, int level,
121                               int xoffset, int yoffset, int zoffset,
122                               sizei width, sizei height, sizei depth,
123                               enum format, enum type,
124                               const void * data);
125
126    with <texture> and <level> indicating which texture array image is being
127    cleared.  It is an error if <texture> is zero or not the name of a texture
128    object, if <texture> is a buffer texture, or if the texture image has
129    a compressed internal format.
130
131    Arguments <xoffset>, <yoffset>, and <zoffset> specify the lower left
132    texel coordinates of a <width>-wide by <height>-high by <depth>-deep
133    rectangular subregion of the texel array and are interpreted as they
134    are in TexSubImage3D as described in section 8.6 (Alternate Texture
135    Image Specification Commands). The subregion must lie within the bounds
136    of the texture image, as described in that section.
137
138    For 2D array textures, <zoffset> is interpreted as the first layer to be
139    cleared and <depth> is the number of layers to clear. Cube map textures are
140    treated as an array of six slices in the z-dimension, where the value
141    of <zoffset> is interpreted as specifying the cube map face for the
142    corresponding <layer> in table 8.25 (Layer numbers for cube map texture
143    faces) and <depth> is the number of faces to clear. For cube map array
144    textures, <zoffset> is the first layer-face to clear, and <depth> is the
145    number of layer-faces to clear. Each layer-face is translated into an
146    array layer and a cube map face as described for layer-face numbers in
147    section 8.5.3 [in OpenGL ES 3.2].
148
149    For texture types that do not have certain dimensions, this
150    command treats those dimensions as having a size of 1.  For example,
151    to clear a portion of a two-dimensional texture, the application would
152    use <zoffset> equal to zero and <depth> equal to one.
153
154    <format> and <type> specify the format and type of the source
155    data and are interpreted as they are for TexImage3D, as described in
156    section 8.4.2 (Transfer of Pixel Rectangles). Textures with a base
157    internal format of DEPTH_COMPONENT, STENCIL_INDEX, or DEPTH_STENCIL
158    require depth component, stencil, or depth/stencil component data
159    respectively. Textures with other base internal formats require RGBA
160    formats. Textures with integer internal formats (see table 8.13) require
161    integer data.
162
163    <data> is a pointer to an array of between one and four components of
164    texel data that will be used as the source for the constant fill value.
165    The elements of <data> are converted by the GL into the
166    <internalformat> of the texture image (that was specified when the level
167    was defined by any of the TexImage, TexStorage or CopyTexImage
168    commands) in the manner described in section 8.4.2 (Transfer of Pixel
169    Rectangles), and then used to fill the specified range of the
170    destination texture level.  If <data> is NULL, then the pointer is
171    ignored and the sub-range of the texture image is filled with zeros.
172    If <texture> is a multisample texture, all the samples in a texel
173    are cleared to the value specified by <data>.
174
175    Errors
176
177        An INVALID_OPERATION error is generated if <texture> is zero or not the
178        name of a texture object.
179
180        An INVALID_OPERATION error is generated if <texture> is a buffer
181        texture.
182
183        An INVALID_OPERATION error is generated if <texture> has a compressed
184        internal format.
185
186        An INVALID_OPERATION error is generated if the base internal format is
187        DEPTH_COMPONENT and <format> is not DEPTH_COMPONENT.
188
189        An INVALID_OPERATION error is generated if the base internal format is
190        DEPTH_STENCIL and <format> is not DEPTH_STENCIL.
191
192        An INVALID_OPERATION error is generated if the base internal format is
193        STENCIL_INDEX and <format> is not STENCIL_INDEX.
194
195        An INVALID_OPERATION error is generated if the base internal format is
196        RGBA and the <format> is DEPTH_COMPONENT, STENCIL_INDEX, or
197        DEPTH_STENCIL.
198
199        An INVALID_OPERATION error is generated if the internal format is
200        integer and <format> does not specify integer data.
201
202        An INVALID_OPERATION error is generated if the internal format is
203        not integer and <format> does specify integer data.
204
205        An INVALID_OPERATION error is generated if the specified subregion
206        does not lie within the bounds of the texture image, as described
207        for TexSubImage3D in section 8.6.
208
209    The command
210
211      void ClearTexImageEXT(uint texture, int level,
212                            enum format, enum type,
213                            const void * data);
214
215    is equivalent to calling ClearTexSubImageEXT with <xoffset>, <yoffset>,
216    and <zoffset> equal to 0 and <width>, <height>, and <depth> equal
217    to the dimensions of the texture image (or zero and one for dimensions
218    the texture doesn't have).
219
220    Errors
221
222        In addition to the errors generated by ClearTexSubImageEXT:
223
224        An INVALID_OPERATION error is generated if the image array identified by
225        <level> has not previously been defined by a TexImage* or TexStorage*
226        command."
227
228Interactions with EXT/OES_texture_buffer or OpenGL ES 3.2
229
230    If EXT_texture_buffer or equivalent functionality is not supported,
231    ignore all references to buffer textures.
232
233Interactions with EXT/OES_texture_cube_map_array or OpenGL ES 3.2
234
235    If EXT_texture_cube_map_array or equivalent functionality is not supported,
236    ignore all references to cube map array textures.
237
238Interactions with OES_texture_stencil8 or OpenGL ES 3.2
239
240    If OES_texture_stencil8 or equivalent functionality is not supported,
241    ignore all references to stencil textures.
242
243Errors
244
245    An INVALID_OPERATION error is generated by ClearTexImageEXT or
246    ClearTexSubImageEXT if <texture> is zero or not the name of a texture object.
247
248    An INVALID_OPERATION error is generated by ClearTexImageEXT or
249    ClearTexSubImageEXT if <texture> is a buffer texture.
250
251    An INVALID_OPERATION error is generated by ClearTexImageEXT or
252    ClearTexSubImageEXT if <texture> has a compressed internal format.
253
254    An INVALID_OPERATION error is generated by ClearTexImageEXT or
255    ClearTexSubImageEXT if the base internal format is DEPTH_COMPONENT and
256    <format> is not DEPTH_COMPONENT.
257
258    An INVALID_OPERATION error is generated by ClearTexImageEXT or
259    ClearTexSubImageEXT if the base internal format is STENCIL_INDEX and
260    <format> is not STENCIL_INDEX.
261
262    An INVALID_OPERATION error is generated by ClearTexImageEXT or
263    ClearTexSubImageEXT if the base internal format is DEPTH_STENCIL and
264    <format> is not DEPTH_STENCIL.
265
266    An INVALID_OPERATION error is generated by ClearTexImageEXT or
267    ClearTexSubImageEXT if the base internal format is RGBA and the <format>
268    is DEPTH_COMPONENT, STENCIL_INDEX, or DEPTH_STENCIL.
269
270    An INVALID_OPERATION error is generated by ClearTexImageEXT or
271    ClearTexSubImageEXT if the internal format is integer and <format> does not
272    specify integer data.
273
274    An INVALID_OPERATION error is generated by ClearTexImageEXT or
275    ClearTexSubImageEXT if the internal format is not integer and <format>
276    does specify integer data.
277
278    An INVALID_OPERATION error is generated if the specified subregion
279    does not lie within the bouds of the texture image, as described
280    for TexSubImage3D in section 8.6.
281
282    An INVALID_OPERATION error is generated by ClearTexImageEXT if the
283    image array identified by <level> has not previously been defined.
284
285New State
286
287    None.
288
289New Implementation Dependent State
290
291    None.
292
293Issues
294
295    See ARB_clear_texture for relevant issues.
296
297    1) How does this differ from ARB_clear_texture?
298
299    RESOLVED:
300      - Removed interactions with features not present in OpenGL ES:
301        - 1D arrays
302        - border texels
303      - Removed CLEAR_TEXTURE token for GetInternalFormat* which relies
304        on the ARB_internalformat_query2 extension which does not have
305        equivalent functionality in OpenGL ES.
306      - minor language updates to sync with OpenGL 4.5 language.
307
308Revision History
309
310    Revision 1, 2015/08/15, thector
311      - Initial revision
312    Revision 2, 2016/09/16, dgkoch
313      - added interactions with texture cube map arrays and stencil textures
314      - added missing suffixes on commands
315      - removed CLEAR_TEXTURE, which relies on functionality not in ES.
316      - minor language updates to sync with OpenGL 4.5 core language.
317      - updated some section references.
318