1Name
2
3    ARB_clear_texture
4
5Name Strings
6
7    GL_ARB_clear_texture
8
9Contact
10
11    Daniel Koch, NVIDIA Corporation (dkoch 'at' nvidia.com)
12
13Contributors
14
15    Graham Sellers, AMD
16    Jonathan Putsman, Imagination
17    Ian Rominick, Intel
18    Jeff Bolz, NVIDIA
19    Pat Brown, NVIDIA
20    Piers Daniel, NVIDIA
21    James Helferty, NVIDIA
22    Members of the ARB working group
23
24Notice
25
26    Copyright (c) 2013 The Khronos Group Inc. Copyright terms at
27        http://www.khronos.org/registry/speccopyright.html
28
29Status
30
31    Complete. Approved by the ARB on June 3, 2013.
32    Ratified by the Khronos Board of Promoters on July 19, 2013.
33
34Version
35
36    Last Modified Date: August 12, 2013
37    Revision: 16
38
39Number
40
41    ARB Extension #145
42
43Dependencies
44
45    OpenGL 1.3 is required.
46
47    This extension is written against the OpenGL 4.3 (Core Profile)
48    Specification (October 18, 2012).
49
50    This extension interacts with EXT_texture_integer.
51
52    This extension interacts with ARB_texture_buffer_object.
53
54    This extension interacts with ARB_texture_multisample.
55
56    This extension interacts with ARB_depth_texture.
57
58    This extension interacts with EXT_packed_depth_stencil and
59    ARB_framebuffer_object.
60
61    This extension interacts with ARB_texture_stencil8.
62
63    This extension interacts with ARB_shader_image_load_store.
64
65    This extension interacts with ARB_internalformat_query2.
66
67Overview
68
69    Texture objects are fundamental to the operation of OpenGL. They are
70    used as a source for texture sampling and destination for rendering
71    as well as being accessed in shaders for image load/store operations
72    It is also possible to invalidate the contents of a texture. It is
73    currently only possible to set texture image data to known values by
74    uploading some or all of a image array from application memory or by
75    attaching it to a framebuffer object and using the Clear or ClearBuffer
76    commands.
77
78    Both uploading initial texture data and clearing by attaching to a
79    framebuffer have potential disadvantages when one simply wants to
80    initialize texture data to a known value. Uploading initial data
81    requires the application to allocate a (potentially large) chunk
82    of memory and transferring that to the GL.  This can be a costly
83    operation both in terms of memory bandwidth and power usage.
84    Alternatively, attaching a texture level to a framebuffer to clear it
85    may not be possible if the texture format isn't supported for
86    rendering, or even if it is, attaching the image to a framebuffer object
87    may cause the texture to be allocated in certain types of memory, which
88    it may otherwise not need to be placed in.
89
90    This extension solves these problems by providing a mechanism whereby
91    the contents of a texture image array can be set to known values by
92    using the ClearTexImage or ClearTexSubImage commands.  These commands
93    can also be useful for initializing an image that will be used for
94    atomic shader operations.
95
96IP Status
97
98    No known IP claims.
99
100New Procedures and Functions
101
102    void ClearTexImage(uint texture, int level,
103                       enum format, enum type,
104                       const void * data);
105
106    void ClearTexSubImage(uint texture, int level,
107                          int xoffset, int yoffset, int zoffset,
108                          sizei width, sizei height, sizei depth,
109                          enum format, enum type,
110                          const void * data);
111
112New Types
113
114    None
115
116New Tokens
117
118    Accepted by the <pname> parameter for GetInternalformativ and
119    GetInternalformati64v:
120
121        CLEAR_TEXTURE           0x9365
122
123Additions to Chapter 7 of the OpenGL 4.3 (Core Profile) Specification
124
125    In section 7.12.2 (Shader Memory Access Synchronization) edit the
126    description of the TEXTURE_UPDATE_BARRIER_BIT to add ClearTexImage
127    and ClearTexSubImage to the list of commands that can write to
128    texture images.
129
130Additions to Chapter 8 of the OpenGL 4.3 (Core Profile) Specification
131(Textures and Samplers)
132
133    Add a new Section 8.x (Clearing Texture Image Data) after
134    Section 8.20 (Invalidating Texture Image Data):
135
136    "All or part of a texture image may be filled with a constant value
137    by calling the command
138
139      void ClearTexSubImage(uint texture, int level,
140                            int xoffset, int yoffset, int zoffset,
141                            sizei width, sizei height, sizei depth,
142                            enum format, enum type,
143                            const void * data);
144
145    with <texture> and <level> indicating which texture array image is being
146    cleared.  It is an error if <texture> is zero or not the name of a texture
147    object, if <texture> is a buffer texture, or if the texture image has
148    a compressed internal format.
149
150    Arguments <xoffset>, <yoffset>, and <zoffset> specify the lower left
151    texel coordinates of a <width>-wide by <height>-high by <depth>-deep
152    rectangular subregion of the texel array and are interpreted as they
153    are in TexSubImage3D as described in section 8.6 (Alternate Texture
154    Image Specification Commands).
155
156    For 1D array textures, <yoffset> is interpreted as the first layer to be
157    cleared and <height> is the number of layers to clear. For 2D array
158    textures, <zoffset> is interpreted as the first layer to be cleared
159    and <depth> is the number of layers to clear. Cube map textures are
160    treated as an array of six slices in the z-dimension, where the value
161    of <zoffset> is interpreted as specifying the cube map face for the
162    corresponding <layer> in table 9.3 (Layer numbers for cube map texture
163    faces) and <depth> is the number of faces to clear. For cube map array
164    textures, <zoffset> is the first layer-face to clear, and <depth> is the
165    number of layer-faces to clear. Each layer-face is translated into an
166    array layer and a cube map face as described for layer-face numbers in
167    section 8.5.3.
168
169    Negative values of <xoffset>, <yoffset>, and <zoffset> correspond
170    to the coordinates of border texels, addressed as in Figure 8.3.
171    Taking <w_s>, <h_s>, <d_s>, <w_b>, <h_b>, and <d_b> to be the specified
172    width, height, depth, and the border width, border height, and border
173    depth of the texel array and taking <x>, <y>, <z>, <w>, <h>, and <d> to
174    be the <xoffset>, <yoffset>, <zoffset>, <width>, <height>, and <depth>
175    argument values, any of the following relationships generate an error:
176              <x> < - <w_b>
177        <x> + <w> > <w_s> - <w_b>
178              <y> < - <h_b>
179        <y> + <h> > <h_s> - <h_b>
180              <z> < - <d_b>
181        <z> + <d> > <d_s> - <d_b>
182    For texture types that do not have certain dimensions, this
183    command treats those dimensions as having a size of 1.  For example,
184    to clear a portion of a two-dimensional texture, the application would
185    use <zoffset> equal to zero and <depth> equal to one.
186
187    <format> and <type> specify the format and type of the source
188    data and are interpreted as they are for TexImage3D, as described in
189    section 8.4.4 (Transfer of Pixel Rectangles). Textures with a base
190    internal format of DEPTH_COMPONENT, STENCIL_INDEX, or DEPTH_STENCIL
191    require depth component, stencil, or depth/stencil component data
192    respectively. Textures with other base internal formats require RGBA
193    formats. Textures with integer internal formats (see table 8.12) require
194    integer data.
195
196    <data> is a pointer to an array of between one and four components of
197    texel data that will be used as the source for the constant fill value.
198    The elements of <data> are converted by the GL into the
199    <internalformat> of the texture image (that was specified when the level
200    was defined by any of the TexImage, TexStorage or CopyTexImage
201    commands) in the manner described in section 8.4.4 (Transfer of Pixel
202    Rectangles), and then used to fill the specified range of the
203    destination texture level.  If <data> is NULL, then the pointer is
204    ignored and the sub-range of the texture image is filled with zeros.
205    If <texture> is a multisample texture, all the samples in a texel
206    are cleared to the same value, that which was specified by <data>.
207
208    Errors
209
210    An INVALID_OPERATION error is generated if <texture> is zero or not the
211    name of a texture object.
212    An INVALID_OPERATION error is generated if <texture> is a buffer texture.
213    An INVALID_OPERATION error is generated if <texture> has a compressed
214    internal format.
215    An INVALID_OPERATION error is generated if the base internal format is
216    DEPTH_COMPONENT and <format> is not DEPTH_COMPONENT.
217    An INVALID_OPERATION error is generated if the base internal format is
218    DEPTH_STENCIL and <format> is not DEPTH_STENCIL.
219    An INVALID_OPERATION error is generated if the base internal format is
220    STENCIL_INDEX and <format> is not STENCIL_INDEX.
221    An INVALID_OPERATION error is generated if the base internal format is
222    RGBA and the <format> is DEPTH_COMPONENT, STENCIL_INDEX, or DEPTH_STENCIL.
223    An INVALID_OPERATION error is generated if the internal format is integer
224    and <format> does not specify integer data.
225    An INVALID_OPERATION error is generated if the internal format is
226    not integer and <format> does specify integer data.
227    An INVALID_OPERATION error is generated if the <xoffset>, <yoffset>,
228    <zoffset>, <width>, <height>, and <depth> parameters (or combinations
229    thereof) fall outside the defined texture image array (including border,
230    if any).
231
232    The command
233
234      void ClearTexImage(uint texture, int level,
235                         enum format, enum type,
236                         const void * data);
237
238    is equivalent to calling ClearTexSubImage with <xoffset>, <yoffset>,
239    and <zoffset> equal to -<b> and <width>, <height>, and <depth> equal
240    to the dimensions of the texture image plus 2x<b> (or zero and one
241    for dimensions the texture doesn't have).
242
243    Errors
244
245    An INVALID_OPERATION error is generated if the image array identified by
246    <level> has not previously been defined by a TexImage* or TexStorage*
247    command."
248
249Additions to Chapter 22 of the OpenGL 4.3 (Core Profile) Specification
250
251    In section 22.3 add the following to the list of <pname> values accepted
252    by GetInternalformativ and GetInternalformati64v:
253
254        CLEAR_TEXTURE: The support for using the resource with the
255        ClearTex*Image commands is returned in <params>.  Possible values
256        returned are FULL_SUPPORT, CAVEAT_SUPPORT, or NONE.  If the resource
257        or operation is not supported, NONE is returned.
258
259Additions to the AGL/EGL/GLX/WGL Specifications
260
261    None
262
263Dependencies on EXT_texture_integer
264
265    If EXT_texture_integer or equivalent functionality is not supported,
266    ignore all references to integer textures.
267
268Dependencies on ARB_texture_buffer_object
269
270    If ARB_texture_buffer_object of equivalent functionality is not supported,
271    ignore all references to buffer textures.
272
273Dependencies on ARB_texture_multisample
274
275    If ARB_texture_multisample or equivalent functionality is not supported,
276    ignore all references to multisample textures.
277
278Dependencies on ARB_depth_texture
279
280    If ARB_depth_texture or equivalent functionality is not supported,
281    ignore all references to depth textures and depth component formats.
282
283Dependencies on EXT_packed_depth_stencil and ARB_framebuffer_object
284
285    If EXT_packed_depth_stencil, ARB_framebuffer_object, or equivalent
286    functionality is not supported, ignore all refereces to depth/stencil
287    textures and depth/stencil components.
288
289Dependencies on ARB_texture_stencil8
290
291    If ARB_texture_stencil8 or equivalent functionality is not supported,
292    ignore all references to stencil textures and stencil index formats.
293
294Dependencies on ARB_shader_image_load_store
295
296    If ARB_shader_image_load_store or equivalent functionality is not
297    supported, ignore the references to TEXTURE_UPDATE_BARRIER_BIT and
298    edits to section 7.12.2.
299
300Dependencies on ARB_internalformat_query2
301
302    If ARB_internalformat_query2 or equivalent functionality is not
303    supported, ignore the references GetInternalformat* and the CLEAR_TEXTURE
304    enum is not added.
305
306Errors
307
308    An INVALID_OPERATION error is generated by ClearTexImage or
309    ClearTexSubImage if <texture> is zero or not the name of a texture object.
310
311    An INVALID_OPERATION error is generated by ClearTexImage or
312    ClearTexSubImage if <texture> is a buffer texture.
313
314    An INVALID_OPERATION error is generated by ClearTexImage or
315    ClearTexSubImage if <texture> has a compressed internal format.
316
317    An INVALID_OPERATION error is generated by ClearTexImage or
318    ClearTexSubImage if the base internal format is DEPTH_COMPONENT and
319    <format> is not DEPTH_COMPONENT.
320
321    An INVALID_OPERATION error is generated by ClearTexImage or
322    ClearTexSubImage if the base internal format is STENCIL_INDEX and
323    <format> is not STENCIL_INDEX.
324
325    An INVALID_OPERATION error is generated by ClearTexImage or
326    ClearTexSubImage if the base internal format is DEPTH_STENCIL and
327    <format> is not DEPTH_STENCIL.
328
329    An INVALID_OPERATION error is generated by ClearTexImage or
330    ClearTexSubImage if the base internal format is RGBA and the <format>
331    is DEPTH_COMPONENT, STENCIL_INDEX, or DEPTH_STENCIL.
332
333    An INVALID_OPERATION error is generated by ClearTexImage or
334    ClearTexSubImage if the internal format is integer and <format> does not
335    specify integer data.
336
337    An INVALID_OPERATION error is generated by ClearTexImage or
338    ClearTexSubImage if the internal format is not integer and <format>
339    does specify integer data.
340
341    An INVALID_OPERATION error is generated by ClearTexSubImage if the
342    <xoffset>, <yoffset>, <zoffset>, <width>, <height>, and <depth>
343    parameters (or combinations thereof) fall outside the defined texture
344    image array (including border, if any).
345
346    An INVALID_OPERATION error is generated by ClearTexImage if the
347    image array identified by <level> has not previously been defined.
348
349New State
350
351    None.
352
353New Implementation Dependent State
354
355    None.
356
357Sample Code
358
359    TBD
360
361Conformance Tests
362
363    Needed.
364
365Issues
366
367    1. Should these commands use <target> or <name> to specify the object?
368
369    DISCUSSION: TexImage/TexSubImage pass in a target and operate on the
370    object that is currently bound to that target. However the
371    InvalidateTexImage/InvalidateTexSubImage commands operate on a named
372    object. A target would be necessary if ClearTex*Image supported
373    defining new textures. It does not support this. It could also be
374    useful for clearing only one face of a cube map - if this is useful
375    this can be accomplished by creating a 2D texture which is view of one
376    face of a cube map.
377
378    RESOLVED. We will use named objects and be consistent with
379    the InvalidateTexImage entry points.
380
381    2. Should scissor and viewport settings be respected?
382
383    DISCUSSION: The scissor and viewport settings really have no meaning
384    with respect to a texture that is not attached to a framebuffer object.
385    D3D11's ClearRenderTargetView also does not apply scissor or viewport.
386
387    RESOLVED. Scissor and viewport are not relevant to this command.
388
389    3. Should we support clearing only a portion of a texture?
390
391    RESOLVED. Yes, it seems like it would be useful functionality.
392
393    4. How many command variants do we need? We may want to provide
394    integer, unsigned integer, or floating-point data. Is a void
395    parameter sufficient, or do we need to use different commands
396    similar to ClearBuffer?
397
398    RESOLVED. Similar to the initial texure data specification via
399    TexSubImage, a single command is provided. The format and type
400    parameters specify how the data should be interpreted, and enough
401    data needs to provided to completely define one texel. This operates
402    similarly to the ClearBufferData commands.
403
404    5. Should depth/stencil textures be supported? If so, are the depth
405    and stencil values provided separately?
406
407    RESOLVED. Depth/stencil textures are supported in the same manner
408    they are for TexSubImage.  The format and type describe how the
409    data is interpreted.
410
411    6. Should compressed textures be supported? If so, does a whole
412    block of data need to be specified?
413
414    DISCUSSION. For many compressed formats it may be fairly straight
415    forward for a driver to construct a block based on a single value.
416    It is unclear if this applies to all formats or not. In any case,
417    if compressed textures are supported, the sub region that is cleared
418    is required to be aligned on with block boundaries.
419
420    RESOLUTION: No. Compressed textures are not support. Not all formats
421    support runtime compression so providing uncompressed data would not
422    be viable. Providing a single block of compressed data may be possible
423    but then it would have to be aligned to block boundaries and this becomes
424    more of a sub-image command than a clear operation. This does not seem
425    to have a compelling use-case so it is not being added at this time. It
426    can always be added in a layered extension if desired.
427
428    7. Should we add an entry point for renderbuffers?
429
430    RESOLVED. No. At this point there is really no use case that
431    renderbuffers support that cannot be supported by multisample textures.
432    Thus in order to avoid aggrandizing renderbuffers, this will not be
433    provided.  Additionally, renderbuffers are by definition renderable,
434    and thus they can be cleared by the standard mechanisms without affecting
435    memory allocation patterns.
436
437    8. Should these commands support support loading <data> from the pixel
438    unpack buffer (ie PBO) or only client memory?
439
440    RESOLVED. ClearTex*Image only supports <data> in client memory, like the
441    comparable ClearBuffer*Data commands. There seems to be little value in
442    supporting buffer-backed sources when there is only one texels' worth of
443    data to upload. If the worst case (RGBA32F) it is only 16 bytes of data.
444
445    9. How does clearing multisample textures work?
446
447    RESOLVED: As with regular textures, the dimensions are specified in texels.
448    All the samples in a texel are cleared to the same values, ie the one set
449    of values which are provided in <data>.
450
451    10. Does conditional rendering interact with the ClearTex*Image commands?
452
453    RESOLVED: No. This is treated in a similar manner to the TexSubImage
454    commands rather than the other image clearing commands and is thus not
455    affected by conditional rendering.  This is similar to the clear buffer
456    data commands.
457
458    11. Would there be any benefit to providing some form of colormask style
459    behavior?
460
461    RESOLVED: No. This is intended to be a simple operation like memset.
462    If more complicated behaviour is required, one of the other mechanisms
463    for specifying texture image data should be used.
464
465    12. Can ClearTexImage be used on buffer textures?
466
467    RESOLVED: No. In the same way that TexSubImage cannot be used for
468    buffer textures, neither can ClearTexImage.  The ClearBuffer{Sub}Data
469    commands can be used for this purpose.
470
471    13. What happens if the subregion to be cleared is larger than the defined
472    texture level's size?
473
474    RESOLVED: This is an error similar to TexSubImage3D.
475
476    14. What about texture zero?
477
478    RESOLVED: Which one? There are many zero textures (one of each target type).
479    Since these commands don't distinguish based on target, this is an error.
480    Also we really don't want to aggrandize texture zero.
481
482    15. What happens for undefined levels?
483
484    RESOLVED: This depends on the command.  An undefined level will have
485    width, height, and depth of zero, and thus a ClearTexSubImage command with
486    a non-zero sized clear region will fail the bounds check and result in
487    an INVALID_OPERATION. A zero-sized clear region with no-offset is allowed,
488    but is a no-op. ClearTexImage though, is defined in terms of
489    ClearTexSubImage called with appropriate dimensions and offsets. Since
490    it's unclear how many dimensions an undefined level would have, we've
491    defined this to be an error.
492
493    16. What happens for incomplete textures?
494
495    RESOLVED: Incomplete textures do not affect the behaviour of these commands
496    since they operate on individual levels.  However see Issue 15 for
497    behaviour on undefined levels.
498
499    17. How does ClearTexture interact with the (compatibility) GENERATE_MIPMAP
500    texture state?
501
502    RESOLVED: It doesn't (i.e. it doesn't provoke automatic mipmap generation).
503    In general the policy is that new functionality doesn't need to interact with
504    legacy functionality. This also falls out of the way the spec is written
505    since section 8.14.5 on automatic mipmap generation says it applies to the
506    image specification operations defined in sections 8.5 to 8.7. ClearTexture
507    is defined in section 8.21.
508
509Revision History
510
511    Revision 16, 2013/08/12, Jon Leech
512        - Clarify issue 8 (public bug 934).
513    Revision 15, 2013/06/25, dgkoch
514        - assign value for GL_CLEAR_TEXTURE
515    Revision 14, 2013/06/21, dgkoch
516        - add CLEAR_TEXTURE for GetInternalformat* query.
517    Revision 13, 2013/06/04, dgkoch
518      - add issue 17.
519    Revision 12, 2013/05/30, Jon Leech
520      - Move new error to per-command Errors section.
521    Revision 11, 2013/05/30, dgkoch
522      - Add Issues 15, 16. Add error for ClearTexImage on undefined levels.
523      - fix naming of ARB_texture_stencil8 dependency.
524    Revision 10, 2013/05/30, Jon Leech
525      - Remove (some) redundant error descriptions from inline spec language
526        and simplify description of layer-faces.
527    Revision 9, 2013/05/29, dgkoch
528      - change error back to INVALID_OP
529    Revision 8, 2013/05/29, dgkoch
530      - added general error conditions to command description
531      - change error for non-texture names to be INVALID_VALUE
532      - minor grammatical and formatting fixes.
533    Revision 7, 2013/05/29, dgkoch
534      - add interaction with ARB_shader_image_load_store / MemoryBarrier
535    Revision 6, 2013/05/02, dgkoch
536      - add interaction with stencil textures
537      - fix typos and formatting
538    Revision 5, 2013/04/23, dgkoch
539      - fix more typos, confirm out of bounds error
540    Revision 4, 2013/04/22, dgkoch
541      - resolved issue 13, and update language appropriately
542      - add error for texture zero, remove error for undefined levels
543      - fix typos
544    Revision 3, 2013/04/21, dgkoch
545      - various formatting fixes
546      - add dependencies
547      - flesh out a lot of spec language instead of referring to other sections
548      - add error conditions
549      - allow larger dimensions than the texture image array.
550      - Resolved issues 6,7,10,11
551      - Added issues 12,13.
552    Revision 2, 2013/03/13, dgkoch
553      - Added issues 9,10,11
554      - Resolved issues 1,2,3,4,5,8,9
555      - update contact & contributors
556    Revision 1, 2013/01/15, dgkoch
557      - Initial revision
558