1Name 2 3 EXT_separate_shader_objects 4 5Name Strings 6 7 GL_EXT_separate_shader_objects 8 9Contributors 10 11 Contributors to ARB_separate_shader_objects and 12 ARB_explicit_attrib_location desktop OpenGL extensions from which this 13 extension borrows heavily 14 15Contact 16 17 Benj Lipchak, Apple (lipchak 'at' apple.com) 18 19Status 20 21 Complete 22 23 NOTE: there is an unrelated OpenGL extension also named 24 "GL_EXT_separate_shader_objects", found in the OpenGL extension registry 25 at http://www.opengl.org/registry/ . These two extensions have similar 26 purposes, but completely different interfaces. 27 28Version 29 30 Date: November 08, 2013 31 Revision: 7 32 33Number 34 35 OpenGL ES Extension #101 36 37Dependencies 38 39 Requires OpenGL ES 2.0. 40 41 Written based on the wording of the OpenGL ES 2.0.25 Full Specification 42 (November 2, 2010). 43 44 Written based on the wording of The OpenGL ES Shading Language 1.0.17 45 Specification (May 12, 2009). 46 47 OpenGL ES 3.0 affects the definition of this extension. 48 49 NV_non_square_matrices affects the definition of this extension. 50 51Overview 52 53 This extension is a subset of ARB_separate_shader_objects appropriate for 54 OpenGL ES, and also tacks on ARB_explicit_attrib_location functionality. 55 56 Conventional GLSL requires multiple shader stages (vertex and fragment) to 57 be linked into a single monolithic program object to specify a GLSL shader 58 for each stage. 59 60 While GLSL's monolithic approach has some advantages for optimizing shaders 61 as a unit that span multiple stages, GPU hardware supports a more flexible 62 mix-and-match approach to specifying shaders independently for these 63 different shader stages. Many developers build their shader content around 64 the mix-and-match approach where they can use a single vertex shader with 65 multiple fragment shaders (or vice versa). 66 67 This extension adopts a "mix-and-match" shader stage model for GLSL 68 allowing multiple different GLSL program objects to be bound at once each 69 to an individual rendering pipeline stage independently of other stage 70 bindings. This allows program objects to contain only the shader stages 71 that best suit the application's needs. 72 73 This extension introduces the program pipeline object that serves as a 74 container for the program bound to any particular rendering stage. It can 75 be bound, unbound, and rebound to simply save and restore the complete 76 shader stage to program object bindings. Like framebuffer 77 and vertex array objects, program pipeline objects are "container" 78 objects that are not shared between contexts. 79 80 To bind a program object to a specific shader stage or set of stages, 81 UseProgramStagesEXT is used. The VERTEX_SHADER_BIT_EXT and 82 FRAGMENT_SHADER_BIT_EXT tokens refer to the conventional vertex and 83 fragment stages, respectively. ActiveShaderProgramEXT specifies the 84 program that Uniform* commands will update. 85 86 While ActiveShaderProgramEXT provides a selector for setting and querying 87 uniform values of a program object with the conventional Uniform* commands, 88 the ProgramUniform* commands provide a selector-free way to modify uniforms 89 of a GLSL program object without an explicit bind. This selector-free model 90 reduces API overhead and provides a cleaner interface for applications. 91 92 Separate linking creates the possibility that certain output varyings of a 93 shader may go unread by the subsequent shader input varyings. In this 94 case, the output varyings are simply ignored. It is also possible input 95 varyings from a shader may not be written as output varyings of a preceding 96 shader. In this case, the unwritten input varying values are undefined. 97 98 This extension also introduces a layout location qualifier to GLSL to pre- 99 assign attribute and varying locations to shader variables. This allows 100 applications to globally assign a particular semantic meaning, such as 101 diffuse color or vertex normal, to a particular attribute and/or varying 102 location without knowing how that variable will be named in any particular 103 shader. 104 105New Procedures and Functions 106 107 void UseProgramStagesEXT(uint pipeline, bitfield stages, 108 uint program); 109 110 void ActiveShaderProgramEXT(uint pipeline, uint program); 111 112 uint CreateShaderProgramvEXT(enum type, sizei count, 113 const char **strings); 114 115 void BindProgramPipelineEXT(uint pipeline); 116 117 void DeleteProgramPipelinesEXT(sizei n, const uint *pipelines); 118 119 void GenProgramPipelinesEXT(sizei n, uint *pipelines); 120 121 boolean IsProgramPipelineEXT(uint pipeline); 122 123 void ProgramParameteriEXT(uint program, enum pname, int value); 124 125 void GetProgramPipelineivEXT(uint pipeline, enum pname, int *params); 126 127 void ProgramUniform1iEXT(uint program, int location, 128 int x); 129 void ProgramUniform2iEXT(uint program, int location, 130 int x, int y); 131 void ProgramUniform3iEXT(uint program, int location, 132 int x, int y, int z); 133 void ProgramUniform4iEXT(uint program, int location, 134 int x, int y, int z, int w); 135 136 void ProgramUniform1fEXT(uint program, int location, 137 float x); 138 void ProgramUniform2fEXT(uint program, int location, 139 float x, float y); 140 void ProgramUniform3fEXT(uint program, int location, 141 float x, float y, float z); 142 void ProgramUniform4fEXT(uint program, int location, 143 float x, float y, float z, float w); 144 145 void ProgramUniform1uiEXT(uint program, int location, 146 uint x); 147 void ProgramUniform2uiEXT(uint program, int location, 148 uint x, uint y); 149 void ProgramUniform3uiEXT(uint program, int location, 150 uint x, uint y, uint z); 151 void ProgramUniform4uiEXT(uint program, int location, 152 uint x, uint y, uint z, uint w); 153 154 void ProgramUniform1ivEXT(uint program, int location, 155 sizei count, const int *value); 156 void ProgramUniform2ivEXT(uint program, int location, 157 sizei count, const int *value); 158 void ProgramUniform3ivEXT(uint program, int location, 159 sizei count, const int *value); 160 void ProgramUniform4ivEXT(uint program, int location, 161 sizei count, const int *value); 162 163 void ProgramUniform1fvEXT(uint program, int location, 164 sizei count, const float *value); 165 void ProgramUniform2fvEXT(uint program, int location, 166 sizei count, const float *value); 167 void ProgramUniform3fvEXT(uint program, int location, 168 sizei count, const float *value); 169 void ProgramUniform4fvEXT(uint program, int location, 170 sizei count, const float *value); 171 172 void ProgramUniform1uivEXT(uint program, int location, 173 sizei count, const uint *value); 174 void ProgramUniform2uivEXT(uint program, int location, 175 sizei count, const uint *value); 176 void ProgramUniform3uivEXT(uint program, int location, 177 sizei count, const uint *value); 178 void ProgramUniform4uivEXT(uint program, int location, 179 sizei count, const uint *value); 180 181 void ProgramUniformMatrix2fvEXT(uint program, int location, 182 sizei count, boolean transpose, 183 const float *value); 184 void ProgramUniformMatrix3fvEXT(uint program, int location, 185 sizei count, boolean transpose, 186 const float *value); 187 void ProgramUniformMatrix4fvEXT(uint program, int location, 188 sizei count, boolean transpose, 189 const float *value); 190 void ProgramUniformMatrix2x3fvEXT(uint program, int location, 191 sizei count, boolean transpose, 192 const float *value); 193 void ProgramUniformMatrix3x2fvEXT(uint program, int location, 194 sizei count, boolean transpose, 195 const float *value); 196 void ProgramUniformMatrix2x4fvEXT(uint program, int location, 197 sizei count, boolean transpose, 198 const float *value); 199 void ProgramUniformMatrix4x2fvEXT(uint program, int location, 200 sizei count, boolean transpose, 201 const float *value); 202 void ProgramUniformMatrix3x4fvEXT(uint program, int location, 203 sizei count, boolean transpose, 204 const float *value); 205 void ProgramUniformMatrix4x3fvEXT(uint program, int location, 206 sizei count, boolean transpose, 207 const float *value); 208 209 210 void ValidateProgramPipelineEXT(uint pipeline); 211 212 void GetProgramPipelineInfoLogEXT(uint pipeline, sizei bufSize, 213 sizei *length, char *infoLog); 214 215New Tokens 216 217 Accepted by <stages> parameter to UseProgramStagesEXT: 218 219 VERTEX_SHADER_BIT_EXT 0x00000001 220 FRAGMENT_SHADER_BIT_EXT 0x00000002 221 ALL_SHADER_BITS_EXT 0xFFFFFFFF 222 223 Accepted by the <pname> parameter of ProgramParameteriEXT and 224 GetProgramiv: 225 226 PROGRAM_SEPARABLE_EXT 0x8258 227 228 Accepted by <type> parameter to GetProgramPipelineivEXT: 229 230 ACTIVE_PROGRAM_EXT 0x8259 231 232 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, and 233 GetFloatv: 234 235 PROGRAM_PIPELINE_BINDING_EXT 0x825A 236 237Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL Operation): 238 239 -- Section 2.10 "Vertex Shaders" (page 26) 240 241 Modify the fourth and fifth paragraphs: 242 243 "To use a vertex shader, shader source code is first loaded into a shader 244 object and then compiled. Alternatively, pre-compiled shader binary code 245 may be directly loaded into a shader object. An OpenGL ES implementation 246 must support one of these methods for loading shaders. If the boolean value 247 SHADER_COMPILER is TRUE, then the shader compiler is supported. If the 248 integer value NUM_SHADER_BINARY_FORMATS is greater than zero, then shader 249 binary loading is supported. 250 251 A shader object corresponds to a stage in the rendering pipeline referred 252 to as its shader stage or type. A vertex shader object is attached to a 253 program object. The program object is then linked, which generates 254 executable code from the compiled shader object(s) attached to the program. 255 When program objects are bound to a shader stage, they become the current 256 program object for that stage. When the current program object for the 257 vertex stage includes a vertex shader, it is considered the active program 258 object for the vertex stage. The current program object for all stages may 259 be set at once using a single unified program object, or the current 260 program object may be set for each stage individually using a separable 261 program object where different separable program objects may be current for 262 other stages. The set of separable program objects current for all stages 263 are collected in a program pipeline object that must be bound for use. 264 When a linked program object is made active for the vertex stage, the 265 executable code for the vertex shaders it contains is used to process 266 vertices." 267 268 Modify the last sentence in the sixth paragraph: 269 270 "... A single program object can contain either a vertex shader, a fragment 271 shader, or both." 272 273 Modify the seventh paragraph: 274 275 "When the program object currently in use for the vertex stage 276 includes a vertex shader, its vertex shader is considered active and 277 is used to process vertices. If the current vertex stage program 278 object has no vertex shader or no program object is current for the 279 vertex stage, the results of vertex shader execution are undefined." 280 281 -- Section 2.10.3 "Program Objects" (page 30) 282 283 Modify the description of linking failures following the description of 284 LinkProgram to read: 285 286 "... if <program> is not separable and does not contain both a vertex and a 287 fragment shader, ..." 288 289 Modify second paragraph, p. 31: 290 291 "If a program has been successfully linked by LinkProgram, it can be made 292 part of the current rendering state for all shader stages with the command 293 294 void UseProgram(uint program); 295 296 If <program> is non-zero, this command will make <program> the current 297 program object. This will install executable code as part of the current 298 rendering state for each shader stage present when the program was last 299 successfully linked. If UseProgram is called with <program> set to zero, 300 then there is no current program object. If <program> has not been 301 successfully linked, the error INVALID_OPERATION is generated and the 302 current rendering state is not modified." 303 304 Insert paragraph immediately after preceding paragraph: 305 306 "The executable code for an individual shader stage is taken from the 307 current program for that stage. If there is a current program object 308 established by UseProgram, that program is considered current for all 309 stages. Otherwise, if there is a bound program pipeline object (section 310 2.10.PPO), the program bound to the appropriate stage of the pipeline 311 object is considered current. If there is no current program object or 312 bound program pipeline object, no program is current for any stage. The 313 current program for a stage is considered active if it contains executable 314 code for that stage; otherwise, no program is considered active for that 315 stage. If there is no active program for the vertex or fragment shader 316 stages, the results of vertex and/or fragment processing will be undefined. 317 However, this is not an error." 318 319 Modify fourth and fifth paragraphs, p. 31: 320 321 "If a program object that is active for any shader stage is re-linked 322 successfully, the LinkProgram command will install the generated 323 executable code as part of the current rendering state for all shader 324 stages where the program is active. Additionally, the newly generated 325 executable code is made part of the state of any program pipeline for all 326 stages where the program is attached. 327 328 If a program object that is active for any shader stage is re-linked 329 unsuccessfully, the link status will be set to FALSE, but existing 330 executables and associated state will remain part of the current rendering 331 state until a subsequent call to UseProgram, UseProgramStagesEXT, or 332 BindProgramPipelineEXT removes them from use. If such a program is 333 attached to any program pipeline object, the existing executables and 334 associated state will remain part of the program pipeline object until a 335 subsequent call to UseProgramStagesEXT removes them from use. An 336 unsuccessfully linked program may not be made part of the current rendering 337 state by UseProgram or added to program pipeline objects by 338 UseProgramStagesEXT until it is successfully re-linked. If such a program 339 was attached to a program pipeline at the time of a failed link, its 340 existing executable may still be made part of the current rendering state 341 indirectly by BindProgramPipelineEXT." 342 343 Insert prior to the description of DeleteProgram, p. 31: 344 345 "Program parameters control aspects of how the program is linked, 346 executed, or stored. To set a program parameter, call 347 348 void ProgramParameteriEXT(uint program, enum pname, int value); 349 350 <pname> identifies which parameter to set for program object 351 <program>. <value> holds the value being set. 352 353 If <pname> is PROGRAM_SEPARABLE_EXT, <value> must be TRUE or FALSE 354 and indicates whether the <program> can be bound for individual 355 pipeline stages via UseProgramStagesEXT after it is next linked." 356 357 Modify the last paragraph of the section, p. 31: 358 359 "If <program> is not current for any GL context, is not the active 360 program for any program pipeline object, and is not the current 361 program for any stage of any program pipeline object, it is deleted 362 immediately. Otherwise, <program> is flagged ..." 363 364 Insert at the end of the section, p. 31: 365 366 "The command 367 368 uint CreateShaderProgramvEXT(enum type, sizei count, 369 const char **strings); 370 371 creates a stand-alone program from an array of null-terminated source 372 code strings for a single shader type. CreateShaderProgramvEXT 373 is equivalent to the following command sequence: 374 375 const uint shader = CreateShader(type); 376 if (shader) { 377 ShaderSource(shader, count, strings, NULL); 378 CompileShader(shader); 379 const uint program = CreateProgram(); 380 if (program) { 381 int compiled = FALSE; 382 GetShaderiv(shader, COMPILE_STATUS, &compiled); 383 ProgramParameteriEXT(program, PROGRAM_SEPARABLE_EXT, TRUE); 384 if (compiled) { 385 AttachShader(program, shader); 386 LinkProgram(program); 387 DetachShader(program, shader); 388 } 389 append-shader-info-log-to-program-info-log 390 } 391 DeleteShader(shader); 392 return program; 393 } else { 394 return 0; 395 } 396 397 The program may not actually link if the output variables in the 398 shader attached to the final stage of the linked program take up 399 too many locations. If this situation arises, the info log may 400 explain this. 401 402 Because no shader is returned by CreateShaderProgramvEXT and the 403 shader that is created is deleted in the course of the command 404 sequence, the info log of the shader object is copied to the program 405 so the shader's failed info log for the failed compilation is 406 accessible to the application." 407 408 -- Add new section 2.10.PPO "Program Pipeline Objects" after 2.10.3 409 "Program Objects" 410 411 "Instead of packaging all shader stages into a single program object, 412 shader types might be contained in multiple program objects each 413 consisting of part of the complete pipeline. A program object may 414 even contain only a single shader stage. This facilitates greater 415 flexibility when combining different shaders in various ways without 416 requiring a program object for each combination. 417 418 Program bindings associating program objects with shader types are 419 collected to form a program pipeline object. 420 421 The command 422 423 void GenProgramPipelinesEXT(sizei n, uint *pipelines); 424 425 returns <n> previously unused program pipeline object names in 426 <pipelines>. These names are marked as used, for the purposes of 427 GenProgramPipelinesEXT only, but they acquire state only when they are 428 first bound. 429 430 Program pipeline objects are deleted by calling 431 432 void DeleteProgramPipelinesEXT(sizei n, const uint *pipelines); 433 434 <pipelines> contains <n> names of program pipeline objects to be 435 deleted. Once a program pipeline object is deleted, it has no 436 contents and its name becomes unused. If an object that is currently 437 bound is deleted, the binding for that object reverts to zero and no 438 program pipeline object becomes current. Unused names in <pipelines> 439 are silently ignored, as is the value zero. 440 441 A program pipeline object is created by binding a name returned by 442 GenProgramPipelinesEXT with the command 443 444 void BindProgramPipelineEXT(uint pipeline); 445 446 <pipeline> is the program pipeline object name. The resulting program 447 pipeline object is a new state vector, comprising all the state and with 448 the same initial values listed in table 6.PPO. 449 450 BindProgramPipelineEXT may also be used to bind an existing program 451 pipeline object. If the bind is successful, no change is made to 452 the state of the bound program pipeline object, and any previous 453 binding is broken. If BindProgramPipelineEXT is called with <pipeline> 454 set to zero, then there is no current program pipeline object. 455 456 If no current program object has been established by UseProgram, the 457 program objects used for each shader stage and for uniform updates are 458 taken from the bound program pipeline object, if any. If there is a 459 current program object established by UseProgram, the bound program 460 pipeline object has no effect on rendering or uniform updates. When a 461 bound program pipeline object is used for rendering, individual shader 462 executables are taken from its program objects as described in the 463 discussion of UseProgram in section 2.10.3. 464 465 BindProgramPipelineEXT fails and an INVALID_OPERATION error is 466 generated if <pipeline> is not zero or a name returned from a 467 previous call to GenProgramPipelinesEXT, or if such a name has since 468 been deleted with DeleteProgramPipelinesEXT. 469 470 The executables in a program object associated with one or more 471 shader stages can be made part of the program pipeline state for 472 those shader stages with the command: 473 474 void UseProgramStagesEXT(uint pipeline, bitfield stages, 475 uint program); 476 477 where <pipeline> is the program pipeline object to be updated, 478 <stages> is the bitwise OR of accepted constants representing 479 shader stages, and <program> is the program object from which the 480 executables are taken. The bits set in <stages> indicate the program 481 stages for which the program object named by <program> becomes 482 current. These stages may include vertex or fragment indicated by 483 VERTEX_SHADER_BIT_EXT or FRAGMENT_SHADER_BIT_EXT respectively. The 484 constant ALL_SHADER_BITS_EXT indicates <program> is to be made current 485 for all shader stages. If <program> refers to a program object with a valid 486 shader attached for an indicated shader stage, this call installs 487 the executable code for that stage in the indicated program pipeline 488 object state. If UseProgramStagesEXT is called with <program> set to 489 zero or with a program object that contains no executable code for the 490 given stages, it is as if the pipeline object has no programmable stage 491 configured for the indicated shader stages. If <stages> is not the 492 special value ALL_SHADER_BITS_EXT and has a bit set that is not 493 recognized, the error INVALID_VALUE is generated. If the program object 494 named by <program> was linked without the PROGRAM_SEPARABLE_EXT parameter 495 set or was not linked successfully, the error INVALID_OPERATION is 496 generated and the corresponding shader stages in the <pipeline> 497 program pipeline object are not modified. 498 499 If <pipeline> is a name that has been generated (without subsequent 500 deletion) by GenProgramPipelinesEXT, but refers to a program pipeline 501 object that has not been previously bound, the GL first creates a 502 new state vector in the same manner as when BindProgramPipelineEXT 503 creates a new program pipeline object. If <pipeline> is not a name 504 returned from a previous call to GenProgramPipelinesEXT or if such a 505 name has since been deleted by DeleteProgramPipelinesEXT, an 506 INVALID_OPERATION error is generated. 507 508 The command 509 510 void ActiveShaderProgramEXT(uint pipeline, uint program); 511 512 sets the linked program named by <program> to be the active program 513 (discussed later in the secion 2.10.4) for the program pipeline 514 object <pipeline>. If <program> has not been successfully linked, 515 the error INVALID_OPERATION is generated and active program is not 516 modified. 517 518 If <pipeline> is a name that has been generated (without subsequent 519 deletion) by GenProgramPipelinesEXT, but refers to a program pipeline 520 object that has not been previously bound, the GL first creates a 521 new state vector in the same manner as when BindProgramPipelineEXT 522 creates a new program pipeline object. If <pipeline> is not a name 523 returned from a previous call to GenProgramPipelinesEXT or if such a 524 name has since been deleted by DeleteProgramPipelinesEXT, an 525 INVALID_OPERATION error is generated. 526 527 528 Shader Interface Matching 529 530 When linking a non-separable program object with multiple shader types, 531 the outputs of one stage form an interface with the inputs of the next 532 stage. These inputs and outputs must typically match in name, type, 533 and qualification. When both sides of an interface are contained in 534 the same program object, LinkProgram will detect mismatches on an 535 interface and generate link errors. 536 537 With separable program objects, interfaces between shader stages may 538 involve the outputs from one program object and the inputs from a 539 second program object. For such interfaces, it is not possible to 540 detect mismatches at link time, because the programs are linked 541 separately. When each such program is linked, all inputs or outputs 542 interfacing with another program stage are treated as active. The 543 linker will generate an executable that assumes the presence of a 544 compatible program on the other side of the interface. If a mismatch 545 between programs occurs, no GL error will be generated, but some or all 546 of the inputs on the interface will be undefined. 547 548 At an interface between program objects, the inputs and outputs are 549 considered to match exactly if and only if: 550 551 * For every user-declared input variable declared, there is an output 552 variable declared in the previous shader matching exactly in name, 553 type, and qualification. 554 555 * There are no user-defined output variables declared without a matching 556 input variable declaration. 557 558 When the set of inputs and outputs on an interface between programs 559 matches exactly, all inputs are well-defined unless the corresponding 560 outputs were not written in the previous shader. However, any mismatch 561 between inputs and outputs results in all inputs being undefined except 562 for cases noted below. Even if an input has a corresponding output 563 that matches exactly, mismatches on other inputs or outputs may 564 adversely affect the executable code generated to read or write the 565 matching variable. 566 567 The inputs and outputs on an interface between programs need not match 568 exactly when input and output location qualifiers (sections 4.3.6.1 and 569 4.3.6.2 of the GLSL Specification) are used. When using location 570 qualifiers, any input with an input location qualifier will be 571 well-defined as long as the other program writes to an output with the 572 same location qualifier, data type, and qualification. Also, an input 573 will be well-defined if the other program writes to an output matching 574 the input in everything but data type as long as the output data type 575 has the same basic component type and more components. The names of 576 variables need not match when matching by location. For the purposes 577 of interface matching, an input with a location qualifier is considered 578 to match a corresponding output only if that output has an identical 579 location qualifier. 580 581 Built-in inputs or outputs do not affect interface matching. Any such 582 built-in inputs are well-defined unless they are derived from built-in 583 outputs not written by the previous shader stage. 584 585 586 Program Pipeline Object State 587 588 The state required to support program pipeline objects consists of 589 a single binding name of the current program pipeline object. This 590 binding is initially zero indicating no program pipeline object is 591 bound. 592 593 The state of each program pipeline object consists of: 594 595 * Three unsigned integers (initially all zero) are required to hold 596 each respective name of the current vertex stage program, current 597 fragment stage program, and active program respectively. 598 * A Boolean holding the status of the last validation attempt, 599 initially false. 600 * An array of type char containing the information log, initially 601 empty. 602 * An integer holding the length of the information log." 603 604 -- Section 2.10.4 "Shader Variables" subsection "Vertex Attributes" 605 606 Change the first sentence of the second full paragraph (p. 34): 607 608 "When a program is linked, any active attributes without a binding 609 specified either through BindAttribLocation or explicitly set 610 within the shader text will be automatically bound to vertex 611 attributes by the GL." 612 613 Add the following sentence to the end of that same paragraph: 614 615 "If an active attribute has a binding explicitly set within the shader text 616 and a different binding assigned by BindAttribLocation, the assignment in 617 the shader text is used." 618 619 -- Section 2.10.4 "Shader Variables" subsection "Uniform Variables" 620 621 Replace the paragraph introducing Uniform* (p. 37): 622 623 "To load values into the uniform variables of the active program object, 624 use the commands 625 626 ... 627 628 If a non-zero program object is bound by UseProgram, it is the 629 active program object whose uniforms are updated by these commands. 630 If no program object is bound using UseProgram, the active program 631 object of the current program pipeline object set by 632 ActiveShaderProgramEXT is the active program object. If the current 633 program pipeline object has no active program or there is no current 634 program pipeline object, then there is no active program. 635 636 The given values are loaded into the ... " 637 638 Change the last bullet in the "Uniform Variables" subsection (p. 38) to: 639 640 "* if there is no active program in use." 641 642 Add to the end of the "Uniform Variables" subsection (p. 38): 643 644 To load values into the uniform variables of a program which may not 645 necessarily be bound, use the commands 646 647 void ProgramUniform{1234}{if}EXT(uint program, int location, 648 T value); 649 void ProgramUniform{1234}uiEXT(uint program, int location, 650 T value); 651 void ProgramUniform{1234}{if}vEXT(uint program, int location, 652 sizei count, const T *value); 653 void ProgramUniform{1234}uivEXT(uint program, int location, 654 sizei count, const uint *value); 655 void ProgramUniformMatrix{234}fvEXT(uint program, int location, 656 sizei count, boolean transpose, 657 const float *value); 658 void ProgramUniformMatrix{2x3,3x2,2x4, 659 4x2,3x4,4x3}fvEXT(uint program, 660 int location, 661 sizei count, 662 boolean transpose, 663 const float *value); 664 665 These commands operate identically to the corresponding commands 666 above without "Program" in the command name except, rather than 667 updating the currently active program object, these "Program" 668 commands update the program object named by the initial <program> 669 parameter. The remaining parameters following the initial <program> 670 parameter match the parameters for the corresponding non-"Program" 671 uniform command. If <program> is not the name of a created program 672 or shader object, the error INVALID_VALUE is generated. If <program> 673 identifies a shader object or a program object that has not been 674 linked successfully, the error INVALID_OPERATION is generated. 675 676 -- Section 2.10.5 "Shader Execution" (p. 40) 677 678 Change the first paragraph: 679 680 "If there is an active program object present for the vertex stage, the 681 executable code for this active program is used to process incoming vertex 682 values." 683 684 Change first paragraph of subsection "Validation", p. 41: 685 686 "It is not always possible to determine at link time if a program object 687 can execute successfully, given that LinkProgram can not know the state of 688 the remainder of the pipeline. Therefore validation is done when the first 689 rendering command (DrawArrays or DrawElements) is issued, to determine if 690 the set of active program objects can be executed. If the current set of 691 active program objects cannot be executed, no primitives 692 are processed and the error INVALID_OPERATION will be generated." 693 694 Add to the list in the second paragraph of subsection "Validation" (p. 41): 695 696 "* A program object is active for at least one, but not all of the 697 shader stages that were present when the program was linked. 698 699 * There is no current unified program object and the current program 700 pipeline object includes a program object that was relinked since 701 being applied to the pipeline object via UseProgramStagesEXT with the 702 PROGRAM_SEPARABLE_EXT parameter set to FALSE." 703 704 Add after the description of ValidateProgram in subsection 705 "Validation": 706 707 "Separable program objects may have validation failures that cannot 708 be detected without the complete program pipeline. Mismatched 709 interfaces, improper usage of program objects together, and the same 710 state-dependent failures can result in validation errors for such 711 program objects. As a development aid, use the command 712 713 void ValidateProgramPipelineEXT(uint pipeline); 714 715 to validate the program pipeline object <pipeline> against the 716 current GL state. Each program pipeline object has a boolean status, 717 VALIDATE_STATUS, that is modified as a result of validation. This 718 status can be queried with GetProgramPipelineivEXT (See section 6.1.8). 719 If validation succeeded, the program pipeline object is guaranteed 720 to execute given the current GL state. 721 722 If <pipeline> is a name that has been generated (without subsequent 723 deletion) by GenProgramPipelinesEXT, but refers to a program pipeline 724 object that has not been previously bound, the GL first creates a 725 new state vector in the same manner as when BindProgramPipelineEXT 726 creates a new program pipeline object. If <pipeline> is not a name 727 returned from a previous call to GenProgramPipelinesEXT or if such a 728 name has since been deleted by DeleteProgramPipelinesEXT, an 729 INVALID_OPERATION error is generated. 730 731Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) 732 733 -- Section 3.8 "Fragment Shaders" (p. 86) 734 735 Replace the last paragraph with: 736 737 "When the program object currently in use for the fragment stage 738 includes a fragment shader, its fragment shader is considered active and 739 is used to process fragments. If the current fragment stage program 740 object has no fragment shader or no program object is current for the 741 fragment stage, the results of fragment shader execution are undefined." 742 743Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment 744Operations and the Frame Buffer) 745 746 None 747 748Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special Functions) 749 750 None 751 752Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State 753Requests) 754 755 -- Section 6.1.8 "Shader and Program Queries" 756 757 Add to GetProgramiv description: 758 759 "If <pname> is PROGRAM_SEPARABLE_EXT, TRUE is returned if the program has 760 been flagged for use as a separable program object that can be bound 761 to individual shader stages with UseProgramStagesEXT." 762 763 Add after GetProgramiv description: 764 765 "The command 766 767 boolean IsProgramPipelineEXT(uint pipeline); 768 769 returns TRUE if <pipeline> is the name of a program pipeline object. 770 If <pipeline> is zero, or a non-zero value that is not the name of a 771 program pipeline object, IsProgramPipelineEXT returns FALSE. No error 772 is generated if <pipeline> is not a valid program pipeline object 773 name. 774 775 The command 776 777 GetProgramPipelineivEXT(uint pipeline, enum pname, int *params); 778 779 returns properties of the program pipeline object named <pipeline> 780 in <params>. The parameter value to return is specified by <pname>. 781 782 If <pipeline> is a name that has been generated (without subsequent 783 deletion) by GenProgramPipelinesEXT, but refers to a program pipeline 784 object that has not been previously bound, the GL first creates a 785 new state vector in the same manner as when BindProgramPipelineEXT 786 creates a new program pipeline object. If <pipeline> is not a name 787 returned from a previous call to GenProgramPipelinesEXT or if such a 788 name has since been deleted by DeleteProgramPipelinesEXT, an 789 INVALID_OPERATION error is generated. 790 791 If <pname> is ACTIVE_PROGRAM_EXT, the name of the active program 792 object of the program pipeline object is returned. 793 794 If <pname> is VERTEX_SHADER, the name of the current program 795 object for the vertex shader type of the program pipeline object is 796 returned. 797 798 If <pname> is FRAGMENT_SHADER, the name of the current program 799 object for the fragment shader type of the program pipeline object 800 is returned. 801 802 If <pname> is VALIDATE_STATUS, the validation status of the 803 program pipeline object, as determined by ValidateProgramPipelineEXT 804 (see section 2.10.5) is returned. 805 806 If <pname> is INFO_LOG_LENGTH, the length of the info log, 807 including a null terminator, is returned. If there is no info log, 808 zero is returned." 809 810 Change paragraph describing GetShaderInfoLog and GetProgram: 811 812 "A string that contains information about the last compilation 813 attempt on a shader object, last link or validation attempt on a 814 program object, or last validation attempt on a program pipeline 815 object, called the info log, can be obtained with the commands 816 817 void GetShaderInfoLog(uint shader, sizei bufSize, 818 sizei *length, char *infoLog); 819 void GetProgramInfoLog(uint program, sizei bufSize, 820 sizei *length, char *infoLog); 821 void GetProgramPipelineInfoLogEXT(uint pipeline, sizei bufSize, 822 sizei *length, char *infoLog); 823 824 These commands return the info log string in <infoLog>. This string 825 will be null-terminated. The actual number of characters written 826 into <infoLog>, excluding the null terminator, is returned in 827 <length>. If <length> is NULL, then no length is returned. The 828 maximum number of characters that may be written into <infoLog>, 829 including the null terminator, is specified by <bufSize>. The number 830 of characters in the info log can be queried with GetShaderiv, 831 GetProgramiv, or GetProgramPipelineivEXT with INFO_LOG_LENGTH. If 832 <shader> is a shader object, the returned info log will either be an 833 empty string or it will contain information about the last compil- 834 ation attempt for that object. If <program> is a program object, the 835 returned info log will either be an empty string or it will contain 836 information about the last link attempt or last validation attempt 837 for that object. If <pipeline> is a program pipeline object, the 838 returned info log will either be an empty string or it will contain 839 information about the last validation attempt for that object. 840 841Additions to Appendix D of the OpenGL ES 2.0 Specification (Shared Objects and 842Multiple Contexts) 843 844 (add sentence to third paragraph, p. 164) Program pipeline objects are not 845 shared. 846 847Additions to the OpenGL ES Shading Language Specification, Version 1.0.17 848 849 Including the following line in a shader can be used to control 850 the language feature described in thie extension: 851 852 #extension GL_EXT_separate_shader_objects : <behavior> 853 854 where <behavior> is as described in section 3.3. 855 856 A new preprocessor #define is added to the OpenGL ES Shading Language: 857 858 #define GL_EXT_separate_shader_objects 1 859 860 -- Section 4.3.3 "Attribute" (page 30): 861 862 Add new section 4.3.3.1 "Attribute Layout Qualifiers" 863 864 "Vertex shaders allow location layout qualifiers on attribute variable 865 declarations. The location layout qualifier identifier for vertex shader 866 attributes is: 867 868 layout-qualifier-id 869 location = integer-constant 870 871 Only one argument is accepted. For example, 872 873 layout(location = 3) attribute vec4 normal; 874 875 establishes that the vertex shader attribute <normal> is copied in from 876 vector location number 3. 877 878 If an input variable with no location assigned in the shader text has a 879 location specified through the OpenGL ES API, the API-assigned location will 880 be used. Otherwise, such variables will be assigned a location by the 881 linker. See section 2.10.4 of the OpenGL Specification for more details. 882 A link error will occur if an attribute variable is declared in multiple 883 vertex shaders with conflicting locations. 884 885 886 -- Section 4.3.5 "Varying" (page 31): 887 888 Add to the end of the section: 889 890 "When an interface between shader stages is formed using shaders from two 891 separate program objects, it is not possible to detect mismatches between 892 vertex shader varying outputs and fragment shader varying inputs when the 893 programs are linked. When there are mismatches between inputs and outputs 894 on such interfaces, the values passed across the interface will be 895 partially or completely undefined. Shaders can ensure matches across such 896 interfaces either by using varying layout qualifiers (Section 4.3.5.1) or 897 by using identical varying declarations. Complete rules for interface 898 matching are found in the "Shader Interface Matching" portion of section 899 2.10.PPO of the OpenGL Specification." 900 901 Add new section 4.3.5.1 "Varying Layout Qualifiers" 902 903 "All shaders allow location layout qualifiers on varying variable 904 declarations. The location layout qualifier identifier for varyings is: 905 906 layout-qualifier-id 907 location = integer-constant 908 909 Only one argument is accepted. For example, 910 layout(location = 3) varying vec4 normal; 911 912 establishes that the shader varying <normal> is assigned to vector 913 location number 3. 914 915 If the declared varying is an array of size <n> and each element takes up 916 <m> locations, it will be assigned <m>*<n> consecutive locations starting 917 with the location specified. For example, 918 919 layout(location = 6) varying vec4 colors[3]; 920 921 will establish that the input <colors> is assigned to vector 922 location numbers 6, 7, and 8. 923 924 If the declared varying is an <n>x<m> matrix, it will be assigned multiple 925 locations starting with the location specified. The number of locations 926 assigned for each matrix will be the same as for an <n>-element array of 927 <m>-component vectors. For example, 928 929 layout(location = 9) varying mat4 transforms[2]; 930 931 will establish that varying <transforms> is assigned to vector location 932 numbers 9-16, with transforms[0] being assigned to locations 9-12 and 933 transforms[1] being assigned to locations 13-16. 934 935 The number of varying locations available to a shader is limited to the 936 implementation-dependent advertised maximum varying vector count. 937 A program will fail to link if any attached shader uses a location greater 938 than or equal to the number of supported locations, unless 939 device-dependent optimizations are able to make the program fit within 940 available hardware resources. 941 942 A program will fail to link if any two varying variables are assigned to 943 the same location, or if explicit location assignments leave the linker 944 unable to find space for other variables without explicit assignments." 945 946Dependencies on OpenGL ES 3.0 947 948 If OpenGL ES 3.0 isn't present, references to 949 ProgramUniform{1234}ui[v] should be ignored. Also, any redundant 950 language about explicit shader variable locations set within the 951 shader text should also be ignored. 952 953 If neither OpenGL ES 3.0 nor NV_non_square_matrices is present, 954 references to ProgramUniformMatrix{2x3,3x2,2x4,4x2,3x4,4x3}fv 955 should be ignored. 956 957 The behavior of mixing GLSL ES 1.00 shaders with GLSL ES 3.00 shaders 958 in the same rendering pipeline is undefined. 959 960 If the GL is OpenGL ES 3.0, make the following changes: 961 962 Replace this sentence from the first paragraph of section 2.10.PPO Shader 963 Interface Matching: 964 965 "These inputs and outputs must typically match in name, type, and 966 qualification." 967 968 with the following language: 969 970 "An output variable is considered to match an input variable in the 971 subequent shader if: 972 973 * the two variables match in name, type, and qualification; or 974 975 * the two variables are declared with the same location layout 976 qualifier and match in type and qualification." 977 978 Add this paragraph after the first paragraph of section 2.10.PPO: 979 980 "Variables declared as structures are considered to match in type if and 981 only if structure members match in name, type, qualification, and 982 declaration order. Variables declared as arrays are considered to match 983 in type only if both declarations specify the same element type and array 984 size. The rules for determining if variables match in qualification are 985 found in the OpenGL Shading Language Specification." 986 987 Replace the last paragraph from section 2.10.PPO: 988 989 "Built-in inputs or outputs do not affect interface matching. Any such 990 built-in inputs are well-defined unless they are derived from built-in 991 outputs not written by the previous shader stage." 992 993 with the following new language: 994 995 "When using GLSL ES 1.00 shaders, built-in inputs or outputs do not affect 996 interface matching. Any such built-in inputs are well-defined unless they 997 are derived from built-in outputs not written by the previous shader stage. 998 999 When using GLSL ES 3.00 shaders in separable programs, gl_Position and 1000 gl_PointSize built-in outputs must be redeclared according to Section 7.5 1001 of the OpenGL Shading Language Specification. Other built-in inputs or 1002 outputs do not affect interface matching. Any such built-in inputs are 1003 well-defined unless they are derived from built-in outputs not written by 1004 the previous shader stage." 1005 1006 and add to GLSL ES 3.00 new section 7.5, Built-In Redeclaration and 1007 Separable Programs: 1008 1009 "The following vertex shader outputs may be redeclared at global scope to 1010 specify a built-in output interface, with or without special qualifiers: 1011 1012 gl_Position 1013 gl_PointSize 1014 1015 When compiling shaders using either of the above variables, both such 1016 variables must be redeclared prior to use. ((Note: This restriction 1017 applies only to shaders using version 300 that enable the 1018 EXT_separate_shader_objects extension; shaders not enabling the 1019 extension do not have this requirement.)) A separable program object 1020 will fail to link if any attached shader uses one of the above variables 1021 without redeclaration." 1022 1023Dependencies on NV_non_square_matrices 1024 1025 If NV_non_square_matrices is supported, 1026 ProgramUniformMatrix{2x3,3x2,2x4,4x2,3x4,4x3}fvEXT is supported in 1027 OpenGL ES 2.0. 1028 1029Errors 1030 1031 UseProgramStagesEXT generates INVALID_OPERATION if the program 1032 parameter has not been successfully linked. 1033 1034 UseProgramStagesEXT generates INVALID_VALUE if <stages> has a bit 1035 set for any other than VERTEX_SHADER_BIT_EXT or 1036 FRAGMENT_SHADER_BIT_EXT, unless <stages> is ALL_SHADER_BITS_EXT. 1037 1038 ActiveShaderProgramEXT generates INVALID_OPERATION if <program> 1039 has not been successfully linked. 1040 1041 DrawArrays and DrawElements generate INVALID_OPERATION when a program 1042 object with multiple attached shaders is active for one or more, but not 1043 all of the shader program types corresponding to the shaders that are 1044 attached. 1045 1046New State 1047 1048 Add to table 6.15 (Program Object State): 1049 1050 Initial 1051 Get Value Type Get Command Value Description Sec 1052 ------------------ ---- ----------------------- ------- ------------------------ ------ 1053 PROGRAM_PIPELINE_- Z+ GetIntegerv 0 Current program pipeline 2.10.PPO 1054 BINDING_EXT object binding 1055 1056 Add new table 6.PPO (Program Pipeline Object State): 1057 1058 Initial 1059 Get Value Type Get Command Value Description Sec 1060 ------------------ ---- ---------------------------- ------- ------------------------ ------ 1061 ACTIVE_PROGRAM_EXT Z+ GetProgramPipelineivEXT 0 The program object 2.10.PPO 1062 that Uniform* commands 1063 update when PPO bound 1064 VERTEX_SHADER Z+ GetProgramPipelineivEXT 0 Name of current vertex 2.10.PPO 1065 shader program object 1066 FRAGMENT_SHADER Z+ GetProgramPipelineivEXT 0 Name of current fragment 2.10.PPO 1067 shader program object 1068 VALIDATE_STATUS B GetProgramPipelineivEXT FALSE Validate status of 2.10.PPO 1069 program pipeline object 1070 S GetProgramPipelineInfoLogEXT empty Info log for program 6.1.8 1071 pipeline object 1072 INFO_LOG_LENGTH Z+ GetProgramPipelineivEXT 0 Length of info log 6.1.8 1073 1074New Implementation Dependent State 1075 1076 None 1077 1078Issues 1079 1080 See ARB_separate_shader_objects extension specification for issues 1081 documented while working on the original desktop OpenGL extension. 1082 1083Revision History 1084 1085 Rev. Date Author Changes 1086 ---- ---------- --------- --------------------------------------------- 1087 1 2011-06-17 Benj Initial revision for ES based on 1088 ARB_separate_shader_objects extension. 1089 1090 2 2011-07-22 Benj Rename APPLE to EXT, specify that PPOs are 1091 not shareable. 1092 1093 3 2011-07-26 Benj Add VALIDATE_STATUS to state tables and 1094 GetProgramPipelineivEXT description, remove 1095 the language erroneously deleting 1096 CURRENT_PROGRAM. 1097 1098 4 2013-03-07 Jon Leech Added note about the unrelated OpenGL 1099 extension of the same name. 1100 1101 5 2013-03-25 Benj Add interactions with OpenGL ES 3.0. 1102 6 2013-09-20 dkoch Add interactions with NV_non_square_matrices. 1103 7 2013-11-08 marka Clarify ProgramUniform*ui availability. 1104