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: September 25, 2019
Revision: 2

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. In addition the vertex shader builtin gl_BaseVertex and gl_BaseInstance are 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. Although the extension name is named WEBGL_draw_instanced_base_vertex_base_instance, the extension must be enabled with the #extension GL_ANGLE_base_vertex_base_instance directive, as shown in the sample code, to use the extension in a shader. Likewise the shading language preprocessor #define GL_ANGLE_base_vertex_base_instance will be defined to 1 if the extension is supported.

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


[NoInterfaceObject]
interface WEBGL_draw_instanced_base_vertex_base_instance {
  void drawArraysInstancedBaseInstanceWEBGL(
      GLenum mode, GLint first, GLsizei count,
      GLsizei instanceCount, GLuint baseInstance
  );
  void drawElementsInstancedBaseVertexBaseInstanceWEBGL(
      GLenum mode, GLsizei count, GLenum type, GLintptr offset,
      GLsizei instanceCount, GLint baseVertex, GLuint baseinstance
  );
};
  

New Functions

void drawArraysInstancedBaseInstanceWEBGL(GLenum mode, GLint first, GLsizei count, GLsizei instanceCount, GLuint baseInstance)
void 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;
  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 baseVertice = 3;
  let baseInstance = 1;
  ext.drawElementsInstancedBaseVertexBaseInstanceWEBGL(
      gl.TRIANGLES, count, gl.UNSIGHNED_SHORT, offset, instanceCount, baseVertex, baseInstance);
}
    
#version 300 es
#extension GL_ANGLE_base_vertex_base_instance : require
void main() {
    gl_Position = vec4(gl_BaseVertex, gl_InstanceID + gl_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