| Name |
| |
| ARB_explicit_attrib_location |
| |
| Name Strings |
| |
| GL_ARB_explicit_attrib_location |
| |
| Contact |
| |
| Ian Romanick, Intel (ian.d.romanick 'at' intel.com) |
| |
| Notice |
| |
| Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at |
| http://www.khronos.org/registry/speccopyright.html |
| |
| Status |
| |
| Complete. Approved by the ARB at the 2010/01/22 F2F meeting. |
| Approved by the Khronos Board of Promoters on March 10, 2010. |
| |
| Version |
| |
| Last Modified Date: August 1, 2011 |
| Revision: 12 |
| |
| Number |
| |
| ARB Extension #79 |
| |
| Dependencies |
| |
| Requires OpenGL 2.0 or GL_ARB_vertex_shader. |
| |
| This extension interacts with GL_ARB_blend_func_extended. |
| |
| This extension is written against the OpenGL 3.2 (Core Profile) |
| specification dated 7/24/2009 and the OpenGL Shading Language 1.50.09 |
| specification dated 7/24/2009. |
| |
| This extension interacts with GL_ARB_separate_shader_objects, |
| GL_ARB_gpu_shader_fp64, OpenGL 4.0, and OpenGL 4.1. |
| |
| Overview |
| |
| This extension provides a method to pre-assign attribute locations to |
| named vertex shader inputs and color numbers to named fragment shader |
| outputs. This allows applications to globally assign a particular |
| semantic meaning, such as diffuse color or vertex normal, to a particular |
| attribute location without knowing how that attribute will be named in any |
| particular shader. |
| |
| IP Status |
| |
| No known IP claims. |
| |
| New Procedures and Functions |
| |
| None |
| |
| New Tokens |
| |
| None |
| |
| Additions to Chapter 2 of the OpenGL 3.2 Specification (OpenGL Operation) |
| |
| Section 2.11.3 "Vertex Attributes": |
| |
| Modify the seventh paragraph on page 53 to read: |
| |
| "When a program is linked, any active attributes without a binding |
| specified either through BindAttribLocation or explicitly set |
| within the shader text will be automatically be bound to vertex |
| attributes by the GL. ... LinkProgram will fail if the attribute |
| bindings assigned by BindAttribLocation do not leave not enough space |
| to assign a location for an active matrix attribute or an active |
| attribute array, both of which require multiple contiguous generic |
| attributes. If an active attribute has a binding explicitly set within |
| the shader text and a different binding assigned by BindAttribLocation, |
| the assignment in the shader text is used." |
| |
| Additions to Chapter 3 of the OpenGL 3.2 Specification (Rasterization) |
| |
| Section 3.9.2 "Shader Execution", subsection "Shader Outputs": |
| |
| Replace the fourth paragraph of page 183: |
| |
| When a program is linked, any varying out variables without a binding |
| specified through BindFragDataLocationIndexed, BindFragDataLocation, or |
| explicitly set within the shader text will automatically be bound to |
| fragment colors and indices by the GL. All such assignments will use |
| color indices of zero. Such bindings can be queried using the commands |
| GetFragDataLocation and GetFragDataIndex. If a varying out variable has a |
| binding explicitly set within the shader text and a different binding |
| assigned by BindFragDataLocationIndexed or BindFragDataLocation, the |
| assignment in the shader text is used. Output binding assignments will |
| cause LinkProgram to fail: |
| |
| * if the number of active outputs is greater than the value of |
| MAX_DRAW_BUFFERS; |
| |
| * if the program has an active output assigned to a location greater |
| than or equal to the value of MAX_DUAL_SOURCE_DRAW_BUFFERS and has an |
| active output assigned an index greater than or equal to one; |
| |
| * if more than one varying out variable is bound to the same number and |
| index; or |
| |
| * if the explicit binding assigments do not leave enough space for the |
| linker to automatically assign a location for a varying out array, |
| which requires multiple contiguous locations. |
| |
| |
| Additions to Chapter 4 of the OpenGL 3.2 Specification (Per-Fragment |
| Operations and the Framebuffer) |
| |
| None. |
| |
| Additions to Chapter 5 of the OpenGL 3.2 Specification (Special Functions) |
| |
| None. |
| |
| Additions to Chapter 6 of the OpenGL 3.2 Specification (State and State |
| Request) |
| |
| None. |
| |
| Additions to Appendix A of the OpenGL 3.2 Specification (Invariance) |
| |
| None. |
| |
| Additions to Appendix B of the OpenGL 3.2 Specification (Corollaries) |
| |
| None. |
| |
| Additions to Appendix C of the OpenGL 3.2 Specification (Compressed Texture |
| Image Formats) |
| |
| None. |
| |
| Additions to Appendix D of the OpenGL 3.2 Specification (Shared Objects and |
| Multiple Contexts) |
| |
| None. |
| |
| Additions to Appendix E of the OpenGL 3.2 Specification (The Deprecation |
| Model) |
| |
| None. |
| |
| Additions to the AGL/GLX/WGL Specifications |
| |
| None. |
| |
| Dependencies on ARB_blend_func_extended |
| |
| If ARB_blend_func_extended is not supported, remove <index> from the |
| layout-qualifier-id list for fragment shader outputs. Remove all language |
| regarding "Nth input to the blend equation," and remove the "factor" |
| example. Additionally, remove references to BindFragDataLocationIndexed |
| and GetFragDataIndex in the API spec language. |
| |
| Dependencies on ARB_separate_shader_objects, ARB_gpu_shader_fp64, OpenGL 4.0, |
| and OpenGL 4.1 |
| |
| If ARB_separate_shader_objects (or OpenGL 4.1) is supported, the layout |
| location qualifier introduced by this extension is extended to apply to |
| inputs for non-vertex shaders and outputs for non-fragment shaders. If |
| ARB_gpu_shader_fp64 (or OpenGL 4.0) is supported, such inputs and outputs |
| can have double-precision component types. |
| |
| When these extensions are supported, there are special rules for the |
| number of locations consumed by "dvec3" and "dvec4" types, which require |
| more storage than is available in a four-component single-precision |
| vector. The rules are: |
| |
| * dvec3/dvec4 vertex inputs consume one location (generic vertex |
| attribute), but can count as two vectors for the purposes of |
| determining if the vertex shader consumes too many inputs |
| |
| * dvec3/dvec4 inputs and outputs for other stages consume two locations |
| |
| The relevant spec edits (modifying language introduced here) can be found |
| in the ARB_separate_shader_objects extension. |
| |
| GLX protocol |
| |
| None. |
| |
| Errors |
| |
| None, see issue #1. |
| |
| New State |
| |
| None. |
| |
| New Implementation Dependent State |
| |
| None. |
| |
| |
| Modifications to The OpenGL Shading Language Specification, Version 1.50.09 |
| |
| Including the following line in a shader can be used to control |
| the language feature described in thie extension: |
| |
| #extension GL_ARB_explicit_attrib_location : <behavior> |
| |
| where <behavior> is as described in section 3.3. |
| |
| A new preprocessor #define is added to the OpenGL Shading Language: |
| |
| #define GL_ARB_explicit_attrib_location 1 |
| |
| Modify the second paragraph of section 4.3.4 "Inputs", p. 30 to read: |
| |
| ... The values copied in are established by the OpenGL API or through the |
| use of the of the layout identifier <location>. ... |
| |
| Replace the first paragraph of section 4.3.8.1 "Input Layout Qualifiers" |
| with: |
| |
| Vertex shaders allow input layout qualifiers on input variable |
| declarations. The layout qualifier identifier for vertex shader inputs |
| is: |
| |
| layout-qualifier-id |
| location = integer-constant |
| |
| Only one argument is accepted. For example, |
| |
| layout(location = 3) in vec4 normal; |
| |
| will establish that the vertex shader input <normal> is copied in from |
| vector location number 3. |
| |
| If the named vertex shader input has a scalar or vector type, it will |
| consume a single location. |
| |
| If the named vertex shader input is an array, it will be assigned |
| consecutive locations starting with the location specified. For example, |
| |
| layout(location = 6) in vec4 colors[3]; |
| |
| will establish that the vertex shader input <colors> is copied in from |
| vector location numbers 6, 7, and 8. |
| |
| If the named vertex shader input is an <n>x<m> matrix, it will be assigned |
| multiple locations starting with the location specified. The number of |
| locations assigned for each matrix will be the same as for an <n>-element |
| array of <m>-component vectors. For example, |
| |
| layout(location = 9) in mat4 transforms[2]; |
| |
| will establish that input <transforms> is assigned to vector location |
| numbers 9-16, with transforms[0] being assigned to locations 9-12 and |
| transforms[1] being assigned to locations 13-16. |
| |
| If an input variable with no location assigned in the shader text has a |
| location specified through the OpenGL API, the API-assigned location will |
| be used. Otherwise, such variables will be assigned a location by the |
| linker. See section 2.11.3 of the OpenGL Specification for more details. |
| A link error will occur if an input variable is declared in multiple |
| vertex shaders with conflicting locations. |
| |
| Replace the first paragraph of section 4.3.8.2 "Output Layout Qualifiers" |
| with: |
| |
| Vertex shaders cannot have output layout qualifiers. |
| |
| Add the following text after the second paragraph on page 39: |
| |
| Fragment shaders allow output layout qualifiers on output variable |
| declarations. The layout qualifier identifier for fragment shader |
| outputs is: |
| |
| layout-qualifier-id |
| location = integer-constant |
| index = integer-constant |
| |
| Each of these qualifiers may appear at most once. If <index> is specified, |
| <location> must also be specified. If <index> is not specified, the |
| default value 0 is used. For example, |
| |
| layout(location = 3) out vec4 color; |
| |
| will establish that the fragment shader output <color> is copied out to |
| fragment color 3 as the first (index zero) input to the blend equation. |
| And, |
| |
| layout(location = 3, index = 1) out vec4 factor; |
| |
| will establish that the fragment shader output <factor> is copied out to |
| fragment color 3 as the second (index one) input to the blend equation. |
| |
| If the named fragment shader output is an array, it will be assigned |
| consecutive locations starting with the location specified. For example, |
| |
| layout(location = 2) out vec4 colors[3]; |
| |
| will establish that the fragment shader output <colors> is copied in from |
| vector location numbers 2, 3, and 4. |
| |
| If an output variable with no location or index assigned in the shader |
| text has a location specified through the OpenGL API, the API-assigned |
| location will be used. Otherwise, such variables will be assigned a |
| location by the linker. All such assignments will have a color index of |
| zero. See section 3.9.2 of the OpenGL Specification for more details. A |
| link error will occur if an input variable is declared in multiple vertex |
| shaders with conflicting location or index values. |
| |
| |
| Issues |
| |
| 1. How should the error be reported when the attribute location |
| specified in the shader source is larger than MAX_VERTEX_ATTRIBUTES? |
| |
| RESOLVED. Generate a link error. The existing spec language already |
| covers this case: |
| |
| "LinkProgram will fail if the assigned binding of an active attribute |
| variable would cause the GL to reference a non-existent generic |
| attribute (one greater than or equal to MAX_VERTEX_ATTRIBS)." |
| |
| 2. What happens when the shader text binds an input to a |
| particular attribute location and the same attribute location is |
| bound to a different attribute via the API? |
| |
| RESOLVED. The setting in the shader is always used. |
| |
| 3. Should layout-qualifier-id be index or location? |
| |
| RESOLVED. location. The API uses both. <index> is used as the |
| parameter name to VertexAttribPointer and BindAttribLocation, but |
| "location" is used in the name of BindAttribLocation and |
| GetAttribLocation. However, there is some expectation that <index> may |
| be used for another purpose later. |
| |
| 4. The GL spec allows BindAttribLocation to be called before attaching |
| shaders or linking. If an application does this and specifies a |
| layout, which takes precedence? |
| |
| RESOLVED. The setting the shader is always used. |
| |
| The three options that were considered: |
| |
| a. The setting from the API, if specified, always wins. |
| |
| b. The setting from the shader, if specified, always wins. |
| |
| c. The setting is order dependent. If the shader is |
| attached after the API setting is made, the shader |
| layout is used. If the API setting is made after the |
| shader is attached, the API setting is used. |
| |
| 5. What happens if an input or output variable is declared in two |
| shader objects with conflicting attribute locations? |
| |
| RESOLVED. A link error will occur. |
| |
| 6. What happens if an input or output variable is declared in two |
| shader objects with an attribute location assigned in one shader but |
| not the other. |
| |
| RESOLVED. The link will succeed and use the explicit assignment from |
| the first shader, as long as there are no other conflicting |
| assignments. |
| |
| |
| Revision History |
| |
| (v12, 2011-08-01, Pat Brown) |
| Add GLSL spec language explicitly specifying the number of vertex |
| shader input locations consumed by basic scalar/vector types and by |
| basic matrix types (bug 7809). Also add interactions with |
| ARB_separate_shader_objects and ARB_gpu_shader_fp64, which extend the |
| location mechanism introduced here. |
| |
| (v11, 2010-01-14, Pat Brown) |
| Resolve the behavior of conflicting attribute assignments via shader |
| text and API calls, with shader text prevailing (bug 5803). Resolve |
| the behavior of conflicting assignments within two separate shader |
| objects (link error). Add spec language allowing for a link error if |
| explicit attribute assignments don't leave enough space for array |
| inputs or outputs (bug 5809). Clarify that any automatic assignments |
| for fragment outputs will use color index zero (bug 5809, interaction |
| with ARB_blend_func_extended). Fix GLSL language to clarify that |
| layout qualifiers for attribute assignments are on individual |
| declarations, and not on the interface qualifiers "in" or "out". |
| |
| (v10, 2009-12-11, Jon Leech) |
| Remove ARB suffixes for integration into 3.3 core spec. |
| |
| (v9, 2009-10-29, Ian Romanick) |
| Resolved issue #4. |
| Changed the resolution of issue #2 to match the resolution to |
| #4. |
| |
| (v8, 2009-10-26, Ian Romanick) |
| Added interactions with ARB_blend_func_extended. |
| |
| (v7, 2009-10-23, Ian Romanick) |
| Reworded overview to include mention of fragment shader outputs. |
| Explicitly state the behavior of specifying a layout for an array. |
| Resolved issue #1 - link error. |
| Resolved issue #3 - changed the use of <index> to <location>. |
| Added issue #4. |
| |
| (v6, 2009-10-22, Ian Romanick) |
| Added ability to specify fragment shader output bindings. |
| |
| Changed layout syntax from "layout(index(n))" to "layout(index = |
| n)". This eliminated the need to modify the shading language |
| grammar. This matches the max_vertices layout qualifier used by |
| geometry shaders. |
| |
| (v5, 2009-10-22, Ian Romanick) |
| Re-worded spec based on OpenGL 3.2 and GLSL 1.50. |
| |
| (v4, 2009-10-22, Ian Romanick) |
| Convert MESA to ARB. Added issue #3. |
| |
| (v3, 2009-02-17, Ian Romanick) |
| After reading the manual page for glBindAttribLocation, added a |
| resolution for issue #2. |
| |
| (v2, 2009-02-11, Ian Romanick) |
| Modified to use the layout keyword from uniform blocks instead |
| of the unusual array-subscript syntax previously proposed. |
| Updated issue #1. |
| |
| (v1, 2009-01-23, Ian Romanick) |
| Initial version. |