xref: /third_party/openGLES/extensions/EXT/EXT_base_instance.txt

Name

    EXT_base_instance

Name Strings

    GL_EXT_base_instance

Contact

    Daniel Koch, NVIDIA (dkoch 'at' nvidia.com)

Contributors

    Dominik Witczak, Mobica
    Jonas Gustavsson, Sony Mobile
    Slawomir Grajewski, Intel
    Contributors to ARB_base_instance

Notice

    Copyright (c) 2011-2014 The Khronos Group Inc. Copyright terms at
        http://www.khronos.org/registry/speccopyright.html

    Portions Copyright (c) 2014 NVIDIA Corporation.

Status

    Complete

Version

    Last Modified Date:         October 24, 2014
    Author Revision:            4

Number

    OpenGL ES Extension #203

Dependencies

    This specification is written against the OpenGL ES 3.1 (June 4, 2014)
    Specification, although it can apply to previous versions.

    OpenGL ES 3.0 is required.

    EXT_draw_elements_base_vertex is required.

    This extension interacts with EXT_multi_draw_indirect.

Overview

    This extension allows the offset within buffer objects used for instanced
    rendering to be specified. This is congruent with the <first> parameter
    in glDrawArrays and the <basevertex> parameter in glDrawElements. When
    instanced rendering is performed (for example, through
    glDrawArraysInstanced), instanced vertex attributes whose vertex attribute
    divisors are non-zero are fetched from enabled vertex arrays per-instance
    rather than per-vertex. However, in unextended OpenGL ES, there is no way
    to define the offset into those arrays from which the attributes are
    fetched. This extension adds that offset in the form of a <baseinstance>
    parameter to several new procedures.

    The <baseinstance> parameter is added to the index of the array element,
    after division by the vertex attribute divisor. This allows several sets of
    instanced vertex attribute data to be stored in a single vertex array, and
    the base offset of that data to be specified for each draw. Further, this
    extension exposes the <baseinstance> parameter as the final and previously
    undefined structure member of the draw-indirect data structure.

IP Status

    None.

New Procedures and Functions

    void DrawArraysInstancedBaseInstanceEXT(enum mode,
                                            int first,
                                            sizei count,
                                            sizei instancecount,
                                            uint baseinstance);

    void DrawElementsInstancedBaseInstanceEXT(enum mode,
                                              sizei count,
                                              enum type,
                                              const void *indices,
                                              sizei instancecount,
                                              uint baseinstance);

    void DrawElementsInstancedBaseVertexBaseInstanceEXT(enum mode,
                                                        sizei count,
                                                        enum type,
                                                        const void *indices,
                                                        sizei instancecount,
                                                        int basevertex,
                                                        uint baseinstance);

New Tokens

    None.

Modifications to Chapter 10 of the OpenGL ES 3.1 Specification (Vertex
Specification and Drawing Commands)

    Modification to Section 10.5, "Drawing Commands using Vertex Arrays"

    (Modify the definition of DrawArraysOneInstance, to define the
    behaviour of the <baseinstance> parameter. Modify the 3rd paragraph
    of the definition of the command, p.247, as follows)

    "If an enabled vertex attribute array is instanced (it has a non-zero
    <divisor> as specified by VertexAttribDivisor), the element index that
    is transferred to the GL, for all vertices, is given by

        floor(<instance> / <divisor>) + <baseinstance>"


    (Replace the description of DrawArraysInstanced, p.248, with the
    following)

    "The command

        void DrawArraysInstancedBaseInstanceEXT(enum mode,
                                                int first,
                                                sizei count,
                                                sizei instancecount,
                                                uint baseinstance);

    behaves identically to DrawArrays, except that <instancecount> instances of
    the range of elements are executed and the value of <instance> advances for
    each iteration. Those attributes that have non-zero values for <divisor>,
    as specified by VertexAttribDivisor, advance once every <divisor>
    instances. Additionally, the first element within those instanced vertex
    attributes is specified in <baseinstance>.

    DrawArraysInstancedBaseInstanceEXT is equivalent to

        if (<mode>, <count>, or <instancecount> is invalid)
            generate  appropriate  error
        else {
            for  (i = 0; i < <instancecount>; i++) {
                DrawArraysOneInstance(<mode>, <first>, <count>, i,
                                      <baseinstance>);
            }
        }

    The command

        void DrawArraysInstanced(enum mode,
                                 int first,
                                 sizei count,
                                 sizei primcount);

    is equivalent to

        DrawArraysInstancedBaseInstanceEXT(<mode>, <first>, <count>,
                                           <instancecount>, 0);"



    (Update the definition of DrawArraysIndirect on p.248 as follows)

    "The command

        void  DrawArraysIndirect(enum mode, const void *indirect);

    is equivalent to

        typedef  struct {
            uint  count;
            uint  instanceCount;
            uint  first;
            uint  baseInstance;
        } DrawArraysIndirectCommand;

        DrawArraysIndirectCommand  *cmd  =
            (DrawArraysIndirectCommand *)indirect;

        DrawArraysInstancedBaseInstanceEXT(mode,
                                           cmd->first,
                                           cmd->count,
                                           cmd->instanceCount,
                                           cmd->baseInstance);"

    (Retain the remainder the description of DrawArraysIndirect, but
    delete the sentence "Results are undefined if <reservedMustBeZero> is
    non-zero, but may not result in program termination." from the Errors
    section.)


    (Modify the definition of DrawElementsOneInstance, to define the
    behaviour of the <baseinstance> parameter. Modify the 3rd paragraph
    of the definition of the command, p.249, as follows)

    "If an enabled vertex attribute array is instanced (it has a non-zero
    attribute divisor as specified by VertexAttribDivisor), the element that
    is transferred to the GL is given by:

        floor(<instance> / <divisor>) + <baseinstance>"


    (Update the text describing DrawElements, p.250, to mention the
    <baseinstance> parameter)

    "The command

        void DrawElements(enum mode,
                          sizei count,
                          enum type,
                          const void *indices);

    behaves identically to DrawElementsOneInstance with the <instance> and
    <baseinstance> parameters set to zero; the effect of calling ..."


    (Replace the description of DrawElementsInstanced, p.251, with the
    following)

    "The command

        void DrawElementsInstancedBaseInstanceEXT(enum mode,
                                                  sizei count,
                                                  enum type,
                                                  const void *indices,
                                                  sizei instancecount,
                                                  uint baseinstance);

    behaves identically to DrawElements except that <instancecount> instances
    of the set of elements are executed, the value of <instance> advances
    between each set. Instanced attributes are advanced as they do during
    execution of DrawArraysInstancedBaseInstaceEXT, and <baseinstance> has
    the same effect. It is equivalent to:

        if  (<mode>, <count>, <type> or <instancecount> is invalid)
            generate  appropriate  error
        else {
            for (int i = 0; i < <instancecount>;  i++) {
                DrawElementsOneInstance(<mode>, <count>, <type>, <indices>,
                                        i, <baseinstance>);
            }
        }

    The command

        void DrawElementsInstanced(enum mode, sizei count, enum type,
                                   const void *indices, sizei instancecount);

    behaves identically to DrawElementsInstancedBaseInstanceEXT except that
    <baseinstance> is zero. It is equivalent to

        DrawElementsInstancedBaseInstanceEXT(<mode>, <count>, <type>,
                                             <indices>, <instancecount>, 0);"


    (Add to the list of functions which include DrawElementsBaseVertexEXT,
    DrawRangeElementsBaseVertexEXT, and DrawElementsInstancedBaseVertexEXT
    (as added by EXT_draw_elements_base_vertex))

        void DrawElementsInstancedBaseVertexBaseInstanceEXT(enum mode,
                                                        sizei count,
                                                        enum type,
                                                        const void *indices,
                                                        sizei instancecount,
                                                        int basevertex,
                                                        uint baseinstance);

    (Append a new paragraph after the description of DrawElementsBaseVertexEXT,
    DrawRangeElementsBaseVertexEXT, and DrawElementsInstancedBaseVertexEXT
    (as added by EXT_draw_elements_base_vertex))

    "For DrawElementsInstancedBaseVertexBaseInstanceEXT, <baseinstance> is
    used to offset the element from which instanced vertex attributes (those
    with a non-zero divisor as specified by VertexAttribDivisor) are taken."


    (Update the definition of DrawElementsIndirect on p.252 as follows)

    "The command

        void  DrawElementsIndirect(enum mode,
                                   enum type,
                                   const void *indirect );

    is equivalent to:

        typedef  struct {
            uint  count;
            uint  instanceCount;
            uint  firstIndex;
            int   baseVertex;
            uint  baseInstance;
        } DrawElementsIndirectCommand;

        if  (no element array buffer is bound) {
            generate appropriate error
        } else {
            DrawElementsIndirectCommand *cmd =
                (DrawElementsIndirectCommand *)indirect;

            DrawElementsInstancedBaseVertexBaseInstanceEXT(
                                            mode,
                                            cmd->count,
                                            type,
                                            cmd->firstIndex * size-of-type,
                                            cmd->instanceCount,
                                            cmd->baseVertex,
                                            cmd->baseInstance);
        }"

    (Retain the remainder of the description of DrawElementsIndirect, but
    delete the sentence "Results are undefined if <reservedMustBeZero> is
    non-zero, but may not result in program termination." from the Errors
    section.)

Additions to the EGL/AGL/GLX/WGL Specifications

    None.

Dependencies on EXT_multi_draw_indirect.

    If EXT_multi_draw_indirect is supported, this extension adds <baseInstance>
    support for the MultiDraw*Indirect commands as well, because they share
    the same command structures.

Errors

    The errors for DrawArraysInstancedBaseInstanceEXT are equivalent to the
    errors for DrawArraysInstanced, but are repeated here for clarity:

    - An INVALID_ENUM error is generated if <mode> is not one of the primitive
      types defined in section 10.1.
    - Specifying <first> < 0 results in undefined behavior. Generating an
      INVALID_VALUE error is recommended in this case.
    - An INVALID_VALUE error is generated if <count> is negative.

    The errors for DrawElementsInstancedBaseInstanceEXT and
    DrawElementsInstancedBaseVertexBaseInstanceEXT are equivalent to the
    errors for DrawElementsInstanced, but are repeated here for clarity:

    - An INVALID_ENUM error is generated if <mode> is not one of the primitive
      types defined in section 10.1.
    - An INVALID_ENUM error is generated if <type> is not UNSIGNED_BYTE,
      UNSIGNED_SHORT, or UNSIGNED_INT.
    - Using an index value greater than MAX_ELEMENT_INDEX will result in
      undefined implementation-dependent behavior, unless primitive restart is
      enabled (see section 10.3.4) and the index value is 2^32 − 1.

New State

    None.

New Implementation Dependent State

    None.

Conformance Testing

    TBD.

Issues

    Note: These issues apply specifically to the definition of the
    EXT_base_instance specification, which is based on the OpenGL
    extension ARB_base_instance as updated in OpenGL 4.4.
    ARB_base_instance can be found in the OpenGL Registry.

    (1) What functionality was removed from ARB_base_instance?

    Nothing. Although there is less language here because ES 3.1 already
    includes some of the reorganizing that the original extension added.

    (2) What functionality was changed and added relative to
        ARB_base_instance?

      - EXT_base_instance more closely matches the language of OpenGL 4.4
      - the <primCount> parameter was renamed to <instanceCount>

    (3) Do these new draw calls require a vertex array object to be bound?

    RESOLVED: No. The DrawArrays and DrawArraysInstanced commands do not
    require a vertex array object to be bound in ES 3.1 and since these are
    specializations of DrawArraysInstancedBaseInstanceEXT, it also does not
    require one to be bound.  Similarly the DrawElements and
    DrawElementsInstanced commands do not require a vertex array object to be
    bound in ES 3.1, and since these commands are specializations of
    DrawElementsInstancedBaseInstanceEXT and
    DrawElementsInstancedBaseVertexBaseInstanceEXT, these commands also do not
    require one to be bound.

    (4) Do these new draw calls support client memory arrays?

    RESOLVED: Yes. There are no restrictions on using client-side memory for
    the other direct drawing commands in ES 3.1, so these command support
    them as well. As per issue (3), the old commands are specializations of
    the new commands, so we keep a comparable feature set.


Revision History

    Rev.    Date      Author    Changes
    ----  ----------  --------  -----------------------------------------
    4     10/24/2014  dkoch     Mark complete and issues resolved.

    3     06/24/2014  dkoch     Fix typographical issues noted by Dominik.

    2     06/20/2014  dkoch     Add interaction with EXT_multi_draw_indirect.

    1     06/13/2014  dkoch     Initial version for ES based on v6 of
                                ARB_base_instance.