Name EXT_draw_instanced Name Strings GL_EXT_draw_instanced Contact Michael Gold, NVIDIA Corporation (gold 'at' nvidia.com) Status Shipping for GeForce 8 Series (November 2006) Version Last Modified Date: June 26, 2013 Author Revision: 2.0 Number OpenGL Extension #327 OpenGL ES Extension #157 Dependencies OpenGL 2.0 or OpenGL ES 2.0 is required. EXT_gpu_shader4 or NV_vertex_shader4 is required if the GL is not OpenGL ES 2.0. OES_element_index_uint affects the definition of this extension. Overview This extension provides the means to render multiple instances of an object with a single draw call, and an "instance ID" variable which can be used by the vertex program to compute per-instance values, typically an object's transform. New Tokens None New Procedures and Functions void DrawArraysInstancedEXT(enum mode, int first, sizei count, sizei primcount); void DrawElementsInstancedEXT(enum mode, sizei count, enum type, const void *indices, sizei primcount); Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) Modify section 2.8 (Vertex Arrays), p. 23 (insert before the final paragraph, p. 30) The internal counter is a 32-bit integer value which may be read by a vertex program as , as described in section 2.X.3.2, or vertex shader as , as described in section 2.15.4.2. The value of this counter is always zero, except as noted below. The command void DrawArraysInstancedEXT(enum mode, int first, sizei count, sizei primcount); behaves identically to DrawArrays except that instances of the range of elements are executed and the value of 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 DrawElementsInstancedEXT(enum mode, sizei count, enum type, const void *indices, sizei primcount); behaves identically to DrawElements except that instances of the set of elements are executed, and the value of 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; } Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) The error INVALID_OPERATION is generated if DrawArraysInstancedEXT or DrawElementsInstancedEXT is called during display list compilation. Dependencies on OpenGL ES 2.0 If the GL is OpenGL ES 2.0, all references to vertex programs and display lists are deleted, and primcount is replaced by instanceCount in the function prototype and pseudocode. Add a new section in 2.10.5 called "Shader Inputs" between "Texture Access" and "Validation" "Besides having access to vertex attributes and uniform variables, vertex shaders can access the read-only built-in variable gl_InstanceIDEXT. The variable gl_InstanceIDEXT 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." Additionally, the following is added to The OpenGL ES Shading Language Specification, Version 1.00.17: "Including the following line in a shader can be used to control the language features described in this extension: #extension GL_EXT_draw_instanced : where is as specified in section 3.4. A new preprocessor #define is added to the OpenGL Shading Language: #define GL_EXT_draw_instanced 1 Change Section 7.1 "Vertex Shader Special Variables" Add the following definitions to the list of built-in variable definitions: highp int gl_InstanceIDEXT; // read-only Add the following paragraph at the end of the section: The variable gl_InstanceIDEXT 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 (DrawArraysInstancedEXT, DrawElementsInstancedEXT). If the current primitive does not come from an instanced draw call, the value of gl_InstanceIDEXT is zero." Dependencies on NV_vertex_program4 If NV_vertex_program4 is not supported and the GL is not OpenGL ES 2.0, all references to vertex.instance are deleted. Dependencies on EXT_gpu_shader4 If EXT_gpu_shader4 is not supported and the GL is not OpenGL ES 2.0, all references to gl_InstanceID are deleted. Dependencies on OES_element_index_uint If OES_element_index_uint is not supported and the GL is OpenGL ES 2.0, omit UNSIGNED_INT and uint from the description of DrawElementsInstancedEXT. Errors INVALID_ENUM is generated by DrawElementsInstancedEXT if is not one of UNSIGNED_BYTE, UNSIGNED_SHORT or UNSIGNED_INT. INVALID_VALUE is generated by DrawArraysInstancedEXT if is less than zero. Issues (1) Should instanceID be provided by this extension, or should it be provided by EXT_gpu_shader4, thus creating a dependence on that spec? Resolved: While this extension could stand alone, its utility would be limited without the additional functionality provided by EXT_gpu_shader4; also, the spec language is cleaner if EXT_gpu_shader4 assumes instanceID is always available, even if its value is always zero without this extension. For OpenGL ES 2.0: This extension does stand alone, introducing gl_InstanceID in GLSL-ES 1.00. (2) Should MultiDrawArrays and MultiDrawElements affect the value of instanceID? Resolved: No, this may cause implementation difficulties and is considered unlikely to provide any real benefit. (3) Should DrawArraysInstanced and DrawElementsInstanced be compiled into display lists? Resolved: No, calling these during display list compilation generate INVALID_OPERATION. (4) What is the maximum range of instances that gl_InstanceIDEXT can index in an OpenGL ES 2.0 vertex shader? Resolved: According to the The OpenGL ES Shading Language 1.00.17 Specification, section 4.5.2 Precision Qualifiers, highp integer range is (-2^16, 2^16). So even though the DrawArraysInstancedEXT and DrawElementsInstancedEXT take instanceCount as a 32-bit unsigned int, the maximum instance the gl_InstanceIDEXT variable can index is 2^16 - 1. If Instance count exceeds 2^16 - 1, it results in an undefined value due to integer overflow and it is possible that gl_InstanceIDEXT wraps, or that it does not. Revision History Rev. Date Author Changes ---- -------- -------- ----------------------------------------- 1.5 05/09/08 gold Removed extraneous parameters to DrawArrays and DrawElements in chapter 2 pseudocode 2.0 06/26/13 benj Add OpenGL ES 2.0 interactions