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