xref: /third_party/openGLES/extensions/NV/NV_draw_instanced.txt

Name

    NV_draw_instanced

Name Strings

    GL_NV_draw_instanced

Contributors
    Contributors to ARB_draw_instanced and EXT_gpu_shader4
    Mathias Heyer, NVIDIA
    Greg Roth, NVIDIA

Contact

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

Status

    Complete

Version

    Last Modified Date:  Aug 28, 2012
    Author Revision: 3

Number

    OpenGL ES Extension #141

Dependencies

    OpenGL ES 2.0 is required.

    The extension is written against the OpenGL ES 2.0.25 Specification.

    Written based on the wording of The OpenGL ES Shading Language
    1.00.14 Specification.

    OES_element_index_uint affects the definition of this extension.

Overview

    A common use case in GL for some applications is to be able to
    draw the same object, or groups of similar objects that share
    vertex data, primitive count and type, multiple times.  This
    extension provides a means of accelerating such use cases while
    limiting the number of required API calls, and keeping the amount
    of duplicate data to a minimum.

    This extension introduces two draw calls which are conceptually
    equivalent to a series of draw calls.  Each conceptual call in
    this series is considered an "instance" of the actual draw call.

    This extension also introduces a read-only built-in variable to
    GLSL which contains the "instance ID."  This variable initially
    contains 0, but increases by one after each conceptual draw call.

    By using the instance ID or multiples thereof as an index into
    a uniform array containing transform data, vertex shaders can
    draw multiple instances of an object with a single draw call.

New Procedures and Functions

    void DrawArraysInstancedNV(enum mode, int first, sizei count,
            sizei primcount);
    void DrawElementsInstancedNV(enum mode, sizei count, enum type,
            const void *indices, sizei primcount);

New Tokens

    None

Additions to Chapter 2 of the OpenGL ES 2.0.25 Specification
(OpenGL ES Operation)

    Modify section 2.8 (Vertex Arrays)

    (Insert before the final paragraph)

    The internal counter <instanceID> is a 32-bit integer value which
    may be read by a vertex shader as <gl_InstanceIDNV>, as
    described in section 2.10.5.2.  The value of this counter is
    always zero, except as noted below.

    The command

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

    behaves identically to DrawArrays except that <primcount>
    instances of the range of elements are executed and the value of
    <instanceID> advances for each iteration.  It has the same effect
    as:

        if (mode, count, or primcount is invalid)
            generate appropriate error
        else {
            for (i = 0; i < primcount; i++) {
                instanceID = i;
                DrawArrays(mode, first, count);
            }
            instanceID = 0;
        }

    The command

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

    behaves identically to DrawElements except that <primcount>
    instances of the set of elements are executed, and the value of
    <instanceID> advances for each iteration.  It has the same effect
    as:

        if (mode, count, primcount, or type is invalid )
            generate appropriate error
        else {
            for (int i = 0; i < primcount; i++) {
                instanceID = i;
                DrawElements(mode, count, type, indices);
            }
            instanceID = 0;
        }

    Add a new section 2.10.5.2 "Shader Inputs" after "Texture Access" in
    Section 2.10.5 "Shader Execution".

    Besides having access to vertex attributes and uniform variables,
    vertex shaders can access the read-only built-in variable
    gl_InstanceIDNV. The variable gl_InstanceIDNV holds the integer
    index of the current primitive in an instanced draw call.  See also
    section 7.1 of the OpenGL ES Shading Language Specification.


Modifications to The OpenGL ES Shading Language Specification, Version
1.00.14

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

      #extension GL_NV_draw_instanced : <behavior>

    where <behavior> is as specified in section 3.4.

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

      #define GL_NV_draw_instanced 1

    Change Section 7.1 "Vertex Shader Special Variables"

    Add the following paragraph after the description of gl_PointSize:

    The variable gl_InstanceIDNV is available as a read-only variable
    from within vertex shaders and holds the integer index of the
    current primitive in an instanced draw call (DrawArraysInstancedNV,
    DrawElementsInstancedNV). If the current primitive does not come
    from an instanced draw call, the value of gl_InstanceIDNV is zero.

    Add the following definitions to the list of built-in variable definitions:

          int gl_InstanceIDNV; // read-only


Dependencies on OES_element_index_uint

    If OES_element_index_uint is not supported, removed all references
    to UNSIGNED_INT indices and the associated GL data type uint in
    the description of DrawElementsInstancedNV.

Errors

    INVALID_ENUM is generated by DrawElementsInstancedNV if <type> is
    not one of UNSIGNED_BYTE, UNSIGNED_SHORT or UNSIGNED_INT.

    INVALID_VALUE is generated by DrawArraysInstancedNV if <first>,
    <count>, or <primcount> is less than zero.

    INVALID_ENUM is generated by DrawArraysInstancedNV or
    DrawElementsInstancedNV if <mode> is not one of the modes described in
    section 2.6.1.

    INVALID_VALUE is generated by DrawElementsInstancedNV if <count> or
    <primcount> is less than zero.

Issues

    1) Should this exist as a separate extension from NV_instanced_arrays?

    Resolved: Yes. Even though these extensions expose similar
    functionality and together they represent a more cohesive extension
    with slightly less tricky text in the process, keeping them separate
    makes the relationship with the desktop extensions clear.

Revision History

    Rev.    Date        Author      Changes
    ----  ------------- ---------   ----------------------------------------
     3    28 Aug 2012    groth      Minor copy edits and corrections to spec references
     2    19 Aug 2012    groth      Correct illustrative code samples
     1    12 Aug 2012    groth      Initial GLES2 version from ARB_draw_instanced and EXT_gpu_shader4