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: 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:

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:

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

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

Revision 8, 2023/09/08