ANGLE_multi_draw.txt

Name

    ANGLE_multi_draw

Name Strings

    GL_ANGLE_multi_draw

Contributors

    Austin Eng, Google Inc.
    Kai Ninomiya, Google Inc.
    Kenneth Russell, Google Inc.
    Contributors to the EXT_multi_draw_arrays specification
    Contributors to the ARB_shader_draw_parameters specification

Contact

    Austin Eng (enga 'at' google.com)

Status

    Incomplete

Version

    Last Modified Date: October 24, 2018
    Author Revision: 1

Number

    OpenGL ES Extension XX

Dependencies

    OpenGL ES 2.0 is required.

    This extension is written against the OpenGL ES 2.0 specification,
    the OpenGL ES 3.0 specification, and the OpenGL ES Shading Language 3.0
    specification.

    The presence of the GL_ANGLE_instanced_arrays or GL_EXT_instanced_arrays 
    extensions affects the definition of this extension.

Overview

    This extension exposes the Multi* draw call variants in
    EXT_multi_draw_arrays functionality in addition to the vertex shader builtin
    gl_DrawID exposed by ARB_shader_draw_parameters for OpenGL.

    These functions behave identically to the standard functions
    DrawArrays() and DrawElements() except they handle multiple lists of
    vertices in one call. Their main purpose is to allow one function call
    to render more than one primitive such as triangle strip, triangle fan,
    etc.

    Additionally, this extension adds a further built-in variable, gl_DrawID
    to the shading language. This variable contains the index of the draw
    currently being processed by a Multi* variant of a drawing command.

IP Status

    No known IP claims.

New Procedures and Functions

    void MultiDrawArraysANGLE(enum mode,
                              const GLint* firsts,
                              const GLsizei* counts,
                              const GLsizei drawcount);

    void MultiDrawElementsANGLE(enum mode,
                                const GLint* counts,
                                GLenum type,
                                const GLvoid* const* indices,
                                const GLsizei drawcount);

    void MultiDrawArraysInstancedANGLE(enum mode,
                                       const GLint* firsts,
                                       const GLsizei* counts,
                                       const GLsizei* instanceCounts,
                                       const GLsizei drawcount);

    void MultiDrawElementsInstancedANGLE(enum mode,
                                         const GLint* counts,
                                         GLenum type,
                                         const GLvoid* const* indices,
                                         const GLsizei* instanceCounts,
                                         const GLsizei drawcount);

New Tokens

    None.

Additions to Chapter 2 of the OpenGL ES 2.0 Specification

    Section 2.8 Vertex Arrays:

    The command

      void MultiDrawArraysANGLE(GLenum mode,
              const GLint* firsts,
              const GLsizei *counts,
              GLsizei drawcount)

    Behaves identically to DrawArrays except that a list of arrays is
    specified instead. The number of lists is specified in the drawcount
    parameter. It has the same effect as:

      for(i=0; i<drawcount; i++) {
        if (*(counts+i)>0) DrawArrays(mode, *(firsts+i), *(counts+i));
      }

    The index of the draw (<i> in the above pseudo-code) may be read by
    a vertex shader as <gl_DrawID>.

    The command

      void MultiDrawElementsANGLE(GLenum mode,
                GLsizei* counts,
                GLenum type,
                const GLvoid* const* indices,
                GLsizei drawcount)

    Behaves identically to DrawElements except that a list of arrays is
    specified instead. The number of lists is specified in the drawcount
    parameter. It has the same effect as:

      for(i=0; i<drawcount; i++) {
          if (*(counts+i)>0) {
              DrawElements(mode, *(counts+i), type, *(indices+i));
          }
      }

    The index of the draw (<i> in the above pseudo-code) may be read by
    a vertex shader as <gl_DrawID>.

Additions to Chapter 2 of the OpenGL ES 3.0 Specification

    Section 2.9.3 Drawing Commands:

    The command

      void MultiDrawArraysInstancedANGLE(
              GLenum mode,
              const GLint* firsts,
              const GLsizei *counts,
              const GLsizei* instanceCounts,
              GLsizei drawcount)

    Behaves identically to DrawArraysInstanced except that a list of arrays is
    specified instead. The number of lists is specified in the drawcount
    parameter. It has the same effect as:

      for(i=0; i<drawcount; i++) {
        if (*(counts+i)>0) DrawArraysInstanced(mode, *(firsts+i), *(counts+i),
              *(instanceCounts+1));
      }

    The index of the draw (<i> in the above pseudo-code) may be read by
    a vertex shader as <gl_DrawID>.

    The command

      void MultiDrawElementsInstancedANGLE(
                GLenum mode,
                GLsizei* counts,
                GLenum type,
                const GLvoid* const* indices,
                const GLsizei* instanceCounts,
                GLsizei drawcount)

    Behaves identically to DrawElementsInstanced except that a list of arrays is
    specified instead. The number of lists is specified in the drawcount
    parameter. It has the same effect as:

      for(i=0; i<drawcount; i++) {
          if (*(counts+i)>0) {
              DrawElementsInstanced(mode, *(counts+i), type,
                                    *(indices+i), *(instanceCounts+1));
          }
      }

    The index of the draw (<i> in the above pseudo-code) may be read by
    a vertex shader as <gl_DrawID>.

Errors

    The error INVALID_VALUE is generated by the new functions if <drawcount>
    is less than 0.

    MultiDrawArraysANGLE, MultiDrawElementsANGLE,
    MultiDrawArraysInstancedANGLE, and MultiDrawElementsInstancedANGLE generate
    the same errors as DrawArrays, DrawElements, DrawArraysInstanced,
    and DrawElementsInstanced, respectively, for any draw <i> where an error
    is generated. If any call would produce an error, no drawing is performed.

Modifications to the OpenGL ES Shading Language Specification, Version 3.00

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

      #extension GL_ANGLE_multi_draw : <behavior>

    where <behavior> is as specified in section 3.5.

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

      #define GL_ANGLE_multi_draw 1

Dependencies on GL_ANGLE_instanced_arrays

    If GL_ANGLE_instanced_arrays or GL_EXT_instanced_arrays is enabled, 
    append the lanuage in "Additions to Chapter 2 of the OpenGL ES 3.0
    Specification, Section 2.9.3 Drawing Commands" to the language in 
    "Additions to Chapter 2 of the OpenGL ES 2.0 Specification, Section 
    2.8 Vertex Arrays".

    If GL_ANGLE_instanced_arrays or GL_EXT_instanced_arrays is not enabled
    and the context is less than a OpenGL ES 3.0 context, the error 
    INVALID_OPERATION is generated by any call to the functions 
    MultiDrawArraysInstancedANGLE and MultiDrawElementsInstancedANGLE.

Issues
    None

Revision History

    Rev.    Date    Author       Changes
    ----  --------  ----------   --------------------------------------------
    1     10/24/18   Austin Eng  First revision.
    2     10/25/18   Austin Eng  Second revision. Add instanced variants