1Name 2 3 ARB_arrays_of_arrays 4 5Name Strings 6 7 GL_ARB_arrays_of_arrays 8 9Contact 10 11 John Kessenich (cepheus 'at' frii.com) 12 13Contributors 14 15 XXX 16 17Notice 18 19 Copyright (c) 2012-2013 The Khronos Group Inc. Copyright terms at 20 http://www.khronos.org/registry/speccopyright.html 21 22Specification Update Policy 23 24 Khronos-approved extension specifications are updated in response to 25 issues and bugs prioritized by the Khronos OpenGL Working Group. For 26 extensions which have been promoted to a core Specification, fixes will 27 first appear in the latest version of that core Specification, and will 28 eventually be backported to the extension document. This policy is 29 described in more detail at 30 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 31 32Status 33 34 Complete. 35 Approved by the ARB on 2012/06/12. 36 37Version 38 39 Last Modified Date: 2012/07/01 40 Revision: 7 41 42Number 43 44 ARB Extension #120 45 46Dependencies 47 48 GLSL 1.2 is required. 49 50 OpenGL ?? (Core Profile) specification is required. (See issues.) 51 52Overview 53 54 Multi-dimensional arrays are a frequently requested feature. This extension 55 removes the restriciton that arrays cannot be formed into arrays, allowing 56 arrays of arrays to be declared. Technically, removing this restriction is 57 all that is necessary to enable this feature, but it is worthwhile showing 58 what the result of doing that looks like. 59 60 The following will be true of arrays of arrays 61 62 - They will first class objects. (They know their size, can be passed by 63 copy-in semantics to functions, etc.) 64 65 - They will only be one-dimensional arrays of other first class objects. 66 (arrays are already first class objects). 67 68 - The syntax 69 70 vec4 a[3][2]; 71 72 Declares a one-dimensional array of size 3 of one-dimensional arrays of 73 size 2 of vec4s. Also, these syntaxes do the same thing: 74 75 vec4[2] a[3]; 76 vec4[3][2] a; 77 78 or, looking at more dimensions, these are all the same 79 80 int a[1][2][3][4][5][6]; 81 82 int[1][2][3][4][5][6] a; 83 84 int[4][5][6] a[1][2][3]; 85 86 note this latter is equivalent to C, in meaning the same thing, if done as 87 88 typedef int int456[4][5][6]; 89 90 int456 a[1][2][3]; 91 92 that is, this GLSL proposal matches C behavior in this way. The type needed for 93 both constructors and nameless parameters is: 94 95 int[1][2][3][4][5][6] 96 97 - This type could be declared as a formal parameter in a function prototype as 98 99 void foo(vec4[3][2]); 100 101 - Accessing is done as 102 103 a[x][y] // x selects which array of size 2 is desired 104 // y selects which vec4 is desired 105 106 a[x] // this results in a one-dimensional array, with all rights and 107 // priviledges implied 108 109 - The .length() operator works as normal: 110 111 a.length() // this is 3 112 a[x].length() // this is 2 113 114 - The constructor for the above is 115 116 vec4[3][2](vec4[2](vec4(0.0), vec4(1.0)), 117 vec4[2](vec4(0.0), vec4(1.0)), 118 vec4[2](vec4(0.0), vec4(1.0))) 119 120 - Initializers for the above are 121 122 vec4 a[3][2] = vec4[3][2](vec4[2](vec4(0.0), vec4(1.0)), 123 vec4[2](vec4(0.0), vec4(1.0)), 124 vec4[2](vec4(0.0), vec4(1.0))); 125 126 // or 127 128 vec4 a[3][2] = {vec4[2](vec4(0.0), vec4(1.0)), 129 vec4[2](vec4(0.0), vec4(1.0)), 130 vec4[2](vec4(0.0), vec4(1.0))) }; 131 132 // or 133 134 vec4 a[3][2] = {{ vec4(0.0), vec4(1.0) }, 135 { vec4(0.0), vec4(1.0) }, 136 { vec4(0.0), vec4(1.0) } }; // requires matching nesting of 137 // {} with object's hierarchy 138 139 140 Note that all the above is naturally already specified in the core 141 specification. 142 143 144New Procedures and Functions 145 146 147New Tokens 148 149 150Additions to Chapter 2 of the OpenGL 4.2 (Core Profile) Specification 151(OpenGL Operation) 152 153 154Additions to Chapter 3 of the OpenGL 4.2 (Core Profile) Specification 155(Rasterization) 156 157 None. 158 159Additions to Chapter 4 of the OpenGL 4.2 (Core Profile) Specification 160(Per-Fragment Operations and the Framebuffer) 161 162 None. 163 164Additions to Chapter 5 of the OpenGL 4.2 (Core Profile) Specification 165(Special Functions) 166 167 168Additions to Chapter 6 of the OpenGL 4.2 (Core Profile) Specification 169(State and State Requests) 170 171 None. 172 173Additions to Chapter 4 of the OpenGL Shading Language Specification, Version 1744.20 (Variables and Types) 175 176 Section 4.1.9 Arrays 177 178 Rewrite the sentences "Only one-dimensional arrays may be declared. All 179 basic types and structures can be formed into arrays." as 180 181 "Arrays only have a single dimension (a single number within "[ ]", 182 however, arrays of arrays can be declared. All types (basic types, 183 structures, arrays) can be formed into an array." 184 185 "When in transparent memory (like in a uniform block), the layout is that 186 the 'inner' (right-most in declaration) dimensions iterate faster than the 187 out dimensions. That is, for the above, the order in memory would be: 188 189 low address...a[0][0] a[0][1] a[1][0] a[1][1] a[2][0] a[2][1]...high address" 190 191 Expand the examples in this section by incorporating the declaration and 192 use content from the overview section above. 193 194 Add 195 196 vec4 a[3][2]; 197 a.length() // this is 3 198 a[x].length() // this is 2 199 200 When the *length* method will return a compile-time constant, the expression 201 in brackets (x above) will be evaluated and subject to the rules required 202 for array indexes, but the array will not be deferenced. Thus, behavior 203 is well defined even if the run-time value of the expression is out of bounds. 204 205 Remove the illegal examples of arrays of arrays. 206 207 Add the following: 208 209 "For unsized arrays, only the outermost dimension can be lacking a 210 size. A type that includes an unknown array size cannot be formed into 211 an array until it gets an explicit size." 212 213 Section 4.1.11 Initializers 214 215 Expand the examples in this section by incorporating the initializer 216 content from the overview section above. 217 218 Section 4.3.4 Input Variables 219 220 For this paragraph, keep this introductory text the same 221 222 "Some inputs and outputs are arrayed, meaning that for an interface between 223 two shader stages either the input or output declaration requires an extra 224 level of array indexing for the declarations to match. 225 226 but rewrite the remainder 227 228 "For example, with 229 the interface between a vertex shader and a geometry shader, vertex shader 230 output variables and geometry shader input variables of the same name must 231 match in type and qualification, except that the vertex shader name cannot 232 be declared as an array while the geometry shader name must be declared 233 as an array, to allow for vertex indexing. 234 It is a link error if a 235 non-arrayed input is not declared with the same type, qualification, and 236 array dimensionality as the matching output. It is an error if an arrayed 237 input is not declared as an array of the same type and qualification as the 238 corresponding (non-array) output. Symmetrically, it is an error if an 239 arrayed output is not declared as an array of the same type and 240 qualification as the corresponding (non-array) input." 241 242 instead as 243 244 "For example, with 245 the interface between a vertex shader and a geometry shader, vertex shader 246 output variables and geometry shader input variables of the same name must 247 match in type and storage qualification, except that the geometry shader will have 248 one more array dimension than the vertex shader, to allow for vertex 249 indexing. 250 If such an arrayed interface variable is not declared with the necessary 251 additional input or output array dimension, a link-time error will result." 252 253 "For non-arrayed interfaces (meaning array dimensionally stays the same between 254 stages), it is a link-time error if the input variable is not declared with the 255 same type, including array dimensionality, as the matching output variable." 256 257 Remove the following paragraph 258 259 "If the output corresponding to an arrayed input is itself an array, it 260 must appear in an output block (see interface blocks below) in the 261 outputting shader and in an input block in the inputting shader with a block 262 instance name declared as an array. This is required because two-dimensional 263 arrays are not supported." 264 265 Section 4.3.6 Output Variables 266 267 Remove the following paragraph 268 269 "As described under the section 4.3.4 'Input Variables' above, if a 270 per-vertex output of the tessellation control shader is itself an array 271 with multiple values per vertex, it must appear in an output block (see 272 interface blocks below) in the tessellation control shader with a block 273 instance name declared as an array." 274 275Additions to Chapter 5 of the OpenGL Shading Language Specification, Version 2764.20 (Built-in Variables) 277 278 Section 5.4 Array Constructors 279 280 Expand the constructor examples with the constructor examples from the 281 overview section of this specification. 282 283 Section 5.7 Structure and Array Operations 284 285 Expand the examples with the .length() and [] examples from the overview 286 section of this specification. 287 288Changes to the grammar 289 290 There are 7 pairs of rules that allowed either an empty array 291 declaration or one with a size. For example: 292 293 init_declarator_list: 294 init_declarator_list COMMA IDENTIFIER LEFT_BRACKET RIGHT_BRACKET 295 init_declarator_list COMMA IDENTIFIER LEFT_BRACKET constant_expression RIGHT_BRACKET 296 297 plus 1 rule for parameter array declarations: 298 299 parameter_declarator: 300 type_specifier IDENTIFIER LEFT_BRACKET constant_expression RIGHT_BRACKET 301 302 These 15 total (2*7 + 1) declaration rules are all replaced with 8 uses 303 of a new rule array_specifier: 304 305 array_specifier: 306 LEFT_BRACKET RIGHT_BRACKET 307 LEFT_BRACKET constant_expression RIGHT_BRACKET 308 array_specifier LEFT_BRACKET RIGHT_BRACKET 309 array_specifier LEFT_BRACKET constant_expression RIGHT_BRACKET 310 311 For example, the pair given in the example above becomes: 312 313 init_declarator_list: 314 init_declarator_list COMMA IDENTIFIER array_specifier 315 316 The LEFT_BRACKET now appears in exactly 5 rules now; the 1 for postfix 317 expressions (remains unchanged) and the 4 for array_specifier. 318 319New State 320 321 None. 322 323New Implementation Dependent State 324 325 None. 326 327Issues 328 329 3301. Do we want to support the following form as well? 331 332 vec4[3][2] a; 333 334 Probably, to match the constructor and formal parameter declaration. These 335 require that 336 337 vec4[3][2] // a valid type 338 339 is a type in its own right, and the general syntax to declare something is 340 341 <type> <name> 342 343 GLSL already has required the following since 1.2: 344 345 vec4[3] a; 346 347 RESOLUTION: Yes, allow this syntax. 348 3492. What does the enumeration API look like? Don't want to enumerate down to 350 10,000 little individual elements, want something more hierarchical instead. 351 352 This will significantly effect this extension if this extension turns into 353 defining a new discovery API. 354 355 Nested issue: What about optimizers eliminating holes in a data structure? 356 357 RESOLUTION: Belongs in another extension. 358 3593. How are large buffer/memory arrays declared? E.g., 360 361 buffer vec4 a[][2]; 362 363 RESOLUTION: Belongs in another extension. Probably will be 364 365 buffer BufferBlock { 366 vec4 a[][2]; 367 }; 368 3694. Can large memory arrays be passed by reference to a function? Want to pick 370 up pointer-like feature without full introduction of pointers. 371 372 RESOLUTION: Belongs in another extension. 373 3745. How does this extension interact with ??, which is adding the large 375 memory/buffer style arrays. 376 377 RESOLUTION: Belongs in another extension. 378 3796. Can vertex inputs be arrays of arrays? 380 381 RESOLUTION: Yes. 382 3837. Can fragment outputs be arrays of arrays? 384 385 RESOLUTION: Yes. 386 3878. Can vertex outputs be arrays of arrays? Note that some stage inputs can 388 now be arrays of arrays, due to adding a new array level to a previous 389 stage's output type. 390 391 RESOLUTION: Yes. 392 3939. Can uniforms be arrays of arrays? 394 395 RESOLUTION: Yes. 396 39710. Can interface blocks (e.g. uniform blocks) be arrays of arrays? 398 399 RESOLUTION: Yes. 400 40111. Can subroutine variables be arrays of arrays? 402 403 Recommended: Yes. 404 405 RESOLUTION: 406 40712. Do we want to eliminate the syntax? 408 409 vec4[2] a[3]; // same as vec4 a[3][2]; 410 411 It might seem the 3 and 2 should be reversed. However, thinking through how 412 precedence, the grammar, etc. all work, this is actually very well defined 413 and correct and consistent with C/C++. 414 415 RESOLUTION: Yes, allow these syntaxes. 416 417Revision History 418 419 Rev. Date Author Changes 420 ---- -------- -------- ----------------------------------------- 421 7 1-Jul-2012 JohnK Added grammar changes. 422 6 10-May-2012 JohnK Editorial fixes before merging into core spec. 423 5 16-Mar-2012 JohnK Update with resolutions from language meeting 424 (Generally, allow arrays of arrays for most I/O, 425 and allow the syntaxes that naturally fall out.) 426 4 24-Feb-2012 JohnK Minor clarifications within issues. 427 3 3-Feb-2012 JohnK Fix reversed 2/3, add new example, resolve issues 2-5 428 2 1-Feb-2012 JohnK Flesh out with specification language 429 1 1-Feb-2012 JohnK Initial revision 430