blob: fd9ec800e6d9f832130de422cdcedd6994105f99 [file] [log] [blame]
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
Specification Update Policy
Khronos-approved extension specifications are updated in response to
issues and bugs prioritized by the Khronos OpenGL Working Group. For
extensions which have been promoted to a core Specification, fixes will
first appear in the latest version of that core Specification, and will
eventually be backported to the extension document. This policy is
described in more detail at
https://www.khronos.org/registry/OpenGL/docs/update_policy.php
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.