blob: daddef33fa2d40657ca0f2b1b1c57a664628c79d [file] [log] [blame]
Name
NV_draw_instanced
Name Strings
GL_NV_draw_instanced
Contributors
Contributors to ARB_draw_instanced and EXT_gpu_shader4
Mathias Heyer, NVIDIA
Greg Roth, NVIDIA
Contact
Greg Roth, NVIDIA (groth 'at' nvidia 'dot' com)
Status
Complete
Version
Last Modified Date: Aug 28, 2012
Author Revision: 3
Number
OpenGL ES Extension #141
Dependencies
OpenGL ES 2.0 is required.
The extension is written against the OpenGL ES 2.0.25 Specification.
Written based on the wording of The OpenGL ES Shading Language
1.00.14 Specification.
OES_element_index_uint affects the definition of this extension.
Overview
A common use case in GL for some applications is to be able to
draw the same object, or groups of similar objects that share
vertex data, primitive count and type, multiple times. This
extension provides a means of accelerating such use cases while
limiting the number of required API calls, and keeping the amount
of duplicate data to a minimum.
This extension introduces two draw calls which are conceptually
equivalent to a series of draw calls. Each conceptual call in
this series is considered an "instance" of the actual draw call.
This extension also introduces a read-only built-in variable to
GLSL which contains the "instance ID." This variable initially
contains 0, but increases by one after each conceptual draw call.
By using the instance ID or multiples thereof as an index into
a uniform array containing transform data, vertex shaders can
draw multiple instances of an object with a single draw call.
New Procedures and Functions
void DrawArraysInstancedNV(enum mode, int first, sizei count,
sizei primcount);
void DrawElementsInstancedNV(enum mode, sizei count, enum type,
const void *indices, sizei primcount);
New Tokens
None
Additions to Chapter 2 of the OpenGL ES 2.0.25 Specification
(OpenGL ES Operation)
Modify section 2.8 (Vertex Arrays)
(Insert before the final paragraph)
The internal counter <instanceID> is a 32-bit integer value which
may be read by a vertex shader as <gl_InstanceIDNV>, as
described in section 2.10.5.2. The value of this counter is
always zero, except as noted below.
The command
void DrawArraysInstancedNV(enum mode, int first, sizei count,
sizei primcount);
behaves identically to DrawArrays except that <primcount>
instances of the range of elements are executed and the value of
<instanceID> advances for each iteration. It has the same effect
as:
if (mode, count, or primcount is invalid)
generate appropriate error
else {
for (i = 0; i < primcount; i++) {
instanceID = i;
DrawArrays(mode, first, count);
}
instanceID = 0;
}
The command
void DrawElementsInstancedNV(enum mode, sizei count, enum type,
const void *indices, sizei primcount);
behaves identically to DrawElements except that <primcount>
instances of the set of elements are executed, and the value of
<instanceID> advances for each iteration. It has the same effect
as:
if (mode, count, primcount, or type is invalid )
generate appropriate error
else {
for (int i = 0; i < primcount; i++) {
instanceID = i;
DrawElements(mode, count, type, indices);
}
instanceID = 0;
}
Add a new section 2.10.5.2 "Shader Inputs" after "Texture Access" in
Section 2.10.5 "Shader Execution".
Besides having access to vertex attributes and uniform variables,
vertex shaders can access the read-only built-in variable
gl_InstanceIDNV. The variable gl_InstanceIDNV holds the integer
index of the current primitive in an instanced draw call. See also
section 7.1 of the OpenGL ES Shading Language Specification.
Modifications to The OpenGL ES Shading Language Specification, Version
1.00.14
Including the following line in a shader can be used to control the
language features described in this extension:
#extension GL_NV_draw_instanced : <behavior>
where <behavior> is as specified in section 3.4.
A new preprocessor #define is added to the OpenGL Shading Language:
#define GL_NV_draw_instanced 1
Change Section 7.1 "Vertex Shader Special Variables"
Add the following paragraph after the description of gl_PointSize:
The variable gl_InstanceIDNV is available as a read-only variable
from within vertex shaders and holds the integer index of the
current primitive in an instanced draw call (DrawArraysInstancedNV,
DrawElementsInstancedNV). If the current primitive does not come
from an instanced draw call, the value of gl_InstanceIDNV is zero.
Add the following definitions to the list of built-in variable definitions:
int gl_InstanceIDNV; // read-only
Dependencies on OES_element_index_uint
If OES_element_index_uint is not supported, removed all references
to UNSIGNED_INT indices and the associated GL data type uint in
the description of DrawElementsInstancedNV.
Errors
INVALID_ENUM is generated by DrawElementsInstancedNV if <type> is
not one of UNSIGNED_BYTE, UNSIGNED_SHORT or UNSIGNED_INT.
INVALID_VALUE is generated by DrawArraysInstancedNV if <first>,
<count>, or <primcount> is less than zero.
INVALID_ENUM is generated by DrawArraysInstancedNV or
DrawElementsInstancedNV if <mode> is not one of the modes described in
section 2.6.1.
INVALID_VALUE is generated by DrawElementsInstancedNV if <count> or
<primcount> is less than zero.
Issues
1) Should this exist as a separate extension from NV_instanced_arrays?
Resolved: Yes. Even though these extensions expose similar
functionality and together they represent a more cohesive extension
with slightly less tricky text in the process, keeping them separate
makes the relationship with the desktop extensions clear.
Revision History
Rev. Date Author Changes
---- ------------- --------- ----------------------------------------
3 28 Aug 2012 groth Minor copy edits and corrections to spec references
2 19 Aug 2012 groth Correct illustrative code samples
1 12 Aug 2012 groth Initial GLES2 version from ARB_draw_instanced and EXT_gpu_shader4