WebGL WEBGL_multi_draw Extension Specification

Name

WEBGL_multi_draw

Contact

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

Contributors

Contributors to the ANGLE_multi_draw specification

Members of the WebGL working group

Version

Last modified date: September 08, 2023
Revision: 8

Number

WebGL extension #40

Dependencies

Written against the WebGL API 1.0 specification.

Overview

This extension exposes the ANGLE_multi_draw functionality to WebGL.

The following WebGL-specific behavioral changes apply:

This extension only exposes the MultiDrawArraysANGLE, MultiDrawElementsANGLE, MultiDrawArraysInstancedANGLE, and MultiDrawElementsInstancedANGLE entrypoints as multiDrawArraysWEBGL, multiDrawElementsWEBGL, multiDrawArraysInstancedWEBGL, and multiDrawElementsInstancedWEBGL.
The implementation must validate the arrays and indices referenced by multiDrawArraysWEBGL, multiDrawElementsWEBGL, multiDrawArraysInstancedWEBGL, and multiDrawElementsInstancedWEBGL, similarly to how indices referenced by drawArrays and drawElements are validated according to section Enabled Vertex Attributes and Range Checking of the WebGL specification.
Although the extension name is WEBGL_multi_draw, 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.
The new draw call entrypoints have typed array or sequence arguments instead of pointer arguments. They additionally include *Offset arguments for each array to choose the starting point into the respective typed array or sequence. This primarily avoids allocation of temporary typed array views.

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

CAD vendors rendering large models comprised of many individual parts face scalability issues issuing large numbers of draw calls from WebGL. This extension reduces draw call overhead by allowing better batching.

When this extension is enabled:

The multiDrawArraysWEBGL, multiDrawElementsWEBGL, multiDrawArraysInstancedWEBGL, and multiDrawElementsInstancedWEBGL entry points are added. These provide a counterpoint to instanced rendering and are more flexible for certain scenarios. They behave identically to multiple calls to drawArrays, drawElements, drawArraysInstanced, and drawElementsInstanced except they handle multiple lists of arguments in one call.
The gl_DrawID builtin is added to the shading language. For any Multi* draw call variant, the index of the draw i may be read by the vertex shader as gl_DrawID. For non Multi* calls, the value of gl_DrawID is 0.
When this extension is enabled, the following extensions are enabled implicitly:
- ANGLE_instanced_arrays
When a vertex shader enables, requires, or warns GL_ANGLE_multi_draw with an #extension directive:
- int gl_DrawID is a built-in input.
The GLSL macro GL_ANGLE_multi_draw is defined as 1.

IDL


[Exposed=(Window,Worker), LegacyNoInterfaceObject]
interface WEBGL_multi_draw {
  undefined multiDrawArraysWEBGL(
      GLenum mode,
      ([AllowShared] Int32Array or sequence<GLint>) firstsList, unsigned long long firstsOffset,
      ([AllowShared] Int32Array or sequence<GLsizei>) countsList, unsigned long long countsOffset,
      GLsizei drawcount);
  undefined multiDrawElementsWEBGL(
      GLenum mode,
      ([AllowShared] Int32Array or sequence<GLsizei>) countsList, unsigned long long countsOffset,
      GLenum type,
      ([AllowShared] Int32Array or sequence<GLsizei>) offsetsList, unsigned long long offsetsOffset,
      GLsizei drawcount);
  undefined multiDrawArraysInstancedWEBGL(
      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,
      GLsizei drawcount);
  undefined multiDrawElementsInstancedWEBGL(
      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,
      GLsizei drawcount);
};

New Functions

undefined multiDrawArraysWEBGL(GLenum mode, ([AllowShared] Int32Array or sequence<GLint>) firstsList, unsigned long long firstsOffset, ([AllowShared] Int32Array or sequence<GLsizei>) countsList, unsigned long long countsOffset, GLsizei drawcount)
undefined multiDrawElementsWEBGL(GLenum mode, ([AllowShared] Int32Array or sequence<GLsizei>) countsList, unsigned long long countsOffset, GLenum type, ([AllowShared] Int32Array or sequence<GLsizei>) offsetsList, unsigned long long offsetsOffset, GLsizei drawcount)
undefined multiDrawArraysInstancedWEBGL(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, GLsizei drawcount)
undefined multiDrawElementsInstancedWEBGL(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, GLsizei drawcount)

Sample Code

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


{
  // multiDrawArrays variant.
  let firsts = new Int32Array(...);
  let counts = new Int32Array(...);
  ext.multiDrawArraysWEBGL(gl.TRIANGLES, firsts, 0, counts, 0, firsts.length);
}

{
  // multiDrawElements variant.
  let counts = new Int32Array(...);
  let offsets = new Int32Array(...);
  ext.multiDrawElementsWEBGL(
      gl.TRIANGLES, counts, 0, gl.UNSIGNED_INT, offsets, 0, counts.length);
}

{
  // multiDrawArraysInstanced variant.
  let firsts = new Int32Array(...);
  let counts = new Int32Array(...);
  let instanceCounts = new Int32Array(...);
  ext.multiDrawArraysInstancedWEBGL(
      gl.TRIANGLES, firsts, 0, counts, 0, instanceCounts, 0, firsts.length);
}

{
  // multiDrawElementsInstanced variant.
  let counts = new Int32Array(...);
  let offsets = new Int32Array(...);
  let instanceCounts = new Int32Array(...);
  ext.multiDrawElementsInstancedWEBGL(
      gl.POINTS, counts, 0, gl.UNSIGNED_SHORT, offsets, 0, instanceCounts, 0,
      counts.length);
}

#extension GL_ANGLE_multi_draw : require
void main() {
    gl_Position = vec4(gl_DrawID, 0, 0, 1);
}

Conformance Tests

Security Considerations

The multi-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, 2018/11/09

Initial version.

Revision 2, 2019/01/21

Moved to draft.

Revision 3, 2019/10/23

Merged features with WEBGL_multi_draw_instanced.

Revision 4, 2020/06/26

Implicitly enable ANGLE_instanced_arrays.

Revision 5, 2020/07/28

Add new function section.

Revision 6, 2020/07/31

Moved to Community Approved.

Revision 7, 2021/05/18

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

Revision 8, 2023/09/08

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