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 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 : where 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 . ... 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 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 is copied in from vector location numbers 6, 7, and 8. If the named vertex shader input is an x 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 -element array of -component vectors. For example, layout(location = 9) in mat4 transforms[2]; will establish that input 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 is specified, must also be specified. If is not specified, the default value 0 is used. For example, layout(location = 3) out vec4 color; will establish that the fragment shader output 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 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 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. 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 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 to . 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.