1Name 2 3 ARB_shader_subroutine 4 5Name Strings 6 7 GL_ARB_shader_subroutine 8 9Contact 10 11 Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com) 12 13Contributors 14 15 Barthold Lichtenbelt, NVIDIA 16 Bill Licea-Kane, AMD 17 Bruce Merry, ARM 18 Eric Werness, NVIDIA 19 Graham Sellers, AMD 20 Greg Roth, NVIDIA 21 Nick Haemel, AMD 22 Pat Brown, NVIDIA 23 Pierre Boudier, AMD 24 Piers Daniell, NVIDIA 25 26Notice 27 28 Copyright (c) 2010-2014 The Khronos Group Inc. Copyright terms at 29 http://www.khronos.org/registry/speccopyright.html 30 31Specification Update Policy 32 33 Khronos-approved extension specifications are updated in response to 34 issues and bugs prioritized by the Khronos OpenGL Working Group. For 35 extensions which have been promoted to a core Specification, fixes will 36 first appear in the latest version of that core Specification, and will 37 eventually be backported to the extension document. This policy is 38 described in more detail at 39 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 40 41Status 42 43 Complete. Approved by the ARB at the 2010/01/22 F2F meeting. 44 Approved by the Khronos Board of Promoters on March 10, 2010. 45 46Version 47 48 Last Modified Date: 02/28/2014 49 Revision: 19 50 51Number 52 53 ARB Extension #90 54 55Dependencies 56 57 This extension is written against the OpenGL 3.2 core specification and 58 version 1.50 of the GLSL specification. 59 60 ARB_gpu_shader5 is required. 61 62 This extension interacts with NV_gpu_program5. 63 64 This extension interacts trivially with EXT_separate_shader_objects. 65 66Overview 67 68 This extension adds support to shaders for "indirect subroutine calls", 69 where a single shader can include many subroutines and dynamically select 70 through the API which subroutine is called from each call site. 71 Switching subroutines dynamically in this fashion can avoid the cost of 72 recompiling and managing multiple shaders, while still retaining most of 73 the performance of specialized shaders. 74 75IP Status 76 77 No known IP claims. 78 79New Procedures and Functions 80 81 int GetSubroutineUniformLocation(uint program, enum shadertype, 82 const char *name); 83 uint GetSubroutineIndex(uint program, enum shadertype, 84 const char *name); 85 void GetActiveSubroutineUniformiv(uint program, enum shadertype, 86 uint index, enum pname, int *values); 87 void GetActiveSubroutineUniformName(uint program, enum shadertype, 88 uint index, sizei bufsize, 89 sizei *length, char *name); 90 void GetActiveSubroutineName(uint program, enum shadertype, uint index, 91 sizei bufsize, sizei *length, char *name); 92 void UniformSubroutinesuiv(enum shadertype, sizei count, 93 const uint *indices); 94 void GetUniformSubroutineuiv(enum shadertype, int location, 95 uint *params); 96 void GetProgramStageiv(uint program, enum shadertype, 97 enum pname, int *values); 98 99New Tokens 100 101 Accepted by the <pname> parameter of GetProgramStageiv: 102 103 ACTIVE_SUBROUTINES 0x8DE5 104 ACTIVE_SUBROUTINE_UNIFORMS 0x8DE6 105 ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS 0x8E47 106 ACTIVE_SUBROUTINE_MAX_LENGTH 0x8E48 107 ACTIVE_SUBROUTINE_UNIFORM_MAX_LENGTH 0x8E49 108 109 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 110 GetFloatv, GetDoublev, and GetInteger64v: 111 112 MAX_SUBROUTINES 0x8DE7 113 MAX_SUBROUTINE_UNIFORM_LOCATIONS 0x8DE8 114 115 Accepted by the <pname> parameter of GetActiveSubroutineUniformiv: 116 117 NUM_COMPATIBLE_SUBROUTINES 0x8E4A 118 COMPATIBLE_SUBROUTINES 0x8E4B 119 UNIFORM_SIZE 120 UNIFORM_NAME_LENGTH 121 122 123Additions to Chapter 2 of the OpenGL 3.2 Specification (OpenGL Operation) 124 125 Add a section "Subroutine Uniform Variables" after Section 2.11.4, 126 "Uniform Variables" 127 128 Subroutine uniform variables are similar to uniform variables, except they 129 are context state rather than program state. Having subroutine uniforms be 130 context state allows them to have different values if the program is used 131 in multiple contexts simultaneously. There is a set of subroutine 132 uniforms for each shader stage. 133 134 The command 135 136 int GetSubroutineUniformLocation(uint program, enum shadertype, 137 const char *name); 138 139 will return the location of the subroutine uniform variable <name> in the 140 shader stage of type <shadertype> attached to <program>, with behavior otherwise 141 identical to GetUniformLocation. The value -1 will be returned if <name> 142 is not the name of an active subroutine uniform. Active subroutine 143 locations are assigned using consecutive integers in the range from zero 144 to the value of ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS minus one for the shader 145 stage. There is an implementation-dependent limit on the number of active 146 subroutine uniform locations in each shader stage; a program will fail to 147 link if the number of subroutine uniform locations required is greater 148 than the value of MAX_SUBROUTINE_UNIFORM_LOCATIONS. If <program> has not 149 been successfully linked, the error INVALID_OPERATION will be generated. 150 For active subroutine uniforms declared as arrays, the declared array 151 elements are assigned consecutive locations. 152 153 Each function in a shader associated with a subroutine type is considered 154 an active subroutine, unless the compiler conclusively determines that the 155 function could never be assigned to an active subroutine uniform. Each 156 active subroutine will be assigned an unsigned integer subroutine index 157 that is unique to the shader stage. This index can be queried with the 158 command 159 160 uint GetSubroutineIndex(uint program, enum shadertype, 161 const char *name); 162 163 where <name> is the null-terminated name of a function in the shader stage 164 of type <shadertype> attached to <program>. Subroutine indices are assigned using 165 consecutive integers in the range from zero to the value of 166 ACTIVE_SUBROUTINES minus one for the shader stage. The value INVALID_INDEX will 167 be returned if <name> is not the name of an active subroutine in the 168 shader stage. After the program has been linked, the subroutine index 169 will not change unless the program is re-linked. 170 171 There is an implementation-dependent limit on the number of active 172 subroutines in each shader stage; a program will fail to link if the 173 number of subroutines is greater than the maximum subroutine count 174 (the value of MAX_SUBROUTINES). 175 176 Information about active subroutine uniforms can be obtained by calling 177 178 void GetActiveSubroutineUniformiv(uint program, enum shadertype, 179 uint index, enum pname, int *values); 180 void GetActiveSubroutineUniformName(uint program, enum shadertype, 181 uint index, sizei bufsize, 182 sizei *length, char *name); 183 184 <program> and <shadertype> specify the program and shader stage. <index> 185 must be an active subroutine uniform index in the range from zero to the 186 value of ACTIVE_SUBROUTINE_UNIFORMS minus one for the shader stage. If <index> 187 is greater than or equal to the value of ACTIVE_SUBROUTINE_UNIFORMS, the 188 error INVALID_VALUE is generated. 189 190 For GetActiveSubroutineUniformiv, <pname> identifies a property of the 191 active subroutine uniform being queried. If <pname> is 192 NUM_COMPATIBLE_SUBROUTINES, a single integer indicating the number of 193 subroutines that can be assigned to the uniform is returned in <values>. 194 If <pname> is COMPATIBLE_SUBROUTINES, an array of integers is returned in 195 <values>, with each integer specifying the index of an active subroutine 196 that can be assigned to the selected subroutine uniform. The number of 197 integers returned is the same as the value returned for 198 NUM_COMPATIBLE_SUBROUTINES. If <pname> is UNIFORM_SIZE, a single integer 199 is returned in <values>. If the selected subroutine uniform is an array, 200 the declared size of the array is returned; otherwise, one is returned. 201 If <pname> is UNIFORM_NAME_LENGTH, a single integer specifying the length 202 of the subroutine uniform name (including the terminating null character) 203 is returned in <values>. 204 205 For GetActiveSubroutineUniformName, the uniform name is returned as a 206 null-terminated string in <name>. The actual number of characters written 207 into <name>, excluding the null terminator is returned in <length>. If 208 <length> is NULL, no length is returned. The maximum number of characters 209 that may be written into <name>, including the null terminator, is 210 specified by <bufsize>. The length of the longest subroutine uniform name 211 in <program> and <shadertype> is given by the value of 212 ACTIVE_SUBROUTINE_UNIFORM_MAX_LENGTH, which can be queried with 213 GetProgramStageiv. 214 215 The name of an active subroutine can be queried given its subroutine 216 index with the command: 217 218 void GetActiveSubroutineName(uint program, enum shadertype, 219 uint index, sizei bufsize, 220 sizei *length, char *name); 221 222 <program> and <shadertype> specify the program and shader stage. <index> 223 must be an active subroutine index in the range from zero to the value of 224 ACTIVE_SUBROUTINES minus one for the shader stage. If <index> is greater than 225 or equal to the value of ACTIVE_SUBROUTINES, the error INVALID_VALUE is 226 generated. The name of the selected subroutine is returned as a 227 null-terminated string in <name>. The actual number of characters written 228 into <name>, excluding the null terminator, is returned in <length>. If 229 <length> is NULL, no length is returned. The maximum number of characters 230 that may be written into <name>, including the null terminator, is 231 specified by <bufsize>. The length of the longest subroutine name in 232 <program> and <shadertype> is given by the value of 233 ACTIVE_SUBROUTINE_MAX_LENGTH, which can be queried with GetProgramStageiv. 234 235 The command 236 237 void UniformSubroutinesuiv(enum shadertype, sizei count, 238 const uint *indices); 239 240 will load all active subroutine uniforms for shader stage <shadertype> 241 with subroutine indices from <indices>, storing <indices>[i] into the 242 uniform at location i. If <count> is not equal to the value of 243 ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS for the program currently in use at 244 shader stage <shadertype>, or if any value in <indices> is greater than or 245 equal to the value of ACTIVE_SUBROUTINES for the shader stage, the error 246 INVALID_VALUE is generated. If, for any subroutine index being loaded to 247 a particular uniform location, the function corresponding to the 248 subroutine index was not associated (as defined in Section 6.1.2 of the 249 GLSL spec) with the type of the subroutine variable at that location, then 250 the error INVALID_OPERATION is generated. If no program is active for 251 the shader stage identified by <shadertype>, the error INVALID_OPERATION 252 is generated. 253 254 Each subroutine uniform must have at least one subroutine to assign to the 255 uniform. A program will fail to link if any stage has one or more 256 subroutine uniforms that has no subroutine associated with the subroutine 257 type of the uniform. 258 259 When UseProgram is called, the subroutine uniforms for all shader stages 260 are reset to arbitrarily chosen default functions with compatible 261 subroutine types. When UseShaderProgramEXT is called, the subroutine 262 uniforms for the shader stage specified by <type> are reset to arbitrarily 263 chosen default functions with compatible subroutine types. 264 265 266Additions to Chapter 3 of the OpenGL 3.2 Specification (Rasterization) 267 268 None. 269 270Additions to Chapter 4 of the OpenGL 3.2 Specification (Per-Fragment 271Operations and the Frame Buffer) 272 273 None. 274 275Additions to Chapter 5 of the OpenGL 3.2 Specification (Special Functions) 276 277 None. 278 279Additions to Chapter 6 of the OpenGL 3.2 Specification (State and 280State Requests) 281 282 Add to Section 6.1.15 (Shader and Program Queries) 283 284 The command 285 286 void GetUniformSubroutineuiv(enum shadertype, int location, 287 uint *params); 288 289 returns the value of the subroutine uniform at location <location> for 290 shader stage <shadertype> of the current program. If <location> is 291 greater than or equal to the value of ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS 292 for the shader currently in use at shader stage <shadertype>, the error 293 INVALID_VALUE is generated. If no program is active, the error 294 INVALID_OPERATION is generated. 295 296 The command 297 298 void GetProgramStageiv(uint program, enum shadertype, 299 enum pname, int *values); 300 301 returns properties of the program object <program> specific to the 302 programmable stage corresponding to <shadertype> in <values>. The 303 parameter value to return is specified by <pname>. If <pname> is 304 ACTIVE_SUBROUTINE_UNIFORMS, the number of active subroutine variables in 305 the stage is returned. If <pname> is ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS, 306 the number of active subroutine variable locations in the stage is 307 returned. If <pname> is ACTIVE_SUBROUTINES, the number of active 308 subroutines in the stage is returned. If <pname> is 309 ACTIVE_SUBROUTINE_UNIFORM_MAX_LENGTH or ACTIVE_SUBROUTINE_MAX_LENGTH, the 310 length of the longest subroutine uniform or subroutine name, respectively, 311 for the stage is returned. The returned name length includes space for a 312 null terminator. If there is no shader of type <shadertype> in <program>, 313 the values returned will be consistent with a shader with no subroutines 314 or subroutine uniforms. 315 316 317Modifications to The OpenGL Shading Language Specification, Version 1.50 318 319 Including the following line in a shader can be used to control the 320 language features described in this extension: 321 322 #extension GL_ARB_shader_subroutine : <behavior> 323 324 where <behavior> is as specified in section 3.3. 325 326 In section 3.6, p.14 (Keywords) 327 328 Add subroutine to the list of reserved keywords. 329 330 Modify Section 6.1.1 (Function Calling Conventions) 331 332 (modify the last paragraph of the section, p. 66, to forbid potential 333 recursion via subroutines) Recursion is not allowed, not even statically. 334 Static recursion is present if the static function-call graph of a program 335 contains cycles. This includes all potential function calls through 336 variables declared as subroutine uniform (described below). It is an 337 error if a single compilation unit (shader) contains either static 338 recursion or the potential for recursion through subroutine variables. 339 340 Add a new Section 6.1.2 (Subroutines) 341 342 Subroutines provide a mechanism allowing shaders to be compiled in a 343 manner where the target of one or more function calls can be changed at 344 run-time without requiring any shader recompilation. For example, a 345 single shader may be compiled with support for multiple illumination 346 algorithms to handle different kinds of lights or surface materials. An 347 application using such a shader may switch illumination algorithms by 348 changing the value of its subroutine uniforms. To use subroutines, a 349 subroutine type is declared, one or more functions are associated with 350 that subroutine type, and a subroutine variable of that type is declared. 351 The function currently assigned to the variable function is then called by 352 using function calling syntax replacing a function name with the name of 353 the subroutine variable. Subroutine variables are assigned to specific 354 functions only through commands (UniformSubroutinesuiv) in the OpenGL API. 355 356 Subroutine types can be declared using a statement similar to a function 357 declaration, as follows: 358 359 subroutine returnType subroutineTypeName(type0 arg0, type1 arg1, 360 ..., typen argn); 361 362 Functions may be associated to subroutine types that have a matching 363 prototype by prepending the subroutine types to the function definition: 364 365 subroutine(subroutineTypeName0, ..., subroutineTypeNameN) 366 returnType functionName (type0 arg0, type1 arg1, ..., typen argn) 367 ... // function body 368 369 Subroutine declarations cannot be prototyped. It is an error to prepend 370 subroutine(...) to a function declaration. It is an error to declare 371 two distinct functions with the same function name within the same shader 372 (i.e. overloaded function names) that are both associated to subroutine 373 types. 374 375 Subroutine types share a namespace with standard function names. 376 Overloading (section 6.1) is not supported for functions that may be 377 associated with subroutine types. A program will fail to link if any 378 shader includes two or more functions with the same name, at least one of 379 which is associated with a subroutine type. 380 381 Subroutine variables are required to be "subroutine uniforms", and 382 are declared with a specific subroutine type in a subroutine uniform 383 variable declaration: 384 385 subroutine uniform subroutineTypeName subroutineVarName; 386 387 and are called the same way simple functions are called. Subroutine 388 variables may be declared as explicitly-sized arrays, which can be 389 dynamically indexed at use. 390 391 Subroutine variables are associated to functions declared with the 392 same subroutine type with the UniformSubroutinesuiv command in the OpenGL 393 API. When a subroutine variable (or an element of a subroutine variable 394 array) is associated to a particular function, all function calls through 395 that variable will call that particular function. 396 397Additions to the AGL/GLX/WGL Specifications 398 399 None. 400 401GLX Protocol 402 403 None. 404 405Errors 406 407 The error INVALID_OPERATION is generated by GetSubroutineUniformLocation 408 if the program object identified by <program> has not been successfully 409 linked. 410 411 The error INVALID_VALUE is generated by GetActiveSubroutineUniformiv or 412 GetActiveSubroutineUniformName if <index> is greater than or equal to the 413 value of ACTIVE_SUBROUTINE_UNIFORMS for the shader stage. 414 415 The error INVALID_VALUE is generated by GetActiveSubroutineName if <index> 416 is greater than or equal to the value of ACTIVE_SUBROUTINES for the shader 417 stage. 418 419 The error INVALID_VALUE is generated by UniformSubroutinesuiv if <count> 420 is not equal to the value of ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS for the 421 shader stage <shadertype>. 422 423 The error INVALID_VALUE is generated by UniformSubroutinesuiv if any value 424 in <indices> is greater than or equal to the value of ACTIVE_SUBROUTINES 425 for the shader stage. 426 427 The error INVALID_OPERATION is generated by UniformSubroutinesuiv if any 428 subroutine index in <indices> identifies a subroutine not associated with 429 the type of the subroutine uniform variable assigned to the corresponding 430 location. 431 432 The error INVALID_OPERATION is generated by UniformSubroutinesuiv if no 433 program is active. 434 435 The error INVALID_VALUE is generated by GetUniformSubroutineuiv if 436 <location> is greater than or equal to the value of 437 ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS for the shader stage. 438 439 The error INVALID_OPERATION is generated by GetUniformSubroutineuiv if no 440 program is active for the shader stage identified by <shadertype>. 441 442 443New State 444 445 (add to table 6.28, Program Object State, p. 293) 446 447 Initial 448 Get Value Type Get Command Value Description Sec. 449 --------------------------- ---------- ----------- ------- --------------------------- ------ 450 ACTIVE_SUBROUTINE_UNIFORM_ 5xZ+ GetProgram- 0 Number of subroutine unif. 2.11.4 451 LOCATIONS Stageiv locations in the shader 452 ACTIVE_SUBROUTINE_UNIFORMS 5xZ+ GetProgram- 0 Number of subroutine unif. 2.11.4 453 Stageiv variables in the shader 454 ACTIVE_SUBROUTINES 5xZ+ GetProgram- 0 Number of subroutine 2.11.4 455 Stageiv functions in the shader 456 ACTIVE_SUBROUTINE_UNIFORM_ 5xZ+ GetProgram- 0 Maximum subroutine uniform 2.11.4 457 MAX_LENGTH Stageiv name length 458 ACTIVE_SUBROUTINE_MAX_LENGTH 5xZ+ GetProgram- 0 Maximum subroutine name 2.11.4 459 Stageiv length 460 NUM_COMPATIBLE_SUBROUTINES 5x0*xZ+ GetActiveSub- - Number of subroutines comp- 2.11.4 461 routineUniformiv atible with a sub. uniform 462 COMPATIBLE_SUBROUTINES 5x0*x0*xZ+ GetActiveSub- - List of subroutines comp- 2.11.4 463 routineUniformiv atible with a sub. uniform 464 UNIFORM_SIZE 5x0*xZ+ GetActiveSub- - Number of elements in sub. 2.11.4 465 routineUniformiv uniform array 466 UNIFORM_NAME_LENGTH 5x0*xZ+ GetActiveSub- - Length of sub. uniform name 2.11.4 467 routineUniformiv 468 - 5x0*xS GetActiveSub- - Sub. uniform name string 2.11.4 469 routineUniformName 470 - 5x0*xS GetActiveSub- - Length of subroutine name 2.11.4 471 routineName 472 - 5x0*xS GetActiveSub- - Subroutine name string 2.11.4 473 routineName 474 475 (For the above, the "5" is indicates separate state for each of the five 476 shader stages in the program.) 477 478 479New Implementation Dependent State 480 481 Minimum 482 Get Value Type Get Command Value Description Sec. Attrib 483 ----------------------------- ---- --------------- ------- --------------------- ------ ------ 484 MAX_SUBROUTINES Z+ GetIntegerv 256 Maximum number of 2.14.1 - 485 subroutines per 486 shader stage 487 MAX_SUBROUTINE_UNIFORM_ Z+ GetIntegerv 1024 Maximum number of 2.X.5 - 488 LOCATIONS subroutine uniform 489 locations per stage 490 491 492Dependencies on NV_gpu_program5: 493 494 If NV_gpu_program5 is supported, the following edits are made to extend 495 the assembly programming model documented in the NV_gpu_program4 extension 496 and extended by NV_gpu_program5. No "OPTION" line is required; the 497 following capability is implied by NV_gpu_program5 program headers such as 498 "!!NVfp5.0". 499 500 New Procedures and Functions 501 502 void ProgramSubroutineParametersuivNV(enum target, sizei count, 503 const uint *params); 504 void GetProgramSubroutineParameteruivNV(enum target, uint index, 505 uint *param); 506 507 New Tokens 508 509 Accepted by the <pname> parameter of GetProgramivARB: 510 511 MAX_PROGRAM_SUBROUTINE_PARAMETERS_NV 0x8F44 512 MAX_PROGRAM_SUBROUTINE_NUM_NV 0x8F45 513 514 (Modify "Section 2.14.1" of the ARB_vertex_program specification, 515 describing program parameters.) 516 517 Each program target has an associated array of program subroutine 518 parameters. Unlike program local parameters, program subroutine parameters 519 are context state rather than program state. Program subroutine parameters 520 are scalar unsigned integer values that correspond to "SUBROUTINENUM" 521 declarations in a program. The number of scalars is given by the 522 implementation-dependent value MAX_PROGRAM_SUBROUTINE_PARAMETERS_NV. 523 The command 524 525 void ProgramSubroutineParametersuivNV(enum target, sizei count, 526 const uint *params); 527 528 updates the values of all program subroutine parameters used by the 529 currently bound program for the given program target <target>. <params> 530 points to an array of <count> values, where the first value is used to 531 update the program subroutine parameter numbered zero and the last value 532 is used to update the program subroutine parameter numbered <count> - 1. 533 The error INVALID_VALUE is generated if <count> is not equal to one plus 534 the maximum program subroutine parameter index used in the currently bound 535 program. 536 537 Program subroutine parameters for a given target are reset to arbitrary 538 defaults when the program string is respecified, and when BindProgram is 539 called to bind a program to that target, even if the specified program is 540 already bound. 541 542 The error INVALID_OPERATION is generated by 543 ProgramSubroutineParametersuivNV if, for any number <i> in [0, <count>), 544 program.subroutine[<i>] is a live parameter of a certain SUBROUTINETYPE, 545 and <params>[<i>] is not a SUBROUTINENUM that was associated to that 546 SUBROUTINETYPE as described in Section 2.X.5. 547 548 Modify Section 2.X.2 of NV_gpu_program4, Program Grammar 549 550 If a program begins with a header string defined by GL_NV_gpu_program5, 551 the following modifications apply to the program grammar: 552 553 <FlowInstruction> ::= <BRAop_instruction> 554 | <FLOWCCop_instruction> 555 | <IFop_instruction> 556 | <REPop_instruction> 557 | <ENDFLOWop_instruction> 558 | <CALI_instruction> 559 560 <namingStatement> ::= <varMods> <ATTRIB_statement> 561 | <varMods> <PARAM_statement> 562 | <varMods> <TEMP_statement> 563 | <varMods> <OUTPUT_statement> 564 | <varMods> <BUFFER_statement> 565 | <ALIAS_statement> 566 | <SUBROUTINETYPE_statement> 567 | <SUBROUTINE_statement> 568 569 <labelList> ::= <identifier> 570 | <identifier> "," <labelList> 571 572 <labelInitList> ::= /* empty */ 573 | <labelList> 574 575 <SUBROUTINETYPE_statement> ::= "SUBROUTINETYPE" <establishName> "{" 576 <labelInitList> "}" 577 578 <progSubroutineParam> ::= "program" "." "subroutine" <arrayMemAbs> 579 580 <progSubroutineParams> ::= <progSubroutineParam> 581 | "program" "." "subroutine" <arrayRange> 582 583 <progSubroutineInitList>::= <progSubroutineParams> 584 | <progSubroutineParams> "," 585 <progSubroutineInitList> 586 587 <SUBROUTINE_statement> ::= "SUBROUTINE" <establishedName> <establishName> 588 "=" <progSubroutineParam> 589 | "SUBROUTINE" <establishedName> <establishName> 590 <optArraySize> "=" "{" <progSubroutineInitList> 591 "}" 592 593 <CALIop> ::= "CALI" 594 595 <CALI_instruction> ::= <CALIop> <opModifiers> <subroutineVarName> 596 <optArrayMem> <optBranchCond> 597 598 <instLabel> ::= <identifier> 599 | <identifier> "SUBROUTINENUM" "(" <int> ")" 600 601 602 Modify Section 2.X.4, Program Execution Environment 603 604 (Update the instruction set table to add CALI) 605 606 Instr- Modifiers 607 uction V F I C S H D Out Inputs Description 608 ------- -- - - - - - - --- -------- -------------------------------- 609 CALI 50 - - - - - - - c indirect subroutine call 610 611 Modify Section 2.X.5 (Program Flow Control) of the NV_gpu_program4 612 specification 613 614 (Add after the description of subroutines) 615 616 Subroutines may be called indirectly using the CALI instruction. An 617 "indirect" call will transfer control to one of a set of labels, where 618 the specific label that is used in a particular program invocation is 619 set through a "subroutine" parameter (see Section 2.14.1). 620 621 Functions that will be used for indirect subroutine calls must all be 622 assigned a unique unsigned integer SUBROUTINENUM using the modified 623 <instLabel> grammar rule. 624 625 A <SUBROUTINETYPE_statement> associates one or more subroutine labels with 626 a "type". For example: 627 628 SUBROUTINETYPE Hero { batman, robin }; 629 630 creates a SUBROUTINETYPE named "Hero" (if it does not already exist) and 631 adds the subroutines whose labels are "batman" and "robin" to the 632 SUBROUTINETYPE. 633 634 A "subroutine" parameter is a special type of program parameter whose value 635 refers to one of a set of subroutines, selected by the API. A subroutine is 636 given a SUBROUTINETYPE when it is declared, and it may refer to any label 637 of that type. Continuing this example: 638 639 SUBROUTINETYPE Hero { superman, wolverine }; 640 SUBROUTINETYPE Hero { batman, robin }; 641 SUBROUTINETYPE GothamHero { batman, robin }; 642 643 # anyHero may "point to" any Hero 644 SUBROUTINE Hero anyHero = program.subroutine[0]; 645 # gothamHero may "point to" any GothamHero 646 SUBROUTINE GothamHero gothamHero = program.subroutine[1]; 647 648 batman SUBROUTINENUM(0): 649 ... 650 robin SUBROUTINENUM(1): 651 ... 652 superman SUBROUTINENUM(2): 653 ... 654 wolverine SUBROUTINENUM(3): 655 ... 656 657 main: 658 # could call any of the four heros 659 CALI anyHero; 660 # could call either batman or robin 661 CALI gothamHero; 662 663 Program subroutine parameters are assigned to labels by setting the 664 corresponding SUBROUTINENUMs via ProgramSubroutineParametersuivNV. For 665 example, 666 667 uint params[2] = {2, 0}; 668 ProgramSubroutineParametersuivNV(target, 2, params); 669 670 would assign program.subroutine[0] (and therefore "anyHero") to "superman", 671 and program.subroutine[1] (and therefore "gothamHero") to "batman". 672 673 All SUBROUTINENUMs must be greater than or equal to zero, and less than the 674 value of MAX_PROGRAM_SUBROUTINE_NUM_NV. A label may be assigned to multiple 675 SUBROUTINETYPEs. A program subroutine parameter may only be assigned to 676 subroutine variables of a single SUBROUTINETYPE. 677 678 Programs that may potentially cause infinite recursion through indirect 679 calls will fail to compile. 680 681 682 Section 2.X.8.Z, CALI: Indirect Subroutine Call 683 684 The CALI instruction conditionally transfers control to the instruction 685 following some label, as described in CAL. The determination of which 686 label is used is described in Section 2.X.5 (Program Flow Control). 687 688 Add to Chapter 6 (State and State Requests) 689 690 The command 691 692 void GetProgramSubroutineParameteruivNV(enum target, uint index, 693 uint *params); 694 695 obtains the current value for the program subroutine parameter numbered 696 <index> for the given program target <target>, and places the single 697 unsigned integer value in the array <params>. The error INVALID_ENUM is 698 generated if <target> specifies a nonexistent program target or a program 699 target that does not support program environment parameters. The error 700 INVALID_VALUE is generated if <index> is greater than or equal to the 701 implementation-dependent number of supported program subroutine parameters 702 for the program target. 703 704 Add various new conditions by which a program string would fail to load. 705 706 The error INVALID_ENUM is generated by GetProgramSubroutineParameteruivNV 707 and ProgramSubroutineParametersuivNV if <target> specifies a nonexistent 708 program target. 709 710 The error INVALID_VALUE is generated by GetProgramSubroutineParameteruivNV 711 if <index> is greater than or equal to the max number of program subroutine 712 parameters, and by ProgramSubroutineParametersuivNV if <count> is <count> 713 is not equal to one plus the maximum program subroutine parameter index used 714 in the currently bound program. 715 716 The error INVALID_OPERATION is generated by 717 ProgramSubroutineParametersuivNV if, for any number <i> in [0, <count>), 718 program.subroutine[<i>] is a live parameter of a certain SUBROUTINETYPE, 719 and <params>[<i>] is not a SUBROUTINENUM that was associated to that 720 SUBROUTINETYPE as described in Section 2.X.5. 721 722 Add new implementation dependent state 723 Minimum 724 Get Value Type Get Command Value Description Sec. Attrib 725 -------------------------------- ---- --------------- ------- --------------------- ------ ------ 726 MAX_PROGRAM_SUBROUTINE_ Z+ GetProgramivARB 1024 Maximum number of 2.14.1 - 727 PARAMETERS_NV program subroutine 728 parameters 729 MAX_PROGRAM_SUBROUTINENUM_NV Z+ GetProgramivARB 256 Maximum SUBROUTINENUM 2.X.5 - 730 value 731 732 733Dependencies on EXT_separate_shader_objects 734 735 If EXT_separate_shader_objects is not supported, remove references to 736 UseShaderProgramEXT. 737 738Issues 739 740 (1) What terms should we use to describe the various data types and 741 concepts in this specification? 742 743 RESOLVED: This extension uses mechanisms similar to function pointers in 744 C. We aren't directly exposing function pointers, but are instead using a 745 function pointer-like data type. We are using the term "subroutine" to 746 qualify various concepts in this extension. The function pointer type is 747 referred to as a "subroutine type". Integer indices used to identify 748 functions that can be assigned to a function pointer type are referred to 749 as "subroutine indices". Uniforms that can hold function pointer values 750 are referred to as "subroutine uniforms". 751 752 We considered using the term "interfaces", but were concerns about 753 confusion with object-oriented programming models -- the model we are 754 using is not object-oriented. Referring instead to these limited function 755 pointers as "subroutines" avoids this confusion and matches its use in 756 similar circumstances. The term is not currently used in any GLSL nor 757 OpenGL specification. 758 759 (2) What happens if you try to link a program that has active subroutines 760 that have no subroutines that can be assigned ot them? 761 762 RESOLVED: Attempting to link a program that calls a function pointer 763 with no potential associations produces a link error. 764 765 (3) What happens if the app specifies a bad subroutine index? 766 767 RESOLVED: There are two different forms of invalid subroutine indices -- 768 ones that correspond to no subroutine, and ones that correspond to a 769 subroutine of the wrong type. If the app specifies a number that 770 corresponds to no subroutine, an INVALID_VALUE error is generated. If the 771 number corresponds to a subroutine of the wrong type, an INVALID_OPERATION 772 error is generated. 773 774 (4) What happens if the shaders change without reassigning subroutine 775 associations? 776 777 RESOLVED: The subroutine uniforms will revert to a default function of 778 of those associated with it in the shader. The default function chosen 779 may be implementation dependent. 780 781 (5) How should subroutine parameters be updated? 782 783 RESOLVED: UniformSubroutinesuivARB requires sending all subroutine 784 parameters at once so they can be validated in a single burst. This is 785 similar to D3D which goes as far as to require setting all of them in the 786 same operation that binds the shader. 787 788 (6) Why is the new "subroutine" state owned by the context rather than 789 by the assembly program or GLSL program/shader? 790 791 RESOLVED: We expect that a common usage of this extension 792 would be to create a so-called "uber-shader" -- a program that can 793 support many different state configurations. If an application uses 794 such a program in multiple contexts, it likely it would not want changes 795 to linkage for one context to affect the other context. 796 797 (7) Does that mean other types of uniforms also need to be context state? 798 799 RESOLVED: Apps can choose to share or not share numeric uniform types at 800 their discretion using UBO, however for more "opaque" uniform types like 801 samplers it may be desirable to have context state. Such a change is 802 beyond the scope of this extension. No effort was made to make subroutine 803 uniforms generic enough to support other potential usages. Should such 804 emerge, they will define their own unique uniform types. 805 806 (8) GLSL allows function name overloading, how can you query a 807 subroutine location in that case? 808 809 RESOLVED: Disallow overloading of function names used for subroutine 810 functions. 811 812 (9) What sort of implementation-dependent limits apply to subroutines? 813 814 RESOLVED: There is an limit on the number of subroutines per shader stage 815 (MAX_SUBROUTINES) and also a limit on the number of subroutine uniform 816 locations (MAX_SUBROUTINE_UNIFORM_LOCATIONS). 817 818 (10) How many subroutine variables be used? Should they be allowed as 819 function parameters, structure members, and arrays? 820 821 RESOLVED: Arrays of subroutine uniforms are allowed. The spec does not 822 currently permit them as function parameters or structure members, as it 823 requires subroutine variables be declared as uniforms. Subroutine 824 function parameters can be emulated by declaring a uniform array holding 825 all possible subroutines that a shader might want to pass as a parameter 826 and then passing an integer index to select a subroutine to call. 827 828 (11) Is the "subroutine" keyword necessary when declaring a subroutine 829 uniform? 830 831 RESOLVED: Yes, "subroutine uniform" in the declaration is required. 832 833 (12) Why don't the new tokens and entry points in this extension have 834 "ARB" suffixes like other ARB extensions? 835 836 RESOLVED: Unlike most ARB extensions, this is a strict subset of 837 functionality already approved for the OpenGL core. This extension 838 exists only to support that functionality on older hardware that cannot 839 implement all the functionality in that OpenGL version. Since there are 840 no possible behavior changes between the ARB extension and core features, 841 source code compatibility is improved by not using suffixes on the 842 extension. 843 844 (13) Are compilers permitted to eliminate unreferenced elements at the end 845 of an array for subroutine uniforms like they can for regular uniforms? 846 847 RESOLVED: No, because of differences in the uniform loading APIs. 848 Consider the following example: 849 850 uniform float array[10]; 851 // shader only references array[0..5] 852 853 The GL implementation is permitted to treat "array" as having a size of 854 6, but may also use the declared size of 10. An application may have 855 built-in knowledge that "array" has a declared length of 10, and might 856 call Uniform1f() with a <count> of 10. The specified behavior for 857 Uniform*() APIs is that any values specified that extend beyond the last 858 active element of the array are ignored. As a result, passing "extra" 859 elements to Uniform*() causes no problems; applications don't need to 860 query the active size of a uniform array to get correct behavior. 861 862 The subroutine uniform loading API is different, as it accepts a single 863 array containing the values for every active uniform. This allows 864 applications to specify the values for all subroutine uniforms in a 865 single call, instead of multiple calls for regular uniforms. However, 866 this approach doesn't provide a mechanism for discarding unused array 867 elements. If "array" above was a subroutine uniform and the application 868 wrote 10 values into the array it would pass to UniformSubroutinesuiv, 869 it might overwrite the values of other subroutines or write off the end 870 of the array if the compiler only assigned 6 locations for "array". If 871 unused elements could be eliminated, implementations would have to query 872 the active size for each subroutine uniform array, even if they knew the 873 declared size up-front. To avoid the need to always query lengths, we 874 instead specify that all elements of an active subroutine array are 875 active. 876 877Revision History 878 879 Rev. Date Author Changes 880 ---- ---------- -------- ---------------------------------------------- 881 19 02/28/2014 Jon Leech Restrict error for UniformSubroutinesuiv to 882 the case where no program stage is active for 883 the shader stage identified by <shadertype> 884 (Bug 11306). 885 886 18 02/10/2011 pbrown Add a clarification to the GLSL spec language 887 prohibiting potential recursion via subroutine 888 uniforms; a program will fail to link if there 889 is any possible combination of subroutine 890 uniform values that would result in recursion 891 (bug 7327). 892 893 17 03/29/2010 pbrown Update issues (1) and (10). 894 895 16 03/21/2010 pbrown Minor clarification in the NV_gpu_program5 896 interaction that no OPTION is required to 897 use subroutines in assembly programs. 898 899 15 02/08/2010 Jon Leech Minor wording changes for consistency with 900 4.0 specification. 901 902 14 01/30/2010 pbrown Specify that implementations are not permitted 903 to chop unreferenced elements off the end of 904 a subroutine uniform array like they are with 905 regular uniforms (bug 5978). Minor 906 clarification on the meaning of "active 907 subroutines". 908 909 13 01/26/2010 pbrown Assigned enum values for enums added by most 910 recent edits. 911 912 12 01/20/2010 pbrown Update state tables to classify per-subroutine 913 and per-subroutine uniform state as "5x" to 914 indicate a separate set of values for each 915 shader stage. 916 917 11 01/18/2010 pbrown Rename GetActiveSubroutineUniformiv. Add 918 enums to query the longest subroutine uniform 919 and subroutine names in a stage. Rename enum 920 NUM_COMPATIBLE_SUBROUTINES. Change error 921 behavior to allow most queries on unlinked 922 programs and ones without the specified stage 923 (except GetSubroutineUniformLocation). Added 924 errors in UniformSubroutines and 925 GetUniformSubroutineuiv if no program is 926 active. Minor spec language cleanups. All 927 based on review comments in bug 5861. 928 929 10 01/15/2010 pbrown Significant changes to allow for full 930 discoverability of subroutine uniforms, 931 subroutines, and their locations (bug 5861). 932 Rename the term "subroutine number" to "active 933 subroutine index". Rename GetSubroutineIndex 934 (was GetSubroutineNumber) and the <indices> 935 parameter of UniformSubroutinesuiv. Fix 936 prototype of GetSubroutineIndex and other APIs 937 to consistently use "uint". Add APIs to query 938 properties of active subroutine uniforms 939 (name, associated subroutines). Separate the 940 notion of subroutine uniform indices and 941 locations just like regular uniforms. Arrays 942 may have one index but multiple locations. 943 Specify that locations are packed in 944 consecutive locations. Rename 945 GetSubroutineName to GetActiveSubroutineName 946 to match other enumeration APIs. Add a query 947 for the number of active subroutine uniform 948 locations, and change the implementation limit 949 to be on active locations instead of indices. 950 Clarify that subroutines in a shader need not 951 be active if there is no active uniform that 952 can call them (bug 5859). Update state tables 953 and some issues. 954 955 9 01/14/2010 pbrown Add some more text to the introduction to 956 subroutines in the GLSL spec section. 957 958 8 12/10/2009 groth ARBify. 959 960 7 12/10/2009 groth Correct prototypes and clarify/correct errors. 961 Fix a few state retrieval typos. 962 963 6 10/29/2009 groth Clarify a number of areas in response to 964 feedback from bmerry. 965 966 5 09/24/2009 groth Fix typo in GLSL example. Assign enums. 967 968 4 09/17/2009 pbrown Add implementation-dependent limits on 969 subroutines. Document some of these limits 970 and restrictions on function overloading and 971 subroutine uniforms with no matching function. 972 973 3 09/16/2009 groth Resolve issues. A few clarifications. 974 rename interface to subroutine. 975 976 2 09/14/2009 groth EXTify. move asm changes to dependencies. 977 978 1 jbolz Internal revisions. 979