1Name 2 3 ARB_program_interface_query 4 5Name Strings 6 7 GL_ARB_program_interface_query 8 9Contact 10 11 Pat Brown, NVIDIA (pbrown 'at' nvidia.com) 12 13Contributors 14 15 Members of the Khronos OpenGL ARB TSG 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: January 10, 2019 40 Revision: 21 41 42Number 43 44 ARB Extension #134 45 46Dependencies 47 48 OpenGL 2.0 is required. 49 50 This extension is written against the OpenGL 4.2 Compatibility Profile 51 Specification (January 19, 2012). 52 53 OpenGL 3.0, ARB_transform_feedback, and EXT_transform_feedback affect the 54 definition of this extension. 55 56 OpenGL 3.1 and ARB_uniform_buffer_object affect the definition of this 57 extension. 58 59 OpenGL 4.0 and ARB_shader_subroutine affect the definition of this 60 extension. 61 62 OpenGL 4.2 and ARB_shader_atomic_counters affect the definition of this 63 extension. 64 65 OpenGL 4.3 and ARB_shader_storage_buffer_object affect the definition of 66 this extension. 67 68 OpenGL 4.3 and ARB_arrays_of_arrays affect the definition of this 69 extension. 70 71 OpenGL 4.3 and ARB_compute_shader affect the definition of this extension. 72 73 OpenGL 4.3 and ARB_explicit_uniform_location affect the definition of this 74 extension. 75 76Overview 77 78 This extension provides a single unified set of query commands that can be 79 used by applications to determine properties of various interfaces and 80 resources used by program objects to communicate with application code, 81 fixed-function OpenGL pipeline stages, and other programs. In unextended 82 OpenGL 4.2, there is a separate set of query commands for each different 83 type of interface or resource used by the program. These different sets 84 of queries are structured nearly identically, but the queries for some 85 interfaces have limited capability (e.g., there is no ability to enumerate 86 fragment shader outputs). 87 88 With the single set of query commands provided by this extension, a 89 consistent set of queries is available for all interfaces, and a new 90 interface can be added without having to introduce a completely new set of 91 query commands. These queries are intended to provide a superset of the 92 capabilities provided by similar queries in OpenGL 4.2, and should allow 93 for the deprecation of the existing queries. 94 95 This extension defines two terms: interfaces and active resources. Each 96 interface of a program object provides a way for the program to 97 communicate with application code, fixed-function OpenGL pipeline stages, 98 and other programs. Examples of interfaces for a program object include 99 inputs (receiving values from vertex attributes or outputs of other 100 programs), outputs (sending values to other programs or per-fragment 101 operations), uniforms (receiving values from API calls), uniform blocks 102 (receiving values from bound buffer objects), subroutines and subroutine 103 uniforms (receiving API calls to indicate functions to call during program 104 execution), and atomic counter buffers (holding values to be manipulated 105 by atomic counter shader functions). Each interface of a program has a 106 set of active resources used by the program. For example, the resources 107 of a program's input interface includes all active input variables used by 108 the first stage of the program. The resources of a program's uniform 109 block interface consists of the set of uniform blocks with at least one 110 member used by any shader in the program. 111 112IP Status 113 114 No known IP claims. 115 116New Procedures and Functions 117 118 void GetProgramInterfaceiv(uint program, enum programInterface, 119 enum pname, int *params); 120 uint GetProgramResourceIndex(uint program, enum programInterface, 121 const char *name); 122 void GetProgramResourceName(uint program, enum programInterface, 123 uint index, sizei bufSize, sizei *length, 124 char *name); 125 void GetProgramResourceiv(uint program, enum programInterface, 126 uint index, sizei propCount, 127 const enum *props, sizei bufSize, 128 sizei *length, int *params); 129 int GetProgramResourceLocation(uint program, enum programInterface, 130 const char *name); 131 int GetProgramResourceLocationIndex(uint program, enum programInterface, 132 const char *name); 133 134New Tokens 135 136 Accepted by the <programInterface> parameter of GetProgramInterfaceiv, 137 GetProgramResourceIndex, GetProgramResourceName, GetProgramResourceiv, 138 GetProgramResourceLocation, and GetProgramResourceLocationIndex: 139 140 UNIFORM 0x92E1 141 UNIFORM_BLOCK 0x92E2 142 PROGRAM_INPUT 0x92E3 143 PROGRAM_OUTPUT 0x92E4 144 BUFFER_VARIABLE 0x92E5 145 SHADER_STORAGE_BLOCK 0x92E6 146 ATOMIC_COUNTER_BUFFER (already in 4.2) 147 VERTEX_SUBROUTINE 0x92E8 148 TESS_CONTROL_SUBROUTINE 0x92E9 149 TESS_EVALUATION_SUBROUTINE 0x92EA 150 GEOMETRY_SUBROUTINE 0x92EB 151 FRAGMENT_SUBROUTINE 0x92EC 152 COMPUTE_SUBROUTINE 0x92ED 153 VERTEX_SUBROUTINE_UNIFORM 0x92EE 154 TESS_CONTROL_SUBROUTINE_UNIFORM 0x92EF 155 TESS_EVALUATION_SUBROUTINE_UNIFORM 0x92F0 156 GEOMETRY_SUBROUTINE_UNIFORM 0x92F1 157 FRAGMENT_SUBROUTINE_UNIFORM 0x92F2 158 COMPUTE_SUBROUTINE_UNIFORM 0x92F3 159 TRANSFORM_FEEDBACK_VARYING 0x92F4 160 161 Accepted by the <pname> parameter of GetProgramInterfaceiv: 162 163 ACTIVE_RESOURCES 0x92F5 164 MAX_NAME_LENGTH 0x92F6 165 MAX_NUM_ACTIVE_VARIABLES 0x92F7 166 MAX_NUM_COMPATIBLE_SUBROUTINES 0x92F8 167 168 Accepted in the <props> array of GetProgramResourceiv: 169 170 NAME_LENGTH 0x92F9 171 TYPE 0x92FA 172 ARRAY_SIZE 0x92FB 173 OFFSET 0x92FC 174 BLOCK_INDEX 0x92FD 175 ARRAY_STRIDE 0x92FE 176 MATRIX_STRIDE 0x92FF 177 IS_ROW_MAJOR 0x9300 178 ATOMIC_COUNTER_BUFFER_INDEX 0x9301 179 BUFFER_BINDING 0x9302 180 BUFFER_DATA_SIZE 0x9303 181 NUM_ACTIVE_VARIABLES 0x9304 182 ACTIVE_VARIABLES 0x9305 183 REFERENCED_BY_VERTEX_SHADER 0x9306 184 REFERENCED_BY_TESS_CONTROL_SHADER 0x9307 185 REFERENCED_BY_TESS_EVALUATION_SHADER 0x9308 186 REFERENCED_BY_GEOMETRY_SHADER 0x9309 187 REFERENCED_BY_FRAGMENT_SHADER 0x930A 188 REFERENCED_BY_COMPUTE_SHADER 0x930B 189 TOP_LEVEL_ARRAY_SIZE 0x930C 190 TOP_LEVEL_ARRAY_STRIDE 0x930D 191 LOCATION 0x930E 192 LOCATION_INDEX 0x930F 193 IS_PER_PATCH 0x92E7 194 195 NUM_COMPATIBLE_SUBROUTINES (already in 4.2) 196 COMPATIBLE_SUBROUTINES (already in 4.2) 197 198 199Additions to Chapter 2 of the OpenGL 4.2 (Compatibility Profile) Specification 200(OpenGL Operation) 201 202 Modify Section 2.14.3, Program Objects (p. 97) 203 204 (insert at the end of the section, p. 101) 205 206 Program Interfaces 207 208 When a program object is made part of the current rendering state, its 209 executable code may communicate with other GL pipeline stages or 210 application code through a variety of /interfaces/. When a program is 211 linked, the GL builds a list of /active resources/ for each interface. 212 Examples of active resources include variables, interface blocks, and 213 subroutines used by shader code. Resources referenced in shader code are 214 considered /active/ unless the compiler and linker can conclusively 215 determine that they have no observable effect on the results produced by 216 the executable code of the program. For example, variables might be 217 considered inactive if they are declared but not used in executable code, 218 used only in a clause of an "if" statement that would never be executed, 219 used only in functions that are never called, or used only in computations 220 of temporary variables having no effect on any shader output. In cases 221 where the compiler or linker cannot make a conclusive determination, any 222 resource referenced by shader code will be considered active. The set of 223 active resources on for any interface is implementation-dependent because 224 it depends on various analysis and optimizations performed by the compiler 225 and linker. 226 227 If a program is linked successfully, the GL will generate lists of active 228 resources based on the executable code produced by the link. If a program 229 is linked unsuccessfully, the link may have failed for a number of 230 reasons, including cases where the program required more resources than 231 supported by the implementation. Implementations are permitted, but not 232 required, to record lists of resources that would have been considered 233 active had the program linked successfully. If an implementation does not 234 record information for any given interface, the corresponding list of 235 active resources is considered empty. If a program has never been linked, 236 all lists of active resources are considered empty. 237 238 The GL provides a number of commands to query properties of the interfaces 239 of a program object. Each such command accepts a <programInterface> 240 token, identifying a specific interface. The supported values for 241 <programInterface> are as follows: 242 243 * UNIFORM corresponds to the set of active uniform variables (section 244 2.14.7) used by <program>. 245 246 * UNIFORM_BLOCK corresponds to the set of active uniform blocks (section 247 2.14.7) used by <program>. 248 249 * ATOMIC_COUNTER_BUFFER corresponds to the set of active atomic counter 250 buffer binding points (section 2.14.7) used by <program>. 251 252 * PROGRAM_INPUT corresponds to the set of active input variables used by 253 the first shader stage of <program>. If <program> includes multiple 254 shader stages, input variables from any shader stage other than the 255 first will not be enumerated. 256 257 * PROGRAM_OUTPUT corresponds to the set of active output variables 258 (section 2.14.11) used by the last shader stage of <program>. If 259 <program> includes multiple shader stages, output variables from any 260 shader stage other than the last will not be enumerated. 261 262 * VERTEX_SUBROUTINE, TESS_CONTROL_SUBROUTINE, 263 TESS_EVALUATION_SUBROUTINE, GEOMETRY_SUBROUTINE, FRAGMENT_SUBROUTINE, 264 and COMPUTE_SUBROUTINE correspond to the set of active subroutines for 265 the vertex, tessellation control, tessellation evaluation, geometry, 266 fragment, and compute shader stages of <program>, respectively 267 (section 2.14.8). 268 269 * VERTEX_SUBROUTINE_UNIFORM, TESS_CONTROL_SUBROUTINE_UNIFORM, 270 TESS_EVALUATION_SUBROUTINE_UNIFORM, GEOMETRY_SUBROUTINE_UNIFORM, 271 FRAGMENT_SUBROUTINE_UNIFORM, and COMPUTE_SUBROUTINE_UNIFORM correspond 272 to the set of active subroutine uniform variables used by the vertex, 273 tessellation control, tessellation evaluation, geometry, fragment, and 274 compute shader stages of <program>, respectively (section 2.14.8). 275 276 * TRANSFORM_FEEDBACK_VARYING corresponds to the set of output variables 277 in the last non-fragment stage of <program> that would be captured 278 when transform feedback is active (section 2.20.2). 279 280 * BUFFER_VARIABLE corresponds to the set of active buffer variables (see 281 the ARB_shader_storage_buffer_object extension) used by <program>. 282 283 * SHADER_STORAGE_BLOCK corresponds to the set of active shader storage 284 blocks (see the ARB_shader_storage_buffer_object extension) used by 285 <program>. 286 287 When building a list of active variable or interface blocks, resources 288 with aggregate types (such as arrays or structures) may produce multiple 289 entries in the active resource list for the corresponding interface. 290 Additionally, each active variable, interface block, or subroutine in the 291 list is assigned an associated name string that can be used by 292 applications to refer to the resources. For interfaces involving 293 variables, interface blocks, or subroutines, the entries of active 294 resource lists are generated as follows: 295 296 * For an active variable declared as a single instance of a basic type, 297 a single entry will be generated, using the variable name from the 298 shader source. 299 300 * For an active variable declared as an array of basic types, a single 301 entry will be generated, with its name string formed by concatenating 302 the name of the array and the string "[0]". 303 304 * For an active variable declared as a structure, a separate entry will 305 be generated for each active structure member. The name of each entry 306 is formed by concatenating the name of the structure, the "." 307 character, and the name of the structure member. If a structure 308 member to enumerate is itself a structure or array, these enumeration 309 rules are applied recursively. 310 311 * For an active variable declared as an array of an aggregate data type 312 (structures or arrays), a separate entry will be generated for each 313 active array element, unless noted immediately below. The name of 314 each entry is formed by concatenating the name of the array, the "[" 315 character, an integer identifying the element number, and the "]" 316 character. These enumeration rules are applied recursively, treating 317 each enumerated array element as a separate active variable. 318 319 * For an active shader storage block member declared as an array, an 320 entry will be generated only for the first array element, regardless 321 of its type. For arrays of aggregate types, the enumeration rules are 322 applied recursively for the single enumerated array element. 323 324 * For an active interface block not declared as an array of block 325 instances, a single entry will be generated, using the block name from 326 the shader source. 327 328 * For an active interface block declared as an array of instances, 329 separate entries will be generated for each active instance. The name 330 of the instance is formed by concatenating the block name, the "[" 331 character, an integer identifying the instance number, and the "]" 332 character. 333 334 * For an active subroutine, a single entry will be generated, using the 335 subroutine name from the shader source. 336 337 When an integer array element or block instance number is part of the name 338 string, it will be specified in decimal form without a "+" or "-" sign or 339 any extra leading zeroes. Additionally, the name string will not include 340 white space anywhere in the string. 341 342 The order of the active resource list is implementation-dependent for all 343 interfaces except for TRANSFORM_FEEDBACK_VARYING. For 344 TRANSFORM_FEEDBACK_VARYING, the active resource list will use the variable 345 order specified in the the most recent call to TransformFeedbackVaryings 346 before the last call to LinkProgram. 347 348 For the ATOMIC_COUNTER_BUFFER interface, the list of active buffer binding 349 points is built by identifying each unique binding point associated with 350 one or more active atomic counter uniform variables. Active atomic 351 counter buffers do not have an associated name string. 352 353 For the UNIFORM, PROGRAM_INPUT, PROGRAM_OUTPUT, and 354 TRANSFORM_FEEDBACK_VARYING interfaces, the active resource list will 355 include all active variables for the interface, including any active 356 built-in variables. 357 358 For PROGRAM_INPUT and PROGRAM_OUTPUT interfaces for shaders that recieve 359 or produce patch primitves, the active resource list will include both 360 per-vertex and per-patch inputs and outputs. 361 362 For the TRANSFORM_FEEDBACK_VARYING interface, the active resource list 363 will entries for the special varying names gl_NextBuffer, 364 gl_SkipComponents1, gl_SkipComponents2, gl_SkipComponents3, and 365 gl_SkipComponents4 (section 2.14.11). These variables are used to control 366 how varying values are written to transform feedback buffers. When 367 enumerating the properties of such resources, these variables are 368 considered to have a TYPE of NONE and an ARRAY_SIZE of 0 (gl_NextBuffer), 369 1, 2, 3, and 4, respectively. 370 371 When a program is linked successfully, active variables in the UNIFORM, 372 PROGRAM_INPUT, PROGRAM_OUTPUT interface, or in any of the subroutine 373 uniform interfaces, are assigned one or more signed integer /locations/. 374 These locations can be used by commands to assign values to uniforms and 375 subroutine uniforms, to identify generic vertex attributes associated with 376 vertex shader inputs, or to identify fragment color output numbers and 377 indices associated with fragment shader outputs. For such variables 378 declared as arrays, separate locations will be assigned to each active 379 array element. Not all active variables are assigned valid locations; the 380 following variables will have an effective location of -1: 381 382 * uniforms declared as atomic counters; 383 384 * members of a uniform block; 385 386 * built-in inputs, outputs, and uniforms (starting with "gl_"); and 387 388 * inputs or outputs not declared with a "location" layout qualifier, 389 except for vertex shader inputs and fragment shader outputs. 390 391 If a program has not been linked or has was last linked unsuccessfully, no 392 locations will be assigned. 393 394 The command 395 396 void GetProgramInterfaceiv(uint program, enum programInterface, 397 enum pname, int *params); 398 399 queries a property of the interface <programInterface> in program 400 <program>, returning its value in <params>. The property to return is 401 specified by <pname>. 402 403 If <pname> is ACTIVE_RESOURCES, the value returned is the number of 404 resources in the active resource list for <programInterface>. If the list 405 of active resources for <programInterface> is empty, zero is returned. 406 407 If <pname> is MAX_NAME_LENGTH, the value returned is the length of the 408 longest active name string for an active resource in <programInterface>. 409 This length includes an extra character for the null terminator. If the 410 list of active resources for <programInterface> is empty, zero is 411 returned. The error INVALID_OPERATION is generated if <programInterface> 412 is ATOMIC_COUNTER_BUFFER, since active atomic counter buffer resources are 413 not assigned name strings. 414 415 If <pname> is MAX_NUM_ACTIVE_VARIABLES, the value returned is the number 416 of active variables belonging to the interface block or atomic counter 417 buffer resource in <programInterface> with the most active variables. If 418 the list of active resources for <programInterface> is empty, zero is 419 returned. The error INVALID_OPERATION is generated if <programInterface> 420 is not UNIFORM_BLOCK, ATOMIC_COUNTER_BUFFER, or SHADER_STORAGE_BLOCK. 421 422 If <pname> is MAX_NUM_COMPATIBLE_SUBROUTINES, the value returned is the 423 number of compatible subroutines belonging to the active subroutine 424 uniform in <programInterface> with the most compatible subroutines. If 425 the list of active resources for <programInterface> is empty, zero is 426 returned. The error INVALID_OPERATION is generated unless 427 <programInterface> is VERTEX_SUBROUTINE_UNIFORM, 428 TESS_CONTROL_SUBROUTINE_UNIFORM, TESS_EVALUATION_SUBROUTINE_UNIFORM, 429 GEOMETRY_SUBROUTINE_UNIFORM, FRAGMENT_SUBROUTINE_UNIFORM, or 430 COMPUTE_SUBROUTINE_UNIFORM. 431 432 Each entry in the active resource list for an interface is assigned a 433 unique unsigned integer index in the range 0..<N>-1, where <N> is the 434 number of entries in the active resource list. The command 435 436 uint GetProgramResourceIndex(uint program, enum programInterface, 437 const char *name); 438 439 returns the unsigned integer index assigned to a resource named <name> in 440 the interface type <programInterface> of program object <program>. The 441 error INVALID_ENUM is generated if <programInterface> is 442 ATOMIC_COUNTER_BUFFER, since active atomic counter buffer resources are 443 not assigned name strings. 444 445 If <name> exactly matches the name string of one of the active resources 446 for <programInterface>, the index of the matched resource is returned. 447 Additionally, if <name> would exactly match the name string of an active 448 resource if "[0]" were appended to <name>, the index of the matched 449 resource is returned. Otherwise, <name> is considered not to be the name 450 of an active resource, and INVALID_INDEX is returned. Note that if an 451 interface enumerates a single active resource list entry for an array 452 variable (e.g., "a[0]"), a <name> identifying any array element other than 453 the first (e.g., "a[1]") is not considered to match. 454 455 For the interface TRANSFORM_FEEDBACK_VARYING, the value INVALID_INDEX 456 should be returned when querying the index assigned to the special names 457 "gl_NextBuffer", "gl_SkipComponents1", "gl_SkipComponents2", 458 "gl_SkipComponents3", and "gl_SkipComponents4". 459 460 The command 461 462 void GetProgramResourceName(uint program, enum programInterface, 463 uint index, sizei bufSize, sizei *length, 464 char *name); 465 466 returns the name string assigned to the single active resource with an 467 index of <index> in the interface <programInterface> of program object 468 <program>. The error INVALID_VALUE is generated if <index> is greater 469 than or equal to the number of entries in the active resource list for 470 <programInterface>. The error INVALID_ENUM is generated if 471 <programInterface> is ATOMIC_COUNTER_BUFFER, since active atomic counter 472 buffer resources are not assigned name strings. 473 474 The name string assigned to the active resource identified by <index> is 475 returned as a null-terminated string in <name>. The actual number of 476 characters written into <name>, excluding the null terminator, is returned 477 in <length>. If <length> is NULL, no length is returned. The maximum 478 number of characters that may be written into <name>, including the null 479 terminator, is specified by <bufSize>. If the length of the name string 480 (including the null terminator) is greater than <bufSize>, the first 481 <bufSize>-1 characters of the name string will be written to <name>, 482 followed by a null terminator. If <bufSize> is zero, no error will be 483 generated but no characters will be written to <name>. The length of the 484 longest name string for <programInterface>, including a null terminator, 485 can be queried by calling GetProgramInterfaceiv with a <pname> of 486 MAX_NAME_LENGTH. 487 488 The command 489 490 void GetProgramResourceiv(uint program, enum programInterface, 491 uint index, sizei propCount, 492 const enum *props, sizei bufSize, 493 sizei *length, int *params); 494 495 returns values for multiple properties of a single active resource with an 496 index of <index> in the interface <programInterface> of program object 497 <program>. For each resource, values for <propCount> properties specified 498 by the array <props> are returned. The error INVALID_VALUE is generated 499 if <propCount> is zero. The error INVALID_ENUM is generated if any value 500 in <props> is not one of the properties described immediately below. The 501 error INVALID_OPERATION is generated if any value in <props> is not 502 allowed for <programInterface>. The set of allowed <programInterface> 503 values for each property can be found in Table X.1. 504 505 The values associated with the properties of the active resource are 506 written to consecutive entries in <params>, in increasing order according 507 to position in <props>. If no error is generated, only the first 508 <bufSize> integer values will be written to <params>; any extra values 509 will not be returned. If <length> is not NULL, the actual number of 510 integer values written to <params> will be written to <length>. 511 512 Property Supported Interfaces 513 --------------------------- ---------------------------------------- 514 NAME_LENGTH all but ATOMIC_COUNTER_BUFFER 515 516 TYPE UNIFORM, PROGRAM_INPUT, PROGRAM_OUTPUT, 517 TRANSFORM_FEEDBACK_VARYING, 518 BUFFER_VARIABLE 519 520 ARRAY_SIZE UNIFORM, BUFFER_VARIABLE, PROGRAM_INPUT, 521 PROGRAM_OUTPUT, VERTEX_SUBROUTINE_ 522 UNIFORM, TESS_CONTROL_SUBROUTINE_UNIFORM, 523 TESS_EVALUATION_SUBROUTINE_UNIFORM, 524 GEOMETRY_SUBROUTINE_UNIFORM, FRAGMENT_ 525 SUBROUTINE_UNIFORM, COMPUTE_SUBROUTINE_ 526 UNIFORM, TRANSFORM_FEEDBACK_VARYING 527 528 OFFSET UNIFORM, BUFFER_VARIABLE 529 BLOCK_INDEX UNIFORM, BUFFER_VARIABLE 530 ARRAY_STRIDE UNIFORM, BUFFER_VARIABLE 531 MATRIX_STRIDE UNIFORM, BUFFER_VARIABLE 532 IS_ROW_MAJOR UNIFORM, BUFFER_VARIABLE 533 534 ATOMIC_COUNTER_BUFFER_INDEX UNIFORM 535 536 BUFFER_BINDING UNIFORM_BLOCK, ATOMIC_COUNTER_BUFFER, 537 SHADER_STORAGE_BLOCK 538 BUFFER_DATA_SIZE UNIFORM_BLOCK, ATOMIC_COUNTER_BUFFER 539 SHADER_STORAGE_BLOCK 540 NUM_ACTIVE_VARIABLES UNIFORM_BLOCK, ATOMIC_COUNTER_BUFFER 541 SHADER_STORAGE_BLOCK 542 ACTIVE_VARIABLES UNIFORM_BLOCK, ATOMIC_COUNTER_BUFFER 543 SHADER_STORAGE_BLOCK 544 545 REFERENCED_BY_VERTEX_ UNIFORM, UNIFORM_BLOCK, ATOMIC_COUNTER_ 546 SHADER BUFFER, SHADER_STORAGE_BLOCK, 547 BUFFER_VARIABLE, PROGRAM_INPUT, 548 PROGRAM_OUTPUT 549 550 REFERENCED_BY_TESS_ UNIFORM, UNIFORM_BLOCK, ATOMIC_COUNTER_ 551 CONTROL_SHADER BUFFER, SHADER_STORAGE_BLOCK, 552 BUFFER_VARIABLE, PROGRAM_INPUT, 553 PROGRAM_OUTPUT 554 555 REFERENCED_BY_TESS_ UNIFORM, UNIFORM_BLOCK, ATOMIC_COUNTER_ 556 EVALUATION_SHADER BUFFER, SHADER_STORAGE_BLOCK, 557 BUFFER_VARIABLE, PROGRAM_INPUT, 558 PROGRAM_OUTPUT 559 560 REFERENCED_BY_GEOMETRY_ UNIFORM, UNIFORM_BLOCK, ATOMIC_COUNTER_ 561 SHADER BUFFER, SHADER_STORAGE_BLOCK, 562 BUFFER_VARIABLE, PROGRAM_INPUT, 563 PROGRAM_OUTPUT 564 565 REFERENCED_BY_FRAGMENT_ UNIFORM, UNIFORM_BLOCK, ATOMIC_COUNTER_ 566 SHADER BUFFER, SHADER_STORAGE_BLOCK, 567 BUFFER_VARIABLE, PROGRAM_INPUT, 568 PROGRAM_OUTPUT 569 570 REFERENCED_BY_COMPUTE_ UNIFORM, UNIFORM_BLOCK, ATOMIC_COUNTER_ 571 SHADER BUFFER, SHADER_STORAGE_BLOCK, 572 BUFFER_VARIABLE, PROGRAM_INPUT, 573 PROGRAM_OUTPUT 574 575 NUM_COMPATIBLE_SUBROUTINES VERTEX_SUBROUTINE_UNIFORM, TESS_CONTROL_ 576 SUBROUTINE_UNIFORM, TESS_EVALUATION_ 577 SUBROUTINE_UNIFORM, GEOMETRY_SUBROUTINE_ 578 UNIFORM, FRAGMENT_SUBROUTINE_UNIFORM, 579 COMPUTE_SUBROUTINE_UNIFORM 580 581 COMPATIBLE_SUBROUTINES VERTEX_SUBROUTINE_UNIFORM, TESS_CONTROL_ 582 SUBROUTINE_UNIFORM, TESS_EVALUATION_ 583 SUBROUTINE_UNIFORM, GEOMETRY_SUBROUTINE_ 584 UNIFORM, FRAGMENT_SUBROUTINE_UNIFORM, 585 COMPUTE_SUBROUTINE_UNIFORM 586 587 TOP_LEVEL_ARRAY_SIZE BUFFER_VARIABLE 588 589 TOP_LEVEL_ARRAY_STRIDE BUFFER_VARIABLE 590 591 LOCATION UNIFORM, PROGRAM_INPUT, PROGRAM_OUTPUT, 592 VERTEX_SUBROUTINE_UNIFORM, TESS_CONTROL_ 593 SUBROUTINE_UNIFORM, TESS_EVALUATION_ 594 SUBROUTINE_UNIFORM, GEOMETRY_SUBROUTINE_ 595 UNIFORM, FRAGMENT_SUBROUTINE_UNIFORM, 596 COMPUTE_SUBROUTINE_UNIFORM 597 598 LOCATION_INDEX PROGRAM_OUTPUT 599 600 IS_PER_PATCH PROGRAM_INPUT, PROGRAM_OUTPUT 601 602 Table X.1, GetProgramResourceiv properties and supported interfaces 603 604 For the property NAME_LENGTH, a single integer identifying the length of 605 the name string associated with an active variable, interface block, or 606 subroutine is written to <params>. The name length includes a terminating 607 null character. 608 609 For the property TYPE, a single integer identifying the type of an active 610 variable is written to <params>. The integer returned is one of the 611 values found in table 2.16. 612 613 For the property COMPATIBLE_SUBROUTINES, an array of integers is written 614 to <params>, with each integer specifying the index of an active 615 subroutine that can be assigned to the selected subroutine uniform. The 616 number of values written to <params> for an active subroutine is given 617 by the value of the property NUM_COMPATIBLE_SUBROUTINES for the 618 resource. 619 620 For the property ARRAY_SIZE, a single integer identifying the number of 621 active array elements of an active variable is written to <params>. The 622 array size returned is in units of the type associated with the property 623 TYPE. For active variables not corresponding to an array of basic types, 624 the value one is written to <params>. If the variable is a shader 625 storage block member in an array with no declared size, the value zero 626 is written to <params>. 627 628 For the property BLOCK_INDEX, a single integer identifying the index of 629 the active interface block containing an active variable is written to 630 <params>. If the variable is not the member of an interface block, the 631 value -1 is written to <params>. 632 633 For the property OFFSET, a single integer identifying the offset of an 634 active variable is written to <params>. For active variables backed by a 635 buffer object, the value written is the offset, in basic machine units, 636 relative to the base of buffer range holding the values of the variable. 637 For active variables not backed by a buffer object, an offset of -1 is 638 written to <params>. 639 640 For the property ARRAY_STRIDE, a single integer identifying the stride 641 between array elements in an active variable is written to <params>. For 642 active variables declared as an array of basic types, the value written is 643 the difference, in basic machine units, between the offsets of consecutive 644 elements in an array. For active variables not declared as an array of 645 basic types, zero is written to <params>. For active variables not backed 646 by a buffer object, -1 is written to <params>, regardless of the variable 647 type. 648 649 For the property MATRIX_STRIDE, a single integer identifying the stride 650 between columns of a column-major matrix or rows of a row-major matrix is 651 written to <params>. For active variables declared a single matrix or 652 array of matrices, the value written is the difference, in basic machine 653 units, between the offsets of consecutive columns or rows in each matrix. 654 For active variables not declared as a matrix or array of matrices, zero 655 is written to <params>. For active variables not backed by a buffer 656 object, -1 is written to <params>, regardless of the variable type. 657 658 For the property IS_ROW_MAJOR, a single integer identifying whether an 659 active variable is a row-major matrix is written to <params>. For active 660 variables backed by a buffer object, declared as a single matrix or array 661 of matrices, and stored in row-major order, one is written to <params>. 662 For all other active variables, zero is written to <params>. 663 664 For the property ATOMIC_COUNTER_BUFFER_INDEX, a single integer identifying 665 the index of the active atomic counter buffer containing an active 666 variable is written to <params>. If the variable is not an atomic counter 667 uniform, the value -1 is written to <params>. 668 669 For the property of BUFFER_BINDING, to index of the buffer binding point 670 associated with the active uniform block, shader storage block, or atomic 671 counter buffer is written to <params>. 672 673 For the property of BUFFER_DATA_SIZE, then the implementation-dependent 674 minimum total buffer object size, in basic machine units, required to hold 675 all active variables associated with an active uniform block, shader 676 storage block, or atomic counter buffer is written to <params>. If the 677 final member of an active shader storage block is array with no declared 678 size, the minimum buffer size is computed assuming the array was declared 679 as an array with one element. 680 681 For the property of NUM_ACTIVE_VARIABLES, the number of active variables 682 associated with an active uniform block, shader storage block, or atomic 683 counter buffer is written to <params>. 684 685 For the property of ACTIVE_VARIABLES, an array of active variable indices 686 associated with an active uniform block, shader storage block, or atomic 687 counter buffer is written to <params>. The number of values written to 688 <params> for an active resource is given by the value of the property 689 NUM_ACTIVE_VARIABLES for the resource. 690 691 For the properties REFERENCED_BY_VERTEX_SHADER, 692 REFERENCED_BY_TESS_CONTROL_SHADER, REFERENCED_BY_TESS_EVALUATION_SHADER, 693 REFERENCED_BY_GEOMETRY_SHADER, REFERENCED_BY_FRAGMENT_SHADER, and 694 REFERENCED_BY_COMPUTE_SHADER, a single integer is written to <params>, 695 identifying whether the active resource is referenced by the vertex, 696 tessellation control, tessellation evaluation, geometry, or fragment 697 shaders, respectively, in the program object. The value one is written to 698 <params> if an active variable is referenced by the corresponding shader, 699 or if an active uniform block, shader storage block, or atomic counter 700 buffer contains at least one variable referenced by the corresponding 701 shader. Otherwise, the value zero is written to <params>. 702 703 For the property TOP_LEVEL_ARRAY_SIZE, a single integer identifying the 704 number of active array elements of the top-level shader storage block 705 member containing to the active variable is written to <params>. If the 706 top-level block member is not declared as an array, the value one is 707 written to <params>. If the top-level block member is an array with no 708 declared size, the value zero is written to <params>. 709 710 For the property TOP_LEVEL_ARRAY_STRIDE, a single integer identifying the 711 stride between array elements of the top-level shader storage block member 712 containing the active variable is written to <params>. For top-level 713 block members declared as arrays, the value written is the difference, in 714 basic machine units, between the offsets of the active variable for 715 consecutive elements in the top-level array. For top-level block members 716 not declared as an array, zero is written to <params>. 717 718 For the property LOCATION, a single integer identifying the assigned 719 location for an active uniform, input, output, or subroutine uniform 720 variable is written to <params>. For input, output, or uniform variables 721 with locations specified by a layout qualifier, the specified location is 722 used. For vertex shader input or fragment shader output variables without 723 a layout qualifier, the location assigned when a program is linked is 724 written to <params>. For all other input and output variables, the value 725 -1 is written to <params>. For uniforms in uniform blocks, the value -1 726 is written to <params>. 727 728 For the property LOCATION_INDEX, a single integer identifying the fragment 729 color index of an active fragment shader output variable is written to 730 <params>. If the active variable is an output for a non-fragment shader, 731 the value -1 will be written to <params>. 732 733 For the property IS_PER_PATCH, a single integer identifying whether the 734 input or output is a per-patch attribute. If the active variable is a 735 per-patch attribute (declared with the "patch" qualifier), the value one 736 is written to <params>; otherwise, the value zero is written to <params>. 737 738 The commands 739 740 int GetProgramResourceLocation(uint program, enum programInterface, 741 const char *name); 742 int GetProgramResourceLocationIndex(uint program, enum programInterface, 743 const char *name); 744 745 returns the location or the fragment color index, respectively, assigned 746 to the variable named <name> in interface <programInterface> of program 747 object <program>. For both commands, the error INVALID_OPERATION is 748 generated if <program> has not been linked or was last linked 749 unsuccessfully. For GetProgramResourceLocation, <programInterface> must 750 be one of UNIFORM, PROGRAM_INPUT, PROGRAM_OUTPUT, 751 VERTEX_SUBROUTINE_UNIFORM, TESS_CONTROL_SUBROUTINE_UNIFORM, 752 TESS_EVALUATION_SUBROUTINE_UNIFORM, GEOMETRY_SUBROUTINE_UNIFORM, 753 FRAGMENT_SUBROUTINE_UNIFORM, or COMPUTE_SUBROUTINE_UNIFORM. For 754 GetProgramResourceLocationIndex, <programInterface> must be 755 PROGRAM_OUTPUT. The value -1 will be returned by either command if an 756 error occurs, if <name> does not identify an active variable on 757 <programInterface>, or if <name> identifies an active variable that does 758 not have a valid location assigned, as described above. The locations 759 returned by these commands are the same locations returned when querying 760 the LOCATION and LOCATION_INDEX resource properties. 761 762 A string provided to GetProgramResourceLocation or 763 GetProgramResourceLocationIndex is considered to match an active variable 764 if: 765 766 * the string exactly matches the name of the active variable; 767 768 * if the string identifies the base name of an active array, where the 769 string would exactly match the name of the variable if the suffix 770 "[0]" were appended to the string; or 771 772 * if the string identifies an active element of the array, where the 773 string ends with the concatenation of the "[" character, an integer 774 (with no "+" sign, extra leading zeroes, or whitespace) identifying an 775 array element, and the "]" character, the integer is less than the 776 number of active elements of the array variable, and where the string 777 would exactly match the enumerated name of the array if the decimal 778 integer were replaced with zero. 779 780 Any other string is considered not to identify an active variable. If the 781 string specifies an element of an array variable, 782 GetProgramResourceLocation and GetProgramResourceLocationIndex return the 783 location or fragment color index assigned to that element. If it 784 specifies the base name of an array, it identifies the resources 785 associated with the first element of the array. 786 787 788 Modify Section 2.14.6, Vertex Attributes, p. 109 789 790 (delete text beginning with the second paragraph of p. 110, through the 791 second paragraph of p. 112) 792 793 (modify the third paragraph, p. 112, removing the first sentence) The 794 command 795 796 void BindAttribLocation(uint program, uint index, const char *name); 797 798 ... 799 800 (insert after second paragraph, p. 113) 801 802 To determine the set of active vertex attribute variables used by a 803 program, applications can query the properties and active resources of the 804 PROGRAM_INPUT interface of a program including a vertex shader. 805 806 Additionally, the command 807 808 void GetActiveAttrib(uint program, uint index, 809 sizei bufSize, sizei *length, int *size, 810 enum *type, char *name); 811 812 can be used to determine properties of the active input variable assigned 813 the index <index> in program object <program>. If no error occurs, the 814 command is equivalent to calling: 815 816 const enum props[] = { ARRAY_SIZE, TYPE }; 817 GetProgramResourceName(program, PROGRAM_INPUT, index, bufSize, length, 818 name); 819 GetProgramResourceiv(program, PROGRAM_INPUT, index, 1, &props[0], 820 1, NULL, size); 821 GetProgramResourceiv(program, PROGRAM_INPUT, index, 1, &props[1], 822 1, NULL, (int *) type); 823 824 If <index> is not the index of an active input variable in <program>, the 825 error INVALID_VALUE is generated. If <program> does not include a vertex 826 shader, it has no active vertex attributes and the error INVALID_VALUE is 827 generated for all values of <index>. For GetActiveAttrib, all active 828 vertex shader input variables are enumerated, including the special 829 built-in inputs gl_VertexID and gl_InstanceID. 830 831 The command 832 833 int GetAttribLocation(uint program, const char *name); 834 835 can be used to determine the location assigned to the active input 836 variable named <name> in program object <program>. The error 837 INVALID_OPERATION is generated and -1 is returned if <program> has not 838 been linked or was last linked unsuccessfully. If <program> has been 839 successfully linked but contains no vertex shader, no error will be 840 generated but -1 will be returned. Otherwise, the command is equivalent 841 to calling: 842 843 GetProgramResourceLocation(program, PROGRAM_INPUT, name); 844 845 There is an implementation-dependent limit on the number of active 846 attribute variables [[compatibility profile only: (either conventional or 847 generic)]] in a vertex shader. A program with more than 848 MAX_VERTEX_ATTRIBS active attribute variables may fail to link, unless 849 device-dependent optimizations are able to make the program fit within 850 available hardware resources. For the purposes of this test, attribute 851 variables of the type dvec3, dvec4, dmat2x3, dmat2x4, dmat3, dmat3x4, 852 dmat4x3, and dmat4 may count as consuming twice as many attributes as 853 equivalent single-precision types. While these types use the same number 854 of generic attributes as their single-precision equivalents, 855 implementations are permitted to consume two single-precision vectors of 856 internal storage for each three- or four-component double-precision 857 vector. 858 859 860 Modify Section 2.14.7, Uniform Variables, p. 113 861 862 (replace text starting with the 3rd paragraph on p. 115 through the 3rd 863 paragraph on p. 127) 864 865 To determine the set of active uniform variables used by a program, 866 applications can query the properties and active resources of the UNIFORM 867 interface of a program. 868 869 Additionally, several dedicated commands are provided to query properties 870 of active uniforms. The commands 871 872 int GetUniformLocation(uint program, const char *name) 873 874 void GetActiveUniformName(uint program, uint uniformIndex, 875 sizei bufSize, sizei *length, 876 char *uniformName); 877 878 are equivalent to calling 879 880 GetProgramResourceLocation(program, UNIFORM, name); 881 882 GetProgramResourceName(program, UNIFORM, uniformIndex, bufSize, length, 883 uniformName); 884 885 The command 886 887 void GetUniformIndices(uint program, sizei uniformCount, 888 const char * const *uniformNames, 889 uint *uniformIndices); 890 891 is equivalent to 892 893 for (int i = 0; i < uniformCount; i++) { 894 uniformIndices[i] = 895 GetProgramResourceIndex(program, UNIFORM, uniformNames[i]; 896 } 897 898 The command 899 900 void GetActiveUniform(uint program, uint index, sizei bufSize, 901 sizei *length, int *size, enum *type, 902 char *name); 903 904 is equivalent to 905 906 const enum props[] = { ARRAY_SIZE, TYPE }; 907 GetProgramResourceName(program, UNIFORM, index, bufSize, length, name); 908 GetProgramResourceiv(program, UNIFORM, index, 909 1, &props[0], 1, NULL, size); 910 GetProgramResourceiv(program, UNIFORM, index, 911 1, &props[1], 1, NULL, (int *) type); 912 913 The command 914 915 void GetActiveUniformsiv(uint program, sizei uniformCount, 916 const uint *uniformIndices, enum pname, 917 int *params); 918 919 is equivalent to 920 921 GLenum prop; 922 for (int i = 0; i < uniformCount; i++) { 923 GetProgramResourceiv(program, UNIFORM, uniformIndices[i], 1, &prop, 924 1, NULL, ¶ms[i]); 925 } 926 927 where the value of <prop> is taken from Table X.2, based on the value of 928 <pname>. 929 930 <pname> <prop> 931 ------------------------------ ------------------------------ 932 UNIFORM_TYPE TYPE 933 UNIFORM_SIZE ARRAY_SIZE 934 UNIFORM_NAME_LENGTH NAME_LENGTH 935 UNIFORM_BLOCK_INDEX BLOCK_INDEX 936 UNIFORM_OFFSET OFFSET 937 UNIFORM_ARRAY_STRIDE ARRAY_STRIDE 938 UNIFORM_MATRIX_STRIDE MATRIX_STRIDE 939 UNIFORM_IS_ROW_MAJOR IS_ROW_MAJOR 940 UNIFORM_ATOMIC_COUNTER_ ATOMIC_COUNTER_BUFFER_INDEX 941 BUFFER_INDEX 942 943 Table X.2, GetProgramResourceiv properties used by 944 GetActiveUniformsiv. 945 946 To determine the set of active uniform blocks used by a program, 947 applications can query the properties and active resources of the 948 UNIFORM_BLOCK interface of a program. 949 950 Additionally, several dedicated commands are provided to query properties 951 of active uniform blocks. The commands 952 953 uint GetUniformBlockIndex(uint program, const char *uniformBlockName); 954 955 void GetActiveUniformBlockName(uint program, uint uniformBlockIndex, 956 sizei bufSize, sizei length, 957 char *uniformBlockName); 958 959 are equivalent to calling 960 961 GetProgramResourceIndex(program, UNIFORM_BLOCK, uniformBlockName); 962 963 and 964 965 GetProgramResourceName(program, UNIFORM_BLOCK, uniformBlockIndex, 966 bufSize, length, uniformBlockName); 967 968 The command 969 970 void GetActiveUniformBlockiv(uint program, uint uniformBlockIndex, 971 enum pname, int *params); 972 973 is equivalent to calling 974 975 GLenum prop; 976 GetProgramResourceiv(program, UNIFORM_BLOCK, uniformBlockIndex, 977 1, &prop, maxSize, NULL, params); 978 979 where the value of <prop> is taken from Table X.3, based on the value of 980 <pname>, and <maxSize> is taken to specify a sufficiently large buffer to 981 receive all values that would be written to <params>. 982 983 <pname> <prop> 984 ------------------------------ ------------------------------ 985 UNIFORM_BLOCK_BINDING BUFFER_BINDING 986 UNIFORM_BLOCK_DATA_SIZE BUFFER_DATA_SIZE 987 UNIFORM_BLOCK_NAME_LENGTH NAME_LENGTH 988 UNIFORM_BLOCK_ACTIVE_UNIFORMS NUM_ACTIVE_VARIABLES 989 UNIFORM_BLOCK_ACTIVE_ ACTIVE_VARIABLES 990 UNIFORM_INDICES 991 UNIFORM_BLOCK_REFERENCED_BY_ REFERENCED_BY_VERTEX_SHADER 992 VERTEX_SHADER 993 UNIFORM_BLOCK_REFERENCED_BY_ REFERENCED_BY_TESS_CONTROL_SHADER 994 TESS_CONTROL_SHADER 995 UNIFORM_BLOCK_REFERENCED_BY_ REFERENCED_BY_TESS_EVALUATION_SHADER 996 TESS_EVALUATION_SHADER 997 UNIFORM_BLOCK_REFERENCED_BY_ REFERENCED_BY_GEOMETRY_SHADER 998 GEOMETRY_SHADER 999 UNIFORM_BLOCK_REFERENCED_BY_ REFERENCED_BY_FRAGMENT_SHADER 1000 FRAGMENT_SHADER 1001 UNIFORM_BLOCK_REFERENCED_BY_ REFERENCED_BY_COMPUTE_SHADER 1002 COMPUTE_SHADER 1003 1004 Table X.3, GetProgramResourceiv properties used by 1005 GetActiveUniformBlockiv. 1006 1007 To determine the set of active atomic counter buffer binding points used 1008 by a program, applications can query the properties and active resources 1009 of the ATOMIC_COUNTER_BUFFER interface of a program. 1010 1011 Additionally, the command 1012 1013 void GetActiveAtomicCounterBufferiv(uint program, uint bufferIndex, 1014 enum pname, int *params); 1015 1016 can be used to determine properties of active atomic counter buffer 1017 bindings used by <program> and is equivalent to calling 1018 1019 GLenum prop; 1020 GetProgramResourceiv(program, ATOMIC_COUNTER_BUFFER, bufferIndex, 1021 1, &prop, maxSize, NULL, params); 1022 1023 where the value of <prop> is taken from Table X.4, based on the value of 1024 <pname>, and <maxSize> is taken to specify a sufficiently large buffer to 1025 receive all values that would be written to <params>. 1026 1027 <pname> <prop> 1028 ------------------------------ ------------------------------ 1029 ATOMIC_COUNTER_BUFFER_BINDING BUFFER_BINDING 1030 ATOMIC_COUNTER_BUFFER_ BUFFER_DATA_SIZE 1031 DATA_SIZE 1032 ATOMIC_COUNTER_BUFFER_ACTIVE_ NUM_ACTIVE_VARIABLES 1033 ATOMIC_COUNTERS 1034 ATOMIC_COUNTER_BUFFER_ACTIVE_ ACTIVE_VARIABLES 1035 ATOMIC_COUNTER_INDICES 1036 ATOMIC_COUNTER_BUFFER_ REFERENCED_BY_VERTEX_SHADER 1037 REFERENCED_BY_VERTEX_SHADER 1038 ATOMIC_COUNTER_BUFFER_ REFERENCED_BY_TESS_CONTROL_SHADER 1039 REFERENCED_BY_TESS_ 1040 CONTROL_SHADER 1041 ATOMIC_COUNTER_BUFFER_ REFERENCED_BY_TESS_EVALUATION_SHADER 1042 REFERENCED_BY_TESS_ 1043 EVALUATION_SHADER 1044 ATOMIC_COUNTER_BUFFER_ REFERENCED_BY_GEOMETRY_SHADER 1045 REFERENCED_BY_GEOMETRY_SHADER 1046 ATOMIC_COUNTER_BUFFER_ REFERENCED_BY_FRAGMENT_SHADER 1047 REFERENCED_BY_FRAGMENT_SHADER 1048 ATOMIC_COUNTER_BUFFER_ REFERENCED_BY_COMPUTE_SHADER 1049 REFERENCED_BY_COMPUTE_SHADER 1050 1051 Table X.4, GetProgramResourceiv properties used by 1052 GetActiveAtomicCounterBufferiv. 1053 1054 1055 Modify Section 2.14.8, Subroutine Uniform Variables, p. 136 1056 1057 (This section could probably use some reorganization and a high-level 1058 introduction to how subroutines and subroutine variables work. As 1059 written now, it mostly talks about the GL APIs operating on these without 1060 a lot of conceptual discussion. These edits makes this section smaller 1061 by redefining the old APIs in terms of the new ones.) 1062 1063 (replace language in the section describing the active subroutine and 1064 subroutine uniform enumeration with the following) 1065 1066 To determine the set of active subroutines and subroutines used by a 1067 particular shader stage of a program, applications can query the 1068 properties and active resources of the interfaces for the shader type, as 1069 listed in Tables X.5 and X.6. 1070 1071 Interface Shader Type 1072 ------------------------------ ------------------------------ 1073 VERTEX_SUBROUTINE VERTEX_SHADER 1074 TESS_CONTROL_SUBROUTINE TESS_CONTROL_SHADER 1075 TESS_EVALUATION_SUBROUTINE TESS_EVALUATION_SHADER 1076 GEOMETRY_SUBROUTINE GEOMETRY_SHADER 1077 FRAGMENT_SUBROUTINE FRAGMENT_SHADER 1078 COMPUTE_SUBROUTINE COMPUTE_SHADER 1079 1080 Table X.5, Interfaces for active subroutines for a particular shader 1081 type in a program. 1082 1083 Interface Shader Type 1084 ------------------------------ ------------------------------ 1085 VERTEX_SUBROUTINE_UNIFORM VERTEX_SHADER 1086 TESS_CONTROL_SUBROUTINE_ TESS_CONTROL_SHADER 1087 UNIFORM 1088 TESS_EVALUATION_SUBROUTINE TESS_EVALUATION_SHADER 1089 UNIFORM 1090 GEOMETRY_SUBROUTINE_UNIFORM GEOMETRY_SHADER 1091 FRAGMENT_SUBROUTINE_UNIFORM FRAGMENT_SHADER 1092 COMPUTE_SUBROUTINE_UNIFORM COMPUTE_SHADER 1093 1094 Table X.6, Interfaces for active subroutine uniforms for a particular 1095 shader type in a program. 1096 1097 Dedicated commands are provided to determine properties of active 1098 subroutines and active subroutine uniforms. The commands 1099 1100 uint GetSubroutineIndex(uint program, enum shadertype, 1101 const char *name); 1102 1103 void GetActiveSubroutineName(uint program, enum shadertype, uint index, 1104 sizei bufsize, sizei *length, char *name); 1105 1106 are equivalent to 1107 1108 GetProgramResourceIndex(program, programInterface, name); 1109 1110 GetProgramResourceName(program, programInterface, index, bufsize, 1111 length, name); 1112 1113 where <programInterface> is taken from Table X.5 according to the value of 1114 <shadertype>. 1115 1116 The commands 1117 1118 void GetSubroutineUniformLocation(uint program, enum shadertype, 1119 const char *name); 1120 1121 void GetActiveSubroutineUniformName(uint program, enum shadertype, 1122 uint index, sizei bufsize, 1123 sizei *length, char *name); 1124 1125 void GetActiveSubroutineUniformiv(uint program, enum shadertype, 1126 uint index, enum pname, int *values); 1127 1128 are equivalent to 1129 1130 GetProgramResourceLocation(program, programInterface, name); 1131 1132 GetProgramResourceName(program, programInterface, index, bufsize, length, 1133 name); 1134 1135 GetProgramResourceiv(program, programInterface, index, 1, &pname, 1136 maxSize, NULL, values); 1137 1138 where <programInterface> is taken from Table X.6 according to the value of 1139 <shadertype>. For GetActiveSubroutineUniformiv, <pname> must be one of 1140 NUM_COMPATIBLE_SUBROUTINES or COMPATIBLE_SUBROUTINES, and <maxSize> is 1141 taken to specify a sufficiently large buffer to receive all values that 1142 would be written to <params>. 1143 1144 1145 Modify Section 2.14.11, Output Variables, p. 140 1146 1147 (replace last paragraph, p. 143 through next-to-last paragraph, p. 144 1148 with the following) 1149 1150 To determine the set of output variables in a linked program object that 1151 will be captured in transform feedback mode, applications can query the 1152 properties and active resources of the TRANSFORM_FEEDBACK_VARYING 1153 interface. 1154 1155 Additionally, the dedicated command 1156 1157 void GetTransformFeedbackVarying(uint program, uint index, 1158 sizei bufSize, sizei *length, 1159 sizei *size, enum *type, char *name); 1160 1161 can be used to enumerate properties of a single output variable captured 1162 in transform feedback mode, and is equivalent to 1163 1164 const enum props[] = { ARRAY_SIZE, TYPE }; 1165 GetProgramResourceName(program, TRANSFORM_FEEDBACK_VARYING, index, 1166 bufSize, length, name); 1167 GetProgramResourceiv(program, TRANSFORM_FEEDBACK_VARYING, index, 1168 1, &props[0], 1, NULL, size); 1169 GetProgramResourceiv(program, TRANSFORM_FEEDBACK_VARYING, index, 1170 1, &props[1], 1, NULL, (int *) type); 1171 1172 1173 GetTransformFeedbackVarying may be used to query any transform 1174 feedback varying variable, not just those specified with 1175 TransformFeedbackVarying. 1176 1177Additions to Chapter 3 of the OpenGL 4.2 (Compatibility Profile) Specification 1178(Rasterization) 1179 1180 Modify Section 3.13.2, Shader Execution, p. 371 1181 1182 (replace next-to-last paragraph, p. 378 through the first paragraph, 1183 p. 379 with the following) 1184 1185 To determine the set of fragment shader output attribute variables used by 1186 a program, applications can query the properties and active resources of 1187 the PROGRAM_OUTPUT interface of a program including a fragment shader. 1188 1189 Additionally, dedicated commands are provided to query the location and 1190 fragment color index assigned to a fragment shader output variable. For 1191 the commands 1192 1193 int GetFragDataLocation(uint program, const char *name); 1194 1195 int GetFragDataIndex(uint program, const char *name); 1196 1197 the error INVALID_OPERATION is generated and -1 is returned if <program> 1198 has not been linked or was last linked unsuccessfully. If <program> has 1199 been successfully linked but contains no fragment shader, no error will be 1200 generated but -1 will be returned. Otherwise, the commands are equivalent 1201 to calling: 1202 1203 GetProgramResourceLocation(program, PROGRAM_OUTPUT, name); 1204 1205 or 1206 1207 GetProgramResourceLocationIndex(program, PROGRAM_OUTPUT, name); 1208 1209 1210Additions to Chapter 4 of the OpenGL 4.2 (Compatibility Profile) Specification 1211(Per-Fragment Operations and the Frame Buffer) 1212 1213 None. 1214 1215Additions to Chapter 5 of the OpenGL 4.2 (Compatibility Profile) Specification 1216(Special Functions) 1217 1218 None. Note that all the commands added here are not included in display 1219 lists, but no specification edits are required since existing blanket 1220 language covers all Get* commands. 1221 1222 1223Additions to Chapter 6 of the OpenGL 4.2 (Compatibility Profile) Specification 1224(State and State Requests) 1225 1226 None. 1227 1228Additions to Appendix A of the OpenGL 4.2 (Compatibility Profile) 1229Specification (Invariance) 1230 1231 None. 1232 1233Additions to Appendix D of the OpenGL 4.2 (Compatibility Profile) 1234Specification (Shared Objects and Multiple Contexts) 1235 1236 None. 1237 1238Additions to the AGL/EGL/GLX/WGL Specifications 1239 1240 None 1241 1242GLX Protocol 1243 1244 TBD 1245 1246Dependencies on OpenGL 3.0, ARB_transform_feedback, and EXT_transform_feedback 1247 1248 If OpenGL 3.0, ARB_transform_feedback, and EXT_transform_feedback are not 1249 supported, references to the TRANSFORM_FEEDBACK_VARYING interface should 1250 be removed. 1251 1252Dependencies on OpenGL 3.1 and ARB_uniform_buffer_object 1253 1254 If OpenGL 3.1 and ARB_uniform_buffer_object are not supported, references 1255 to the UNIFORM_BLOCK interface should be removed. 1256 1257Dependencies on OpenGL 4.0 and ARB_shader_subroutine 1258 1259 If OpenGL 4.0 and ARB_shader_subroutine are not supported, references to 1260 the VERTEX_SUBROUTINE, TESS_CONTROL_SUBROUTINE, 1261 TESS_EVALUATION_SUBROUTINE, GEOMETRY_SUBROUTINE, FRAGMENT_SUBROUTINE, 1262 COMPUTE_SUBROUTINE, VERTEX_SUBROUTINE_UNIFORM, 1263 TESS_CONTROL_SUBROUTINE_UNIFORM, TESS_EVALUATION_SUBROUTINE_UNIFORM, 1264 GEOMETRY_SUBROUTINE_UNIFORM, FRAGMENT_SUBROUTINE_UNIFORM, and 1265 COMPUTE_SUBROUTINE_UNIFORM interfaces should be removed. 1266 1267Dependencies on OpenGL 4.2 and ARB_shader_atomic_counters 1268 1269 If OpenGL 4.2 and ARB_shader_atomic_counters are not supported, references 1270 to the ATOMIC_COUNTER_BUFFER interfaces should be removed. 1271 1272Dependencies on OpenGL 4.3 and ARB_shader_storage_buffer_object 1273 1274 If OpenGL 4.3 and ARB_shader_storage_buffer_object are not supported, 1275 references to the BUFFER_VARIABLE and SHADER_STORAGE_BLOCK interfaces 1276 should be removed. 1277 1278Dependencies on OpenGL 4.3 and ARB_arrays_of_arrays 1279 1280 If OpenGL 4.3 and ARB_arrays_of_arrays are not supported, language 1281 describing the enumeration of multi-dimensional arrays (i.e., arrays of 1282 arrays) should be removed. 1283 1284Dependencies on OpenGL 4.3 and ARB_compute_shader 1285 1286 If OpenGL 4.3 and ARB_compute_shader are not supported, references to the 1287 COMPUTE_SUBROUTINE and COMPUTE_SUBROUTINE_UNIFORM interfaces should be 1288 removed. 1289 1290Dependencies on OpenGL 4.3 and ARB_explicit_uniform_location 1291 1292 If OpenGL 4.3 and ARB_explicit_uniform_location are not supported, 1293 references to uniform variables being declared with a layout qualifier 1294 should be removed. 1295 1296Errors 1297 1298 An INVALID_VALUE error is generated by GetProgramInterfaceiv, 1299 GetProgramResourceIndex, GetProgramResourceName, GetProgramResourceiv, 1300 GetProgramResourceLocation, and GetProgramResourceLocationIndex if 1301 <program> is not the name of either a shader or program object. 1302 1303 An INVALID_OPERATION error is generated by GetProgramInterfaceiv, 1304 GetProgramResourceIndex, GetProgramResourceName, GetProgramResourceiv, 1305 GetProgramResourceLocation, and GetProgramResourceLocationIndex if 1306 <program> is the name of a shader object. 1307 1308 INVALID_OPERATION is generated by GetProgramInterfaceiv if the parameter 1309 <pname> is not supported for the interface <programInterface>. 1310 1311 INVALID_ENUM is generated by GetProgramResourceIndex if <programInterface> 1312 is ATOMIC_COUNTER_BUFFER. 1313 1314 INVALID_VALUE is generated by GetProgramResourceName if <index> is greater 1315 than or equal to the number of entries in the active resource list for 1316 <programInterface>. 1317 1318 INVALID_ENUM is generated by GetProgramResourceName if <programInterface> 1319 is ATOMIC_COUNTER_BUFFER. 1320 1321 INVALID_VALUE is generated by GetProgramResourceiv if <propCount> is zero. 1322 1323 INVALID_ENUM is generated by GetProgramResourceiv if any value in <props> 1324 is not a property name supported by the command. 1325 1326 INVALID_OPERATION is generated by GetProgramResourceiv if any value in 1327 <props> is not supported for the interface <programInterface>. 1328 1329 INVALID_OPERATION is generated by GetProgramResourceLocation and 1330 GetProgramResourceLocationIndex if <program> has not been linked or was 1331 last linked unsuccessfully. 1332 1333New State 1334 1335 Insert new tables after Table 6.53, Program Object State (cont.), p. 557: 1336 1337 Add table, labeled "Program Interface State" 1338 1339 Initial 1340 Get Value Type Get Command Value Description Sec. 1341 ----------------------- ---- ----------- ------- ------------------------ ----- 1342 ACTIVE_RESOURCES nxZ+ GetProgramInterfaceiv 0 number of active resources 2.14.3 1343 on an interface 1344 MAX_NAME_LENGTH nxZ+ GetProgramInterfaceiv 0 maximum name length for 2.14.3 1345 active resources 1346 MAX_NUM_ACTIVE_VARIABLES nxZ+ GetProgramInterfaceiv 0 maximum number of active 2.14.3 1347 variables for active 1348 resources 1349 MAX_NUM_COMPATIBLE_SUBROUTINES nxZ+ GetProgramInterfaceiv 0 maximum number of compat- 2.14.3 1350 ible subroutines for 1351 subroutine uniforms 1352 1353 Add table, labeled "Program Object Resource State" 1354 1355 Initial 1356 Get Value Type Get Command Value Description Sec. 1357 ----------------------- ---- ----------- ------- ------------------------ ----- 1358 NAME_LENGTH Z+ GetProgram- - length of active resource 2.14.3 1359 Resourceiv name 1360 TYPE Z+ GetProgram- - active resource data type 2.14.3 1361 Resourceiv 1362 ARRAY_SIZE Z+ GetProgram- - active resource array size 2.14.3 1363 Resourceiv 1364 OFFSET Z+ GetProgram- - active resource offset in 2.14.3 1365 Resourceiv memory 1366 BLOCK_INDEX Z+ GetProgram- - index of interface block 2.14.3 1367 Resourceiv owning resource 1368 ARRAY_STRIDE Z+ GetProgram- - active resource array 2.14.3 1369 Resourceiv stride in memory 1370 MATRIX_STRIDE Z+ GetProgram- - active resource matrix 2.14.3 1371 Resourceiv stride in memory 1372 IS_ROW_MAJOR Z+ GetProgram- - active resource stored as 2.14.3 1373 Resourceiv a row major matrix? 1374 ATOMIC_COUNTER_BUFFER_INDEX Z+ GetProgram- - index of atomic counter 2.14.3 1375 Resourceiv buffer owning resource 1376 BUFFER_BINDING Z+ GetProgram- - buffer binding assigned 2.14.3 1377 Resourceiv to active resource 1378 BUFFER_DATA_SIZE Z+ GetProgram- - minimum buffer data size 2.14.3 1379 Resourceiv required for resource 1380 NUM_ACTIVE_VARIABLES Z+ GetProgram- - number of active variables 2.14.3 1381 Resourceiv owned by active resource 1382 ACTIVE_VARIABLES Z+ GetProgram- - list of active variables 2.14.3 1383 Resourceiv owned by active resource 1384 REFERENCED_BY_VERTEX_SHADER Z+ GetProgram- - active resource used by 2.14.3 1385 Resourceiv vertex shader? 1386 REFERENCED_BY_TESS_CONTROL_ Z+ GetProgram- - active resource used by 2.14.3 1387 SHADER Resourceiv tess. control shader? 1388 REFERENCED_BY_TESS_EVALUATION_ Z+ GetProgram- - active resource used by 2.14.3 1389 SHADER Resourceiv tess evaluation shader? 1390 REFERENCED_BY_GEOMETRY_SHADER Z+ GetProgram- - active resource used by 2.14.3 1391 Resourceiv geometry shader? 1392 REFERENCED_BY_FRAGMENT_SHADER Z+ GetProgram- - active resource used by 2.14.3 1393 Resourceiv fragment shader? 1394 REFERENCED_BY_COMPUTE_SHADER Z+ GetProgram- - active resource used by 2.14.3 1395 Resourceiv compute shader? 1396 TOP_LEVEL_ARRAY_SIZE Z+ GetProgram- - array size of top level 2.14.3 1397 Resourceiv shd. storage block member 1398 TOP_LEVEL_ARRAY_STRIDE Z+ GetProgram- - array stride of top level 2.14.3 1399 Resourceiv shd. storage block member 1400 LOCATION Z+ GetProgram- - location assigned to 2.14.3 1401 Resourceiv active resource 1402 LOCATION_INDEX Z+ GetProgram- - location index assigned 2.14.3 1403 Resourceiv to active resource 1404 IS_PER_PATCH Z+ GetProgram- - is active input/output 2.14.3 1405 Resourceiv a per-patch attribute? 1406 NUM_COMPATIBLE_SUBROUTINES Z+ GetProgram- - number of compatible 2.14.3 1407 Resourceiv subroutines for active 1408 subroutine uniform 1409 COMPATIBLE_SUBROUTINES Z+ GetProgram- - list of compatible 2.14.3 1410 Resourceiv subroutines for active 1411 subroutine uniform 1412 1413New Implementation Dependent State 1414 1415 None. 1416 1417Sample Code 1418 1419 !!! TBD !!! 1420 1421Conformance Tests 1422 1423 !!! TBD !!! 1424 1425Issues 1426 1427 (1) Does the list of active resources in a program include built-ins where 1428 applicable? 1429 1430 RESOLVED: Yes; built-ins should be enumerated when present. 1431 1432 (2) Should this extension fully support all program interfaces and 1433 resources, even those that have limited or no query capabilities 1434 today? In particular, there is very little enumeration support for 1435 fragment outputs and transform feedback varyings. OpenGL 4.1 added 1436 ARB_separate_shader_objects that allowed two independent programs to 1437 form an interface, but provided no mechanism for querying the active 1438 variables on either side of that interface. 1439 1440 RESOLVED: Let's support as much as we can with a single set of 1441 functions. 1442 1443 (3) How should we support enumeration of variables and interface blocks 1444 provided by the ARB_shader_storage_buffer_object extension? 1445 1446 RESOLVED: The enumeration mechanisms provided by this extension will be 1447 the only way to enumerate buffer variables and shader storage blocks. 1448 ARB_shader_storage_buffer_object will require this extension. 1449 1450 (4) The commands provided this extension are intended to supersede 1451 existing enumeration APIs (e.g., GetActiveUniform, GetActiveAttrib). 1452 The old APIs can eventually be deprecated. Both new and old APIs 1453 generate a list of active resources and assign indices to each entry 1454 in the list. Should assigned indices match between the new and old 1455 APIs? 1456 1457 RESOLVED: Yes. While there is no strong reason why the new APIs 1458 couldn't adopt new enumeration rules for existing resource types, it's 1459 easier to enumerate the same way that we've done for the older API 1460 calls, for several reasons: 1461 1462 * Minimizes changes for existing applications using the old 1463 enumeration APIs or for applications needing to support both the new 1464 and old APIs. All they need to do is map their existing API usage 1465 to the new APIs without having to reconsider whether any other 1466 assumption of their old logic is still valid. 1467 1468 * Minimizes complexity for implementations needing to support both new 1469 and old APIs, at least until the old APIs are deprecated/removed. 1470 1471 * Makes it easier to redefine the existing functions in terms of the 1472 new ones. 1473 1474 (5) Existing enumeration APIs handle entities like arrays of structures by 1475 unrolling them. For example, a uniform array of structures with 8 1476 elements and 3 structure members will result in 24 entries enumerated 1477 by GetActiveUniform. Should we re-work the API to enumerate fewer 1478 entries? 1479 1480 RESOLVED: For existing resources, no, for the reasons discussed above. 1481 The main problem with that approach is if a shader uses a uniform block 1482 with a large array of structures. For newer resource types, we can and 1483 will adopt new rules. 1484 1485 (6) How should enumeration rules work for complex arrays/structures in 1486 shader storage blocks (ARB_shader_storage_buffer_object)? 1487 1488 RESOLVED: One of the intended use cases is to allow for shader storage 1489 blocks consisting of little more than a large (or unsized) array of 1490 structures. For example, we might have shader code like: 1491 1492 struct VertexInfo { 1493 float position[3]; 1494 float normal[3]; 1495 }; 1496 buffer VertexCollection { 1497 VertexInfo v[10000]; 1498 }; 1499 1500 If existing uniform enumeration API rules were applied, this would 1501 enumerate 20000 separate active resources (10000 array elements with two 1502 members each). That seems crazy. This specification optimizes for this 1503 case by flattening arrays at the top of the block. For that shader, we 1504 would enumerate only the first element of each array ("v[0].position[0]" 1505 and "v[0].normal[0]"). The properties TOP_LEVEL_ARRAY_SIZE and 1506 TOP_LEVEL_ARRAY_STRIDE allow applications to determine the size (if 1507 declared) and stride in buffer object memory. 1508 1509 For more complex hierarchies, we chose to continue unrolling arrays in 1510 the middle of the hierarchy to avoid the need to specify a more complex 1511 API. For example, in this code 1512 1513 struct VertexInfo { 1514 float position[3]; 1515 float normal[3]; 1516 }; 1517 struct TriangleInfo { 1518 VertexInfo v[3]; 1519 }; 1520 buffer VertexCollection { 1521 TriangleInfo t[10000]; 1522 }; 1523 1524 we would unroll "TriangleInfo" and enumerate six resources: 1525 1526 t[0].v[0].position[0] 1527 t[0].v[0].normal[0] 1528 t[0].v[1].position[0] 1529 t[0].v[1].normal[0] 1530 t[0].v[2].position[0] 1531 t[0].v[2].normal[0] 1532 1533 Flattening "v[]" to a single entry would require either some sort of 1534 recursive enumeration (e.g., enumerate "t" as a structure and provide 1535 "pointers" to a collection of members), or some sort of new property 1536 that returns a variable-length array of strides. 1537 1538 (7) The ARB_array_of_arrays extension allows shaders to declare 1539 multi-dimensional arrays that could be enumerated by this API? How 1540 should arrays of arrays be enumerated? 1541 1542 RESOLVED: We define rules consistent with our enumeration rules for 1543 other complex types. For existing one-dimensional arrays, we enumerate 1544 a single entry if the array is an array of basic types, or separate 1545 entries for each array element if the array is an array of structures. 1546 We follow similar rules here. For a uniform array such as: 1547 1548 uniform vec4 a[5][4][3]; 1549 1550 we enumerate twenty different entries ("a[0][0][0]" through 1551 "a[4][3][0]"), each of which is treated as an array with three elements. 1552 This is morally equivalent to what you'd get if you worked around the 1553 limitation in current GLSL via: 1554 1555 struct ArrayBottom { vec4 c[3]; }; 1556 struct ArrayMid { ArrayBottom b[3]; }; 1557 uniform ArrayMid a[5]; 1558 1559 which would enumerate "a[0].b[0].c[0]" through "a[4].b[3].c[0]". 1560 1561 We also apply the top-level array flattening for shader storage block 1562 members. For example: 1563 1564 buffer Block { 1565 vec4 a[5][4][3]; 1566 }; 1567 1568 would enumerate only four entries -- "a[0][0][0]" through "a[0][3][0]", 1569 where each enumerated entry corresponds to an array of size 3, has a 1570 top-level size of 5, and has a top-level stride appropriate for its 1571 layout in memory. 1572 1573 (8) For GetProgramResourceIndex, what sort of strings can be used to match 1574 the resource names for arrays of arrays? For example, let's say a 1575 shader declares a uniform such as: 1576 1577 uniform vec4 a[3][4][5]; 1578 1579 Which one of the following names are accepted? "a[2][1][0]" to 1580 identify the base of the bottom-level array? "a[2][1]", to identify 1581 the same without the final "[0]"? "a[2]", equivalent to "a[2][0][0]"? 1582 Just "a", equivalent to "a[0][0][0]"? 1583 1584 RESOLVED: We only accept entries of the form "a[2][1][0]" or 1585 "a[2][1]", which is consistent with the existing rules that only allow 1586 applications to omit the last index of a bottom-level array that has 1587 been rolled up. 1588 1589 (9) Should be consolidate the commands GetAttribLocation, 1590 GetUniformLocation, GetSubroutineUniformLocation, GetFragDataLocation 1591 (and GetFragDataIndex) into a single generic API? 1592 1593 RESOLVED: Yes. This spec provides GetProgramResourceLocation and 1594 GetProgramResourceLocationIndex commands to consolidate the existing 1595 set of commands. Additionally, GetProgramResourceiv can be used to 1596 query locations via the LOCATION and LOCATION_INDEX properties. 1597 1598 There are a number of irregularities in the assignment of locations as 1599 compared to other uniform types: 1600 1601 * Atomic counter uniforms, uniforms in blocks are not assigned 1602 locations. 1603 1604 * Built in inputs and outputs are not assigned locations. 1605 1606 * The locations of inputs other than vertex shader inputs and 1607 fragment shader outputs don't interact with any other GL state; 1608 they are used only for interfacing with other programs. For such 1609 variables, we choose the return the specified location number if a 1610 variable is declared with a layout qualifier, and -1 (no valid 1611 location) otherwise. Variables declared without location layout 1612 qualifiers will be assigned an internal location by the 1613 compiler/linker, but those locations do not necessarily correspond 1614 to the canonical integer locations supported in layout qualifiers. 1615 1616 * For fragment shader outputs, not only do we have a location, but 1617 we also have an associated index that can be queried with 1618 GetFragDataIndex. 1619 1620 (10) What should we do about tokens like ACTIVE_UNIFORMS and 1621 ACTIVE_UNIFORM_MAX_LENGTH that are specific to an interface, but are 1622 queried today by GetProgramiv? 1623 1624 RESOLVED: We provide a new GetProgramInterfaceiv query to return 1625 properties of an interface. The value returned today by ACTIVE_UNIFORMS 1626 can be determined by calling GetProgramInterfaceiv with a 1627 <programInterface> of UNIFORM and a <pname> of ACTIVE_RESOURCES. 1628 ACTIVE_RESOURCES can also be used for other interfaces to get values 1629 returned today with other query tokens (e.g., ACTIVE_ATTRIBUTES). 1630 1631 (11) What sort of interface should we use for querying properties of 1632 active resources? We have two different styles of query today. 1633 Functions like GetActiveUniform() allow applications to query 1634 multiple (fixed) properties of a single active uniform. Functions 1635 like GetActiveUniforms() allow applications to query a single 1636 property of multiple active uniforms? 1637 1638 RESOLVED: GetProgramResourceiv allows applications to query multiple 1639 properties of a single resource in a single call; applications pass in 1640 an array of properties to query. 1641 1642 We considered providing a command GetProgramResourcesiv that would have 1643 allowed an application to query multiple properties of multiple 1644 resources in a single call, by passing in an array of resource indices. 1645 We decided not to include this for simplicity. Also note that the most 1646 common use case we envisioned would be to query all properties of all 1647 active resources, with code like the following: 1648 1649 struct VariableInfo { 1650 GLenum type; 1651 GLint location; 1652 }; 1653 GLenum inputProps[] = { GL_TYPE, GL_LOCATION }; 1654 GLuint nInputProps = sizeof(inputProps) / sizeof(GLenum); 1655 GLint nActive; 1656 glGetProgramInterface(program, GL_PROGRAM_INPUT, GL_ACTIVE_RESOURCES, 1657 &nActive); 1658 VariableInfo *varInfo = malloc(nActive*sizeof(VariableInfo)); 1659 GLuint *indices = malloc(nActive*sizeof(GLuint)); 1660 for (GLuint i = 0; i < nActive; i++) { indices[i] = i; } 1661 glGetProgramResourcesiv(program, GL_PROGRAM_INPUT, 1662 nActive, indices, nInputProps, inputProps, 1663 nActive*nInputProps, NULL, (GLint*)varInfo); 1664 1665 Such an API would require applications to fill in a dummy array of 1666 indices to express "all indices". With the simplified API, more GL 1667 calls are required, but the code is overall simpler: 1668 1669 glGetProgramInterface(program, GL_PROGRAM_INPUT, GL_ACTIVE_RESOURCES, 1670 &nActive); 1671 VariableInfo *varInfo = malloc(nActive*sizeof(VariableInfo)); 1672 for (GLuint i = 0; i < nActive; i++) { 1673 glGetProgramResourceiv(program, GL_PROGRAM_INPUT, i, 1674 nInputProps, inputProps, 1675 nActive*nInputProps, NULL, 1676 (GLint*) (&varInfo[i])); 1677 } 1678 1679 (12) For GetProgramResourceiv, how should we handle queries of properties 1680 that return a variable number of values (e.g., 1681 COMPATIBLE_SUBROUTINES)? Should we support these queries in the 1682 general "multiple properties of multiple resources" query, or provide 1683 a separate "single property of single resource query"? Should we 1684 just write out a variable number of values to <params>? If we allow 1685 for a variable number of values to be written to <params>, should we 1686 provide some sort of <bufSize> parameter to guard against overflows? 1687 1688 RESOLVED: We will support these properties in the general "multiple 1689 properties of a single resource" query and write out the variable number 1690 of values to consecutive locations in the array. If an application 1691 wants to query such properties for multiple resources at once, it can 1692 parse the values returned by the GL. If NUM_COMPATIBLE_SUBROUTINES is 1693 immediately before COMPATIBLE_SUBROUTINES in the property list, the 1694 number of compatible subroutines written to the buffer (N) will be found 1695 immediately immediately prior to the N compatible subroutine numbers. 1696 We will provide a <bufSize> parameter to guard against overflow. 1697 Applications can ensure they have an adequately-sized buffer by calling 1698 GetProgramInterfaceiv with a <pname> of MAX_NUM_COMPATIBLE_SUBROUTINES 1699 to determine the maximum number of subroutines that will be written to 1700 any one buffer. 1701 1702 It's not clear how valuable the variable-length enumeration queries 1703 actually are. Unextended OpenGL 4.2 has two such queries today: 1704 COMPATIBLE_SUBROUTINES and UNIFORM_BLOCK_ACTIVE_UNIFORMS. 1705 UNIFORM_BLOCK_ACTIVE_UNIFORMS isn't strictly needed; an application can 1706 determine this list themselves by querying the UNIFORM_BLOCK_INDEX 1707 property of each active uniform. We could do something similar for 1708 compatible subroutines. 1709 1710 (13) Should we add a mechanism for enumerating subroutine types supported 1711 by a program and querying the subroutine type for subroutines and 1712 subroutine uniforms? 1713 1714 RESOLVED: No. Such a mechanism could have been used to reduce the need 1715 for variable-length return values for GetProgramResourcesiv in some 1716 cases. Instead of supporting COMPATIBLE_SUBROUTINES (list all 1717 subroutines compatible with a uniform type), we could have allowed 1718 applications to query the subroutine type for both subroutines and 1719 subroutine uniforms and match them in application code. The problem 1720 with that approach is that subroutines can have multiple associated 1721 subroutine types, so a variable-length return value would still be 1722 needed to query subroutine types. 1723 1724 (14) Should we support "REFERENCED_BY_*" for uniforms and buffer 1725 variables? 1726 1727 RESOLVED: Yes. It isn't supported in unextended OpenGL 4.2, but the 1728 functionality seems to make sense. 1729 1730 (15) Since this extension is being developed at the same time as compute 1731 shaders, should we add compute shader-specific enums for the old 1732 queries that would be superseded by the the queries added here? Or 1733 should we rely solely on the new queries? For example, should we add 1734 a new token "UNIFORM_BLOCK_REFERENCED_BY_COMPUTE_SHADER"? 1735 1736 RESOLVED: Yes, we will add old-style enums for the compute shader stage 1737 for all previously existing APIs. 1738 1739 (16) How are inputs and outputs in the built-in interface block 1740 "gl_PerVertex" enumerated? 1741 1742 RESOLVED: We will follow the default rule for enumerating block members 1743 in the OpenGL API, which is: 1744 1745 * If a variable is a member of an interface block without an instance 1746 name, it is enumerated using just the variable name. 1747 1748 * If a variable is a member of an interface block with an instance 1749 name, it is enumerated as "BlockName.Member", where "BlockName" is 1750 the name of the interface block (not the instance name) and "Member" 1751 is the name of the variable. 1752 1753 For example, in the following code: 1754 1755 uniform Block1 { 1756 int member1; 1757 }; 1758 uniform Block2 { 1759 int member2; 1760 } instance2; 1761 uniform Block3 { 1762 int member3; 1763 } instance3[2]; // uses two separate buffer bindings 1764 1765 the three uniforms (if active) are enumerated as "member1", 1766 "Block2.member2", and "Block3.member3". 1767 1768 For tessellation control, tessellation evaluation, and geometry shaders, 1769 per-vertex built-in inputs like gl_Position are in a block with an 1770 instance name of "gl_in[]". Additionally, for tessellation control 1771 shaders, per-vertex built-in outputs like gl_Position are in a block 1772 with an instance name of "gl_out[]". In these cases, applying the 1773 standard rules would result in an enumerated name of 1774 "gl_PerVertex.gl_Position". 1775 1776 (17) Should we add support for enumerating per-patch shader 1777 inputs/outputs? If so, how to distinguish between per-vertex and 1778 per-patch? 1779 1780 RESOLVED: Yes. When program inputs or outputs include per-patch 1781 attributes, those variables will be enumerated along with per-vertex 1782 attributes. To determine if an input or output is per-patch, use the 1783 resource property IS_PER_PATCH. 1784 1785 (18) Do we enumerate the special "marker" variables for transform feedback 1786 varyings (gl_NextBuffer, gl_SkipComponents[1234])? If so, what are 1787 their properties? 1788 1789 RESOLVED: Yes, we should definitely enumerate them so applications can 1790 determine programmatically what would be written to transform feedback 1791 buffers. This capability is already supported by the existing 1792 GetTransformFeedback query. We follow the existing behavior -- all of 1793 these entries are enumerated with a type of NONE. gl_NextBuffer returns 1794 an array size of 0; gl_SkipComponents[1234] returns an array size equal 1795 to the specified number of components. 1796 1797 (19) Should we support a <bufsize> arguments to prevent buffer overflows 1798 on the GetProgramInterfaceiv query? 1799 1800 RESOLVED: Yes, to provide a "safe" mechanism since the query might 1801 return an unpredictable and program-dependent amount of data. We also 1802 provide a <length> parameter that can be used to return the number of 1803 words written by the query to be consistent with other similar APIs. 1804 1805 (20) Are "old" token names (e.g., UNIFORM_TYPE) accepted by "new" 1806 commmands (GetProgramResourceiv)? Are "new" token names (TYPE) 1807 accepted by "old" commands (GetActiveUniforms)? 1808 1809 RESOLVED: No. New queries support only the new enums; old queries 1810 support only the old ones. 1811 1812 (21) While programs may include shader code for multiple stages, shader 1813 subroutines and subroutine uniforms are specific to a single stage in 1814 the program. This means that there is a separate interface for each 1815 program stage. Should we specify <programInterface> tokens for a 1816 cross-product of interfaces and stages (e.g., VERTEX_SUBROUTINE, 1817 FRAGMENT_SUBROUTINE_UNIFORM)? Or should we provide generic 1818 <programInterface> tokens (SUBROUTINE, SUBROUTINE_UNIFORM) and accept 1819 a second <stage> parameter? 1820 1821 RESOLVED: Use concatenated tokens to avoid creating adding a separate 1822 set of per-stage APIs. With this solution, we have means 12 1823 concatenated tokens (6 stages crossed with SUBROUTINE and 1824 SUBROUTINE_UNIFORM); we don't expect a massive number of new tokens in 1825 the future. 1826 1827 (22) What data type should be used for the <params> (return data) argument 1828 to GetProgramResourceiv()? 1829 1830 RESOLVED: Use an "int *" to be consistent with all the other 1831 "*iv"-style queries. 1832 1833 We considered using a "void *" so applications could avoid manual casts 1834 for cases where the API would be used to fill a structure with 1835 properties of a resource, as in code like the following: 1836 1837 struct VariableInfo { 1838 GLenum type; 1839 GLint location; 1840 } varInfo; 1841 GLenum inputProps[] = { GL_TYPE, GL_LOCATION }; 1842 GLuint nInputProps = sizeof(inputProps) / sizeof(GLenum); 1843 ... 1844 glGetProgramResourceiv(program, GL_PROGRAM_INPUT, index, 1845 nInputProps, inputProps, nInputProps, NULL, 1846 (GLint*)varInfo); 1847 1848 (23) The special "marker" names "gl_NextBuffer" and "gl_SkipComponents*" 1849 may appear multiple times in the array of strings passed to 1850 TransformFeedbackVaryings. How is this condition handled in the new 1851 enumeration APIs? 1852 1853 RESOLVED: For the purposes of enumerating active resources in the 1854 TRANSFORM_FEEDBACK_VARYINGS interface, each instance of the marker is 1855 assigned its own index, and the name and properties associated with that 1856 index can be queried. [See also issue (18).] This is consistent with 1857 how GetTransformFeedbackVaryings works in unextended OpenGL 4.2. 1858 1859 The problem is that since a marker name can have multiple associated 1860 indices, it's not clear what value should be returned when passing such 1861 a string to GetProgramResourceIndex(). We specify that passing any of 1862 these marker strings should return the value INVALID_INDEX, regardless 1863 of the number of times the marker appears in the inputs to 1864 TransformFeedbackVaryings. Unextended OpenGL 4.2 does not provide the 1865 ability to query the index associated with an active transform feedback 1866 varying name, so this is a new issue in this extension. 1867 1868 (24) The PROGRAM_INPUT and PROGRAM_OUTPUT interfaces are provided to allow 1869 applications to query active inputs and outputs in a program. Do we 1870 enumerate all variables qualified with "in" and "out", or should 1871 special "system" built-ins such as gl_VertexID, gl_InstanceID, and 1872 gl_FrontFacing be excluded? 1873 1874 RESOLVED: We enumerate all active variables qualified with "in" or 1875 "out" in the PROGRAM_INPUT and PROGRAM_OUTPUT interfaces, including 1876 special variables. Additionally, because we redefine the function 1877 glGetActiveAttrib in terms of this in terms of the PROGRAM_INPUT 1878 interface, we should enumerate the specials gl_VertexID and 1879 gl_InstanceID there as well. Previously, there was no explicit spec 1880 language whether these variables should be enumerated by 1881 GetActiveAttrib, and various OpenGL implementations behaved differently. 1882 This approach allows applications to enumerate all inputs used by a 1883 vertex shader, whether or not they correspond to attributes in 1884 conventional or generic vertex attribute arrays. 1885 1886 (25) What should the value of ARRAY_SIZE be for non-array and unsized 1887 array variables? 1888 1889 RESOLVED: For compatibility with GetActiveUniform, ARRAY_SIZE of a 1890 non-array variable is one (initially this was specified as zero, an 1891 unintentional incompatibility). For unsized array variables, the size 1892 is zero. 1893 1894Revision History 1895 1896 Revision 21, January 10, 2019 (Jon Leech) 1897 - Add the property COMPATIBLE_SUBROUTINES to those queriable by 1898 GetProgramResourceiv (github OpenGL-Registry issue #11) 1899 Revision 20, August 19, 2013 (Jon Leech) 1900 - Change ARRAY_SIZE query to return one for active variables not 1901 corresponding to an array of basic types, rather than zero, for 1902 compatibility with GetActiveUniform (Bug 10647). Return zero for 1903 explicitly unsized arrays (Bug 10641). Add extra 'const' qualifier 1904 for GetUniformIndices <uniformNames> argument (Bug 10703). 1905 Revision 19, July 11, 2013 (Jon Leech) 1906 - Clarify that GetTransformFeedbackVarying can be used to query 1907 any transform feedback varying variable (Bug 10472). 1908 Revision 18, July 10, 2012 (pbrown) 1909 - Specify an INVALID_ENUM error when ATOMIC_COUNTER_BUFFER is passed 1910 to GetProgramResourceIndex or GetProgramResourceName. Clarify that 1911 the array element portion of a string passed to 1912 GetProgramResourceLocation or GetProgramResourceLocationIndex 1913 must not have, a "+" sign, extra leading zeroes, or whitespace (bug 1914 9254). 1915 Revision 17, July 7, 2012 (pbrown) 1916 - Specify that "special" built-ins inputs and outputs such as 1917 "gl_VertexID" should be enumerated in the PROGRAM_INPUT and 1918 PROGRAM_OUTPUT interfaces, as well as the legacy function 1919 GetActiveAttrib. Add spec language counting the built-ins gl_VertexID 1920 and gl_InstanceID against the active attribute limit (bug 9201). 1921 Revision 16, July 2, 2012 (pbrown) 1922 - Fix typos in the language mapping OpenGL 4.2 active subroutine and 1923 subroutine uniform enumeration functions to the new interfaces. 1924 Revision 15, June 21, 2012 (Jon Leech) 1925 - Update errors to match the generic errors for all commands taking 1926 <program> names (INVALID_VALUE if neither a shader nor program 1927 object name, and INVALID_OPERATION if a shader object name) (Bug 1928 9145). 1929 Revision 14, June 14, 2012 (Jon Leech) 1930 - Add INVALID_VALUE error if <program> is not the name of a valid 1931 program object (Bug 9145). 1932 Revision 13, May 31, 2012 (pbrown) 1933 - Specify that passing the special "marker" strings "gl_NextBuffer" 1934 and "gl_SkipComponents*" to GetProgramResourceIndex() will always 1935 return INVALID_INDEX (bug 9071). 1936 Revision 12, May 31, 2012 (pbrown) 1937 - Allow the BUFFER_VARIABLE, PROGRAM_INPUT, and PROGRAM_OUTPUT 1938 interfaces to be used by the REFERENCED_BY_*_SHADER property in 1939 GetProgramResourceiv (bug 9007). 1940 - Remove duplicate reference to BUFFER_VARIABLE in the list of 1941 interfaces supported by the ARRAY_SIZE property in 1942 GetProgramResourceiv. 1943 Revision 11, May 18, 2012 (pbrown) 1944 - Clarify that the LOCATION_INDEX property is only supported for the 1945 PROGRAM_OUTPUT interface and not for PROGRAM_INPUT. 1946 Revision 10, May 10, 2012 (pbrown) 1947 - Rename the formal parameter <interface> used by the functions in this 1948 extension to <programInterface>. Certain versions of the Microsoft 1949 C/C++ compiler and/or its headers cause "interface" to be treated as a 1950 reserved keyword. 1951 Revision 9, May 10, 2012 (pbrown) 1952 - Fix incorrect enumerant assignments. ATOMIC_COUNTER_BUFFER has 1953 already been assigned for ARB_shader_atomic_counters. Fix 1954 cut-and-paste error assigning a duplicate value to 1955 TESS_CONTROL_SUBROUTINE. Reassign value for IS_PER_PATCH to fill 1956 the ATOMIC_COUNTER_BUFFER hole. 1957 Revision 8, May 2, 2012 (pbrown) 1958 - Reserve enumerants. 1959 - Add state table entries. 1960 - Mark issues as resolved per the Khronos F2F. 1961 - Add issue (22), where we decided to keep the "int *" argument to 1962 GetProgramResourceiv(). 1963 Revision 7, April 25, 2012 1964 - Rename IS_PATCH_ATTRIB to IS_PER_PATCH (bug 8752). 1965 Revision 6, April 12, 2012 1966 - Add explicit language indicating that per-patch attributes can be 1967 enumerated in the PROGRAM_INPUT and PROGRAM_OUTPUT interfaces, plus 1968 the IS_PATCH_ATTRIB property. 1969 - Take a first cut at redefining all the existing enumeration APIs in 1970 terms of the new APIs. 1971 - Add missing OFFSET token to new token list. 1972 - Rename BUFFER_SIZE to BUFFER_DATA_SIZE to be consistent with older 1973 token names. 1974 - Mark various issues as resolved. 1975 Revision 5, April 12, 2012 1976 - Remove support for querying properties of multiple resources in a 1977 single call; rename GetProgramResourcesiv to GetProgramResourceiv 1978 since only a single resource is queried at a time. 1979 - Fold issue (22) into issue (11). 1980 Revision 4, April 5, 2012 1981 - Add issue (22) about the need to allocate/fill an array of indices even 1982 if you want to query properties of all active resources at once. 1983 Revision 3, April 5, 2012 1984 - Checkpoint with various edits/cleanups. Add an introduction; clean up 1985 new procedures, tokens, errors, and issues sections. 1986 - Rename APIs to GetProgramInterface and GetProgramResource*. 1987 - Add GetProgramResourceLocation API as a generic location query. 1988 - Add interactions with ARB_compute_shader. 1989 - Add interactions with ARB_explicit_uniform_location. 1990 - Add discussion of enumeration of built-in variables and special 1991 transform feedback markers. 1992 - Add general discussion of locations assigned to active variables. 1993 - Add interface properties MAX_NUM_ACTIVE_VARIABLES and 1994 MAX_NUM_COMPATIBLE_SUBROUTINES. 1995 - Add resource properties LOCATION and LOCATION_INDEX. 1996 - Add <bufSize> and <length> parameters to GetProgramResourcesiv. 1997 Revision 2, March 22, 2012 1998 - Added new function prototypes for review purposes. 1999 Revision 1, March 14, 2012 2000 - Initial revision. 2001 2002