WebGL
Khronos
 

WebGL WEBGL_draw_instanced_base_vertex_base_instance Extension Draft Specification

Name

WEBGL_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

Members of the WebGL working group

Version

Last modified date: May 26, 2021
Revision: 3

Number

WebGL extension #46

Dependencies

Written against the WebGL API 2.0 specification.

Overview

This extension exposes the DrawArraysInstancedBaseInstanceANGLE and DrawElementsInstancedBaseVertexBaseInstanceANGLE entrypoints as drawArraysInstancedBaseInstanceWEBGL and drawElementsInstancedBaseVertexBaseInstanceWEBGL. The vertex shader extension GL_ANGLE_base_vertex_base_instance is not added. The vertex shader builtins gl_BaseVertex and gl_BaseInstance are not added. The implementation must validate the arrays and indices referenced by drawArraysInstancedBaseInstanceWEBGL and drawElementsInstancedBaseVertexBaseInstanceWEBGL, 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.

When this extension is enabled:

IDL


[Exposed=(Window,Worker), LegacyNoInterfaceObject]
interface WEBGL_draw_instanced_base_vertex_base_instance {
  undefined drawArraysInstancedBaseInstanceWEBGL(
      GLenum mode, GLint first, GLsizei count,
      GLsizei instanceCount, GLuint baseInstance);
  undefined drawElementsInstancedBaseVertexBaseInstanceWEBGL(
      GLenum mode, GLsizei count, GLenum type, GLintptr offset,
      GLsizei instanceCount, GLint baseVertex, GLuint baseInstance);
};
  

New Functions

undefined drawArraysInstancedBaseInstanceWEBGL(GLenum mode, GLint first, GLsizei count, GLsizei instanceCount, GLuint baseInstance)
undefined drawElementsInstancedBaseVertexBaseInstanceWEBGL(GLenum mode, GLsizei count, GLenum type, GLintptr offset, GLsizei instanceCount, GLint baseVertex, GLuint baseInstance)

Sample Code

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

{
  // drawArraysInstancedBaseInstance variant.
  let first = 0;
  let count = 3;
  let instanceCount = 2;
  let baseInstance = 1;
  gl.uniform1i(u_BaseVertex_location, 0);
  gl.uniform1i(u_BaseInstance_location, baseInstance);
  ext.drawArraysInstancedBaseInstanceWEBGL(
      gl.TRIANGLES, first, count, instanceCount, baseInstance);
}

{
  // drawElementsInstancedBaseVertexBaseInstance variant.
  // Assumes that the indices which have been previously uploaded to the
  // ELEMENT_ARRAY_BUFFER are to be treated as UNSIGNED_SHORT.
  let count = 3;
  let offset = 0;
  let instanceCount = 2;
  let baseVertex = 3;
  let baseInstance = 1;
  gl.uniform1i(u_BaseVertex_location, baseVertex);
  gl.uniform1i(u_BaseInstance_location, baseInstance);
  ext.drawElementsInstancedBaseVertexBaseInstanceWEBGL(
      gl.TRIANGLES, count, gl.UNSIGHNED_SHORT, offset, instanceCount, baseVertex, baseInstance);
}
    
#version 300 es
uniform int u_BaseVertex;
uniform int u_BaseInstance;
void main() {
    gl_Position = vec4(u_BaseVertex, gl_InstanceID + u_BaseInstance, 0, 1);
}
    

Conformance Tests

Security Considerations

The 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, 2021/05/26