xref: /third_party/openGLES/extensions/ARB/ARB_explicit_attrib_location.txt

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.