NV_explicit_attrib_location

GL_NV_explicit_attrib_location

Contributors to ARB_explicit_attrib_location
Mathias Heyer, NVIDIA

Greg Roth, NVIDIA (groth 'at' nvidia.com)

Shipping on Tegra

Last Modified Date:         September 20, 2013
Revision:                   2

OpenGL ES Extension #159

Requires OpenGL ES 2.0.

Written based on the wording of the OpenGL ES 2.0.25 Full Specification
(November 2, 2010).

Written based on the wording of The OpenGL ES Shading Language 1.0.17
Specification (May 12, 2009).    

This extension provides a method to pre-assign attribute locations
to named vertex shader inputs.  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.

None

None

Section 2.10.4 "Shader Variables", subsection "Vertex Attributes"

Modify the first paragraph to read:

"Vertex shaders can define named attribute variables, which are
bound to the generic vertex attributes that are set by
VertexAttrib*. This binding can be specified by the application
before the program is linked, either through BindAttribLocation
(described below) or explicitly within the shader text, or
automatically assigned by the GL when the program is linked."

Modify the third paragraph describing BindAttribLocation 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 automatically be bound to vertex attributes by
the GL. Such bindings can be queried using the command
GetAttribLocation. LinkProgram will fail if the assigned binding of
an active attribute variable would cause the GL to reference a
nonexistent generic attribute (one greater than or equal to the
value of MAX_VERTEX_ATTRIBS). LinkProgram will fail if the attribute
bindings specified either through BindAttribLocation or explicitly
set within the shader text do not leave enough space to assign a
location for an active matrix attribute, which requires 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."

Including the following line in a shader can be used to control
the language feature described in this extension:

  #extension GL_NV_explicit_attrib_location : <behavior>

where <behavior> is as described in section 3.4.

A new preprocessor #define is added to the OpenGL ES Shading Language:

  #define GL_NV_explicit_attrib_location 1

Add new section 4.3.3.1 "Attribute Layout Qualifiers"

"Vertex shaders allow location layout qualifiers on attribute
variable declarations. They can appear with an individual variable
declared with an attribute qualifier:

    <layout-qualifier> attribute <declaration>;

Layouts qualified declarations can only be made at global scope,
and only on attribute variable declarations.

<layout-qualifier> expands to:

    layout-qualifier :
        layout (<layout-qualifier-id>)

    <layout-qualifier-id> :
        location = <integer-constant>

Only one argument is accepted.  For example,

  layout(location = 3) attribute vec4 normal;

will establish that the vertex shader attribute <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 attribute is a matrix, it will be
assigned multiple locations starting with the location specified.
The number of locations assigned for each matrix will be equal to
the number of columns in the matrix  For example,

    layout(location = 9) attribute mat4 transform;

will establish that input <transform> is assigned to vector location
numbers 9-12.

If an attribute variable with no location assigned in the shader
text has a location specified through the OpenGL ES API, the API-
assigned location will be used.  Otherwise, such variables will be
assigned a location by the linker.  See section 2.10.4 of the OpenGL
ES Specification for more details.

None, see issue #1.

None.

None.

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.  Not relevant to ES.

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. Not relevant to ES.

Rev.    Date        Author       Changes
----   ----------   ---------    ------------------------------------
 2     09/20/2013   dkoch        minor edits for publishing
 1     04/25/2012   groth        First revision based on
                                 ARB_explicit_attrib_location.