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: September 08, 2023
Revision: 8

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 ANGLE_base_vertex_base_instance functionality to WebGL.

The following WebGL-specific behavioral changes apply:

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.
Although the extension name is WEBGL_multi_draw_instanced_base_vertex_base_instance, the extension must be enabled with the #extension GL_ANGLE_multi_draw directive, as shown in the sample code, to use the gl_DrawID built-in in a shader. Likewise the shading language preprocessor #define GL_ANGLE_multi_draw, will be defined to 1 if the extension is supported.

Consult the above extension for documentation, issues and new functions and enumerants.

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:

The multiDrawArraysInstancedBaseInstanceWEBGL and multiDrawElementsInstancedBaseVertexBaseInstanceWEBGL entry points are added. They behave identically to multiple calls to drawArraysInstanced and drawElementsInstanced except they handle multiple lists of arguments in one call, plus that the first element within those instanced vertex attributes is specified in baseInstancesList.
The multiDrawElementsInstancedBaseVertexBaseInstanceWEBGL in addition specifies the value of base vertex of each draw call to be values inbaseVerticesList instead of zero.
When this extension is enabled, the following extensions are enabled implicitly:
- WEBGL_multi_draw

IDL

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

New Functions

undefined multiDrawArraysInstancedBaseInstanceWEBGL(GLenum mode, ([AllowShared] Int32Array or sequence<GLint>) firstsList, unsigned long long firstsOffset, ([AllowShared] Int32Array or sequence<GLsizei>) countsList, unsigned long long countsOffset, ([AllowShared] Int32Array or sequence<GLsizei>) instanceCountsList, unsigned long long instanceCountsOffset, ([AllowShared] Uint32Array or sequence<GLuint>) baseInstancesList, unsigned long long baseInstancesOffset, GLsizei drawcount)
undefined multiDrawElementsInstancedBaseVertexBaseInstanceWEBGL(GLenum mode, ([AllowShared] Int32Array or sequence<GLsizei>) countsList, unsigned long long countsOffset, GLenum type, ([AllowShared] Int32Array or sequence<GLsizei>) offsetsList, unsigned long long offsetsOffset, ([AllowShared] Int32Array or sequence<GLsizei>) instanceCountsList, unsigned long long instanceCountsOffset, ([AllowShared] Int32Array or sequence<GLint>) baseVerticesList, unsigned long long baseVerticesOffset, ([AllowShared] Uint32Array or sequence<GLuint>) baseInstancesList, unsigned long long 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.UNSIGNED_SHORT,
      offsets, 0, instanceCounts, 0, baseVertices, 0, baseInstances, 0,
      counts.length);
}

#version 300 es
#extension GL_ANGLE_multi_draw : require
void main() {
    gl_Position = vec4(gl_VertexID, gl_InstanceID, gl_DrawID, 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

Initial version.

Revision 2, 2019/09/25

Change parameters order.
Move to draft.

Revision 3, 2020/06/26

Implicitly enable WEBGL_multi_draw

Revision 4, 2020/07/14

Change types of countsList, offsetsList, and instanceCountsList from sequence<GLint> to sequence<GLsizei>
Change type of baseInstances from Int32Array to Uint32Array and sequence<GLint> to sequence<GLuint>

Revision 5, 2020/07/28

Add parentheses around union types in IDL

Revision 6, 2021/05/18

Add [AllowShared] to all typed array arguments for compatibility with multi-threaded WebAssembly.

Revision 7, 2021/05/26

Removed GLSL extension and builtins.

Revision 8, 2023/09/08

Changed offset arguments to "unsigned long long" for Wasm.