1Name 2 3 ARB_explicit_uniform_location 4 5Name Strings 6 7 GL_ARB_explicit_uniform_location 8 9Contact 10 11 Piers Daniell, NVIDIA (pdaniell 'at' nvidia.com) 12 13Contributors 14 15 Bruce Merry 16 Christophe Riccio, AMD 17 Pat Brown, NVIDIA 18 19Notice 20 21 Copyright (c) 2012-2013 The Khronos Group Inc. Copyright terms at 22 http://www.khronos.org/registry/speccopyright.html 23 24Specification Update Policy 25 26 Khronos-approved extension specifications are updated in response to 27 issues and bugs prioritized by the Khronos OpenGL Working Group. For 28 extensions which have been promoted to a core Specification, fixes will 29 first appear in the latest version of that core Specification, and will 30 eventually be backported to the extension document. This policy is 31 described in more detail at 32 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 33 34Status 35 36 Complete. 37 Approved by the ARB on 2012/06/12. 38 39Version 40 41 Last Modified Date: 05/15/2012 42 Revision: 6 43 44Number 45 46 ARB Extension #128 47 48Dependencies 49 50 Requires OpenGL 3.3 or ARB_explicit_attrib_location. 51 52 This extension interacts with ARB_shader_subroutine. 53 54 This extension is written against the OpenGL 4.2 (Compatibility Profile) 55 and the OpenGL Shading Language 4.20.11 specification. 56 57Overview 58 59 This extension provides a method to pre-assign uniform locations to 60 uniform variables in the default uniform block, including subroutine 61 uniforms. This allows an application to modify the uniform values without 62 requiring a GL query like GetUniformLocation, GetSubroutineUniformLocation 63 and GetSubroutineIndex. 64 65IP Status 66 67 No known IP claims. 68 69New Procedures and Functions 70 71 None 72 73New Tokens 74 75 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 76 GetFloatv, GetDoublev, and GetInteger64v: 77 78 MAX_UNIFORM_LOCATIONS 0x826E 79 80Additions to Chapter 2 of the OpenGL 4.2 Specification (OpenGL Operation) 81 82 Section 2.14.7 "Uniform Variables": 83 84 Modify the third paragraph on page 114 to read: 85 86 "When a program is successfully linked, all active uniforms, except for 87 atomic counters, belonging to the program object's default uniform block 88 are initialized as defined by the version of the OpenGL Shading Language 89 used to compile the program. A successful link will also generate a 90 location for any active uniform in the default uniform block which don't 91 already have an explicit location defined in the shader. The generated 92 locations will never take the location of a uniform with an explicit 93 location defined in the shader, even if that uniform is determined to 94 be inactive. The values of active uniforms in the default uniform block 95 can be changed using this location and the appropriate Uniform* command 96 (see below). These generated locations are invalidated and new ones 97 assigned after each successful re-link. The explicitly defined locations 98 and the generated locations must be in the range of 0 to 99 MAX_UNIFORM_LOCATIONS minus one." 100 101 Section 2.14.8 "Subroutine Uniform Variables": 102 103 Modify the last paragraph on page 136 to read: 104 105 "The command 106 107 int GetSubroutineUniformLocation(uint program, enum shadertype, 108 const char *name); 109 110 will return the location of the subroutine uniform variable <name> in the 111 shader stage of type <shadertype> attached to <program>, with behavior 112 otherwise identical to GetUniformLocation. The value -1 will be returned 113 if <name> is not the name of an active subroutine uniform. The subroutine 114 uniform may have an explicit location specified in the shader. At link 115 time, all active subroutine uniforms without an explicit location will be 116 assigned a unique location. The value ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS 117 is the largest assigned or generated location plus one. An assigned 118 location will never take the location of an explicitly assigned location 119 in, even if that subroutine uniform is inactive. Between the location 0 120 and ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS minus one there may be unused 121 locations either because they weren't assigned a subroutine uniform or 122 because the subroutine uniform was determined to be inactive by the 123 linker. These locations will be ignored when assigning the subroutine 124 index as described below. 125 126 There is an implementation-dependent limit on the number of active 127 subroutine uniform locations in each shader stage; a program will fail 128 to link if the number of subroutine uniform locations required is greater 129 than the value of MAX_SUBROUTINE_UNIFORM_LOCATIONS or if an explicit 130 subroutine uniform location is outside this limit. If <program> has not 131 been successfully linked, the error INVALID_OPERATION will be generated. 132 For active subroutine uniforms declared as arrays, the declared array 133 elements are assigned consecutive locations. 134 135 Each function in a shader associated with a subroutine type is considered 136 an active subroutine, unless the compiler conclusively determines that 137 the function could never be assigned to an active subroutine uniform. 138 The subroutine functions can be assigned an explicit index in the shader 139 between 0 and MAX_SUBROUTINES minus one. At link time, all active 140 subroutines without an explicit index will be assigned an index between 0 141 and ACTIVE_SUBROUTINES minus one. An assigned index will never take the 142 same index of an explicitly assigned index in the shader, even if that 143 subroutine is inactive. Between index 0 and ACTIVE_SUBROUTINES minus one 144 there may be unused indices either because they weren't assigned an 145 index by the linker or because the subroutine was determined to be 146 inactive by the linker. If there are no explicitly defined subroutine 147 indices in the shader the implementation must assign indices between 148 0 and ACTIVE_SUBROUTINES minus one with no index unused. It is 149 recommended, but not required, the application assigns a range of tightly 150 packed indices starting from zero to avoid indices between 0 and 151 ACTIVE_SUBROUTINES minus one being unused. 152 153 The index can be queried with the command: 154 155 uint GetSubroutineIndex(uint program, enum shadertype, 156 const char *name); 157 158 where name is the null-terminated name of a function in the shader stage 159 of type <shadertype> attached to <program>. The value INVALID_INDEX will 160 be returned if name is not the name of an active subroutine in the shader 161 stage. After the program has been linked, the subroutine index will not 162 change unless the program is re-linked." 163 164 Modify the second paragraph on page 138 to read: 165 166 "The name of an active subroutine can be queried given its subroutine 167 index with the command: 168 169 void GetActiveSubroutineName(uint program, enum shadertype, uint index, 170 sizei bufsize, dizei *length, char *name); 171 172 <program> and <shadertype> specify the program and shader stage. <index> 173 must be a subroutine index in the range from zero to the value of 174 ACTIVE_SUBROUTINES minus one for the shader stage. If <index> is greater 175 than or equal to the value of ACTIVE_SUBROUTINES, the error INVALID_VALUE 176 is generated. The name of the selected subroutine is returned as a null- 177 terminated string in name. The actual number of characters written into 178 name, excluding the null terminator, is returned in length. If length is 179 NULL, no length is returned. If the index refers to an unused subroutine 180 index, the string returned in <name> is an empty string and the length 181 returned is zero. ..." 182 183 Modify the last paragraph on page 138 to read: 184 185 "The command 186 187 void UniformSubroutinesuiv(enum shadertype, sizei count, 188 const uint *indices); 189 190 will load all active subroutine uniforms for shader stage <shadertype> 191 with subroutine indices from <indices>, storing <indices>[i] into the 192 uniform at location i. Any locations between 0 and 193 ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS minus one which are not used will be 194 ignored. If <count> is not equal to the value of 195 ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS for the program currently in use at 196 shader stage <shadertype>, or if the uniform at location i is used and 197 the value in <indices>[i] is greater than or equal to the value 198 of ACTIVE_SUBROUTINES for the shader stage, the error INVALID_VALUE is 199 generated. If the value of <indices>[i] for a used location specifies an 200 unused index the error INVALID_VALUE is generated. If, for any subroutine 201 index being loaded to a particular uniform location, the function 202 corresponding to the subroutine index was not associated (as defined in 203 section 6.1.2 of the OpenGL Shading Language Specification) with the type 204 of the subroutine variable at that location, then the error 205 INVALID_OPERATION is generated. If no program is active, the error 206 INVALID_OPERATION is generated." 207 208Additions to Chapter 6 of the OpenGL 4.2 Specification (OpenGL Operation) 209 210 Section 6.1.18 "Shader and Program Queries": 211 212 Modify the second paragraph on page 501: 213 214 "The command 215 216 void GetUniformSubroutineuiv(enum shadertype, int location, uint *params); 217 218 returns the value of the subroutine uniform at location <location> for 219 shader stage <shadertype> of the current program. If <location> is 220 greater than or equal to the value of ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS 221 for the shader currently in use at shader stage <shadertype>, the error 222 INVALID_VALUE is generated. If <location> represents an unused location, 223 the value INVALID_INDEX is returned and no error is generated. If no 224 program is active, the error INVALID_OPERATION is generated." 225 226Additions to the AGL/GLX/WGL Specifications 227 228 None. 229 230Dependencies on ARB_shader_subroutine 231 232 If ARB_shader_subroutine is not supported, remove all references to 233 subroutine uniform locations and subroutine indices. 234 235GLX protocol 236 237 None 238 239Errors 240 241 INVALID_VALUE is generated if an unused index is assigned to an 242 active and used subroutine uniform variable by UniformSubroutinesuiv. 243 244New State 245 246 None 247 248New Implementation Dependent State 249 250 Changes to table 6.64, p. 568 (Implementation Dependent Values) 251 252 Minimum 253 Get Value Type Get Command Value Description Sec. Attribute 254 --------- ---- ----------- ------- ----------- ---- --------- 255 MAX_UNIFORM_LOCATIONS Z+ GetIntegerv 1024 Maximum number of user- 2.14.7 - 256 assignable uniform locations 257 258Modifications to The OpenGL Shading Language Specification, Version 4.20.06 259 260 Including the following line in a shader can be used to control 261 the language feature described in thie extension: 262 263 #extension GL_ARB_explicit_uniform_location : <behavior> 264 265 where <behavior> is as described in section 3.3. 266 267 A new preprocessor #define is added to the OpenGL Shading Language: 268 269 #define GL_ARB_explicit_uniform_location 1 270 271 Insert a new section called 4.4.3 "Uniform Variable Layout Qualifiers": 272 273 "Layout qualifiers can be used for uniform variables and subroutine 274 uniforms. The layout qualifier identifiers for uniform variables and 275 subroutine uniforms are: 276 layout-qualifier-id 277 location = integer-constant 278 279 The location idenifier can be used with default-block uniform 280 variables and subroutine uniforms. The location specifies the 281 location by which the OpenGL API can reference the uniform and update its value. 282 Individual elements of a uniform array are assigned consecutive locations 283 with the first element taking location <location>. No two default-block 284 uniform variables in the program can have the same location, even if they 285 are unused, otherwise a compiler or linker error will be generated. No two 286 subroutine uniform variables can have the same location in the same shader 287 stage, otherwise a compiler or linker error will be generated. Valid 288 locations for default-block uniform variable locations are in the range of 289 0 to the implementation-defined maximum number of uniform locations. Valid 290 locations for subroutine uniforms are in the range of 0 to the 291 implementation-defined per-stage maximum number of subroutine uniform 292 locations minus one. 293 294 Locations can be assigned to default-block uniform arrays and structures. 295 The first inner-most scalar, vector or matrix member or element takes the 296 specified <location> and the compiler assigns the next inner-most member 297 or element the next incremental location value. Each subsequent inner-most 298 member or element gets incremental locations for the entire structure or 299 array. This rule applies to nested structures and arrays and gives each 300 inner-most scalar, vector, or matrix type a unique location. For arrays 301 without an explicit size, the size is calculated based on its static 302 usage. When the linker generates locations for uniforms without an 303 explicit location, it assumes for all uniforms with an explicit location 304 all their array elements and structure members are used and the linker 305 will not generate a conflicting location, even if that element of member 306 is deemed unused." 307 308 Insert a new section called 4.4.4 "Subroutine Function Layout Qualifiers": 309 310 "Layout qualifiers can be used for subroutine functions. The layout 311 qualifier identifiers for subroutine functions are: 312 layout-qualifier-id 313 index = integer-constant 314 315 Each subroutine with an index qualifier in the shader must be given 316 a unique index, otherwise a compile or link error will be generated. The 317 indices must be in the range of 0 to the implementation defined maximum 318 number of subroutines minus one. It's recommended, but not required, that 319 the shader assigns a range of tightly packed <index> values starting 320 from zero so that the GL subroutine function enumeration API returns a 321 non-empty name for all active indices." 322 323Issues 324 325 1) Can the application mix uniforms with explicit locations with 326 regular uniforms without explicit locations? 327 328 RESOLVED: Yes, uniform locations assigned automatically at link time 329 will not alias any uniform with explicit locations, even if those 330 uniforms are inactive. 331 332 2) Can the application mix subroutine uniforms with explicit locations 333 with subroutine uniforms without explicit locations? Also, can the 334 application mix subroutines with explicit indices with subroutines 335 without an index specified. 336 337 RESOLVED: Yes, any subroutine uniforms without an explicit location 338 will be assigned a location between 0 and 339 ACTIVE_UNIFORM_SUBROUTINE_LOCATIONS minus 1 with a location that 340 has not been used by the shader, regardless of whether it refers 341 to a subroutine uniform that is unused. The value of 342 ACTIVE_UNIFORM_SUBROUTINE_LOCATIONS is calculated as the max of 343 the explicit location and automatically assigned location. If 344 there are unused locations between 0 and 345 ACTIVE_UNIFORM_SUBROUTINE_LOCATION, these will be ignored by 346 UniformSubroutinesiv(). Similarily with the subroutine 347 indices, the linker will allocate unused indices to the subroutines 348 without an explicit index and the value of ACTIVE_SUBROUTINES 349 will be the max of the largest explicit index and the linker 350 assigned index. There may be unused indices between 0 and 351 ACTIVE_SUBROUTINES minus 1 and UniformSubroutinesiv() will return 352 an error if the app attempts to use an unused index with an active 353 and used subroutine uniform. 354 355 3) How should an application determine unique default-block uniform 356 variable locations? 357 358 RESOLVED: Each transparent basic-type uniform variable consumes exactly 359 one location, regarless of it's type. Transparent basic-types, as defined 360 in section 4.1 are booleans, integers, floats, doubles, vectors and 361 matrices. An array of basic-type uniforms consumes consecutive locations, 362 incrementing by one for each consecutive element. Structures of 363 basic-type uniforms assign consecutive locations to each member 364 where the first base member takes the first location. These rules apply 365 recursively to nested structures and arrays assigning consecutive 366 locations each consecutive basic-type variable. 367 368 Any uniform variables without an explicit location assigned will be 369 assigned a unique location by the linker. It's implementation defined 370 what locations the linker chooses for these variables, the only 371 requirement being that these generated locations do not alias any 372 explicitly defined locations. 373 374 Note that subroutine uniform variables are not in the same namespace 375 as default-block uniform variables. Subroutine uniform locations 376 are per shader stage rather than per program and they are referenced 377 through a different API so can have the same locations as uniform 378 variables. 379 380 4) What happens if Uniform* is called with an explicitly defined 381 uniform location, but that uniform is deemed inactive by the 382 linker? 383 384 RESOLVED: The call is ignored for inactive uniform variables and 385 no error is generated. Uniforms without an explicit location that 386 are determined to be inactive return -1 for the the location when 387 GetUniformLocation is queried. Calling Uniform* with a location 388 of -1 is also ignored. That behavior isn't changed. 389 390 5) What is the value of ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS after 391 successfully compiling and linking a program? 392 393 RESOLVED: The value of ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS is 394 calculated per shader stage to be the max of the explicitly 395 defined subroutine uniform variable locations and the generated 396 locations for subroutine uniform variables without a defined 397 location. The consequence of this is that there will be some 398 locations between 0 and ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS minus one 399 that are unused. UniformSubroutinesuiv ignores index entries for 400 unused locations. 401 402 6) Does the application need to query ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS 403 to figure out the <count> parameter to UniformSubroutine? 404 405 RESOLVED: No, it doesn't have to. If the application knows the shader 406 source and it only uses explicit subroutine uniform variables locations 407 it can figure out ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS by simply taking the 408 maximum location defined plus one. If there are generated subroutine 409 uniform locations the application will need to query 410 ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS like before. 411 412 7) What is the value of ACTIVE_SUBROUTINES after successfully compiling 413 and linking a program? 414 415 RESOLVED: The value of ACTIVE_SUBROUTINES is calculated per shader 416 stage to be the max of the explicitly defined subroutine index 417 values and the generated indices for subroutines without a defined 418 index. The consequence of this is that there will be some invalid 419 indices between 0 and ACTIVE_SUBROUTINES minus one which don't 420 reference any subroutine. If GetActiveSubroutineName is called with 421 one of these unused indices, no error is generated but the <name> 422 returned will be an empty string and the <length> will be zero. 423 424 8) Does the query for ACTIVE_UNIFORMS in the program include inactive 425 uniform variables with explicit locations? 426 427 RESOLVED: No, only the active default-block uniforms are included in 428 this count. It's only the <location> of inactive uniform variables that 429 can be used with existing GL fuctions like Uniform*, UniformMatrix*, 430 ProgramUniform*, etc. and are ignored. Otherwise these inactive uniforms 431 operate like they did before this extension. 432 433 9) Should we introduce the concept of "location" in addition to the 434 existing "index" for subroutine functions? This would make it more 435 consistent with regular uniforms. You would use the "index" property 436 for the purposes of enumerating the enties with GetActiveSubroutineName 437 and "location" for the purposes of UniformSubroutinesuiv. This will 438 avoid the issue of GetActiveSubroutineName having possibly empty 439 strings returned for indices between 0 and ACTIVE_SUBROUTINES-1. 440 441 RESOLVED: No, not at this time. The downside of introducing a "location" 442 property is that we'll need to introduce a new function called 443 GetSubroutineLocation, which would return an "int" where -1 means 444 invalid location, and then use these values instead of indexes with 445 UniformSubroutinesuiv. Unfortunately, UniformSubroutinesuiv takes 446 an array of "uints". Also, it would be quite confusing to have both 447 GetSubroutineLocation and GetSubroutineIndex, especially for existing 448 apps that already used GetSubroutineIndex. It would be tricky to 449 specify which should be used and tricky the support the transition 450 of apps between OpenGL 4.2 and OpenGL 4.3 usage. And that complexity 451 feels less attractive than the benefit of solving the enumeration 452 issue. Apps that tightly pack their index assignments won't have 453 a problem so in practice a holey enumeration would be an app choice. 454 455Revision History 456 457 Rev. Date Author Changes 458 ---- -------- -------- ----------------------------------------------- 459 6 05/15/12 pdaniell Fix the Errors section to match the added 460 spec language. 461 462 5 04/26/12 pdaniell Add issue #9 and resolve all issues based on 463 Dublin face to face discussion. Minor edits 464 based on feedback from criccio. 465 466 4 04/25/12 pdaniell Edits based on feedback from pbrown. 467 468 3 04/24/12 pdaniell Further improvements and clarifications. Add 469 MAX_UNIFORM_LOCATIONS. 470 471 2 04/23/12 pdaniell Fixes and improvements based on bmerry's 472 feedback and discussions with pbrown. Add 473 new issues. 474 475 1 10/26/11 pdaniell Initial version. 476