1Name 2 3 ARB_separate_shader_objects 4 5Name Strings 6 7 GL_ARB_separate_shader_objects 8 9Contact 10 11 Mark Kilgard, NVIDIA (mjk 'at' nvidia.com) 12 Greg Roth, NVIDIA (groth 'at' nvidia.com) 13 Pat Brown, NVIDIA (pbrown 'at' nvidia.com) 14 15Contributors 16 17 Bruce Merry, ARM 18 Daniel Koch, TransGaming 19 Eric Werness, NVIDIA 20 Graham Sellers, AMD 21 Greg Roth, NVIDIA 22 Jason Green, TransGaming 23 John Kessenich, Intel 24 Jon Leech 25 Kevin Rogovin 26 Nick Haemel, AMD 27 Robert Ohannessian 28 29Notice 30 31 Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at 32 http://www.khronos.org/registry/speccopyright.html 33 34Specification Update Policy 35 36 Khronos-approved extension specifications are updated in response to 37 issues and bugs prioritized by the Khronos OpenGL Working Group. For 38 extensions which have been promoted to a core Specification, fixes will 39 first appear in the latest version of that core Specification, and will 40 eventually be backported to the extension document. This policy is 41 described in more detail at 42 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 43 44Status 45 46 Complete. Approved by the ARB on June 9, 2010. 47 Approved by the Khronos Board of Promoters on July 23, 2010. 48 49Version 50 51 Last Modified Date: 1 August 2011 52 Version: 25 53 54Number 55 56 ARB Extension #97 57 58Dependencies 59 60 Written based on the wording of the OpenGL 4.0 Compatibility 61 Profile (March 11, 2010) specification. 62 63 Written based on the wording of The OpenGL Shading Language 4.00.8 64 (March 10, 2010) specification. 65 66 This extension requires OpenGL 2.0 or ARB_shader_objects. 67 68 This extension interacts with OpenGL 4.0 (Core Profile). 69 70 This extension interacts with GLSL 1.40 (and earlier). 71 72 This extension interacts with ARB_geometry_shader4, 73 EXT_geometry_shader4, and/or NV_geometry_shader4. 74 75 This extension depends on ARB_explicit_attrib_location. 76 77 This extension interacts with ARB_tessellation_shader or OpenGL 4.0. 78 79 This extension interacts with GL_ARB_gpu_shader_fp64 or OpenGL 4.0. 80 81 This extension interacts with ARB_explicit_attrib_location, 82 ARB_vertex_attrib_64bit, OpenGL 3.3, and OpenGL 4.1. 83 84 This extension interacts with the EXT_separate_shader_objects extension. 85 86 This extension interacts with ARB_vertex_program, ARB_fragment_program, 87 NV_gpu_program4 and related assembly extensions. 88 89Overview 90 91 Conventional GLSL requires multiple shader stages (vertex, 92 fragment, geometry, tessellation control, and tessellation 93 evaluation) to be linked into a single monolithic program object to 94 specify a GLSL shader for each stage. 95 96 While GLSL's monolithic approach has some advantages for 97 optimizing shaders as a unit that span multiple stages, all 98 existing GPU hardware supports the more flexible mix-and-match 99 approach. 100 101 Shaders written for HLSL9, Cg, the prior OpenGL assembly program 102 extensions, and game console favor a more flexible "mix-and-match" 103 approach to specifying shaders independently for these different 104 shader stages. Many developers build their shader content around 105 the mix-and-match approach where they can use a single vertex shader 106 with multiple fragment shaders (or vice versa). 107 108 This extension adopts a "mix-and-match" shader stage model for GLSL 109 allowing multiple different GLSL program objects to be bound at once 110 each to an individual rendering pipeline stage independently of 111 other stage bindings. This allows program objects to contain only 112 the shader stages that best suit the applications needs. 113 114 This extension introduces the program pipeline object that serves as 115 a container for the program bound to any particular rendering stage. 116 It can be bound, unbound, and rebound to simply save and restore the 117 complete shader stage to program object bindings. Like framebuffer 118 and vertex array objects, program pipeline objects are "container" 119 objects that are not shared between contexts. 120 121 To bind a program object to a specific shader stage or set of 122 stages, UseProgramStages is used. The VERTEX_SHADER_BIT, 123 GEOMETRY_SHADER_BIT, FRAGMENT_SHADER_BIT, TESS_CONTROL_SHADER_BIT, 124 and TESS_EVALUATION_SHADER_BIT tokens refer to the conventional 125 vertex, geometry, fragment, tessellation control and tessellation 126 evaluation stages respectively. ActiveShaderProgram specifies the 127 program that Uniform* commands will update. 128 129 While ActiveShaderProgram allows the use of conventional Uniform* 130 commands to update uniform variable values for separable program 131 objects, this extension provides a preferrable interface in a set 132 of ProgramUniform* commands that update the same uniform variables 133 but take a parameter indicating the program object to be updated, 134 rather than updating the currently active program object. These 135 commands mirror those introduced in EXT_direct_state_access. 136 137 While glActiveShaderProgram provides a selector for setting and 138 querying uniform values of a program object, the glProgramUniform* 139 commands provide a selector-free way to modify uniforms of a GLSL 140 program object without an explicit bind. This selector-free model 141 reduces API overhead and provides a cleaner interface for 142 applications. 143 144 Separate linking creates the possibility that certain output varyings 145 of a shader may go unread by the subsequent shader inputting varyings. 146 In this case, the output varyings are simply ignored. It is also 147 possible input varyings from a shader may not be written as output 148 varyings of a preceding shader. In this case, the unwritten input 149 varying values are undefined. 150 151 This extension builds on the proof-of-concept provided by 152 EXT_separate_shader_objects which demonstrated that separate 153 shader objects can work for GLSL. EXT_separate_shader_objects 154 was a response to repeated requests for this functionality from 155 3D developers. 156 157 This ARB version addresses several "loose ends" in the prior 158 EXT extension. In particular, it allows user-defined varyings 159 with explicitly defined locations or implicitly assigned locations. 160 161 This ARB extension extends the GLSL language's use of layout 162 qualifiers to provide cross-stage interfacing. 163 164IP Status 165 166 No known IP claims. 167 168New Procedures and Functions 169 170 void UseProgramStages(uint pipeline, bitfield stages, 171 uint program); 172 173 void ActiveShaderProgram(uint pipeline, uint program); 174 175 uint CreateShaderProgramv(enum type, sizei count, 176 const char **strings); 177 178 void BindProgramPipeline(uint pipeline); 179 180 void DeleteProgramPipelines(sizei n, const uint *pipelines); 181 182 void GenProgramPipelines(sizei n, uint *pipelines); 183 184 boolean IsProgramPipeline(uint pipeline); 185 186 void ProgramParameteri(uint program, enum pname, int value); 187 188 void GetProgramPipelineiv(uint pipeline, enum pname, int *params); 189 190 void ProgramUniform1i(uint program, int location, 191 int x); 192 void ProgramUniform2i(uint program, int location, 193 int x, int y); 194 void ProgramUniform3i(uint program, int location, 195 int x, int y, int z); 196 void ProgramUniform4i(uint program, int location, 197 int x, int y, int z, int w); 198 199 void ProgramUniform1ui(uint program, int location, 200 uint x); 201 void ProgramUniform2ui(uint program, int location, 202 uint x, uint y); 203 void ProgramUniform3ui(uint program, int location, 204 uint x, uint y, uint z); 205 void ProgramUniform4ui(uint program, int location, 206 uint x, uint y, uint z, uint w); 207 208 void ProgramUniform1f(uint program, int location, 209 float x); 210 void ProgramUniform2f(uint program, int location, 211 float x, float y); 212 void ProgramUniform3f(uint program, int location, 213 float x, float y, float z); 214 void ProgramUniform4f(uint program, int location, 215 float x, float y, float z, float w); 216 217 void ProgramUniform1d(uint program, int location, 218 double x); 219 void ProgramUniform2d(uint program, int location, 220 double x, double y); 221 void ProgramUniform3d(uint program, int location, 222 double x, double y, double z); 223 void ProgramUniform4d(uint program, int location, 224 double x, double y, double z, double w); 225 226 void ProgramUniform1iv(uint program, int location, 227 sizei count, const int *value); 228 void ProgramUniform2iv(uint program, int location, 229 sizei count, const int *value); 230 void ProgramUniform3iv(uint program, int location, 231 sizei count, const int *value); 232 void ProgramUniform4iv(uint program, int location, 233 sizei count, const int *value); 234 235 void ProgramUniform1uiv(uint program, int location, 236 sizei count, const uint *value); 237 void ProgramUniform2uiv(uint program, int location, 238 sizei count, const uint *value); 239 void ProgramUniform3uiv(uint program, int location, 240 sizei count, const uint *value); 241 void ProgramUniform4uiv(uint program, int location, 242 sizei count, const uint *value); 243 244 void ProgramUniform1fv(uint program, int location, 245 sizei count, const float *value); 246 void ProgramUniform2fv(uint program, int location, 247 sizei count, const float *value); 248 void ProgramUniform3fv(uint program, int location, 249 sizei count, const float *value); 250 void ProgramUniform4fv(uint program, int location, 251 sizei count, const float *value); 252 253 void ProgramUniform1dv(uint program, int location, 254 sizei count, const double *value); 255 void ProgramUniform2dv(uint program, int location, 256 sizei count, const double *value); 257 void ProgramUniform3dv(uint program, int location, 258 sizei count, const double *value); 259 void ProgramUniform4dv(uint program, int location, 260 sizei count, const double *value); 261 262 void ProgramUniformMatrix2fv(uint program, int location, 263 sizei count, boolean transpose, 264 const float *value); 265 void ProgramUniformMatrix3fv(uint program, int location, 266 sizei count, boolean transpose, 267 const float *value); 268 void ProgramUniformMatrix4fv(uint program, int location, 269 sizei count, boolean transpose, 270 const float *value); 271 272 void ProgramUniformMatrix2dv(uint program, int location, 273 sizei count, boolean transpose, 274 const double *value); 275 void ProgramUniformMatrix3dv(uint program, int location, 276 sizei count, boolean transpose, 277 const double *value); 278 void ProgramUniformMatrix4dv(uint program, int location, 279 sizei count, boolean transpose, 280 const double *value); 281 282 void ProgramUniformMatrix2x3fv(uint program, int location, 283 sizei count, boolean transpose, 284 const float *value); 285 void ProgramUniformMatrix3x2fv(uint program, int location, 286 sizei count, boolean transpose, 287 const float *value); 288 void ProgramUniformMatrix2x4fv(uint program, int location, 289 sizei count, boolean transpose, 290 const float *value); 291 void ProgramUniformMatrix4x2fv(uint program, int location, 292 sizei count, boolean transpose, 293 const float *value); 294 void ProgramUniformMatrix3x4fv(uint program, int location, 295 sizei count, boolean transpose, 296 const float *value); 297 void ProgramUniformMatrix4x3fv(uint program, int location, 298 sizei count, boolean transpose, 299 const float *value); 300 301 void ProgramUniformMatrix2x3dv(uint program, int location, 302 sizei count, boolean transpose, 303 const double *value); 304 void ProgramUniformMatrix3x2dv(uint program, int location, 305 sizei count, boolean transpose, 306 const double *value); 307 void ProgramUniformMatrix2x4dv(uint program, int location, 308 sizei count, boolean transpose, 309 const double *value); 310 void ProgramUniformMatrix4x2dv(uint program, int location, 311 sizei count, boolean transpose, 312 const double *value); 313 void ProgramUniformMatrix3x4dv(uint program, int location, 314 sizei count, boolean transpose, 315 const double *value); 316 void ProgramUniformMatrix4x3dv(uint program, int location, 317 sizei count, boolean transpose, 318 const double *value); 319 320 void ValidateProgramPipeline(uint pipeline ); 321 322 void GetProgramPipelineInfoLog(uint pipeline, sizei bufSize, 323 sizei *length, char *infoLog); 324 325New Tokens 326 327 Accepted by <stages> parameter to UseProgramStages: 328 329 VERTEX_SHADER_BIT 0x00000001 330 FRAGMENT_SHADER_BIT 0x00000002 331 GEOMETRY_SHADER_BIT 0x00000004 332 TESS_CONTROL_SHADER_BIT 0x00000008 333 TESS_EVALUATION_SHADER_BIT 0x00000010 334 ALL_SHADER_BITS 0xFFFFFFFF 335 336 Accepted by the <pname> parameter of ProgramParameteri and 337 GetProgramiv: 338 339 PROGRAM_SEPARABLE 0x8258 340 341 Accepted by <type> parameter to GetProgramPipelineiv: 342 343 ACTIVE_PROGRAM 0x8259 344 345 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 346 GetInteger64v, GetFloatv, and GetDoublev: 347 348 PROGRAM_PIPELINE_BINDING 0x825A 349 350Additions to Chapter 2 of the OpenGL 4.0 Compatibility Profile 351Specification (OpenGL Operation): 352 353 -- Section 2.14 "Vertex Shaders" (page 89) 354 355 Modify the third paragraphs: 356 357 To use a vertex shader, shader source code is first loaded into a 358 shader object and then compiled. A shader object corresponds to a 359 stage in the rendering pipeline referred to as its shader stage or 360 type. One or more vertex shader objects are attached to a program 361 object. The program object is then linked, which generates 362 executable code from all the compiled shader objects attached to the 363 program. When program objects are bound to a shader stage, they 364 become the current program object for that stage. When the current 365 program object for the vertex stage includes a vertex shader, it is 366 considered the active program object for the vertex stage. The 367 current program object for all stages may be set at once using a 368 single unified program object, or the current program object may be 369 set for each stage individually using a separable program object 370 where different separable program objects may be current for other 371 stages. The set of separable program objects current for all stages 372 are collected in a program pipeline object that must be bound for 373 use. When a linked program object is made active for the vertex 374 stage, the executable code for the vertex shaders it contains is 375 used to process vertices." 376 377 Modify the last sentence in the fourth paragraph: 378 379 "... A single program object can contain all of vertex, tessellation 380 control, tessellation evaluation, geometry, and fragment shaders, or 381 any subset thereof." 382 383 Modify the fifth paragraph: 384 385 "When the program object currently in use for the vertex stage 386 includes a vertex shader, its vertex shader is considered active and 387 is used to process vertices. If the current vertex stage program 388 object has no vertex shader or no program object is current for the 389 vertex stage, ..." 390 391 -- Section 2.14.2 "Program Objects" (page 91) 392 393 In the list of linking failures following the description of 394 LinkProgram, modify the bullets reading "the program contains no objects 395 to form a vertex shader" when using a tessellation control, tessellation 396 evaluation, or geometry shader (pp. 92-93) to read: 397 398 - the program is not separable and contains no objects to form a 399 vertex shader; 400 401 Modify the eighth paragraph: 402 403 If a program has been successfully linked by LinkProgram, it can be made 404 part of the current rendering state for all shader stages with the command 405 406 void UseProgram(uint program); 407 408 If <program> is non-zero, this command will make <program> the current 409 program object. This will install executable code as part of the current 410 rendering state for each shader stage present when the program was last 411 successfully linked. If UseProgram is called with <program> set to zero, 412 then there is no current program object. If <program> has not been 413 successfully linked, the error INVALID_OPERATION is generated and the 414 current rendering state is not modified. 415 416 Insert before the last paragraph, p. 93: 417 418 The executable code for an individual shader stage is taken from the 419 current program for that stage. If there is a current program object 420 established by UseProgram, that program is considered current for all 421 stages. Otherwise, if there is a bound program pipeline object (section 422 2.14.PPO), the program bound to the appropriate stage of the pipeline 423 object is considered current. If there is no current program object or 424 bound program pipeline object, no program is current for any stage. The 425 current program for a stage is considered active if it contains executable 426 code for that stage; otherwise, no program is considered active for that 427 stage. If there is no active program for the vertex or fragment shader 428 stages, 429 [[ Compatibility Profile ]] 430 fixed-function vertex and/or fragment processing will be used to process 431 vertices and/or fragments. 432 [[ Core Profile ]] 433 the results of vertex and/or fragment processing will be undefined. 434 However, this is not an error. 435 [[ End Profile-Specific Language ]] 436 If there is no active program for the tessellation control, tessellation 437 evaluation, or geometry shader stages, those stages are ignored. 438 439 Insert at the end of the section, p. 94 (note: this will be inserted 440 below several of the edits that follow). 441 442 "The command 443 444 uint CreateShaderProgramv(enum type, sizei count, 445 const char **strings); 446 447 creates a stand-alone program from an array of null-terminated 448 source code strings for a single shader type. CreateShaderProgramv 449 is equivalent to the following command sequence: 450 451 const uint shader = CreateShader(type); 452 if (shader) { 453 ShaderSource(shader, count, strings, NULL); 454 CompileShader(shader); 455 const uint program = CreateProgram(); 456 if (program) { 457 int compiled = FALSE; 458 GetShaderiv(shader, COMPILE_STATUS, &compiled); 459 ProgramParameteri(program, PROGRAM_SEPARABLE, TRUE); 460 if (compiled) { 461 AttachShader(program, shader); 462 LinkProgram(program); 463 DetachShader(program, shader); 464 } 465 append-shader-info-log-to-program-info-log 466 } 467 DeleteShader(shader); 468 return program; 469 } else { 470 return 0; 471 } 472 473 The program may not actually link if the output variables in the 474 shader attached to the final stage of the linked program take up 475 too many locations. If this situation arises, the info log may 476 explain this. 477 478 Because no shader is returned by CreateShaderProgramv and the 479 shader that is created is deleted in the course of the command 480 sequence, the info log of the shader object is copied to the program 481 so the shader's failed info log for the failed compilation is 482 accessible to the application." 483 484 Modify first and second paragraphs, p. 94: 485 486 If a program object that is active for any shader stage is re-linked 487 successfully, the LinkProgram command will install the generated 488 executable code as part of the current rendering state for all shader 489 stages where the program is active. Additionally, the newly generated 490 executable code is made part of the state of any program pipeline for all 491 stages where the program is attached. 492 493 If a program object that is active for any shader stage is re-linked 494 unsuccessfully, the link status will be set to FALSE, but existing 495 executables and associated state will remain part of the current rendering 496 state until a subsequent call to UseProgram, UseProgramStages, or 497 BindProgramPipeline removes them from use. If such a program is attached 498 to any program pipeline object, the existing executables and associated 499 state will remain part of the program pipeline object until a subsequent 500 call to UseProgramStages removes them from use. An unsuccessfully linked 501 program may not be made part of the current rendering state by UseProgram 502 or added to program pipeline objects by UseProgramStages until it is 503 successfully re-linked. If such a program was attached to a program 504 pipeline at the time of a failed link, its existing executable may still 505 be made part of the current rendering state indirectly by 506 BindProgramPipeline. 507 508 Modify the last paragraph of the section, p. 94: 509 510 "If <program> is not current for any GL context, is not the active 511 program for any program pipeline object, and is not the current 512 program for any stage of any program pipeline object, it is deleted 513 immediately. Otherwise, program is flagged ..." 514 515 Insert prior to the description of DeleteProgram, p. 94 (note: this text 516 is inserted above the previous edit): 517 518 "Program parameters control aspects of how the program is linked, 519 executed, or stored. To set a program parameter, call 520 521 void ProgramParameteri(uint program, enum pname, int value) 522 523 <pname> identifies which parameter to set for program object 524 <program>. <value> holds the value being set. 525 If <pname> is PROGRAM_SEPARABLE, <value> must be TRUE or FALSE 526 and indicates whether the <program> can be bound for individual 527 pipeline stages via UseProgramStages after it is next linked. 528 If <pname> is any other value, the error INVALID_ENUM is 529 generated. 530 531 -- New section 2.14.PPO "Program Pipeline Objects" after 2.14.2 532 "Program Objects" 533 534 Instead of packaging all shader stages into a single program object, 535 shader types might be contained in multiple program objects each 536 consisting of part of the complete pipeline. A program object may 537 even contain only a single shader stage. This facilitates greater 538 flexibility when combining different shaders in various ways without 539 requiring a program object for each combination. 540 541 Program bindings associating program objects with shader types are 542 collected to form a program pipeline object. 543 544 The command 545 546 void GenProgramPipelines(sizei n, uint *pipelines); 547 548 returns <n> previously unused program pipeline object names in 549 <pipelines>. These names are marked as used, for the purposes of 550 GenProgramPipelines only, but they acquire state only when they are 551 first bound. 552 553 Program pipeline objects are deleted by calling 554 555 void DeleteProgramPipelines(sizei n, const uint *pipelines); 556 557 <pipelines> contains <n> names of program pipeline objects to be 558 deleted. Once a program pipeline object is deleted, it has no 559 contents and its name becomes unused. If an object that is currently 560 bound is deleted, the binding for that object reverts to zero and no 561 program pipeline object becomes current. Unused names in <pipelines> 562 are silently ignored, as is the value zero. 563 564 A program pipeline object is created by binding a name returned by 565 GenProgramPipelines with the command 566 567 void BindProgramPipeline(uint pipeline); 568 569 <pipeline> is the program pipeline object name. The resulting program 570 pipeline object is a new state vector, comprising ACTIVE_PROGRAM, 571 VERTEX_SHADER, GEOMETRY_SHADER, FRAGMENT_SHADER, TESS_CONTROL_SHADER, 572 and TESS_EVALUATION_SHADER. 573 574 BindProgramPipeline may also be used to bind an existing program 575 pipeline object. If the bind is successful, no change is made to 576 the state of the bound program pipeline object, and any previous 577 binding is broken. If BindProgramPipeline is called with <pipeline> 578 set to zero, then there is no current program pipeline object. 579 580 If no current program object has been established by UseProgram, the 581 program objects used for each shader stage and for uniform updates are 582 taken from the bound program pipeline object, if any. If there is a 583 current program object established by UseProgram, the bound program 584 pipeline object has no effect on rendering or uniform updates. When a 585 bound program pipeline object is used for rendering, individual shader 586 executables are taken from its program objects as described in the 587 discussion of UseProgram in section 2.14.2. 588 589 BindProgramPipeline fails and an INVALID_OPERATION error is 590 generated if <pipeline> is not zero or a name returned from a 591 previous call to GenProgramPipelines, or if such a name has since 592 been deleted with DeleteProgramPipelines. 593 594 The executables in a program object associated with one or more 595 shader stages can be made part of the program pipeline state for 596 those shader stages with the command: 597 598 void UseProgramStages(uint pipeline, bitfield stages, 599 uint program); 600 601 where <pipeline> is the program pipeline object to be updated, 602 <stages> is the bitwise OR of accepted constants representing 603 shader stages, and <program> is the program object from which the 604 executables are taken. The bits set in <stages> indicate the program 605 stages for which the program object named by <program> becomes 606 current. These stages may include tessellation control, tessellation 607 evaluation, vertex, geometry, or fragment indicated by TESS_CONTROL_- 608 SHADER_BIT, TESS_EVALUATION_SHADER_BIT, VERTEX_SHADER_BIT, GEOMETRY_- 609 SHADER_BIT, or FRAGMENT_SHADER_BIT respectively. The constant ALL_- 610 SHADER_BITS indicates <program> is to be made current for all 611 shader stages. If <program> refers to a program object with a valid 612 shader attached for an indicated shader stage, this call installs 613 the executable code for that stage in the indicated program pipeline 614 object state. If UseProgramStages is called with <program> set to 615 zero or with a program object that contains no executable code for a 616 given stages, it is as if the pipeline object has no programmable stage 617 configured for the indicated shader stages. If <stages> is not the 618 special value ALL_SHADER_BITS and has a bit set that is not recognized, 619 the error INVALID_VALUE is generated. If the program object named 620 by <program> was linked without the PROGRAM_SEPARABLE parameter set 621 or was not linked successfully, the error INVALID_OPERATION is 622 generated and the corresponding shader stages in the <pipeline> 623 program pipeline object are not modified. 624 625 If <pipeline> is a name that has been generated (without subsequent 626 deletion) by GenProgramPipelines, but refers to a program pipeline 627 object that has not been previously bound, the GL first creates a 628 new state vector in the same manner as when BindProgramPipeline 629 creates a new program pipeline object. If <pipeline> is not a name 630 returned from a previous call to GenProgramPipelines or if such a 631 name has since been deleted by DeleteProgramPipelines, an INVALID_- 632 OPERATION error is generated. 633 634 The command 635 636 void ActiveShaderProgram(uint pipeline, uint program); 637 638 sets the linked program named by <program> to be the active program 639 (discussed later in the secion 2.14.4) for the program pipeline 640 object <pipeline> . If <program> has not been successfully linked, 641 the error INVALID_OPERATION is generated and active program is not 642 modified. 643 644 If <pipeline> is a name that has been generated (without subsequent 645 deletion) by GenProgramPipelines, but refers to a program pipeline 646 object that has not been previously bound, the GL first creates a 647 new state vector in the same manner as when BindProgramPipeline 648 creates a new program pipeline object. If <pipeline> is not a name 649 returned from a previous call to GenProgramPipelines or if such a 650 name has since been deleted by DeleteProgramPipelines, an INVALID_- 651 OPERATION error is generated. 652 653 654 Shader Interface Matching 655 656 When multiple shader stages are active, the outputs of one stage form an 657 interface with the inputs of the next stage. At each such interface, 658 shader inputs are matched up against outputs from the previous stage: 659 660 * An output block is considered to match an input block in the 661 subsequent shader if the two blocks have the same block name, and the 662 members of the block match exactly in name, type, qualification, and 663 declaration order. 664 665 * An output variable is considered to match an input variable in the 666 subequent shader if: 667 668 * the two variables match in name, type, and qualification; or 669 670 * the two variables are declared with the same location layout 671 qualifier and match in type and qualification. 672 673 Variables or block members declared as structures are considered to match 674 in type if and only if structure members match in name, type, 675 qualification, and declaration order. Variables or block members declared 676 as arrays are considered to match in type only if both declarations 677 specify the same element type and array size. The rules for determining 678 if variables or block members match in qualification are found in the 679 OpenGL Shading Language Specification. 680 681 Tessellation control shader per-vertex output variables and blocks and 682 tessellation control, tessellation evaluation, and geometry shader 683 per-vertex input variables and blocks are required to be declared as 684 arrays, with each element representing input or output values for a single 685 vertex of a multi-vertex primitive. For the purposes of interface 686 matching, such variables and blocks are treated as though they were not 687 declared as arrays. 688 689 For program objects containing multiple shaders, LinkProgram will check 690 for mismatches on interfaces between shader stages in the program being 691 linked and generate a link error if a mismatch is detected. A link error 692 will be generated if any statically referenced input variable or block 693 does not have a matching output. If either shader redeclares the built-in 694 array gl_ClipDistance[] ((compatibility profile only: or gl_TexCoord[])), 695 the array must have the same size in both shaders. ((compatibility 696 profile only: If either shader redeclares built-in input or output color 697 variables, they must have matching interpolation qualifiers, as described 698 in the OpenGL Shading Language Specification.)) 699 700 With separable program objects, interfaces between shader stages may 701 involve the outputs from one program object and the inputs from a 702 second program object. For such interfaces, it is not possible to 703 detect mismatches at link time, because the programs are linked 704 separately. When each such program is linked, all inputs or outputs 705 interfacing with another program stage are treated as active. The 706 linker will generate an executable that assumes the presence of a 707 compatible program on the other side of the interface. If a mismatch 708 between programs occurs, no GL error will be generated, but some or all 709 of the inputs on the interface will be undefined. 710 711 At an interface between program objects, the set of inputs and outputs are 712 considered to match exactly if and only if: 713 714 * The built-in input and output blocks used on the interface 715 ("gl_PerVertex" or "gl_PerFragment") match, as described below. 716 717 * Every declared input block or variable must have a matching output, as 718 described above. 719 720 * There are no output blocks or user-defined output variables 721 declared without a matching input block or variable declaration. 722 723 When the set of inputs and outputs on an interface between programs 724 matches exactly, all inputs are well-defined unless the corresponding 725 outputs were not written in the previous shader. However, any mismatch 726 between inputs and outputs results in all inputs being undefined except 727 for cases noted below. Even if an input has a corresponding output 728 that matches exactly, mismatches on other inputs or outputs may 729 adversely affect the executable code generated to read or write the 730 matching variable. 731 732 The inputs and outputs on an interface between programs need not match 733 exactly when input and output location qualifiers (sections 4.3.8.1 and 734 4.3.8.2 of the GLSL Specification) are used. When using location 735 qualifiers, any input with an input location qualifier will be 736 well-defined as long as the other program writes to a matching output, as 737 described above. The names of variables need not match when matching by 738 location. 739 740 Additionally, scalar and vector inputs with location layout qualifiers 741 will be well-defined if there is a corresponding output satisfying all of 742 the following conditions: 743 744 * the input and output match exactly in qualification, including in the 745 location layout qualifier; 746 747 * the output is a vector with the same basic component type and has more 748 components than the input; and 749 750 * the common component type of the input and output is "int", "uint", or 751 "float" (scalars and vectors with "double" component type are 752 excluded). 753 754 In this case, the components of the input will be taken from the first 755 components of the matching output, and the extra components of the output 756 will be ignored. 757 758 To use any built-in input or output in the gl_PerVertex and 759 gl_PerFragment blocks in separable program objects, shader code must 760 redeclare those blocks prior to use. A separable program will 761 fail to link if: 762 763 * it contains multiple shaders of a single type with different 764 redeclarations of these built-in input and output blocks; or 765 766 * any shader uses a built-in block member not found in the 767 redeclaration of that block. 768 769 [[ There are two somewhat different versions of the following language -- 770 one for the compatibility profile and the other for the core 771 profile. ]] 772 773 [[ Compatibility Profile ]] 774 775 As described above, an exact interface match requires matching built-in 776 input and output blocks. At an interface between two non-fragment 777 shader stages, the gl_PerVertex input and output blocks are considered 778 to match if and only if the block members members match exactly in 779 name, type, qualification, and declaration order. At an interface 780 involving the fragment shader stage, a gl_PerVertex output block is 781 considered to match a gl_PerFragment input block if all of the 782 following conditions apply: 783 784 * the gl_PerVertex block includes either gl_FrontColor or 785 gl_BackColor if and only if the gl_PerFragment block includes 786 gl_Color; 787 788 * the gl_PerVertex block includes either gl_FrontSecondaryColor or 789 gl_BackSecondaryColor if and only if the gl_PerFragment block 790 includes gl_SecondaryColor; 791 792 * the gl_PerVertex block includes gl_FogFragCoord if and only if the 793 gl_PerFragment block also includes gl_FogFragCoord; and 794 795 * the size of gl_TexCoord[] in gl_PerVertex and gl_PerFragment is 796 identical. 797 798 At an interface between gl_PerVertex outputs and gl_PerFragment inputs, 799 the presence or absence of any block members other than those listed 800 immediately above does not affect interface matching. 801 802 [[ Core Profile ]] 803 804 As described above, an exact interface match requires matching built-in 805 input and output blocks. At an interface between two non-fragment 806 shader stages, the gl_PerVertex input and output blocks are considered 807 to match if and only if the block members members match exactly in 808 name, type, qualification, and declaration order. At an interface 809 involving the fragment shader stage, the presence or absence of any 810 built-in output does not affect interface matching. 811 812 [[ End Profile-Specific Language ]] 813 814 Built-in inputs or outputs not found in blocks do not affect interface 815 matching. Any such built-in inputs are well-defined unless they are 816 derived from built-in outputs not written by the previous shader stage. 817 818 819 Program Pipeline Object State 820 821 "The state required to support program pipeline objects consists of 822 a single binding name of the current program pipeline object. This 823 binding is initially zero indicating no program pipeline object is 824 bound. 825 826 The state of each program pipeline object consists of: 827 828 * Six unsigned integers (initially all zero) are required to hold 829 each respective name of the current vertex stage program, current 830 geometry stage program, current fragment stage program, current 831 tessellation control stage program, current tessellation evaluation 832 stage program, and active program respectively. 833 * A Boolean holding the status of the last validation attempt, 834 initially false 835 * An array of type char containing the information log, initially 836 empty. 837 * An integer holding the length of the information log" 838 839 -- Section 2.14.4 "Uniform Variables" (page 97) 840 841 Replace the 1st paragraph of the "Loading Uniform Variables In The 842 Default Uniform Block" section (page 108): 843 844 "To load values into the uniform variables of the active program 845 object, use the commands ... 846 847 ... If a non-zero program object is bound by UseProgram, it is the 848 active program object whose uniforms are updated by these commands. 849 If no program object is bound using UseProgram, the active program 850 object of the current program pipeline object set by ActiveShader- 851 Program is the active program object. If the current program pipeline 852 object has no active program or there is not current program pipeline 853 object, then there is no active program. 854 The given values are loaded into the default ... " 855 856 Change the last bullet in the "Loading Uniform Variables In The 857 Default Uniform Block" section (page 110) to: 858 859 "* if there is no active program in use." 860 861 Add to the end of the subsection "Loading Uniform Variables In The 862 Default Uniform Block" section (page 110): 863 864 To load values into the uniform variables of the default uniform 865 block of a program which may not necessarily be bound, use the 866 commands 867 868 void ProgramUniform{1234}{ifd}(uint program, int location, 869 T value); 870 void ProgramUniform{1234}{ifd}v(uint program, int location, 871 sizei count, const T value); 872 void ProgramUniform{1234}ui(uint program, int location, 873 T value); 874 void ProgramUniform{1234}uiv(uint program, int location, 875 sizei count, T value); 876 void ProgramUniformMatrix{234}{fd}v 877 (uint program, int location, 878 sizei count, boolean transpose, 879 const float *value); 880 void ProgramUniformMatrix{2x3 3x2 2x4 4x2 3x4 4x3}{fd}v 881 (uint program, int location, 882 sizei count, boolean transpose, 883 const float *value); 884 885 These commands operate identically to the corresponding commands 886 above without "Program" in the command name except, rather than 887 updating the currently active program object, these "Program" 888 commands update the program object named by the initial <program> 889 parameter.The remaining parameters following the initial <program> 890 parameter match the parameters for the corresponding non-"Program" 891 uniform command. If <program> is not the name of a created program 892 or shader object, the error INVALID_VALUE is generated. If <program> 893 identifies a shader object or a program object that has not been 894 linked successfully, the error INVALID_OPERATION is generated. 895 896 -- Section 2.14.4 "Subroutine Uniform Variables" (page 114) 897 898 Modify the last paragraph of the section, p. 117 899 900 When the active program for a shader stage is re-linked or changed by a 901 call to UseProgram, BindProgramPipeline, or UseProgramStages, subroutine 902 uniforms for that stage are reset to arbitrarily chosen default functions 903 with compatible subroutine types. 904 905 906 -- Section 2.14.8 "Shader Execution" (page 122) 907 908 Change the first paragraph: 909 910 "If there is an active program object present for the vertex, 911 tessellation control, tessellation evaluation, or geometry shader 912 stages, the executable code for these active programs is used 913 to process incoming vertex values rather than the fixed-function 914 vertex processing described in sections 2.12 through 2.13. In 915 particular, ..." 916 917 Modify first paragraph of "Validation", p. 129 918 919 (replace first paragraph) It is not always possible to determine at link 920 time if a program object can execute successfully, given that LinkProgram 921 can not know the state of the remainder of the pipeline. Therefore 922 validation is done when the first rendering command is issued, to 923 determine if the set of active program objects can be executed. If the 924 current set of active program objects cannot be executed, no primitives 925 are processed and the error INVALID_OPERATION will be generated. 926 927 Add to the list in the second paragraph of subsection "Validation" 928 (Page 129): 929 930 "* A program object is active for at least one, but not all of the 931 shader stages that were present when the program was linked. 932 933 * One program object is active for at least two shader stages and 934 a second program is active for a shader stage between two stages 935 for which the first program was active. 936 937 * There is an active program for tessellation control, tessellation 938 evaluation, or geometry stages with corresponding executable 939 shader, but there is no active program with executable vertex 940 shader. 941 942 * There is not current unified program object and the current program 943 pipeline object includes a program object that was relinked since 944 being applied to the pipeline object via UseProgramStages with the 945 PROGRAM_SEPARABLE parameter set to FALSE." 946 947 Add after the description of ValidateProgram in subsection 948 "Validation": 949 950 "Separable program objects may have validation failures that cannot 951 be detected without the complete program pipeline. Mismatched 952 interfaces, improper usage of program objects together, and the same 953 state-dependent failures can result in validation errors for such 954 program objects. As a development aid, use the command 955 956 void ValidateProgramPipeline(uint pipeline ); 957 958 to validate the program pipeline object <pipeline> against the 959 current GL state. Each program pipeline object has a boolean status, 960 VALIDATE_STATUS, that is modified as a result of validation. This 961 status can be queried with GetProgramPipelineiv (See section 6.1.18). 962 If validation succeeded, the program pipeline object is guaranteed 963 to execute given the current GL state. 964 965 If <pipeline> is a name that has been generated (without subsequent 966 deletion) by GenProgramPipelines, but refers to a program pipeline 967 object that has not been previously bound, the GL first creates a 968 new state vector in the same manner as when BindProgramPipeline 969 creates a new program pipeline object. If <pipeline> is not a name 970 returned from a previous call to GenProgramPipelines or if such a 971 name has since been deleted by DeleteProgramPipelines, an INVALID_- 972 OPERATION error is generated. 973 974 -- Section 2.15 "Tessellation" (page 131) 975 976 (modify second paragraph, p. 132) ... Tessellation is considered active if 977 and only if there is an active tessellation control or tessellation 978 evaluation program object. 979 980 (modify next-to-last paragraph, p. 132) Patch primitives are not supported 981 by pipeline stages below the tessellation evaluation shader. If there is 982 no active tessellation evaluation program, the error INVALID_OPERATION is 983 generated by Begin, and any command that performs an implicit Begin, if 984 the primitive mode is PATCHES. 985 986 Modify last paragraph, p. 132: 987 988 "A program object or program pipeline object that includes a 989 tessellation shader of any kind must also include a vertex shader. 990 If the current program state has a tessellation shader but no 991 vertex shader at Begin or any command that implicitly calls Begin, an 992 INVALID_OPERATION error will be generated." 993 994 -- Section 2.15.1 "Tessellation Control Shaders" (page 133) 995 996 Change the first paragraph of "Tessellation Control Shader Execution 997 Environment" (p. 134) 998 999 "If there is an active program for the tessellation control stage, the 1000 executable version of the program's tessellation control shader is used 1001 ..." 1002 1003 -- Section 2.15.3 "Tessellation Evaluation Shaders" (page 147) 1004 1005 Change the first paragraph of "Tessellation Evaluation Shader 1006 Execution Environment" (p. 149) 1007 1008 "If there is an active program for the tessellation evaluation stage, the 1009 executable version of the program's tessellation evaluation shader is 1010 used ..." 1011 1012 -- Section 2.16, "Geometry Shaders" (page 153) 1013 1014 Change the 4th paragraph: 1015 1016 "A program object or program pipeline object that includes a 1017 geometry shader must also include a vertex shader. If the current 1018 program state has a geometry shader but no vertex shader at Begin or 1019 any command that implicitly calls Begin, an INVALID_OPERATION error 1020 will be generated." 1021 1022 -- Section 2.16.1, Geometry Shader Input Primitives, p. 153 1023 1024 (modify first paragraph of the section) ... will generate an 1025 INVALID_OPERATION error if the primitive <mode> parameter is incompatible 1026 with the input primitive type of the geometry shader of the active 1027 geometry program object, as discussed below. 1028 1029 -- Section 2.16.4, Geometry Shader Execution Environment 1030 1031 Change the first paragraph: 1032 1033 "If there is an active program for the geometry stage, the executable 1034 version of the program's geometry shader is used ..." 1035 1036 -- Section 2.20 "Transform Feedback" (page 167) 1037 1038 Modify first paragraph and add the subsequent paragraphs: 1039 1040 "In transform feedback mode, attributes of the vertices of 1041 primitives passed to the transform feedback stage are written out to 1042 one or more buffer objects. The vertices are fed back after vertex 1043 color clamping, but before flatshading and clipping. The transformed 1044 vertices may be optionally discarded after being stored into one or 1045 more buffer objects, or they can be passed on down to the clipping 1046 stage for further processing. The set of attributes captured is 1047 determined when a program is linked. 1048 1049 The data captured in transform feedback mode depends on the active 1050 programs on each of the shader stages. If a program is active for 1051 the geometry shader stage, transform feedback captures the vertices 1052 of each primitive emitted by the geometry shader. Otherwise, if a 1053 program is active for the tessellation evaluation shader stage, 1054 transform feedback captures each primitive produced by the 1055 tessellation primitive generator, whose vertices are processed by the 1056 tessellation evaluation shader. Otherwise, transform feedback 1057 captures each primitive processed by the vertex shader. 1058 1059 If separable program objects are in use, the set of attributes 1060 captured is taken from the program object active on the last shader 1061 stage processing the primitives captured by transform feedback. The 1062 set of attributes to capture in transform feedback mode for any 1063 other program active on a previous shader stage is ignored." 1064 1065 Add to list of INVALID_OPERATION errors on page 172 1066 1067 * by UseProgramStages if the program pipeline object it refers to is 1068 current and the current transform feedback object is active and not 1069 paused. 1070 1071 * by BindProgramPipeline if the current transform feedback object is 1072 active and not paused. 1073 1074 * by ResumeTransformFeedback if the program pipeline object being 1075 used by the current transform feedback object is not bound, any of 1076 its shader stage bindings has changed, or a single program object 1077 is active and overriding it. 1078 1079Additions to Chapter 3 of the OpenGL 4.0 Compatibility Profile 1080Specification (Rasterization) 1081 1082 -- Section 3.12 "Fragment Shaders" (page 321) 1083 1084 Replace the second to the last paragraph with: 1085 1086 "When the current fragment shader program object currently includes 1087 a fragment shader, its fragment shader is considered active, and is 1088 used to process fragments. If the fragment shader program object 1089 has no fragment shader, or no fragment shader program object is 1090 currently in use, the fixed-function fragment processing operations 1091 described in the previous sections are used." 1092 1093Additions to Chapter 4 of the OpenGL 4.0 Compatibility Profile 1094Specification (Per-Fragment Operations and the Frame Buffer) 1095 1096 None 1097 1098Additions to Chapter 5 of the OpenGL 4.0 Compatibility Profile 1099Specification (Special Functions) 1100 1101 -- Section 5.5 "Display Lists" (page 410) 1102 1103 Add CreateShaderProgram, GenProgramPipelines, DeleteProgram- 1104 Pipelines, and BindProgramPipelines to the "Program and shader 1105 objects" list of commands that cannot be compiled into a display 1106 list but are instead executed immediately. 1107 1108Additions to Chapter 6 of the OpenGL 4.0 Compatibility Profile Specific- 1109ation (State and State Requests) 1110 1111 -- Section 6.1.18 "Shader and Program Queries" 1112 1113 Add to GetProgramiv description: 1114 1115 "If <pname> is PROGRAM_SEPARABLE, TRUE is returned if the program has 1116 been flagged for use as a separable program object that can be bound 1117 to individual shader stages with UseProgramStages." 1118 1119 Add after GetProgramiv description: 1120 1121 "The command 1122 1123 boolean IsProgramPipeline(uint pipeline); 1124 1125 returns TRUE if <pipeline> is the name of a program pipeline object. 1126 If <pipeline> is zero, or a non-zero value that is not the name of a 1127 program pipeline object, IsProgramPipeline returns FALSE. No error 1128 is generated if <pipeline> is not a valid program pipeline object 1129 name. 1130 1131 The command 1132 1133 GetProgramPipelineiv(uint pipeline, enum pname, int *params); 1134 1135 returns properties of the program pipeline object named <pipeline> 1136 in <params>. The parameter value to return is specified by <pname>. 1137 1138 If <pipeline> is a name that has been generated (without subsequent 1139 deletion) by GenProgramPipelines, but refers to a program pipeline 1140 object that has not been previously bound, the GL first creates a 1141 new state vector in the same manner as when BindProgramPipeline 1142 creates a new program pipeline object. If <pipeline> is not a name 1143 returned from a previous call to GenProgramPipelines or if such a 1144 name has since been deleted by DeleteProgramPipelines, an INVALID_- 1145 OPERATION error is generated. 1146 1147 If <pname> is ACTIVE_PROGRAM, the name of the active program 1148 object of the program pipeline object is returned. 1149 If <pname> is VERTEX_SHADER, the name of the current program 1150 object for the vertex shader type of the program pipeline object is 1151 returned. 1152 If <pname> is FRAGMENT_SHADER, the name of the current program 1153 object for the fragment shader type of the program pipeline object 1154 is returned. 1155 If <pname> is GEOMETRY_SHADER, the name of the current program 1156 object for the geometry shader type of the program pipeline object 1157 is returned; 1158 If <pname> is TESS_CONTROL_SHADER, the name of the current 1159 program object for the tessellation control shader type of the 1160 program pipeline object is returned; 1161 If <pname> is TESS_EVALUATION_SHADER, the name of the current 1162 program object for the tessellation evaluations shader type of the 1163 program pipeline object is returned. 1164 If <pname> is VALIDATE_STATUS, the validation status of the 1165 program pipeline object, as determined by ValidateProgramPipeline 1166 (see section 2.14.8) is returned. 1167 If <pname> is INFO_LOG_LENGTH, the length of the info log, 1168 including a null terminator, is returned. If there is no info log, 1169 zero is returned." 1170 If <pname> is not the name of an accepted parameter, an INVALID_- 1171 ENUM error is generated. 1172 1173 Change paragraph describing GetShaderInfoLog and GetProgram: 1174 1175 "A string that contains information about the last compilation 1176 attempt on a shader object, last link or validation attempt on a 1177 program object, or last validation attempt on a program pipeline 1178 object, called the info log, can be obtained with the commands 1179 1180 void GetShaderInfoLog (uint shader, sizei bufSize, 1181 sizei *length, char *infoLog); 1182 void GetProgramInfoLog (uint program, sizei bufSize, 1183 sizei *length, char *infoLog); 1184 void GetProgramPipelineInfoLog (uint pipeline, sizei bufSize, 1185 sizei *length, char *infoLog); 1186 1187 These commands return the info log string in <infoLog>. This string 1188 will be null-terminated. The actual number of characters written 1189 into <infoLog>, excluding the null terminator, is returned in 1190 <length>. If <length> is NULL, then no length is returned. The 1191 maximum number of characters that may be written into <infoLog>, 1192 including the null terminator, is specified by <bufSize>. The number 1193 of characters in the info log can be queried with GetShaderiv, 1194 GetProgramiv, or GetProgramPipelineiv with INFO_LOG_LENGTH. If 1195 <shader> is a shader object, the returned info log will either be an 1196 empty string or it will contain information about the last compil- 1197 ation attempt for that object. If <program> is a program object, the 1198 returned info log will either be an empty string or it will contain 1199 information about the last link attempt or last validation attempt 1200 for that object. If <pipeline> is a program pipeline object, the 1201 returned info log will either be an empty string or it will contain 1202 information about the last validation attempt for that object. 1203 1204 1205Additions to Appendix D of the OpenGL 4.0 Compatibility Profile Specific- 1206ation (Shared Objects and Multiple Contexts) 1207 1208 (modify third paragraph, p. 533, making program pipeline objects 1209 non-shared) Framebuffer, query, vertex array, and program pipeline 1210 objects are not shared. 1211 1212 1213Additions to the AGL/GLX/WGL Specifications 1214 1215 None 1216 1217Additions to the OpenGL Shading Language Specification, Version 4.00.8 1218 1219 Including the following line in a shader can be used to control 1220 the language feature described in thie extension: 1221 1222 #extension GL_ARB_separate_shader_objects : <behavior> 1223 1224 where <behavior> is as described in section 3.3. 1225 1226 A new preprocessor #define is added to the OpenGL Shading Language: 1227 1228 #define GL_ARB_separate_shader_objects 1 1229 1230 -- Section 4.3 "Storage Qualifiers" (page 32): 1231 1232 Add to the end of the section: 1233 1234 When comparing an output from one shader stage to an input of a second 1235 shader stage, the input and output are considered to match only if 1236 compatible storage qualifiers are used. An output declared with "out", 1237 "centroid out", "sample out", or "patch out" matches an input only if the 1238 input is declared with "in", "centroid in", "sample in", or "patch in", 1239 respectively. Additionally, an output will only match an input with 1240 identical interpolation qualifiers. 1241 1242 [[ Note: If the GLSL specification is updated to break out "centroid", 1243 "sample", and "patch" as separate auxillary qualifiers instead of 1244 tightly coupling with "in" and "out" as in GLSL 4.00, this language 1245 should be rewritten to require that these auxillary qualifiers match 1246 (and that "in" match "out", of course). ]] 1247 1248 -- Section 4.3.4 "Inputs" (page 36): 1249 1250 Add to the end of the section: 1251 1252 When an interface between shader stages is formed using shaders from two 1253 separate program objects, it is not possible to detect mismatches between 1254 inputs and outputs when the programs are linked. When there are 1255 mismatches between inputs and outputs on such interfaces, the values 1256 passed across the interface will be partially or completely undefined. 1257 Shaders can ensure matches across such interfaces either by using input 1258 and output layout qualifiers (Sections 4.3.8.1 and 4.3.8.2) or by using 1259 identical input and output declarations. Complete rules for interface 1260 matching are found in the "Shader Interface Matching" portion of section 1261 2.14.PPO of the OpenGL Specification. 1262 1263 -- Section 4.3.8.1 "Input Layout Qualifiers" (page 44): 1264 1265 All shaders allow location input layout qualifiers on input variable 1266 declarations. The location layout qualifier identifier for inputs is: 1267 1268 layout-qualifier-id 1269 location = integer-constant 1270 1271 Only one argument is accepted. For example, 1272 1273 layout(location = 3) in vec4 normal; 1274 1275 establishes that the shader input <normal> is assigned to location number 1276 3. For vertex shader inputs, the location specifies the number of the 1277 generic vertex attribute from which input values are taken. For inputs of 1278 all other shader types, the location specifies a vector number that can be 1279 used to match against outputs from a previous shader stage, even if that 1280 shader is in a different program object. 1281 1282 If the declared input has a scalar or vector type, it will consume a 1283 single location, except for non-vertex inputs of type "dvec3" and "dvec4", 1284 which will consume two consecutive locations. Inputs of type "double" and 1285 "dvec2" will consume only a single location in all shaders. 1286 1287 If the declared input is an array of size <n> and each element takes up 1288 <m> locations, it will be assigned <m>*<n> consecutive locations starting 1289 with the location specified. For example, 1290 1291 layout(location = 6) in vec4 colors[3]; 1292 1293 will establish that the input <colors> is assigned to vector 1294 location numbers 6, 7, and 8. 1295 1296 If the declared input is an <n>x<m> single- or double-precision matrix, it 1297 will be assigned multiple locations starting with the location specified. 1298 The number of locations assigned for each matrix will be the same as for 1299 an <n>-element array of <m>-component vectors. For example, 1300 1301 layout(location = 9) in mat4 transforms[2]; 1302 1303 will establish that input <transforms> is assigned to vector location 1304 numbers 9-16, with transforms[0] being assigned to locations 9-12 and 1305 transforms[1] being assigned to locations 13-16. 1306 1307 If the declared input is a structure, its members will be assigned 1308 consecutive locations in the order of declaration, with the first member 1309 assigned the location specified for the structure. The number of 1310 locations consumed by a structure member is determined by applying the 1311 rules above recursively as though the structure member were declared as 1312 an input variable of the same type. For example, 1313 1314 layout(location = 3) struct S { 1315 vec3 a; 1316 mat2 b; 1317 vec4 c[2]; 1318 } s; 1319 1320 will assign location 3 to "s.a", locations 4 and 5 to the two column 1321 vectors of "s.b", and locations 6 and 7 to "s.c". 1322 1323 Location layout qualifiers may be used on input variables declared as 1324 structures, but not on individual members. Location layout qualifiers may 1325 not be used on input blocks or input block members. 1326 1327 The number of input locations available to a shader is limited. For 1328 vertex shaders, the limit is the advertised number of vertex attributes. 1329 For all other shaders, the limit is implementation-dependent and must be 1330 no less than one fourth of the advertised maximum input component count. 1331 A program will fail to link if any attached shader uses a location greater 1332 than or equal to the number of supported locations, unless 1333 device-dependent optimizations are able to make the program fit within 1334 available hardware resources. 1335 1336 A program will fail to link if any two non-vertex shader input variables 1337 are assigned to the same location. For vertex shaders, multiple input 1338 variables may be assigned to the same location using either layout 1339 qualifiers or via the OpenGL API. However, such aliasing is intended only 1340 to support vertex shaders where each execution path accesses at most one 1341 input at each location. Implementations are permitted, but not required, 1342 to generate link errors if they detect that every path through the vertex 1343 shader executable accesses multiple inputs assigned to any single 1344 location. For all shader types, a program will fail to link if explicit 1345 location assignments leave the linker unable to find space for other 1346 variables without explicit assignments. 1347 1348 For the purposes of determining if a non-vertex input matches an output 1349 from a previous shader stage, the location layout qualifier (if any) must 1350 match. 1351 1352 -- Section 4.3.8.2 "Output Layout Qualifiers" (page 48) 1353 1354 Modify the description of fragment output qualifiers. 1355 1356 All shaders allow location output layout qualifiers on output 1357 variable declarations. The location layout qualifier identifier for 1358 outputs is: 1359 1360 layout-qualifier-id 1361 location = integer-constant 1362 1363 Fragment shaders allow an additional index output layout qualifiers: 1364 1365 layout-qualifier-id 1366 location = integer-constant 1367 index = integer-constant 1368 1369 Each of these qualifiers may appear at most once. If index is 1370 specified, location must also be specified. If index is not 1371 specified, the value 0 is used. For example, in a fragment shader, 1372 1373 layout(location = 3) out vec4 color; 1374 1375 will establish that the fragment shader output <color> is assigned 1376 to fragment color 3 as the first (index zero) input to the blend 1377 equation. And, 1378 1379 layout(location = 3, index = 1) out vec4 factor; 1380 1381 will establish that the fragment shader output factor is assigned 1382 to fragment color 3 as the second (index one) input to the blend 1383 equation. 1384 1385 For fragment shader outputs, the location and index specify the color 1386 output number and index receiving the values of the output. For outputs 1387 of all other shader types, the location specifies a vector number that can 1388 be used to match against inputs in a subsequent shader stage, even if that 1389 shader is in a different program object. 1390 1391 If the declared output has a scalar or vector type, it will consume a 1392 single location, except for outputs of type "dvec3" and "dvec4", which 1393 will consume two consecutive locations. Outputs of type "double" and 1394 "dvec2" will consume only a single location in all shaders. 1395 1396 If the declared output is an array, it will be assigned consecutive 1397 locations starting with the location specified. For example, 1398 1399 layout(location = 2) out vec4 colors[3]; 1400 1401 will establish that <colors> is assigned to vector location 1402 numbers 2, 3, and 4. 1403 1404 If the declared output is an <n>x<m> single- or double-precision matrix, 1405 it will be assigned multiple locations starting with the location 1406 specified. The number of locations assigned will be the same as for an 1407 <n>-element array of <m>-component vectors. 1408 1409 If the declared output is a structure, its members will be assigned 1410 consecutive locations in the order of declaration, with the first member 1411 assigned the location specified for the structure. The number of 1412 locations consumed by a structure member is determined by applying the 1413 rules above recursively as though the structure member were declared as 1414 an output variable of the same type. 1415 1416 Location layout qualifiers may be used on output variables declared as 1417 structures, but not on individual members. Location layout qualifiers may 1418 not be used on output blocks or output block members. 1419 1420 The number of output locations available to a shader is limited. For 1421 fragment shaders, the limit is the advertised number of draw buffers. For 1422 all other shaders, the limit is implementation-dependent and must be no 1423 less than one fourth of the advertised maximum output component count. A 1424 program will fail to link if any attached shader uses a location greater 1425 than or equal to the number of supported locations, unless 1426 device-dependent optimizations are able to make the program fit within 1427 available hardware resources. 1428 1429 A program will fail to link if any two fragment shader output variables 1430 are assigned to the same location and index, or if any two output 1431 variables from the same non-fragment shader stage are assigned to the same 1432 location. For fragment shader outputs, locations can be assigned using 1433 either a layout qualifier or via the OpenGL API. For all shader types, a 1434 program will fail to link if explicit location assignments leave the 1435 linker unable to find space for other variables without explicit 1436 assignments. 1437 1438 For the purposes of determining if a non-fragment output matches an input 1439 from a subsequent shader stage, the location layout qualifier (if any) 1440 must match. 1441 1442 -- Section 4.5.2, "Precision Qualifiers" (page 53) 1443 1444 (add new paragraph to the end of the section) For the purposes of 1445 determining if an output from one shader stage matches an input of the 1446 next stage, the precision qualifier need not match. 1447 1448 -- Section 4.6.1, "The Invariant Qualifier" (page 55) 1449 1450 (add new paragraph to the end of the section) For the purposes of 1451 determining if an output from one shader stage matches an input of the 1452 next stage, the "invariant" qualifier need not match. 1453 1454 -- Section 4.7, "The Precise Qualifier" (page 56) 1455 1456 (add new paragraph to the end of the section) For the purposes of 1457 determining if an output from one shader stage matches an input of the 1458 next stage, the "precise" qualifier need not match. 1459 1460 1461GLX Protocol 1462 1463 The following rendering command is sent to the server as part of a 1464 glXRender request: 1465 1466 UseProgramStages 1467 2 8 rendering command length 1468 2 ZZZZ rendering command opcode 1469 4 ENUM type 1470 4 CARD32 program 1471 1472 ActiveShaderProgram 1473 2 4 rendering command length 1474 2 ZZZZ rendering command opcode 1475 4 CARD32 program 1476 1477Errors 1478 1479 UseProgramStages generates INVALID_OPERATION if the program 1480 parameter has not been successfully linked. 1481 1482 UseProgramStages generates INVALID_OPERATION if transform feedback 1483 is active. 1484 1485 UseProgramStages generates INVALID_VALUE if <stages> has a bit 1486 set for any other than TESS_CONTROL_SHADER_BIT, TESS_EVALUATION_- 1487 SHADER_BIT, VERTEX_SHADER_BIT, GEOMETRY_SHADER_BIT, or FRAGMENT_- 1488 SHADER_BIT, unless <stages> is ALL_SHADER_BITS. 1489 1490 ActiveShaderProgram generates INVALID_OPERATION if the program 1491 parameter has not been successfully linked. 1492 1493 The INVALID_OPERATION error produced by LinkProgram if the program 1494 object has a geometry, tessellation control, or tessellation 1495 evalutations shader attached and no vertex shader attached is now 1496 produced at Begin time. 1497 1498 The error INVALID_OPERATION is generated if Begin, or any command 1499 that implicitly calls Begin, is called when a program object with 1500 multiple attached shaders is active for one or more, but not all of 1501 the shader program types corresponding to the shaders that are 1502 attached. 1503 1504 The error INVALID_OPERATION is generated if Begin, or any command 1505 that implicitly calls Begin, is called when an active program object 1506 has two shaders attached that have shader program types in between 1507 them with active programs that are not zero and are not equal to the 1508 active program of the first two shaders. 1509 1510 INVALID_OPERATION is generated if any of the commands added by this 1511 extension are executed between the execution of Begin and the 1512 corresponding execution of End. 1513 1514Dependencies on OpenGL 4.0 (Core Profile) 1515 1516 If the OpenGL 4.0 core profile is used, references to built-in shader 1517 variables found only in the compatibility profile should be removed. 1518 Additionally, the fragment shader built-in input block "gl_PerFragment" 1519 doesn't exist, and references to it should be removed. When matching 1520 shader outputs to fragment inputs, the members of "gl_PerVertex" output 1521 block do not affect matching. References to fixed-function vertex and 1522 fragment processing should also be removed. 1523 1524Dependencies on GLSL 1.40 and earlier 1525 1526 This extension typically requires that shaders redeclare "gl_PerVertex" 1527 or "gl_PerFragment" to use members of built-in input or output blocks in 1528 separable shaders. However, since input and output interface blocks 1529 are not supported in GLSL 1.40 or earlier, such redeclarations are not 1530 even possible using older versions of GLSL. 1531 1532 To deal with this case, this extension provides a specific exception to 1533 this rule, allowing vertex and fragment shaders using #version 140 or 1534 lower to redeclare all variables that would otherwise belong to these 1535 blocks at global scope. When linking separable programs using such 1536 shaders, the set of redeclared inputs/outputs are taken to form an 1537 implicit redeclaration of "gl_PerVertex" or "gl_PerFragment". After this, 1538 normal matching rules for the gl_PerVertex and gl_PerFragment blocks are 1539 applied. When using this capability: 1540 1541 * all built-in vertex outputs or fragment inputs must be redeclared; 1542 1543 * all shaders of a given type must make the same redeclarations; and 1544 1545 * to get an exact interface match, the vertex output and fragment input 1546 redeclarations must be compatible according to block matching rules. 1547 1548 This exception is important because we expect this extension to be 1549 supported on implementations and GPUs supporting only OpenGL 2.1, which 1550 doesn't support the interface blocks added by GLSL 1.50. 1551 1552 Note that this exception applies only to shaders using #version 140. When 1553 using this extension with shaders using #version 150 or higher, the 1554 shaders must redeclare gl_PerVertex or gl_PerFragment blocks. 1555 1556 The following edits to the GLSL 1.40 (revision 7) specification are made 1557 when this extension is enabled by an #extension directive: 1558 1559 Add new Section 7.7, Built-In Redeclaration and Separable Programs 1560 1561 The following vertex shader outputs may be redeclared at global scope to 1562 specify a built-in output interface, with or without special qualifiers: 1563 1564 gl_Position 1565 gl_PointSize 1566 gl_ClipDistance[] 1567 gl_ClipVertex (compatibility only) 1568 gl_FrontColor (compatibility only) 1569 gl_BackColor (compatibility only) 1570 gl_FrontSecondaryColor (compatibility only) 1571 gl_BackSecondaryColor (compatibility only) 1572 gl_TexCoord[] (compatibility only) 1573 gl_FogFragCoord (compatibility only) 1574 1575 The following fragment shader inputs may be redeclared at global scope 1576 to specify a built-in input interface, with or without special 1577 qualifiers: 1578 1579 gl_Color (compatibility only) 1580 gl_SecondaryColor (compatibility only) 1581 gl_TexCoord[] (compatibility only) 1582 gl_FogFragCoord (compatibility only) 1583 1584 When compiling shaders using any of the above variables, all such 1585 variables must be redeclared prior to use. ((Note: This restriction 1586 applies only to shaders using version 140 or earlier that enable the 1587 ARB_separate_shader objects extension; shaders not enabling the 1588 extension do not have this requirement.)) A separable program object 1589 will fail to link if any attached shader uses one of the above variables 1590 without redeclaration, or if it has two shaders of the same type using 1591 any of these variables where the sets of variable declarations don't 1592 match exactly. 1593 1594 Additionally, the API specification language in this specification 1595 (written assuming input and output blocks in GLSL) is modified as follows: 1596 1597 (Add to the end of the "Shader Interface Matching" section) 1598 1599 When using vertex or fragment shaders with version 140 or lower in 1600 separable programs, the language doesn't support input and output blocks 1601 or redeclaration of gl_PerVertex or gl_PerFragment. In such cases, an 1602 implicit block redeclaration is formed from the set of vertex shader 1603 outputs or fragment shader inputs redeclared according to Section 7.7 of 1604 the OpenGL Shading Language Specification. The order of individual 1605 variable redeclarations does not affect the resulting implicit block 1606 redeclaration. The block matching rules described above are then 1607 applied to such implicit block redeclarations. Note that an implicit 1608 block redeclaration is never considered to match with an explicit block 1609 redeclaration. 1610 1611 1612Dependencies on ARB_geometry_shader4, EXT_geometry_shader4, NV_geometry_- 1613shader4, and/or OpenGL version 3.2 1614 1615 If none of ARB_geometry_shader4, EXT_geometry_shader4, NV_geometry_- 1616 shader4, or OpenGL 3.2 are supported by the implementation, ignore 1617 all references to geometry shaders and generate an INVALID_ENUM 1618 error when UseProgramStages is called with GEOMETRY_SHADER_BIT 1619 set in <stages>. 1620 1621Dependencies on ARB_tessellation_shader and OpenGL 4.0 1622 1623 If ARB_tessellation_shader and OpenGL 4.0 are not supported by the 1624 implementation, ignore references to tessellation control and evaluation 1625 shaders and generate an INVALID_ENUM error when UseProgramStages is called 1626 with TESS_CONTROL_SHADER_BIT or TESS_EVALUTAION_SHADER_BIT is set in 1627 <stages>. 1628 1629Dependencies on ARB_gpu_shader_fp64 and OpenGL 4.0 1630 1631 If ARB_gpu_shader_fp64 and OpenGL 4.0 are not supported by the 1632 implementation, ignore references to double sized uniforms including 1633 ProgramUniform* calls with a 'd' suffix. Additionally, references to 1634 double-precision GLSL variable types should be removed. 1635 1636Dependencies on ARB_explicit_attrib_location, ARB_vertex_attrib_64bit, OpenGL 16373.3, and OpenGL 4.1 1638 1639 If ARB_explicit_attrib_location (or OpenGL 3.3) is supported, vertex 1640 shader input variables (including ones with double-precision components) 1641 can select associated generic attributes with an explicit location layout 1642 qualifier in lieu of calling BindAttribLocation. If 1643 ARB_vertex_attrib_64bit (or OpenGL 4.1) is supported, vertex shader inputs 1644 can use types with double-precision components. 1645 1646 When these extensions are supported, there are special rules for the 1647 number of locations consumed by "dvec3" and "dvec4" types, which require 1648 more storage than is available in a four-component single-precision 1649 vector. The rules are: 1650 1651 * dvec3/dvec4 vertex inputs consume one location (generic vertex 1652 attribute), but can count as two vectors for the purposes of 1653 determining if the vertex shader consumes too many inputs 1654 1655 * dvec3/dvec4 inputs and outputs for other stages consume two locations 1656 1657 The relevant spec edits (modifying language introduced by 1658 ARB_explicit_attrib_location) can be found in this extension. 1659 1660Dependencies on EXT_separate_shader_objects 1661 1662 This extension provides program pipeline objects, to which separable 1663 program objects can be attached via UseProgramStages (for rendering) and 1664 ActiveShaderProgram (for uniform updates). A single pipeline object can 1665 be bound via BindProgramPipeline. The programs attached to the bound 1666 pipeline object are used unless a non-separable object is made current via 1667 UseProgram. Effectively UseProgram has a higher priority than 1668 BindProgramPipeline. 1669 1670 EXT_separate_shader_objects does something very similar, but without 1671 pipeline objects. Instead, the single program attachment point set by 1672 UseProgram is replaced by an array of attachment points updated by 1673 UseShaderProgramEXT and ActiveProgramEXT. UseProgram is redefined 1674 to update all attachment points. This collection of attachment points is 1675 functionally equivalent to the program pipeline object in this extension, 1676 and can be thought of as a special pipeline object. 1677 1678 If both extensions are supported, the rule giving priority to UseProgram 1679 over pipeline objects needs to be updated, given that the single 1680 UseProgram binding point is replaced by a collection of binding points. 1681 We effectively treat this collection of binding points as another pipeline 1682 object, and treat that object as higher priority if it has a program 1683 attached to *any* attachment point. The priority rules in this spec are 1684 rewritten as follows: 1685 1686 The executable code for an individual shader stage is taken from the 1687 current program for that stage. If there is a current program object 1688 for any shader stage or for uniform updates established by UseProgram, 1689 UseShaderProgramEXT, or ActiveProgramEXT, the current program for that 1690 stage (if any) is considered current. Otherwise, if there is a bound 1691 program pipeline object ... 1692 1693 Note that with these rules, it's not possible to mix program objects bound 1694 to the context with program objects bound to a program pipeline object; if 1695 any program is bound to the context, the current pipeline object is 1696 ignored. 1697 1698Dependencies on ARB_vertex_program, ARB_fragment_program, NV_gpu_program4, and 1699related assembly extensions 1700 1701 On implementations supporting both GLSL and assembly programmability, it 1702 is necessary to make a determination of what executable code (if any) is 1703 run in each program stage. The logic for determining the active 1704 executable is as follows: 1705 1706 * If there is an active GLSL program for the stage, either from a 1707 program bound by UseProgram or from a program bound to the active 1708 program pipeline object, that program's executable will be used. 1709 1710 * Otherwise, the bound assembly program from this stage will be used if 1711 enabled. 1712 1713 * Otherwise, the stage will be skipped (tessellation control, 1714 evaluation, and geometry), fixed function vertex or fragment 1715 processing will be used (compatibility profile), or undefined results 1716 will occur (core profile). 1717 1718 This is the same behavior present without this extension; the only 1719 difference is that active GLSL programs are determined on a stage-by-stage 1720 basis with this extension. 1721 1722New State 1723 1724 Add to Table 6.45 (Program Object State): 1725 1726 Get Value Type Get Command Initial Value Description Sec Attribute 1727 ------------------- ---- -------------------- ------------- ------------------------ ------ --------- 1728 ACTIVE_PROGRAM Z+ GetProgramPipelineiv 0 The program object 2.20.2 - 1729 that Uniform* commands 1730 update when PPO bound 1731 VERTEX_SHADER Z+ GetProgramPipelineiv 0 Name of current vertex 2.20.2 - 1732 shader program object 1733 GEOMETRY_SHADER Z+ GetProgramPipelineiv 0 Name of current geometry 2.20.2 - 1734 shader program object 1735 FRAGMENT_SHADER Z+ GetProgramPipelineiv 0 Name of current fragment 2.20.2 - 1736 shader program object 1737 TESS_CONTROL_SHADER Z+ GetProgramPipelineiv 0 Name of current tessell- 2.20.2 - 1738 ation control shader 1739 program object 1740 TESS_EVALUATION_SHADER Z+ GetProgramPipelineiv 0 Name of current tessell- 2.20.2 - 1741 ation evaluation shader 1742 program object 1743 VALIDATE_STATUS B GetProgramPipelineiv FALSE Validate status of 2.14.8 - 1744 program pipeline object 1745 PROGRAM_PIPELINE_- Z+ GetIntegerv 0 Current program pipeline 2.14.PPO - 1746 BINDING object binding 1747 1748New Implementation Dependent State 1749 1750 None 1751 1752Issues 1753 1754 1. What should this extension be called? 1755 1756 RESOLVED: ARB_separate_shader_objects 1757 1758 The adjective "separate" is used in several extension names 1759 (EXT_blend_equation_separate, EXT_blend_func_separate, 1760 EXT_separate_specular_color, ATI_separate_stencil) when joined 1761 state is made configurable separately. 1762 1763 The phrase "shader_objects" refers generally to GLSL shader 1764 objects, matching the ARB_shader_objects name. 1765 1766 Whether the name should be "separate_shader_objects" 1767 or "shader_objects_separate" is less clear. The various 1768 "separate" extensions have different conventions as to whether 1769 separate is prefixed or suffixed with the separated state. 1770 The prefixed form is more natural to say aloud, is consistent 1771 with the ATI_separate_stencil naming approach, and abbreviates 1772 to SSO (instead of the inopportune abbreviation SOS). 1773 1774 The ability to use monolithic program objects that might be more 1775 optimized with individual shader program objects makes this name 1776 a little less appropriate. 1777 1778 1a. How is the extension different from the prior EXT version? 1779 1780 RESOLVED: The ARB extension is a strict superset adding: 1781 1782 * tessellation interactions, and 1783 1784 * GLSL language additions for layout qualifiers to support 1785 rendezous-by-API-resource and rendezous-by-structure-offset 1786 cross-stage interfacing. 1787 1788 * A container program pipeline object to bind separate 1789 programs to rather than to the context directly. 1790 1791 * Support for transform feedback interactions. 1792 1793 * CreateShaderProgramv takes multiple strings to better 1794 match ShaderSource 1795 1796 * More. . . 1797 1798 2. What happens to a user-defined input varying variable that are 1799 not written by a preceding shader's write to the corresponding 1800 output varying variable. 1801 1802 RESOLVED: The input variable variable's value is left undefined. 1803 Implementations are encouraged but not required to zero the 1804 value. 1805 1806 GLSL has a "rendezvous by name" model for connecting varying 1807 output variables to varying input variables of a subsequent 1808 shader. With separate shaders, there's no assurance whether a 1809 preceding shader will write a given user-defined input varying 1810 variable. HLSL9, Cg, and OpenGL assembly extension programs 1811 handle this situation by with "rendezvous by API resource" model. 1812 In GLSL terms, this means separate GLSL shaders /must/ communicate 1813 by built-in varying variables rather than user-defined varying 1814 variables. 1815 1816 It is undesirable from a performance standpoint to attempt to 1817 support "rendezvous by name" for arbitrary separate shaders 1818 because the separate shaders won't be naturally compiled to 1819 match their varying inputs and outputs of the same name without 1820 a special link step. Such a special link would introduce an 1821 extra validation overhead to binding separate shaders. The link 1822 itself would have to be deferred until glBegin time since separate 1823 shaders won't match when transitioning from one set of consistent 1824 shaders to another. This special link would still create errors 1825 or undefined behavior when the names of input and output varyings 1826 matched but their types did not match. 1827 1828 Also the expectation from other shading APIs that support 1829 mix-and-match shader usage is that "rendezvous by API resource" 1830 is the expected norm. 1831 1832 Specifying the behavior being undefined allows a future ARB 1833 version of this extension to be more specific without encumbering 1834 this extension with enforcing a specific error. 1835 1836 3. Do different program objects currently used by different shader 1837 types share a single name space for uniforms? 1838 1839 RESOLVED: No, different program objects have their own separate 1840 name space for uniforms and each has locations specific to its 1841 unique program object. 1842 1843 4. How do the glUniform* commands determine what program object 1844 to query? 1845 1846 RESOLVED: In a program pipeline object, this extension provides 1847 separate program binding points for each stage, as well as an "active" 1848 program specified by glActiveShaderProgram. When glUniform is called 1849 when a program pipeline object is active, the active program specifies 1850 the program used by glUniform* commands. This active program is 1851 simply a selector and doesn't actually control any rendering 1852 operation. 1853 1854 The active program can be queried with glGetProgramPipelineiv with a 1855 <pname> of GL_ACTIVE_PROGRAM. 1856 1857 When a non-zero program is passed to UseProgram, any subsequent 1858 uniform updates will affect that program, ignoring the active program 1859 in any bound pipeline object. For example: 1860 1861 glUseProgram(0); 1862 glBindProgramPipeline(1); 1863 glActiveProgram(1, 2); 1864 glUniform1f(0, 3.0); // affects program 2 1865 glUseProgram(3); 1866 glUniform1f(0, 3.0); // affects program 3 1867 glUseProgram(0); 1868 glUniform1f(0, 3.0); // affects program 2 1869 1870 1871 As an alternative to setting the GL_ACTIVE_PROGRAM selector 1872 with glActiveShaderProgram, applications are instead encouraged 1873 to use the glProgramUniform* commands introduced by the 1874 EXT_direct_state_access extension which do not depend on a 1875 selector but specify the program object with which to update 1876 the specified uniform location explicitly. 1877 1878 5. Do the glGetUniform* queries depend on the active program state 1879 (GL_ACTIVE_PROGRAM)? 1880 1881 RESOLVED: No, the glGetUniform* queries take the program 1882 object for the query as an explicit parameter to the query. 1883 These queries do not rely on a selector. In other words, the 1884 uniform queries are always selector-free. 1885 1886 6a. Should the fragment shader program object be allowed to changed 1887 within transform feedback mode? 1888 1889 RESOLVED: No, this should generate a GL_INVALID_OPERATION error. 1890 1891 The OpenGL 3.0 and EXT_transform_feedback specifications say 1892 glUseProgram generates a GL_INVALID_OPERATION error when transform 1893 feedback is active. 1894 1895 The rationale for this is that user-defined varying outputs from 1896 the vertex or geometry shader might change. 1897 1898 Perhaps it is desirable to allow different shader program objects 1899 when transform feedback mode is active, but this extension 1900 doesn't change the existing GLSL error behavior. In fact, 1901 glUseProgramStages generate the same error glUseProgram does. 1902 1903 6b. Should the active program be allowed to changed within transform 1904 feedback mode? 1905 1906 RESOLVED: Yes. 1907 1908 The active program simply allows uniforms to be changed but 1909 doesn't actually change how the graphics pipeline itself is 1910 configured or what programs are used for vertex, geometry, 1911 and fragment processing. 1912 1913 7. What happens if you have a program object current for a shader stage, 1914 but the program object doesn't contain an executable for that stage? 1915 1916 RESOLVED: This is not an error; instead it is as though there were no 1917 program bound to that stage. We have two different notions for 1918 programs bound to shader stages. A program is "current" for a stage 1919 if it bound to that stage in the active program pipeline object. A 1920 program is "active" for a stage if it is current and it has an 1921 executable for this stage. In this case, the program would be current 1922 but not active. 1923 1924 When no program is active for a stage, the stage will be replaced with 1925 fixed functionality logic (compatibility profile vertex and fragment), 1926 disabled (tessellation control and evaluation, geometry), or have 1927 undefined results (core profile vertex and fragment). 1928 1929 Support for programs that are current but not active is intentional 1930 behavior. Consider an example where an application wants to use two 1931 different types of separate program object -- one for all types of 1932 vertex processing and a second for fragment processing. Some of the 1933 vertex pipe programs might include tessellation or geometry shaders; 1934 others might only include a vertex shader. With this configuration, 1935 the application can use code like the following: 1936 1937 #define GL_ALL_VERTEX_PIPE_SHADER_BITS \ 1938 (GL_VERTEX_SHADER_BIT | \ 1939 GL_TESS_CONTROL_SHADER_BIT | \ 1940 GL_TESS_EVALUATION_SHADER_BIT | \ 1941 GL_GEOMETRY_SHADER_BIT) 1942 1943 glUseProgramStages(pipeline, GL_ALL_VERTEX_PIPE_SHADER_BITS, 1944 vertex_pipe_program); 1945 glUseProgramStages(pipeline, GL_FRAGMENT_SHADER_BIT, 1946 fragment_pipe_program); 1947 1948 Such code wouldn't have to determine if <vertex_pipe_program> has 1949 tessellation or geometry shaders. Instead, it simply sets all 1950 possible bits, which removes the old program from all non-fragment 1951 stages. For stages not present in the new program, the program will 1952 be current but not active, and it will be as though no program were 1953 bound to such stages. 1954 1955 8a. What happens if a linked program object with multiple stages (e.g., 1956 vertex and fragment) is active on those stages, but there is a second 1957 program active in stages between the first and last stages of that 1958 program (e.g., a geometry-only program)? 1959 1960 RESOLVED: Such a configuration will result in a draw-time validation 1961 error. We allow the linker to perform internal optimizations on the 1962 interfaces between stages of a multi-stage program object. For a 1963 vertex-fragment program, the vertex shader outputs can be optimized to 1964 pass along only those outputs needed as fragment shader inputs. Such 1965 a shader would not necessarily be set up to successfully pass those 1966 outputs to a separate geometry-only program, even if the declared 1967 vertex outputs would naturally match up with the declared geometry 1968 inputs. 1969 1970 8b. What happens if a linked program object with multiple stages is 1971 active on some of its stages, but not on others? 1972 1973 RESOLVED: Such a configuration would result in a draw-time 1974 validation error. Consider a program with vertex and fragment 1975 shaders, where the interface between stages is optimized as in the 1976 previous example. If the vertex shader from this program were to be 1977 used with a separate fragment-only program instead of the program's 1978 fragment shader, the optimized vertex outputs wouldn't necessarily 1979 match the inputs from the second program, even if the set of 1980 variables on that interface were compatible. 1981 1982 9. Is glUseProgramStages allowed to be compiled within a 1983 display list? 1984 1985 RESOLVED: Yes, just like glUseProgram is allowed within a 1986 display list. 1987 1988 10. Should there be some easier to use API for creating a GLSL 1989 program that programs a single shader type? 1990 1991 RESOLVED: Yes, see the glCreateShaderProgram command. 1992 1993 The existing GLSL API for creating a GLSL program involves a lot 1994 of steps to support multiple source strings, re-specification of 1995 source code, attaching and detaching multiple shader objects, 1996 and cross-stage linking. These features are not particularly 1997 relevant for creating separate shader programs. 1998 1999 11. Can glCreateShaderProgram be compiled into a display list? 2000 2001 RESOLVED: No. 2002 2003 glCreateShaderProgram is equivalent to a sequence of commands 2004 that are themselves not allowed to be compiled into a display 2005 list. 2006 2007 12. Should glCreateShaderProgram allow user-defined varyings? 2008 2009 RESOLVED: Yes. However, to get defined results when passing 2010 varying values between separate programs, applications are 2011 required to match inputs to outputs. This matching can be 2012 achieved either with the "location" layout qualifier, or by 2013 declaring the exact same set of inputs and outputs in the adjacent 2014 shader stages. 2015 2016 2017 13. How are interpolation modifiers handled for separate shader 2018 programs? 2019 2020 RESOLVED: GLSL only provides interpolation modifiers for user- 2021 defined varyings. These modifiers can be used in conjunction 2022 with the layout location qualifiers specified in this extension. 2023 Such modifiers must match. 2024 2025 14. Should glLinkProgram work to re-link a shader created with 2026 glCreateShaderProgram? 2027 2028 RESOLVED: NO because the shader created by glCreateShaderProgram 2029 is detached and deleted as part of the glCreateShaderProgram 2030 sequence. This means if you call glLinkProgram on a program 2031 returned from glCreateShaderProgram, you'll find the re-link 2032 fails because no shader object is attached. 2033 2034 An application is free to attach one or more new shader objects 2035 to the program and then relink would work. 2036 2037 This is fine because re-linking isn't necessary/expected. 2038 2039 15. Wouldn't re-linking be necessary if the application wanted to 2040 use glBindAttribLocation to assign a user-defined attribute to 2041 a specific vertex attribute? 2042 2043 RESOLVED: Yes and that's a problem if glCreateShaderProgram 2044 is used because the shader object is detached and deleted. 2045 2046 User-defined attributes will work when glCreateShaderProgram 2047 is used to easily create a vertex shader program, but the 2048 application must be satisfied with the implementation-dependent 2049 linker-assigned user-defined attributes returned by 2050 glGetAttribLocation. 2051 2052 We could provide a new set of built-in attributes that correspond 2053 to declared as: 2054 2055 attribute vec4 gl_VertexAttrib[]; 2056 2057 How would these attributes map to the other built-in attributes? That 2058 would depend on the implementation. As with ARB_vertex_program, some 2059 implementations could choose to alias such generate vertex attributes 2060 with conventional vertex attributes (color, fog coord, etc.) or an 2061 implementation could treat the generic attributes as disjoint from the 2062 conventional vertex attributes. 2063 2064 If this is unsatisfactory, the solution is to avoid using 2065 glCreateShaderProgram and instead use the traditional GLSL 2066 approach for creating programs (create shader, compile shader, 2067 attach shader, bind attributes, link shader, use shader). 2068 2069 Demonstrating how to workaround this particular issue, here's 2070 an example of creating and using a vertex shader for use with 2071 separate shader objects that includes explicit binding of output 2072 varyings to fragment data locations. First the shader: 2073 2074 varying in vec4 attribA; 2075 varying in vec4 attribB; 2076 void main() 2077 { 2078 gl_Position = ftransform(); 2079 gl_FrontColor = attribA; 2080 gl_BackColor = attribB; 2081 } 2082 2083 Now creating and using a linked program from this shader where 2084 attribA is initialized by vertex attribute 5 and attribB is 2085 initialized by vertex attribute 7. 2086 2087 GLuint ppo; 2088 GenProgramPipelines(1, &ppo); 2089 BindProgramPipeline(ppo); 2090 const GLuint shader = glCreateShader(GL_VERTEX_SHADER); 2091 if (shader) { 2092 const GLint len = (GLint) strlen(aboveShaderString); 2093 glShaderSource(shader, 1, &aboveShaderString, &len); 2094 glCompileShader(shader); 2095 const uint program = glCreateProgram(); 2096 if (program) { 2097 GLint compiled = FALSE; 2098 glGetShaderiv(shader, COMPILE_STATUS, &compiled); 2099 if (compiled) { 2100 glAttachShader(program, shader); 2101 2102 // Crucial code that glCreateShaderProgram doesn't do 2103 glBindAttribLocation(program, 5, "attribA"); 2104 glBindAttribLocation(program, 7, "attribB"); 2105 2106 glLinkProgram(program); 2107 glDetachShader(program, shader); 2108 2109 // Show this program can actually be used as a vertex shader 2110 glUseProgramStages(GL_VERTEX_SHADER, program); 2111 } 2112 } 2113 glDeleteShader(shader); 2114 return program; 2115 } else { 2116 return 0; 2117 } 2118 2119 Optionally, the glDetachShader and glDeleteShader commands could 2120 be removed to allow this program to be re-linked after different 2121 glBindAttribLocation calls. 2122 2123 16. Can you use glBindFragDataLocation to direct varying output 2124 variables from a fragment shader program created by 2125 glCreateShaderProgram to specific color buffers? 2126 2127 RESOLVED: NO for much the same reason you can't do this with 2128 attributes as described in issue 15. But you could create the 2129 program with the standard GLSL creation process where you attach 2130 your own shaders and relink. 2131 2132 For fragment shader programs created with 2133 glCreateShaderProgram, there is already the gl_FragData[] 2134 builtin to output to numbered color buffers. For integer 2135 framebuffers, we would need to add: 2136 2137 varying out ivec4 gl_IntFragData[]; 2138 2139 User-defined output fragment shader varyings can still be used 2140 as long as the application is happy with the linker-assigned 2141 locations. 2142 2143 Demonstrating how to workaround this particular issue, here's 2144 an example of creating and using a fragment shader for use with 2145 separate shader objects that includes explicit binding of output 2146 varyings to fragment data locations. First the shader: 2147 2148 varying out ivec4 bufferA; 2149 varying out ivec4 bufferB; 2150 void main() 2151 { 2152 bufferA = ivec4(1,2,3,4); 2153 bufferB = ivec4(5,6,7,8); 2154 } 2155 2156 Now creating and using a linked program from this shader where 2157 bufferA outputs to color buffer 0 and bufferB outputs to color 2158 buffer 1: 2159 2160 GLuint ppo; 2161 GenProgramPipelines(1, &ppo); 2162 BindProgramPipeline(ppo); 2163 const GLuint shader = glCreateShader(GL_FRAGMENT_SHADER); 2164 if (shader) { 2165 const GLint len = (GLint) strlen(aboveShaderString); 2166 glShaderSource(shader, 1, &aboveShaderString, &len); 2167 glCompileShader(shader); 2168 const uint program = glCreateProgram(); 2169 if (program) { 2170 GLint compiled = FALSE; 2171 glGetShaderiv(shader, COMPILE_STATUS, &compiled); 2172 if (compiled) { 2173 glAttachShader(program, shader); 2174 2175 // Crucial code that glCreateShaderProgram doesn't do 2176 glBindFragDataLocation(program, 0, "bufferA"); 2177 glBindFragDataLocation(program, 1, "bufferB"); 2178 2179 glLinkProgram(program); 2180 glDetachShader(program, shader); 2181 2182 // Show this program can actually be used as a fragment shader 2183 glUseProgramStages(GL_FRAGMENT_SHADER, program); 2184 } 2185 } 2186 glDeleteShader(shader); 2187 return program; 2188 } else { 2189 return 0; 2190 } 2191 2192 Optionally, the glDetachShader and glDeleteShader could be 2193 removed to allow this program to be re-linked after different 2194 glBindFragDataLocation calls. 2195 2196 17. Can you output varyings in transform feedback from a separate 2197 shader program created with glCreateShaderProgram? 2198 2199 RESOLVED: No. 2200 2201 glTransformFeedbackVaryings requires a re-link to take effect on 2202 a program. glCreateShaderProgram detaches and deletes the 2203 shader object use to create the program so a glLinkProgram will 2204 fail. 2205 2206 You can still create a vertex or geometry shader program 2207 with the standard GLSL creation process where you could use 2208 glTransformFeedbackVaryings and glLinkProgram. 2209 2210 18. I just don't get it? Why is it such a big deal to just require 2211 apps to link all their vertex and fragment shaders together? 2212 Please explain a situation where mix-and-match shaders is 2213 substantially better than GLSL as it exists without this 2214 extension? 2215 2216 RESOLUTION: Consider the (not uncommon) case of a vertex shader 2217 for skinning a character. The vertex shader is used in four 2218 distinct types of rendering passes, each using the one vertex 2219 shader but different fragment shaders. 2220 2221 For GLSL today, this situation today requires 4 program objects, 2222 each containing the one vertex shader paired with each one of 2223 the fragment shaders. 2224 2225 The one vertex shader has an array of dozens of skinning matrices 2226 along with numerous other uniform parameters. 2227 2228 Each fragment shader has its own different set of uniforms too. 2229 2230 Each GLSL program object has its own (combined) set of GLuint 2231 locations for the active uniforms of the vertex and fragment 2232 shaders objects linked into the particular program object. 2233 2234 The locations for a given program object are arbitrary and 2235 the location values of two distinct program objects have no 2236 correlation. This is true even when they each link in the same 2237 vertex shader (or alternatively same fragment shader). 2238 2239 Now the application is saddled with the burden of managing 2240 distinct location values for the same vertex shader skinning 2241 matrices and other uniform variables as well as making sure 2242 the values of these variables are mirroed over all four program 2243 objects containing the skinning vertex shader. 2244 2245 What's worse is despite all the program objects being loaded 2246 with the same vertex shader uniform variables for skinning, the 2247 driver is exceedingly unlikely to recoginize that binding from 2248 one of these program objects to another is going to result in 2249 no actual vertex shader state change. Noticing that the uniform 2250 vertex shader variables are changing in lock-step over a series 2251 of program objects (when the uniform fragment shader variables 2252 ARE allowed to diverge) is exceedingly expensive. 2253 2254 This situation is simple to optimize with mix-and-match shaders 2255 because there is just a single vertex shader to worry about. 2256 It's only the current fragment shader program that is changing 2257 so only the fragment shader state must be updated/re-validated. 2258 2259 It's also much easier and less expensive for the application to 2260 update the vertex shader state because there is just one copy 2261 of it to update. 2262 2263 19. Which should take precedence if both are bound, program objects 2264 or program pipeline objects? 2265 2266 RESOLVED: Program objects. Due to concerns about existing 2267 middleware depending on the program object state to determine 2268 the current program rendering state, the program object should 2269 override any program pipeline object that might be bound. 2270 2271 2272 20. Should UseProgramStages take a bitfield rather than derive the 2273 information from the program object? 2274 2275 RESOLVED: Yes. Though it seems pointless to include a bitfield 2276 that can only be erroneous if it includes bits set for shaders 2277 not present in the program object, without it there is no way to 2278 disassociate a shader type from a program object once it has 2279 been done. 2280 2281 21. What should the behavior be if a program object is deleted that 2282 is part of the current program pipeline object? 2283 2284 RESOLVED: Just as program objects made current via UseProgram 2285 are flagged for deletion until they are no longer referenced, 2286 program objects that form part of the current program pipeline 2287 object will be flagged and remain until no references remain. 2288 2289 Deletion of current program objects has special treatment in 2290 OpenGL. Such are not immediately deleted, but rather flagged for 2291 deletion and remain until they are no longer referenced. Being 2292 current indirectly as part of the current program pipeline object 2293 rather than directly via UseProgram makes no fundamental 2294 difference to the state of the program object or the rendering 2295 state. Whenever possible, an object made current as part of a 2296 container object should behave exactly as it would if it were 2297 to bypass that container object. In defference to that goal, 2298 objections to perpetuating the irregular behavior of program 2299 object deletion are set aside in favor of maintaining consistent 2300 behavior. 2301 2302 22. If multiple potential sources of transform feedback input are 2303 active from different program objects, where should transform feedback 2304 capture its input? 2305 2306 RESOLVED: The later stage in the ordered pipeline of stages 2307 should be the source of the transform feedback input. This is 2308 true at any given time regardless of how the state may change 2309 due to binding and releasing of different program objects. So if 2310 a geometry shader program is active and then removed, transform 2311 feedback input may switch to the vertex shader. This potential 2312 for changes requires an error with ResumeTransformFeedback if 2313 the related state has changed since it was paused. 2314 2315 23. How do built-in inputs in one stage interface with built-in outputs 2316 from a previous stage? 2317 2318 UNRESOLVED: There are several different classes of inputs that 2319 have different behavior: 2320 2321 (a) "System inputs" are ones that are not derived directly from a 2322 corresponding output. These inputs are treated as though they 2323 had their own dedicated locations; use of these variables in a 2324 shader do not affect whether the shader matches up with the 2325 outputs of a previous shader stage. Examples of such inputs 2326 include "gl_InvocationID", "gl_SamplePosition", 2327 "gl_PointCoord", and "gl_TessCoord". 2328 2329 (b) "System outputs" are are typically consumed by a fixed-function 2330 unit. These outputs are treated as though they had their own 2331 dedicated locations; use of these variables in a shader do not 2332 affect whether the shader matches up with the outputs of a 2333 previous shader stage. Examples of such outputs include 2334 "gl_Layer", "gl_TessLevelOuter[]". 2335 2336 (c) Non-system inputs and outputs are those passed more-or-less 2337 directly between shader stages. For fragment shader inputs, 2338 non-system inputs may be interpolated, but the interpolated 2339 values will be derived directly from outputs of the previous 2340 shader stages. These inputs and outputs are not treated as 2341 having dedicated locations. To ensure an exact match between 2342 two shader stages, the set of non-system inputs and outputs on 2343 the interface must match. 2344 2345 All built-in inputs and outputs not found in the gl_PerVertex and 2346 gl_PerFragment blocks are treated as belonging to categories (a) 2347 and (b). Members of gl_PerVertex may or may not be treated as 2348 "system" variables, depending on the specific interface. (See the 2349 next issue for more details.) 2350 2351 24. How does the use of built-in inputs or outputs affect the exact 2352 interface matching? Does their use affect matching for 2353 user-defined inputs? 2354 2355 UNRESOLVED: As noted in the previous issue, built-ins outside the 2356 gl_PerVertex and gl_PerFragment blocks are considered "system" 2357 variables that don't affect interface matching at all. For members 2358 of gl_PerVertex and gl_PerFragment, there are two types of 2359 interface between separable programs with different rules. 2360 2361 In interfaces not involving a fragment shader (e.g., vertex to 2362 geometry), shader outputs in gl_PerVertex are not interpreted by 2363 any fixed-function unit. As such, we will treat all inputs and 2364 outputs as non-system. To get defined results passing these 2365 built-ins between stages, gl_PerVertex must be declared identically 2366 on both sides of the interface. 2367 2368 In interfaces involving a fragment shader, some of the gl_PerVertex 2369 outputs will be consumed by the rasterizer and may not be passed to 2370 subsequent stages. In particular, the built-in outputs 2371 gl_Position, gl_PointSize, gl_ClipDistance[], and gl_ClipVertex 2372 (compatibility only) are consumed by the rasterizer. 2373 gl_ClipDistance[] is available in the fragment shader, but will 2374 typically not be read there; all other outputs are not available in 2375 the fragment shader. As a result, these outputs are treated as 2376 system outputs and are ignored when testing if gl_PerVertex and 2377 gl_PerFragment match. Since gl_PerVertex and gl_PerFragment 2378 typically won't match, we specify a member-by-member comparison. A 2379 mismatch occurs if a gl_PerFragment input is found without a 2380 corresponding gl_PerVertex output, or vice versa. 2381 2382 If non-system built-in inputs and outputs don't match on an 2383 interface, we don't guarantee that correct values are passed 2384 between stages (inputs are undefined). Additionally, a mismatch 2385 will mean that the values passed using user-defined inputs and 2386 outputs without location qualifiers are also not guaranteed, since 2387 the locations assigned for these built-ins might affect the 2388 assignments for user-defined variables. 2389 2390 25. How does the use of two-sided color built-ins (e.g., gl_FrontColor 2391 vs. gl_BackColor) affect the matching of inputs and outputs on an 2392 interface? 2393 2394 UNRESOLVED: For interfaces between two non-fragment stages, front 2395 and back colors are treated as separate variables over the 2396 interfaces. For interfaces involving a non-fragment stage with 2397 fragment, both pairs of front and back colors are treated as a 2398 single color for matching purposes. For example, a vertex shader 2399 is treated as effectively writing the fragment input "gl_Color" if 2400 it writes either "gl_FrontColor" or "gl_BackColor". 2401 2402 26. How should built-in inputs behave when used with user-defined 2403 variables with explicit locations? 2404 2405 UNRESOLVED: Built-ins are unaffected by the presence of 2406 user-defined variables with explicit locations. A mismatch in 2407 built-ins does not affect matching of user-defined variables with 2408 explicit locations. 2409 2410 Note that built-ins can not be assigned explicit locations. This 2411 means that: 2412 2413 (a) when non-system built-in usage doesn't match, the mismatch 2414 affects all such built-ins, plus any user-defined variables 2415 that aren't assigned explicit locations; and 2416 2417 (b) when user-defined variables without locations don't match 2418 between shaders, the mismatch affects all non-system 2419 built-ins as well. 2420 2421 27. How does the handling of built-in inputs and outputs in this 2422 extension differ from EXT_separate_shader_objects? 2423 2424 UNRESOLVED: In EXT_separate_shader_objects, shaders could only use 2425 built-ins to pass values between stages. In this extension, 2426 user-defined variables can be used. 2427 2428 In this extension, the usage of "non-system" built-ins is required 2429 to match between stages. In EXT_separate_shader_objects, there was 2430 no requirement that the set of built-in outputs written by one 2431 stage had to match the inputs read by another stage. 2432 2433 Implementations supporting EXT_separate_shader_objects are likely to 2434 provide logically separate locations for all shader built-ins. That 2435 extension didn't provide for undefined values when the set of 2436 built-ins used on one side of the interface didn't exactly match those 2437 on that other side, so implementations were required to assign 2438 matching locations even if texture coordinates or colors were used as 2439 outputs in one program but not inputs in another. 2440 2441 28. This extension requires shaders to redeclare gl_PerVertex and 2442 gl_PerFragment to use certain important built-ins. However, GLSL 2443 1.40 (OpenGL 3.1 and earlier) doesn't support input and output 2444 blocks at all. Should we support this extension on such GL/GLSL 2445 versions? If so, how? 2446 2447 RESOLVED: Yes, we expect that some implementations will want to 2448 support this extension on GPUs not capable of supporting OpenGL 3.2 2449 and GLSL 1.50. 2450 2451 To handle such cases, we don't require block redeclarations in shaders 2452 using #version 140 and earlier. Instead, we treat it these cases as 2453 though gl_PerVertex and gl_PerFragment existed and were re-declared 2454 implicitly. We allow shaders to redeclare all relevant built-ins, and 2455 require that shaders redeclare each of these built-ins that it uses. 2456 The set of redeclared built-ins is then assembled into an implicit 2457 block redeclaration and normal block matching rules are then applied. 2458 2459 This capability is provided only for shaders using #version 140 or 2460 lower. We considered adding a forward compatibility path allowing 2461 similar constructs in #version 150 and higher shaders, but opted 2462 against adding a second mechanism where block redeclaration is already 2463 available. Additionally, the fact that #version 140 shaders using 2464 this feature already have to redeclare all relevant variables means 2465 that shaders written for #version 140 plus this extension are likely 2466 to already have something looking very much like a block 2467 redeclaration, and should be easily ported. 2468 2469 We considered adding support for input and output blocks to GLSL 2470 1.40 as part of this extension, but decided that was too large of 2471 a change. 2472 2473 The relevant language here is only included in the extension spec. It 2474 doesn't need to be included in the core, because the only way to use 2475 the new features here with #version 140 shaders is via this extension. 2476 2477 29. How do input and output "location" layout qualifiers behave with this 2478 extension and ARB_explicit_attrib_location? 2479 2480 RESOLVED: ARB_explicit_attrib_location added "location" layout 2481 qualifiers for vertex shader inputs and fragment shader outputs to 2482 interface with fixed-function vertex pulling and blending hardware. 2483 This extension adds "location" qualifiers for all other shader inputs 2484 and outputs. To use these qualifiers, shaders must either enable the 2485 appropriate extension(s) using #extension or select a GLSL version 2486 incorporating the functionality using #version. In vertex and 2487 fragment shaders, it may be necessary to enable both extensions -- one 2488 for inputs and the other for outputs. 2489 2490 A shader using location layout qualifiers without an appropriate 2491 #extension or #version directive will fail to compile. 2492 2493 30. Can program pipeline objects be shared between contexts? 2494 2495 RESOLVED: No. Like framebuffer and vertex array objects (added by 2496 OpenGL 3.0), they are considered "container" objects to which other 2497 shareable objects can be attached. 2498 2499 31. How does one figure out how many locations are consumed by an input or 2500 output? 2501 2502 RESOLVED: Basic scalar and single-precision vector types are 2503 considered to consume one (vector) location. Double-precision scalar 2504 and vector types consume either one or two locations, as discussed 2505 further below. An array with <n> elements, each consuming <m> 2506 locations, will consume <n>*<m> locations. Matrix types are treated 2507 as arrays of two to four column vectors. Locations are assigned in 2508 structure types by assigning consecutive locations member-by-member 2509 according to the member declaration order. 2510 2511 31. How many locations are consumed by shader inputs and outputs with 2512 double-precision types? 2513 2514 RESOLVED: For inputs and outputs passed between shader stages, values 2515 of type "double" and "dvec2" consume a single location. Values of 2516 type "dvec3" and "dvec4" require more storage than a single-precision 2517 four-component vector, and thus consume two locations. 2518 2519 For vertex shader inputs, each location is associated with a generic 2520 vertex attribute. Since each such attribute in the API can hold a 2521 full "dvec4" if specified with VertexAttribL* or VertexAttribLPointer, 2522 values of type "double", "dvec2", "dvec3", and "dvec4" consume only a 2523 single location (generic vertex attribute). However, for the purposes 2524 of determining if a vertex shader uses "too many" attribute vectors in 2525 LinkProgram, vertex shader inputs of types "dvec3" and "dvec4" can be 2526 counted as consuming two vector attributes. For example, if a vertex 2527 shader specifies: 2528 2529 layout(location=4) in dvec4 attribs[4]; 2530 2531 the values for the four elements of "attribs" will be taken from 2532 vertex attributes 4-7, though "attribs" may be counted as consuming 2533 eight vectors worth of attributes. 2534 2535 Arrays or matrix types with double-precision components are treated as 2536 comprising 2537 2538 33. Are location layout qualifiers allowed on block declarations? On 2539 block member declarations? 2540 2541 RESOLVED: Location layout qualifiers are not allowed on either block 2542 or block member declarations in this extension. One implication of 2543 this behavior is that in input/output interface between programs, the 2544 sets of declared inputs and outputs must match exactly, since 2545 interface blocks can not be matched by location. Future extensions 2546 may consider relaxing either or both restrictions. 2547 2548 34. Should we ever allow inputs and outputs to match if they are of 2549 different type? 2550 2551 RESOLVED: The location system in this extension is expressed in units 2552 of four-component vectors. Because of this common numeric location, 2553 we allow outputs with a vector type to be fed to inputs with a scalar 2554 or smaller vector type as long as they have the same location and 2555 basic component type. For example, if a vertex shader includes: 2556 2557 layout(location = 4) out vec4 vsout; 2558 2559 and a fragment shader includes: 2560 2561 layout(location = 4) in vec2 fsin; 2562 2563 the two components of <fsin> will be obtained by interpolating the x 2564 and y components of <vsout>. The z and w components of <vsout> will 2565 be ignored. 2566 2567 We do not permit this behavior for double-precision vectors, because 2568 large types (dvec3, dvec4) consume two locations while smaller types 2569 (double, dvec2) consume only one. Allowing this behavior would be 2570 problematic for arrays. For example, in a vertex shader output 2571 declared as: 2572 2573 layout(location = 4) out dvec4 vsout[2]; 2574 2575 "vsout[1]" would be assigned locations 6 and 7, while in a fragment 2576 shader input declared as 2577 2578 layout(location = 4) in dvec2 fsin[2]; 2579 2580 "fsin[1]" would be assigned location 5. 2581 2582 35. What are the rules for determining if inputs and outputs match by 2583 qualification? 2584 2585 RESOLVED: In order for an input in one shader stage to be considered 2586 to match an output in another, some of the qualifiers must match but 2587 others need not match. In particular: 2588 2589 * The base storage qualifier ("in" and "out") across an interface 2590 will naturally not match -- one side uses "in", the other uses 2591 "out". 2592 2593 * Auxilliary storage qualifiers ("centroid", "sample", and "patch") 2594 and interpolation qualifiers ("flat", "smooth", "noperspective") 2595 must match. 2596 2597 * The location layout qualifier, if specified, must match. 2598 2599 * Layout qualifiers specific to one shader type (e.g., "stream" for 2600 geometry shader outputs) need not match. 2601 2602 * Precision qualifiers have no effect in OpenGL and need not match. 2603 2604 * The qualifiers "invariant" and "precise" affect only how outputs 2605 are computed within a shader stage and need not match between 2606 stages. 2607 2608 36. How does the behavior of input/output interface matching differ 2609 between separable programs and non-separable programs? 2610 2611 RESOLVED: The rules for matching individual variables or block 2612 members between stages are identical for separable and non-separable 2613 programs, with one exception -- matching variables of different type 2614 with the same location, as discussed in issue 34, applies only to 2615 separable programs. 2616 2617 However, the ability to enforce matching requirements differs between 2618 program types. In non-separable programs, both sides of an interface 2619 are contained in the same linked program. In this case, if the linker 2620 detects a mismatch, it will generate a link error. 2621 2622 For separable programs, the two sides of an interface may be in 2623 different programs, so the linker will be unable to detect a mismatch. 2624 In these cases, applications are responsible for ensuring matching 2625 inputs/outputs are used on either side of the interface. Input 2626 variables are undefined when mismatches occur. Matching can be done 2627 across the entire interface by ensuring that the exact same set of 2628 declarations is used on both sides of the interface. Alternately, 2629 matching can be done variable-by-variable by using identical types and 2630 matching location layout qualifiers. 2631 2632Revision History 2633 2634 Rev. Date Author Changes 2635 ---- ----------- --------- --------------------------------------------- 2636 25 1 Aug 2011 pbrown More clearly specify interface matching rules 2637 for shader inputs and outputs, for cases 2638 where both sides of an interface are found in 2639 the same program and where they are in 2640 different programs (bug 7030). Add 2641 dependencies with several ARB extensions and 2642 core version. Add several new spec issues 2643 related to shader interface matching. 2644 2645 Add GLSL spec language describing what 2646 qualifiers must match for inputs/outputs to 2647 be considered to match in qualification. Add 2648 clarifications on the number of locations 2649 consumed by different types of shader 2650 inputs/outputs. Specify that vertex shader 2651 inputs of type "dvec3" and "dvec4" consume a 2652 single location for the purposes of matching 2653 with generic vertex attributes in the API 2654 (bug 7809). More clearly specify that 2655 location layout qualifiers are not allowed on 2656 blocks and block members. 2657 2658 24 25 Jul 2011 pbrown Remove the language erroneously deleting 2659 CURRENT_PROGRAM. In the EXT extension, this 2660 token was aliased to ACTIVE_PROGRAM_EXT, and 2661 was used to indicate the last program set by 2662 either ActiveProgramEXT or UseProgram. In 2663 the ARB extension, the SSO active programs 2664 are now program pipeline object state and 2665 CURRENT_PROGRAM should still be used to query 2666 the last program set by UseProgram (bug 7822). 2667 2668 23 25 Jul 2011 Jon Leech Add VALIDATE_STATUS to state tables and 2669 GetProgramPipelineiv description (bug 7748). 2670 2671 22 6 Jun 2011 pbrown Treat program pipeline objects as non-shared 2672 container objects, like framebuffer and 2673 vertex array objects (bug 7713). 2674 2675 21 9 Aug 2010 pbrown Expand ProgramUniform* function prototypes 2676 to individual entries for tools parsing 2677 extension specs. Add missing "*" characters 2678 for ProgramUniform*v functions. 2679 2680 20 15 Jul 2010 pbrown Proposed update to locations for vectors 2681 with double-precision components (bug 6635). 2682 2683 19 13 Jul 2010 pbrown Clarify issues 7 and 8. 2684 2685 18 13 Jul 2010 Jon Leech Clarify interactions of current program 2686 & pbrown object and current program pipeline object, 2687 and error conditions when a PPO with missing 2688 shader stages is current. Add language for 2689 the interaction of separate shader objects 2690 and per-stage subroutine uniforms (bug 6641). 2691 Specify behavior for successful and failed 2692 links of programs bound to PPOs (bug 6642). 2693 Add interactions for assembly program 2694 extensions and EXT_separate_shader_objects. 2695 Add missing code for CreateShaderProgramv 2696 treating such programs as separable. 2697 Update miscellaneous spec sections that 2698 don't account for per-stage active programs. 2699 2700 17 08 Jul 2010 pbrown Fix interface matching language in "Inputs" 2701 section of GLSL spec; modify API spec to 2702 allow type mismatches when using location 2703 qualifiers (e.g., passing a vec4 to a vec3). 2704 2705 16 08 Jul 2010 pbrown Restore error for linking a non-separable 2706 program without a vertex shader (bug 6517). 2707 Modify language describing the number of 2708 available locations (bug 6598). Add language 2709 disallowing aliasing of inputs and outputs 2710 except for previously allowed vertex shader 2711 input aliasing (bug 6599). Further work on 2712 block matching rules for built-in input and 2713 output blocks, including final rules for 2714 #version 140 shaders (bug 6636). 2715 Miscellaneous typo fixes. 2716 2717 15 07 Jul 2010 pbrown Minor typo corrections. Add specific 2718 language for the core profile, which won't 2719 have gl_PerFragment. Add issue on the use 2720 of location qualifiers and #extension; fix 2721 spec to match. 2722 2723 14 21 Jun 2010 pbrown Updated "Shader Interface Matching" 2724 section to include new rules for built-in 2725 inputs and outputs. Added more 2726 dependencies on the core profile and older 2727 versions of GLSL. Added several issues. 2728 2729 13 07 Jun 2010 groth Minor relinking clarification. New begin error 2730 2731 12 01 Jun 2010 groth More clarifications. Better introduction 2732 More consistency. 2733 2734 11 28 May 2010 groth Language clarifications and issue corrections 2735 2736 10 21 May 2010 groth move new xfb errors into pre-existing list 2737 cleaned up sundry issues 2738 further clarified deletion behavior 2739 various other non-controversial cleanups 2740 2741 9 20 May 2010 groth Add validateProgramPipeline/infolog 2742 clarify xfb interaction 2743 complete interface location allocation 2744 language. mention location limits. 2745 2746 8 19 May 2010 groth Finish responding to Pat's feedback. 2747 Reorganization for clarity. 2748 2749 7 15 May 2010 groth Respond to various feedback 2750 2751 6 10 May 2010 groth multiple shaders to CreateShaderProgram. 2752 Rename ActiveProgram, CreateShaderProgram 2753 Sundry corrections. 2754 2755 5 08 May 2010 groth remove default PPO. add active program 2756 definitively to PPO. add a few issues. 2757 fix nits. 2758 2759 4 06 May 2010 groth Clarify PPO role. Add language about implicit 2760 interfaces. 2761 2762 3 04 May 2010 groth Add container object. Add DSA uniform commands. 2763 2764 2 23 Apr 2010 groth Fill out sections explaining GLSL layout 2765 pragmas. Add tessellation awareness. Forbid 2766 certain use of monolithic and shader programs. 2767 2768 1 13 Jan 2010 mjk Initial revision 2769