1Name 2 3 OES_shader_image_atomic 4 5Name Strings 6 7 GL_OES_shader_image_atomic 8 9Contact 10 11 Bill Licea-Kane, Qualcomm Technologies, Inc. ( billl 'at' qti.qualcomm.com ) 12 13Contributors 14 15 Jeff Bolz, NVIDIA 16 Pat Brown, NVIDIA 17 Daniel Koch, NVIDIA 18 Jon Leech 19 Barthold Lichtenbelt, NVIDIA 20 Bill Licea-Kane, AMD 21 Eric Werness, NVIDIA 22 Graham Sellers, AMD 23 Greg Roth, NVIDIA 24 Nick Haemel, AMD 25 Pierre Boudier, AMD 26 Piers Daniell, NVIDIA 27 28Notice 29 30 Copyright (c) 2011-2015 The Khronos Group Inc. Copyright termsat 31 http://www.khronos.org/registry/speccopyright.html 32 33Specification Update Policy 34 35 Khronos-approved extension specifications are updated in response to 36 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 37 extensions which have been promoted to a core Specification, fixes will 38 first appear in the latest version of that core Specification, and will 39 eventually be backported to the extension document. This policy is 40 described in more detail at 41 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 42 43Status 44 45 Complete. 46 Ratified by the Khronos Board of Promoters on 2014/03/14. 47 48Version 49 50 Last Modified Date: April 30, 2015 51 Revision: 5 52 53Number 54 55 OpenGL ES Extension #171 56 57Dependencies 58 59 This extension is written against the OpenGL ES Version 3.1 (April 29, 60 2015) Specification. 61 62 This extension is written against the OpenGL ES Shading Language 3.10, 63 Revision 3, 6 June 2014 Specification. 64 65 OpenGL ES 3.1 and GLSL ES 3.10 are required. 66 67Overview 68 69 This extension provides built-in functions allowing shaders to perform 70 atomic read-modify-write operations to a single level of a texture 71 object from any shader stage. These built-in functions are named 72 imageAtomic*(), and accept integer texel coordinates to identify the 73 texel accessed. These built-in functions extend the Images in ESSL 3.10. 74 75Additions to Chapter 7 of the OpenGL ES 3.1 specification (Programs and Shaders) 76 77 Change the first paragraph of section 7.10 "Images" on p. 113: 78 79 "Images are special uniforms used in the OpenGL ES Shading Language to 80 identify a level of a texture to be read or written using image load, 81 store, and atomic built-in functions in the manner ..." 82 83 84 Change the third paragraph of section 7.10: 85 86 "The type of an image variable must match the texture target of the image 87 currently bound to the image unit, otherwise the result of a load, 88 store, or atomic operation..." 89 90 91 Change the first sentence of section 7.11 "Shader Memory Access" on p. 92 113: 93 94 "... shader buffer variables, or to texture or buffer object memory using 95 built-in image load, store, and atomic functions operating on shader 96 image variables..." 97 98Additions to Chapter 8 of the OpenGL ES 3.1 specification (Textures and Samplers) 99 100 Change the caption to table 8.26, p. 199 101 102 "Table 8.26: Mapping of image load, store, and atomic texel..." 103 104 105 Change the first sentence of the second paragraph on p. 199: 106 107 "When a shader accesses the texture bound to an image unit using a 108 built-in image load, store or atomic function..." 109 110 111 Change the fourth paragraph: 112 113 "If the individual texel identified for an image load, store, or atomic 114 operation ... Invalid image stores will have no effect. Invalid image 115 atomics will not update any texture bound to the image unit and will 116 return zero. An access is considered invalid if..." 117 118 119 Change the first complete paragraph on p. 200: 120 121 "Additionally, there are a number of cases where image load, store, or 122 atomic operations are considered to involve a format mismatch. In such 123 cases, undefined values will be returned by image loads and atomic 124 operations, and undefined values will be written by stores and atomic 125 operations. A format mismatch will occur if:" 126 127 128 Change the last paragraph on p. 200: 129 130 "Any image variable used for shader loads or atomic memory operations 131 must be declared with a format <layout> qualifier matching ..." 132 133 134 Change the last paragraph on p. 200: 135 136 "When the format associated with an image unit does not exactly match the 137 internal format of the texture bound to the image unit, image loads, 138 stores and atomic operations re-interpret the memory holding the 139 components of an accessed texel according to the format of the image 140 unit. The re-interpretation for image loads and the read portion of 141 image atomics is performed as though data were copied from the texel of 142 the bound texture to a similar texel represented in the format of the 143 image unit. Similarly, the re-interpretation for image stores and the 144 write portion of image atomics is performed as though ..." 145 146Changes to Chapter 20 (State Tables) 147 148 Modify the description of MAX_IMAGE_UNITS in table 20.47 on p. 404: 149 150 "MAX_IMAGE_UNITS ... No. of units for image load/store/atomics" 151 152Additions to Appendix A of the OpenGL ES 3.1 specification (Invariance) 153 154 Change the third sentence of the first paragraph in section A.1, p. 408: 155 156 "This repeatability requirement doesn't apply when using shaders 157 containing side effects (image stores, image atomic operations, atomic 158 counter operations ..." 159 160 161 Change the last sentence of Rule 4 in section A.3, p. 310: 162 163 "Invariance is relaxed for shaders with side effects, such as image 164 stores, image atomic operations, or accessing atomic counters (see 165 section A.4)." 166 167 168 Change the first sentence of the second paragraph of Rule 5, p. 310: 169 170 "If a sequence of GL commands specifies primitives to be rendered with 171 shaders containing side effects (image stores, image atomic operations, 172 atomic counter operations ..." 173 174 175 Change the first sentence of Rule 6, p. 411: 176 177 "For any given GL and framebuffer state vector, and for any given GL 178 command, the contents of any framebuffer state not directly or 179 indirectly affected by results of shader image stores, image atomic 180 operations, or atomic counter operations ..." 181 182 183 Change the first bullet of Rule 7, p. 411: 184 185 "* shader invocations do not use image atomic operations or atomic 186 counters;" 187 188 189 Change the first sentence of the second paragraph of Rule 7: 190 191 "When any sequence of GL commands triggers shader invocations that 192 perform image stores, image atomic operations, atomic counter 193 operations ..." 194 195 196Modifications to the OpenGL ES 3.10 Shading Language Specification 197 198 Including the following line in a shader can be used to control the 199 language features described in this extension: 200 201 #extension GL_OES_shader_image_atomic : <behavior> 202 203 where <behavior> is as specified in section 3.3. 204 205 New preprocessor #defines are added to the OpenGL Shading Language: 206 207 #define GL_OES_shader_image_atomic 208 209 210 Modifications to Chapter 4 (Variables and Types) of the OpenGL ES 3.10 211 Shading Language Specification 212 213 Change the first sentence of the third paragraph of section 4.1.7.2 214 (Images), p. 28: 215 216 "Image variables are used in the image load, store, and 217 atomic functions described in section 8.12 ..." 218 219 220 Add to section 8.12 (Image Functions) 221 222 Add new overview and syntax and description table following existing 223 Image Functions table, p. 129: 224 225 "The atomic functions perform operations on individual texels or samples 226 of an image variable. Atomic memory operations read a value from the 227 selected texel, compute a new value using one of the operations 228 described below, write the new value to the selected texel, and return 229 the original value read. The contents of the texel being updated by the 230 atomic operation are guaranteed not to be updated by any other image 231 store or atomic function between the time the original value is read and 232 the time the new value is written. 233 234 Atomic memory operations are supported on only a subset of all image 235 variable types; <image> must be either: 236 237 * a signed integer image variable (type starts "iimage") and a format 238 qualifier of "r32i", used with a <data> argument of type "int", or 239 * an unsigned integer image variable (type starts "uimage") and a 240 format qualifier of "r32ui", used with a <data> argument of type 241 "uint", or 242 * a float image variable (type starts "image") and a format qualifier 243 of "r32f", used with a <data> argument of type "float" 244 (imageAtomicExchange only). 245 246 Add to the table of image functions, p. 129: 247 248 Syntax Description 249 ------------------------------- ------------------------------------- 250 highp uint imageAtomicAdd( Computes a new value by adding the 251 coherent IMAGE_PARAMS, value of <data> to the contents of 252 uint data); the selected texel. 253 highp int imageAtomicAdd( 254 coherent IMAGE_PARAMS, 255 int data); 256 ----------------------------------------------------------------------- 257 highp uint imageAtomicMin( Computes a new value by taking the 258 coherent IMAGE_PARAMS, minimum of the value of <data> and 259 uint data); the contents of the selected texel. 260 highp int imageAtomicMin( 261 coherent IMAGE_PARAMS, 262 int data); 263 ----------------------------------------------------------------------- 264 highp uint imageAtomicMax( Computes a new value by taking the 265 coherent IMAGE_PARAMS, maximum of the value of <data> and 266 uint data); the contents of the selected texel. 267 highp int imageAtomicMax( 268 coherent IMAGE_PARAMS, 269 int data); 270 ----------------------------------------------------------------------- 271 highp uint imageAtomicAnd( Computes a new value by performing a 272 coherent IMAGE_PARAMS, bitwise AND of the value of <data> 273 uint data); and the contents of the selected 274 highp int imageAtomicAnd( texel. 275 coherent IMAGE_PARAMS, 276 int data); 277 ----------------------------------------------------------------------- 278 highp uint imageAtomicOr( Computes a new value by performing a 279 coherent IMAGE_PARAMS, bitwise OR of the value of <data> 280 uint data); and the contents of the selected 281 highp int imageAtomicOr( texel. 282 coherent IMAGE_PARAMS, 283 int data); 284 ----------------------------------------------------------------------- 285 highp uint imageAtomicXor( Computes a new value by performing a 286 coherent IMAGE_PARAMS, bitwise EXCLUSIVE OR of the value of 287 uint data); <data> and the contents of the 288 highp int imageAtomicXor( selected texel. 289 coherent IMAGE_PARAMS, 290 int data); 291 ----------------------------------------------------------------------- 292 highp uint imageAtomicExchange( Computes a new value by simply 293 coherent IMAGE_PARAMS, copying the value of <data>. 294 uint data); 295 highp int imageAtomicExchange( 296 coherent IMAGE_PARAMS, 297 int data); 298 highp float imageAtomicExchange( 299 coherent IMAGE_PARAMS, 300 float data); 301 ----------------------------------------------------------------------- 302 highp uint imageAtomicCompSwap( Compares the value of <compare> and 303 coherent IMAGE_PARAMS, the contents of the selected texel. 304 uint compare, If the values are equal, the new 305 uint data); value is given by <data>; otherwise, 306 highp int imageAtomicCompSwap( it is taken from the original value 307 coherent IMAGE_PARAMS, loaded from the texel. 308 int compare, 309 int data); 310 ----------------------------------------------------------------------- 311 312Issues 313 314 (0) This extension is based on ARB_shader_image_load_store. What 315 are the major differences? 316 317 1 - This extension splits out only the image atomic operations 318 from ARB_shader_image_load_store. 319 2 - It depends on image load/store functionality that is part of 320 OpenGL ES 3.1, and inherits the list of differences from 321 desktop implementations in ES 3.1. Note that issue 0 of the 322 (unpublished) XXX_shader_image_load_store used for prototyping 323 ES 3.1 language contains the list explicitly; perhaps it should 324 should be reproduced here as well. 325 326 (1) Should the shading language built-ins have OES suffixes? 327 328 RESOLVED: No. Per Bug 11637, the WG made a policy decision 329 that GLSL ES identifiers imported without semantic change 330 or subsetting as OES extensions from core GLSL do not carry 331 suffixes. The #extension mechanism must still be used to 332 enable the appropriate extension before the functionality can 333 be used. 334 335Revision History 336 337 Rev. Date Author Changes 338 1 2014-01-30 wwlk Initial draft 339 2 2014-01-31 wwlk Update to current draft base specs 340 (further updates coming as 341 additional draft specs done. 342 Otherwise, this spec is probably 343 ready to review.) 344 3 2014-02-11 dkoch remove GLSL builtin suffixes per issue 1. 345 4 2014-03-04 dkoch add coherent to image parameter (Bug 11595) 346 5 2015-04-30 Jon Leech Require OpenGL ES 3.1 and remove dependency 347 on nonexistent shader_image_load_store 348 extension. Rewrite changes against the 349 published ES 3.1 / ESSL 3.10 specifications. 350 Remove references to multisampled image 351 atomic support, which does not exist in ES 352 3.1. (Bugs 13879, 13887) 353