1Name 2 3 EXT_shader_io_blocks 4 5Name String 6 7 GL_EXT_shader_io_blocks 8 9Contact 10 11 Jon Leech (oddhack 'at' sonic.net) 12 Daniel Koch, NVIDIA (dkoch 'at' nvidia.com) 13 14Contributors 15 16 Daniel Koch, NVIDIA (dkoch 'at' nvidia.com) 17 Pat Brown, NVIDIA (pbrown 'at' nvidia.com) 18 Slawomir Grajewski, Intel 19 Graham Connor, Imagination 20 Ben Bowman, Imagination 21 Jonathan Putsman, Imagination 22 23Notice 24 25 Copyright (c) 2008-2013 The Khronos Group Inc. Copyright terms at 26 http://www.khronos.org/registry/speccopyright.html 27 28 Portions Copyright (c) 2013-2014 NVIDIA Corporation. 29 30Status 31 32 Complete. 33 34Version 35 36 Last Modified Date: October 8, 2014 37 Revision: 8 38 39Number 40 41 OpenGL ES Extension #180 42 43Dependencies 44 45 OpenGL ES 3.1 and OpenGL ES Shading Language 3.10 are required. 46 47 This specification is written against the OpenGL ES 3.1 (March 17, 48 2014) and OpenGL ES 3.10 Shading Language (March 17, 2014) 49 Specifications. 50 51 OES_shader_multisample_interpolation trivially affects the definition of 52 this extension. 53 54 EXT_geometry_shader interacts with this extension. 55 56 EXT_tessellation_shader interacts with this extension. 57 58Overview 59 60 This extension extends the functionality of interface blocks to 61 support input and output interfaces in the OpenGL ES Shading Language. 62 63 Input and output interface blocks are used for forming the 64 interfaces between vertex, tessellation control, tessellation 65 evaluation, geometry and fragment shaders. This accommodates passing 66 arrays between stages, which otherwise would require multi-dimensional 67 array support for tessellation control outputs and for tessellation 68 control, tessellation evaluation, and geometry shader inputs. 69 70 This extension provides support for application defined 71 interface blocks which are used for passing application-specific 72 information between shader stages. 73 74 This extension moves the built-in "per-vertex" in/out variables 75 to a new built-in gl_PerVertex block. This is necessary for 76 tessellation and geometry shaders which require a separate 77 instance for each vertex, but it can also be useful for vertex 78 shaders. 79 80 Finally, this extension allows the redeclaration of the 81 gl_PerVertex block in order to reduce the set of variables that must 82 be passed between shaders. 83 84New Procedures and Functions 85 86 None 87 88New Tokens 89 90 None 91 92Additions to Chapter 7 of the OpenGL ES 3.1 Specification (Programs and Shaders) 93 94 Modify section 7.4.1 "Shader Interface Matching": 95 96 When multiple shader stages are active, the outputs of one stage form an 97 interface with the inputs of the next stage. At each such interface, 98 shader inputs are matched up against outputs from the previous stage: 99 100 * An output block is considered to match an input block in the 101 subsequent shader if the two blocks have the same block name, and 102 the members of the block match exactly in name, type, qualification, 103 and declaration order. 104 105 * An output variable is considered to match an input variable in the 106 subsequent shader if: 107 108 - the two variables match in name, type, and qualification; or 109 110 - the two variables are declared with the same location layout 111 qualifier and match in type and qualification. 112 113 Variables or block members declared as structures are considered to 114 match in type if and only if structure members match in name, type, 115 qualification, and declaration order. Variables or block members 116 declared as arrays are considered to match in type only if both 117 declarations specify the same element type and array size. The rules for 118 determining if variables or block members match in qualification are 119 found in the OpenGL ES Shading Language Specification. 120 121 For program objects containing multiple shaders, LinkProgram will check 122 for mismatches on interfaces between shader stages in the program being 123 linked and generate a link error if a mismatch is detected. A link error 124 will be generated if any statically referenced input variable or block 125 does not have a matching output. 126 127 With separable program objects ... 128 129 At an interface between program objects, the set of inputs and outputs 130 are considered to match exactly if and only if: 131 132 * Every declared input block or variable has a matching output, 133 as described above. 134 135 * There are no output blocks or user-defined output variables declared 136 without a matching input block or variable declaration. 137 138 * All matched input and output variables (in a block or otherwise) have 139 identical precision qualification. 140 141 When the set of inputs and outputs ... 142 143 [allow but not require 144 redeclaration] 145 When using any built-in input or output in the gl_PerVertex block in 146 separable program objects, shader code may redeclare that block prior 147 to use. If the shader does not redeclare the block, the intrinsically 148 declared definition of that block will be used. 149 150 A separable program will fail to link if: 151 152 * the shader uses a built-in block member not found in the 153 (re)declaration of that block. 154 155 There is one exception to this rule described below. 156 157 As described above, an exact interface match requires matching built-in 158 input and output blocks. At an interface between two non-fragment shader 159 stages, the gl_PerVertex input and output blocks are considered to match 160 if and only if the block members match exactly in name, type, 161 qualification, and declaration order. At an interface involving the 162 fragment shader stage, the presence or absence of any built-in output 163 [Relax per Issue 9] 164 does not affect interface matching. At an interface involving the 165 vertex shader stage, built-in outputs not found in a block in the 166 vertex shader are considered to match the corresponding inputs found 167 in the gl_PerVertex input block of the subsequent non-fragment stage, 168 provided they match in precision qualification. 169 170 Built-in inputs or outputs not found in blocks do not affect interface 171 matching. Any such built-in inputs are well-defined unless they are 172 derived from built-in outputs not written by the previous shader stage. 173 174New State 175 176 None 177 178New Implementation Dependent State 179 180 None 181 182Additions to the OpenGL ES Shading Language 3.10 Specification 183 184 Including the following line in a shader can be used to control the 185 language features described in this extension: 186 187 #extension GL_EXT_shader_io_blocks : <behavior> 188 189 where <behavior> is as specified in section 3.4. 190 191 A new preprocessor #define is added to the OpenGL ES Shading Language: 192 193 #define GL_EXT_shader_io_blocks 1 194 195 If the EXT_geometry_shader extension is enabled, the 196 EXT_shader_io_blocks extension is also implicitly enabled. 197 198 If the EXT_tessellation_shader extension is enabled, the 199 EXT_shader_io_blocks extension is also implicitly enabled. 200 201 202 Modify section 3.8 "Identifiers:" 203 204 Replace the second paragraph with the following: 205 206 Identifiers starting with "gl_" are reserved for use by OpenGL ES, and 207 may not be declared in a shader as either a variable or a function; this 208 results in a compile-time error. However, as noted in the specification, 209 there are some cases where previously declared variables can be redeclared, 210 and predeclared "gl_" names are allowed to be redeclared in a shader only 211 for these specific purposes. More generally, it is a compile-time error to 212 redeclare a variable, including those starting "gl_". 213 214 215 Modify section 4.3.4 "Input Variables": 216 217 Add following the first paragraph on p. 39: 218 219 ... superfluous declarations of input variables. 220 221 Only the input variables that are statically read need to be written by 222 the previous stage; it is allowed to have superfluous declarations of 223 input variables. This is shown in the following table. 224 225[?? clarify this is for internal interfaces only] 226 ----------------------------------------------------------------------------------- 227 | | Consuming Shader (input variables) | 228 | Treatment of Mismatched +---------------------------------------------------+ 229 | Input Variables | No | Declared but | Declared and | 230 | | Declaration | no Static Use | Static Use | 231 +-----------------------------+-------------+---------------+---------------------| 232 | | No Declaration | Allowed | Allowed | Link-Time Error | 233 | Generating |----------------+-------------+---------------+---------------------| 234 | Shader | Declared but | Allowed | Allowed | Allowed (values | 235 | (output | no Static Use | | | are undefined) | 236 | variables) |----------------+-------------+---------------+---------------------| 237 | | Declared and | | | Allowed (values are | 238 | | Static Use | Allowed | Allowed | potentially undef.) | 239 | | | | | | 240 ----------------------------------------------------------------------------------- 241 242 Consumption errors are based on static use only. Compilation may 243 generate a warning, but not an error, for any dynamic use the compiler 244 can deduce that might cause consumption of undefined values. 245 246 See section 7 "Built-in Variables" ... 247 248 249 (Modify the first paragraph, starting "The output of the vertex shader", 250 on p. 41): 251 252 The fragment shader inputs form an interface with the last active shader 253 in the vertex processing pipeline. For this interface, the last active 254 shader stage output variables and fragment shader input variables of the 255 same name must match in type and qualification, with a few exceptions... 256 257 258 (Modify the third paragraph on p. 41): 259 260 Shaders can ensure matches across such interfaces either by using input 261 and output layout qualifiers (sections 4.4.1 "Input Layout Qualifiers" 262 and 4.4.2 "Output Layout Qualifiers") or by using identical input and 263 output declarations of blocks or variables. Complete rules for interface 264 matching are found ... 265 266 267 Modify section 4.3.9 "Interface Blocks": 268 269 Input, output, uniform, and buffer variable declarations can be grouped 270 into named interface blocks to provide coarser granularity backing than 271 is achievable with individual declarations. They can have an optional 272 instance name, used in the shader to reference their members. An output 273 block of one programmable stage is backed by a corresponding input block 274 in the subsequent programmable stage. A uniform block is backed by the 275 application with a buffer object. A block of buffer variables, called a 276 shader storage block, is also backed by the application with a buffer 277 object. It is a compile-time error to have an input block in a vertex 278 shader or an output block in a fragment shader; these uses are reserved 279 for future use. 280 281 An interface block is started by an "in", "out", "uniform", or "buffer" 282 keyword, followed by a block name, followed by an open curly brace ( { ) 283 as follows: 284 285 (modify the grammar rules after the third paragraph) 286 287 interface-block: 288 layout-qualifier_opt interface-storage-qualifier block-name 289 { member-list } instance-name_opt ; 290 291 interface-storage-qualifier: 292 in 293 out 294 uniform 295 buffer 296 297 ... 298 299 Each of the above elements ... 300 301 ... with four uniforms grouped inside it. 302 303 Types and declarators are the same as for other input, output, uniform, 304 and buffer variable declarations outside blocks, with these exceptions: 305 306 * opaque types are not allowed 307 * structure definitions cannot be nested inside a block 308 309 Any of these would result in a compile-time error. Otherwise, built-in 310 types, previously declared structures, and arrays of these are allowed 311 as the type of a declarator in the same manner they are allowed outside 312 a block. 313 314 If no optional qualifier is used in a member-declaration, the 315 qualification of the variable is just in, out, uniform, or buffer as 316 determined by interface-storage-qualifier. If optional qualifiers are 317 used, they can include interpolation qualifiers and storage qualifiers, 318 and they must declare an input, output, or uniform variable consistent 319 with the interface qualifier of the block: input, output, uniform, and 320 buffer variables can only be declared in in, out, uniform, and shader 321 storage blocks, respectively. 322 323 Repeating the "in", "out", "uniform", or "buffer" interface qualifier 324 for a member's storage qualifier is optional. "centroid in" and "sample 325 in" variables are consistent with "in" blocks, and "centroid out" and 326 "sample out" variables are consistent with "out" blocks. 327 328 A <shader interface> is defined to be one of these: 329 330 * All the uniform variables of a program. This spans all compilation 331 units linked together within one program. 332 * All the buffer blocks declared in a program. 333 * The boundary between adjacent programmable pipeline stages: This 334 spans all the outputs declared in all compilation units of the 335 first stage and all the inputs declared in all compilation units 336 of the second stage. Note that the fragment shader is considered 337 to have a shared boundary with the previous adjacent stage even 338 though in practice, all values passed from prior stages to the 339 fragment shader first pass through the rasterizer and 340 interpolator. 341 342 The block name (block-name) is used to match interfaces: an output block 343 of one pipeline stage will be matched to an input block with the same 344 name in the subsequent pipeline stage. For uniform or shader storage 345 blocks, the application uses the block name to identify the block. Block 346 names have no other use within a shader beyond interface matching; it is 347 a compile-time error to use a block name at global scope for anything 348 other than as a block name (e.g., use of a block name for a global 349 variable name or function name is currently reserved). It is a 350 compile-time error to use the same block name for more than one block 351 declaration in the same shader interface (as defined above) within one 352 shader, even if the block contents are identical. 353 354 Matched block names within a shader interface (as defined above) must 355 match in terms of having the same number of declarations with the same 356 sequence of types, precisions, and the same sequence of member names, as 357 well as having the same member-wise layout qualification (see next 358 section). Matched uniform block names (but not input or output block 359 names) must also either all be lacking an instance name or all having an 360 instance name, putting their members at the same scoping level. When 361 instance names are present on matched block names, it is allowed for the 362 instance names to differ; they need not match for the blocks to match. 363 Furthermore, if a matching block is declared as an array, then the array 364 sizes must also match (or follow array matching rules for the interface 365 between a vertex and a geometry shader). Any mismatch will generate a 366 link-time error. A block name is allowed to have different definitions 367 in different interfaces within the same shader, allowing, for example, 368 an input block and output block to have the same name. 369 370 If an instance name (instance-name) is not used, the names declared 371 inside the block are scoped at the global level and accessed as if they 372 were declared outside the block. If an instance name is used, then it 373 puts all the members inside a scope within its own name space, accessed 374 with the field selector ( . ) operator (analogously to structures). For 375 example, 376 377 uniform Transform_1 378 { 379 mat4 modelview; // API will use "modelview" 380 } 381 uniform Transform_2 382 { 383 mat4 projection; // API will use "Transform_2.projection" 384 } transform_2; // instance name 385 mat4 projection; // different than transform_2.projection 386 mat4 modelview; // illegal, already defined 387 388 Outside the shading language (i.e., in the API), members are similarly 389 identified except the block name is always used in place of the instance 390 name (API accesses are to interfaces, not to shaders). If there is no 391 instance name, then the API does not use the block name to access a 392 member, just the member name. 393 394 Within an interface, all declarations of the same global name must be 395 for the same object and must match in type and in whether they declare a 396 variable or member of a block with no instance name. The API also needs 397 this name to uniquely identify an object in the interface. It is a 398 link-time error if any particular interface contains 399 400 * two different blocks, each having no instance name, and each 401 having a member of the same name, or 402 * a variable outside a block, and a block with no instance name, 403 where the variable has the same name as a member in the block. 404 405 out Vertex { 406 vec4 Position; // API transform/feedback will use "Vertex.Position" 407 vec2 Texture; 408 } Coords; // shader will use "Coords.Position" 409 out Vertex2 { 410 vec4 Color; // API will use "Color" 411 float Color2; 412 }; 413 // in same program as Vertex2 above: 414 out Vertex3 { 415 float Intensity; 416 vec4 Color; // ERROR, name collision with Color in Vertex2 417 }; 418 float Color2; // ERROR, collides with Color2 in Vertex2 419 420 For blocks declared as arrays, the array index must also be included 421 when accessing members, as in this example 422 423 uniform Transform { // API uses "Transform[2]" to refer to instance 2 424 mat4 ModelViewMatrix; 425 mat4 ModelViewProjectionMatrix; 426 float Deformation; 427 } transforms[4]; 428 ... 429 ... = transforms[2].ModelViewMatrix; // shader access of instance 2 430 // API uses "Transform.ModelViewMatrix" to query an offset or other query 431 432 For uniform or shader storage blocks declared as an array, each 433 individual array element corresponds to a separate buffer object, 434 backing one instance of the block. As the array size indicates the 435 number of buffer objects needed, uniform and shader storage block array 436 declarations must specify an array size. All indices used to index a 437 uniform or shader storage block array must be constant integral 438 expressions. 439 440 When using OpenGL ES API entry points to identify the name of an 441 individual block in an array of blocks, the name string must include an 442 array index (e.g., Transform[2]). When using OpenGL ES API entry points 443 to refer to offsets or other characteristics of a block member, an array 444 index must not be specified (e.g., Transform.ModelViewMatrix). 445 446 There are implementation dependent limits on the number of uniform 447 blocks and the number of shader storage blocks that can be used per 448 stage. If either limit is exceeded, it will cause a link-time error. 449 450 451 Modify section 4.4 "Layout Qualifiers": 452 453 Layout qualifiers can appear in several forms of declaration. They can 454 appear as part of an interface block definition or block member, as 455 shown in the grammar in the previous section. They can also appear with 456 just an interface qualifier (a storage qualifier that is "in", "out", or 457 "uniform") to establish layouts of other declarations made with that 458 interface qualifier: 459 460 layout-qualifier interface-qualifier ; 461 462 ... 463 464 The layout-qualifier expands to 465 466 layout-qualifier : 467 layout ( layout-qualifier-id-list ) 468 469 layout-qualifier-id-list : 470 layout-qualifier-id 471 layout-qualifier-id , layout-qualifier-id-list 472 473 layout-qualifier-id 474 layout-qualifier-name 475 layout-qualifier-name = layout-qualifier-value 476 477 The tokens used for layout-qualifier-name are identifiers, not keywords. 478 Generally, they can be listed in any order. Order-dependent meanings 479 exist only if explicitly called out below. Similarly, these identifiers 480 are not case sensitive, unless explicitly noted otherwise. 481 482 More than one layout qualifier may appear in a single declaration. 483 Additionally, the same layout-qualifier-name can occur multiple times 484 within a layout qualifier or across multiple layout qualifiers in the 485 same declaration. When the same layout-qualifier-name occurs multiple 486 times, in a single declaration, the last occurrence overrides the former 487 occurrence(s). Further, if such a layout-qualifier-name will effect 488 subsequent declarations or other observable behavior, it is only the 489 last occurrence that will have any effect, behaving as if the earlier 490 occurrence(s) within the declaration are not present. This is also true 491 for overriding layout-qualifier-names, where one overrides the other 492 (e.g., row_major vs. column_major); only the last occurrence has any 493 effect. 494 495 [[ The last paragraph of this section in GLSL 4.40 and the really nice 496 table of layout qualifiers from different stages could be inserted 497 at this point, but aren't necessary. ]] 498 499 4.4.1 Input Layout Qualifiers 500 501 Some input layout qualifiers apply to all shader languages and some 502 apply only to specific languages. The latter are discussed in separate 503 sections below. 504 505 All shaders, except compute shaders, allow "location" layout qualifiers 506 on input variable declarations, input block declarations, and input 507 block member declarations. 508 509 The layout qualifier identifier for inputs is: 510 511 layout-qualifier-id 512 location = integer-constant 513 514 Only one argument is accepted. For example, 515 516 layout(location = 3) in vec4 normal; 517 518 will establish that the shader input <normal> is assigned to vector 519 location number 3. For vertex shader inputs, the location specifies the 520 number of the vertex attribute from which input values are taken. For 521 inputs of all other shader types, the location specifies a vector number 522 that can be used to match against outputs from a previous shader stage, 523 even if that shader is in a different program object. 524 525 The following language describes how many locations are consumed by a 526 given type. However, geometry shader inputs, tessellation control shader 527 inputs and outputs, and tessellation evaluation inputs all have an 528 additional level of arrayness relative to other shader inputs and outputs. 529 This outer array level is removed from the type before considering how 530 many locations the type consumes. 531 532 If a shader input is any scalar or vector type, it will consume a single 533 location. 534 535 If the declared input (after potentially removing an outer array level as 536 just described above) is an array of size <n> and each of the elements 537 takes <m> locations, it will be assigned <m> * <n> consecutive locations 538 starting with the location specified. For example, 539 540 layout (location = 6) in vec4 colors[3]; 541 542 will establish that the shader input <colors> is assigned to vector 543 location numbers 6, 7, and 8. 544 545 If the declared input is an <n> x <m> matrix, it will be assigned multiple 546 locations starting with the location specified. The number of locations 547 assigned for each matrix will be the same as for an <n>-element array of 548 <m>-component vectors. For example, 549 550 layout (location = 9) in mat4 transforms[2]; 551 552 will establish that shader input <transforms> is assigned to vector 553 locations 9-16, with <transforms[0]> being assigned to locations 9-12, 554 and <transforms[1]> being assigned to locations 13-16. 555 556 If the declared input is a structure or block, its members will be 557 assigned consecutive locations in their order of declaration, with the 558 first member assigned the location provided in the layout qualifier. For 559 a structure, this process applies to the entire structure. It is a 560 compile-time error to use a location qualifier on a member of a 561 structure. For a block, this process applies to the entire block, or 562 until the first member is reached that has a location layout qualifier. 563 When a block member is declared with a location qualifier, its location 564 comes from that qualifier: The member's location qualifier overrides the 565 block-level declaration. Subsequent members are again assigned 566 consecutive locations, based on the newest location, until the next 567 member declared with a location qualifier. The values used for locations 568 do not have to be declared in increasing order. 569 570 If a block has no block-level location layout qualifier, it is required 571 that either all or none of its members have a location layout qualifier, 572 or a compile-time error results. 573 574 The locations consumed by block and structure members are determined by 575 applying the rules above recursively as though the structure member were 576 declared as an input variable of the same type. For example: 577 578 layout(location = 3) in struct S { 579 vec3 a; // gets location 3 580 mat2 b; // gets locations 4 and 5 581 vec4 c[2]; // gets locations 6 and 7 582 layout (location = 8) vec2 A; // ERROR, can't use on struct member 583 } s; 584 585 layout(location = 4) in block { 586 vec4 d; // gets location 4 587 vec4 e; // gets location 5 588 layout(location = 7) vec4 f; // gets location 7 589 vec4 g; // gets location 8 590 layout (location = 1) vec4 h; // gets location 1 591 vec4 i; // gets location 2 592 vec4 j; // gets location 3 593 vec4 k; // ERROR, location 4 already used 594 }; 595 596 The number of input locations available to a shader is limited. For 597 vertex shaders, the limit is the advertised number of vertex attributes. 598 For all other shaders, the limit is implementation-dependent and must be 599 no less than one fourth of the advertised maximum input component count. 600 A program will fail to link if any attached shader uses a location 601 greater than or equal to the number of supported locations, unless 602 device-dependent optimizations are able to make the program fit within 603 available hardware resources. 604 605 A program will fail to link if explicit location assignments leave the 606 linker unable to find space for other variables without explicit 607 assignments. 608 609 For the purposes of determining if a non-vertex input matches an output 610 from a previous shader stage, the location layout qualifier (if any) 611 must match. 612 613 If a vertex shader input variable with no location assigned in the 614 shader text has a location specified through the OpenGL ES API, the 615 API-assigned location will be used. Otherwise, such variables will 616 be assigned a location by the linker. See section 2.11.5 "Vertex 617 Attributes" of the OpenGL ES 3.1 Graphics System Specification for 618 more details. 619 620 It is an error if more than one input or element of a matrix input is 621 bound to the same location. 622 623 624 Add new subsection 4.4.1.fs: 625 626 4.4.1.fs Fragment Shader Inputs 627 628 Fragment shaders can have an input layout for redeclaring the built-in 629 variable gl_FragCoord: 630 631 in vec4 gl_FragCoord; // redeclaration that changes nothing is allowed 632 633 The built-in gl_FragCoord is only predeclared in fragment shaders, so 634 redeclaring it in any other shader language results in a compile-time 635 error. 636 637 Fragment shaders also allow the following layout qualifier on "in" only 638 (not with variable declarations) 639 640 layout-qualifier-id 641 early_fragment_tests 642 643 to request that fragment tests be performed before fragment shader 644 execution, as described in section 3.9.2 "Early Fragment Tests" of the 645 OpenGL ES Specification. 646 647 For example, specifying 648 649 layout(early_fragment_tests) in; 650 651 will make per-fragment tests be performed before fragment shader 652 execution. In addition, it is an error to statically write to 653 gl_FragDepth in the fragment shader. 654 655 If this is not declared, per-fragment tests will be performed after 656 fragment shader execution. 657 658 4.4.1.1 Compute Shader Inputs ... 659 660 661 Replace section 4.4.2 662 663 4.4.2 Output Layout Qualifiers 664 665 Some output layout qualifiers apply to all shader languages and some 666 apply only to specific languages. The latter are discussed in separate 667 sections below. 668 669 As with input layout qualifiers, all shaders except compute shaders 670 allow location layout qualifiers on output variable declarations, output 671 block declarations, and output block member declarations. 672 673 The layout qualifier identifier for outputs is: 674 675 layout-qualifier-id 676 location = integer-constant 677 678 [remove language for 679 for indexed outputs] 680 The usage and rules for applying the location qualifier to blocks and 681 structures are exactly as described in section 4.4.1 "Input Layout 682 Qualifiers". 683 684 685 This qualifier may appear at most once with a declaration. For example, 686 687 layout(location = 3) out vec4 color; 688 689 will establish that the fragment shader output color is assigned to 690 fragment color 3. 691 692 For fragment shader outputs, the location specifies the color output 693 number receiving the values of the output. For outputs of all other 694 shader stages, the location specifies a vector number that can be used 695 to match against inputs in a subsequent shader stage, even if that 696 shader is in a different program object. 697 698 Declared outputs of scalar or vector type consume a single location. 699 700 If the declared output is an array, it will be assigned consecutive 701 locations starting with the location specified. For example, 702 703 layout(location = 2) out vec4 colors[3]; 704 705 will establish that <colors> is assigned to vector location numbers 2, 706 3, and 4. 707 708 If the declared output is an n x m matrix, it will be assigned multiple 709 locations starting with the location specified. The number of locations 710 assigned will be the same as for an n-element array of m-component 711 vectors. 712 713 If the declared output is a structure, its members will be assigned 714 consecutive locations in the order of declaration, with the first member 715 assigned the location specified for the structure. The number of 716 locations consumed by a structure member is determined by applying the 717 rules above recursively as though the structure member were declared as 718 an output variable of the same type. 719 720 Location layout qualifiers may be used on output variables declared as 721 structures, but it is a compile-time error to use them on individual 722 members. Location layout qualifiers may be used on output blocks and 723 output block members. 724 725 The number of output locations available to a shader is limited. For 726 fragment shaders, the limit is the advertised number of draw buffers. 727 For all other shaders, the limit is implementation-dependent and must be 728 no less than one fourth of the advertised maximum output component 729 count (compute shaders have no outputs.) A program will fail to link if 730 any attached shader uses a location greater than or equal to the number 731 of supported locations, unless device-dependent optimizations are able 732 to make the program fit within available hardware resources. 733 Compile-time errors may also be given if at compile time it is known the 734 link will fail. A negative output location will result in a compile-time 735 error. 736 737 A program will fail to link if any of the following occur: 738 739 * any two fragment shader output variables are assigned to the same 740 location 741 * if any two output variables from the same vertex stage are assigned 742 to the same location. 743 744 For all shader types, a program will fail to link if explicit location 745 assignments leave the linker unable to find space for other variables 746 without explicit assignments. 747 748 If an output variable has no location assigned in the shader text, it 749 will be assigned a location by the linker. See section 3.9.2 "Shader 750 Execution" of the OpenGL ES Specification for more details. 751 752 For the purposes of determining if a non-fragment output matches an 753 input from a subsequent shader stage, the location layout qualifier (if 754 any) must match. 755 756 757 (Add new subsection 4.4.2.fs): 758 759 4.4.2.fs Fragment Outputs 760 761 Fragment shaders can have an output layout for redeclaring the built-in 762 variable gl_FragDepth: 763 764 out float gl_FragDepth; // redeclaration that changes nothing is allowed 765 766 The built-in gl_FragDepth is only predeclared in fragment shaders, so 767 redeclaring it in any other shader language results in a compile-time 768 error. 769 770 771 (Remove subsection 4.5.1 "Linking of Vertex Outputs and Fragment 772 Inputs". Note that the table from this section is moved to section 773 4.3.4, while most of the interface matching language is now dealt with 774 in "Shader Interface Matching" in the OpenGL ES Specification as 775 modified by this extension.) 776 777 778 (Modify the first two paragraphs of section 7.1 "Vertex Shader Special 779 Variables", moving one paragraph up one level to the introduction of 780 chapter 7): 781 782 7 Built-in Variables 783 784 Some OpenGL operations occur in fixed functionality and need to provide 785 values to or receive values from shader executables. Shaders communicate 786 with fixed-function OpenGL pipeline stages, and optionally with other 787 shader executables, through the use of built-in input and output 788 variables. 789 790 7.1 Vertex Shader Special Variables 791 792 In the vertex language, the built-ins are intrinsically declared as 793 follows: 794 795 in highp int gl_VertexID; 796 in highp int gl_InstanceID; 797 798 out gl_PerVertex { 799 highp vec4 gl_Position; 800 highp float gl_PointSize; 801 }; 802 803 The variable gl_Position is intended for writing the homogeneous vertex 804 position. It can be written at any time during shader execution. This 805 value will be used by the following shader stage, or if there are no 806 other shaders prior to the fragment shader, by primitive assembly, 807 clipping, culling, and other fixed functionality operations that operate 808 on primitives after vertex processing has occurred. Its value is 809 undefined after vertex processing if the vertex shader does not write 810 gl_Position. 811 812 The variable gl_PointSize ... 813 814 Add a new section 7.io following section 7.3 "Built-In Uniform State": 815 816 7.io Redeclaring Built-in Blocks 817 818 [allow but not 819 require redecl.] 820 The gl_PerVertex block can be redeclared in a shader to explicitly 821 indicate what subset of the members will be used. This is necessary to 822 establish the interface between multiple programs. If the gl_PerVertex 823 block is not redefined in a given program, the intrinsically declared 824 definition of that block is used for the program interface. 825 826 For example: 827 828 out gl_PerVertex { 829 highp vec4 gl_Position; // will use gl_Position 830 highp float gl_PointSize; // will use gl_PointSize 831 highp vec4 t; // error, only gl_PerVertex members allowed 832 }; // no other members of gl_PerVertex will be used 833 834 This establishes the output interface the shader will use with the 835 subsequent pipeline stage. It must be a subset of the built-in members 836 of gl_PerVertex. Such a redeclaration can also add the invariant 837 qualifier and interpolation qualifiers. 838 839 Other layout qualifiers, like location, cannot be added to such a 840 redeclaration, unless specifically stated. 841 842 If a built-in interface block is redeclared, it must appear in the 843 shader before any use of any member included in the built-in 844 declaration, or a compile-time error will result. It is also a 845 compile-time error to redeclare the block more than once or to redeclare 846 a built-in block and then use a member from that built-in block that was 847 not included in the redeclaration. Also, if a built-in interface block 848 is redeclared, no member of the built-in declaration can be redeclared 849 outside the block redeclaration. If multiple shaders using members of a 850 built-in block belonging to the same interface are linked together in 851 the same program, they must all redeclare the built-in block in the same 852 way, as described in section 4.3.7 "Interface Blocks" for interface 853 block matching, or a link-time error will result. It will also be a 854 link-time error if some shaders in a program redeclare a specific 855 built-in interface block while another shader in that program does not 856 redeclare that interface block yet still uses a member of that interface 857 block. If a built-in block interface is formed across shaders in 858 different programs, the shaders must all redeclare the built-in block in 859 the same way (as described for a single program), or the values passed 860 along the interface are undefined. 861 862Dependencies on OES_shader_multisample_interpolation 863 864 If OES_shader_multisample_interpolation is not supported, references to 865 "sample in", "sample out" and the extension should be ignored. 866 867Dependencies on EXT_geometry_shader 868 869 If EXT_geometry_shader is enabled, this extension is implicitly 870 enabled for geometry shaders. 871 872 If EXT_geometry_shader is not supported, ignore all references to 873 geometry shaders. 874 875Dependencies on EXT_tessellation_shader 876 877 If EXT_tessellation_shader is enabled, this extension is implicitly 878 enabled for tessellation control and evaluation shaders. 879 880 If EXT_tessellation_shader is not supported, ignore all references to 881 tessellation shaders. 882 883Issues 884 885 (1) What functionality was removed from interface blocks relative to 886 GL 4.4? 887 888 - Interactions with features not supported by the underlying 889 ES 3.1 API and Shading Language, including: 890 * gl_ClipDistance shader inputs and outputs. 891 * "component" layout 892 * location aliasing 893 * fragment shader output "index" layout 894 * fragment shader gl_FragDepth layout "depth*" qualifiers 895 * double-precision scalars and vectors 896 * matching across shader stages with different qualifiers (other 897 than precision and "in"/"out"). 898 * References allowing or assuming more than one shader object per 899 pipeline stage. 900 * gl_PerFragment is not added (only exists in compatibility profile). 901 902 (2) What functionality was changed and added relative to interface blocks 903 in GL 4.4? 904 905 - separable shaders are not required to redeclare the gl_PerVertex block. 906 - clarifications on types allowed for vertex and fragment shader inputs 907 from ES 3.0. 908 909 (3) Are any grammar additions required in chapter 9? 910 911 There may be something needed for supporting interface blocks on in/out 912 declarations, but I believe not, since the existing GLSL-ES 3.10 grammar 913 already has these as storage_qualifier tokens. 914 915 (4) Shader Interface Matching rules have been updated to relax precision 916 matching on shader outputs and inputs, as previously required in ES 917 3.0. This was changed during 3.1 development but is now proposed to 918 return to 3.0 behavior, matching this extension. 919 920 RESOLVED. Per Bug 11189, when using a program that contains both sides 921 of an interface, the precision qualifier on inputs/outputs does not need 922 to match. However for two separable programs, the precision qualifiers 923 on inputs/outputs are required to match on the external interfaces. 924 Failing to do so results in a validation error. 925 926 (5) In section 4.3.7 "Interface Matching", the corresponding part of 927 desktop GLSL 4.40 (pp. 49-50) has some material that's very 928 different than GLSL-ES language. Still need to review its 929 applicability here. 930 931 UNRESOLVED. This should be addressed by rebasing on the ES 3.1 specs. 932 933 (6) Should we allow re-declaring the gl_PerVertex block? 934 935 DISCUSSION: If we do, we need to update Section 3.8 with language from 936 Section 3.7 in the GLSL 4.4 spec about redeclaring 'gl_' variables. 937 If we don't, applications will always pay the space for gl_PointSize, 938 and would never be able to have 'invariant' or different interpolation 939 or precision qualifiers on vertex, tessellation, or geometry shader 940 built-in outputs. This seems undesirable. 941 942 RESOLVED: Yes. Section 3.8 updated. 943 944 (7) What is the behavior of LinkProgram with respect to gl_PerVertex 945 blocks? 946 947 DISCUSSION: 948 a) When using monolithic programs, gl_PerVertex does not need to be 949 redeclared in any shader stage. 950 951 b) When using separable programs with only OpenGL ES 3.1-level 952 functionality (vertex and fragment only), gl_PerVertex does not need to 953 be redeclared. In fact, gl_PerVertex can't be redeclared, since no 954 language mechanism exists in unextended ES 3.1 to do so. Adding such a 955 requirement merely due to the presence of this extension would break 956 valid OpenGL ES 3.1-level applications. The lack of a redeclaration 957 requirement in OpenGL ES 3.1 is a difference relative to OpenGL 4.1, 958 but the reasons why we added this requirement in OpenGL 4.1 (many 959 shader stages, a larger set of built-ins, and the desire to be able to 960 treat gl_PerVertex members like other "regular" varyings) don't exist 961 in unextended ES 3.1. 962 963 c) When using separable programs, any shader with the ability to redeclare 964 gl_PerVertex could require redeclaration when any of its members are 965 used. This would be mostly compatible with OpenGL 4.1, which requires 966 all stages to redeclare and provides the ability to do so in all 967 stages. However, since the intrinsically declared gl_PerVertex blocks 968 are actually fairly small in ES, redeclaring gl_PerVertex is optional 969 in ES. The basic rules here are: 970 971 - gl_PerVertex exists iff EXT_shader_io_blocks is enabled. 972 - EXT_shader_io_blocks is always enabled if EXT_geometry_shader 973 or EXT_tesselation_shader is enabled. 974 - EXT_shader_io_blocks can be optionally enabled for VS and FS. 975 976 (8) What happens when you use the following together in a program 977 pipeline? 978 - a separable vertex-only program A which doesn't enable 979 EXT_shader_io_blocks, and 980 - a separable program B containing a tessellation or geometry shader 981 982 DISCUSSION: This was not an issue in OpenGL because separable shaders 983 were added (in GL 4.1) after geometry shaders and input blocks were 984 added (in GL 3.2), so any separable program with a vertex shader could 985 redeclare gl_PerVertex. There are basically 3 options: 986 987 a) Driver has to make any combination of VS outputs in A and redeclared 988 input gl_PerVertex block in B work correctly. 989 b) Lack of redeclaring gl_PerVertex in A implies interface mismatch with 990 redeclared gl_PerVertex in B. Per the standard rules, if there is no 991 complete interface match, all inputs are undefined except for 992 individual variables that match by location, just as with user- 993 defined variables. Built-ins can't be assigned numeric locations, so 994 would be considered not to match. 995 c) It is an error. The vertex shader must be modified to support 996 being used in combination with geometry and tessellation shaders. 997 998 RESOLVED: (a) There will only be one or at most two (if 999 EXT_geometry_point_size is enabled) outputs from the vertex shader 1000 that would need to be matched up with the gl_PerVertex block in the 1001 next shader. It doesn't seem onerous to just make it work, and it is 1002 desirable to be able to just drop a geometry shader into an otherwise 1003 valid ES 3.1 application without modifying the vertex shader. 1004 1005 (9) Why are there so many edits to section 4.4.1 and 4.4.2 and what 1006 really changed? 1007 1008 Some of this is due to restructuring to create subsections specific to 1009 different shader stages, some appears to be correct (but potentially 1010 redundant) language from GLSL 4.40, and some is useful block-related 1011 language. 1012 1013 (10) One of the new matching requirements for ES 3.1 is that 1014 interpolation qualifies don't need to match. Is that true for block 1015 members as well, or just loose variables? 1016 1017 RESOLVED. This is true for block members as well. 1018 In general, we'll allow the same rules for matching variables and 1019 block members. Then a block matches iff the block members match. 1020 1021[?? still need to apply/verify edits for this]. 1022 1023Revision History 1024 1025 Rev. Date Author Changes 1026 ---- -------- --------- --------------------------------------------------- 1027 1 12/19/13 dkoch Extracted functionality from EXT_geometry_shader v9 1028 2 01/16/14 dkoch Fix a couple typos. Removed contraditory sentence. 1029 3 02/12/14 dkoch Resolve issues 5, 8, and 9 and supporting edits. 1030 Incorporate clarifications from Bug 11362. 1031 4 02/27/14 dkoch Add issue 11. Edits for this still pending. 1032 5 03/09/14 Jon Leech Rebase on OpenGL ES 3.1 and change suffix to EXT. 1033 6 03/26/14 dkoch Update contributors. 1034 7 03/28/14 Jon Leech Sync with released ES 3.1 specs. Reflow text. 1035 8 08/10/14 jhf Removed contradictory language forbidding 1036 location layout qualifiers on output blocks 1037 or output block members (Bug 12831)