WebGL
Khronos
 

WebGL WEBGL_multi_draw_instanced_base_vertex_base_instance Extension Draft Specification

Name

WEBGL_multi_draw_instanced_base_vertex_base_instance

Contact

WebGL working group (public_webgl 'at' khronos.org)

Contributors

Contributors to the ANGLE_base_vertex_base_instance specification

Contributors to the WEBGL_multi_draw specification

Members of the WebGL working group

Version

Last modified date: May 26, 2021
Revision: 7

Number

WebGL extension #47

Dependencies

Written against the WebGL API 2.0 specification.

Implementations must also support the WEBGL_multi_draw extension.

Implementations must also support the WEBGL_draw_instanced_base_vertex_base_instance extension.

Overview

This extension exposes the MultiDrawArraysInstancedBaseInstanceANGLE and MultiDrawElementsInstancedBaseVertexBaseInstanceANGLE entrypoints as multiDrawArraysInstancedBaseInstanceWEBGL and multiDrawElementsInstancedBaseVertexBaseInstanceWEBGL. The implementation must validate the arrays and indices referenced by multiDrawArraysInstancedBaseInstanceWEBGL and multiDrawElementsInstancedBaseVertexBaseInstanceWEBGL, similarly to how indices referenced by drawArrays and drawElements are validated according to section Enabled Vertex Attributes and Range Checking and Range Checking of the WebGL specification.

The baseVertex functionality could effectly help reduce CPU overhead with static batching and text rendering in game engine implementations.

The baseInstance functionality could make instanced arrays more useful as they could start instancing from a particular point in the buffer.

The multi draw functionality could help reduce draw call overhead by allowing better batching.

When this extension is enabled:

IDL

[Exposed=(Window,Worker), LegacyNoInterfaceObject]
interface WEBGL_multi_draw_instanced_base_vertex_base_instance {
  undefined multiDrawArraysInstancedBaseInstanceWEBGL(
      GLenum mode,
      ([AllowShared] Int32Array or sequence<GLint>) firstsList, GLuint firstsOffset,
      ([AllowShared] Int32Array or sequence<GLsizei>) countsList, GLuint countsOffset,
      ([AllowShared] Int32Array or sequence<GLsizei>) instanceCountsList, GLuint instanceCountsOffset,
      ([AllowShared] Uint32Array or sequence<GLuint>) baseInstancesList, GLuint baseInstancesOffset,
      GLsizei drawCount
  );
  undefined multiDrawElementsInstancedBaseVertexBaseInstanceWEBGL(
      GLenum mode,
      ([AllowShared] Int32Array or sequence<GLsizei>) countsList, GLuint countsOffset,
      GLenum type,
      ([AllowShared] Int32Array or sequence<GLsizei>) offsetsList, GLuint offsetsOffset,
      ([AllowShared] Int32Array or sequence<GLsizei>) instanceCountsList, GLuint instanceCountsOffset,
      ([AllowShared] Int32Array or sequence<GLint>) baseVerticesList, GLuint baseVerticesOffset,
      ([AllowShared] Uint32Array or sequence<GLuint>) baseInstancesList, GLuint baseInstancesOffset,
      GLsizei drawCount
  );
};
  

New Functions

undefined multiDrawArraysInstancedBaseInstanceWEBGL(GLenum mode, ([AllowShared] Int32Array or sequence<GLint>) firstsList, GLuint firstsOffset, ([AllowShared] Int32Array or sequence<GLsizei>) countsList, GLuint countsOffset, ([AllowShared] Int32Array or sequence<GLsizei>) baseInstancesList, GLuint baseInstancesOffset, GLsizei drawCount)
undefined multiDrawElementsInstancedBaseVertexBaseInstanceWEBGL(GLenum mode, ([AllowShared] Int32Array or sequence<GLsizei>) countsList, GLuint countsOffset, GLenum type, ([AllowShared] Int32Array or sequence<GLsizei>) offsetsList, GLuint offsetsOffset, ([AllowShared] Int32Array or sequence<GLsizei>) instanceCountsList, GLuint instanceCountsOffset, ([AllowShared] Int32Array or sequence<GLint>) baseVerticesList, GLuint baseVerticesOffset, ([AllowShared] Uint32Array or sequence<GLuint>) baseInstancesList, GLuint baseInstancesOffset, GLsizei drawCount)

Sample Code

var ext = gl.getExtension("WEBGL_multi_draw_instanced_base_vertex_base_instance");

{
  // multiDrawArraysInstancedBaseInstance variant.
  let firsts = new Int32Array(...);
  let counts = new Int32Array(...);
  let instanceCounts = new Int32Array(...);
  let baseInstances = new Uint32Array(...);
  ext.multiDrawArraysInstancedBaseInstanceWEBGL(
      gl.TRIANGLES, first, 0, counts, 0, instanceCounts, 0, baseInstances, 0, counts.length);
}

{
  // multiDrawElementsInstancedBaseVertexBaseInstance variant.
  // Assumes that the indices which have been previously uploaded to the
  // ELEMENT_ARRAY_BUFFER are to be treated as UNSIGNED_SHORT.
  let counts = new Int32Array(...);
  let offsets = new Int32Array(...);
  let instanceCounts = new Int32Array(...);
  let baseVertices = new Int32Array(...);
  let baseInstances = new Uint32Array(...);
  ext.multiDrawElementsInstancedBaseVertexBaseInstanceWEBGL(
      gl.TRIANGLES, counts, 0, gl.UNSIGHNED_SHORT,
      offsets, 0, instanceCounts, 0, baseVertices, 0, baseInstances, 0,
      counts.length);
}
    
#version 300 es
void main() {
    gl_Position = vec4(gl_VertexID, gl_InstanceID, 0, 1);
}
    

Conformance Tests

Security Considerations

The multi-draw-base-vertex-base-instance-draw APIs are subject to all of the same rules regarding out-of-range array accesses as the core WebGL APIs.

Issues

Revision History

Revision 1, 2019/08/28

Revision 2, 2019/09/25

Revision 3, 2020/06/26

Revision 4, 2020/07/14

Revision 5, 2020/07/28

Revision 6, 2021/05/18

Revision 7, 2021/05/26