1Name 2 3 EXT_draw_instanced 4 5Name Strings 6 7 GL_EXT_draw_instanced 8 9Contact 10 11 Michael Gold, NVIDIA Corporation (gold 'at' nvidia.com) 12 13Status 14 15 Shipping for GeForce 8 Series (November 2006) 16 17Version 18 19 Last Modified Date: June 26, 2013 20 Author Revision: 2.0 21 22Number 23 24 OpenGL Extension #327 25 OpenGL ES Extension #157 26 27Dependencies 28 29 OpenGL 2.0 or OpenGL ES 2.0 is required. 30 31 EXT_gpu_shader4 or NV_vertex_shader4 is required if the GL is not OpenGL ES 2.0. 32 33 OES_element_index_uint affects the definition of this extension. 34 35Overview 36 37 This extension provides the means to render multiple instances of 38 an object with a single draw call, and an "instance ID" variable 39 which can be used by the vertex program to compute per-instance 40 values, typically an object's transform. 41 42New Tokens 43 44 None 45 46New Procedures and Functions 47 48 void DrawArraysInstancedEXT(enum mode, int first, sizei count, 49 sizei primcount); 50 void DrawElementsInstancedEXT(enum mode, sizei count, enum type, 51 const void *indices, sizei primcount); 52 53Additions to Chapter 2 of the OpenGL 2.0 Specification 54(OpenGL Operation) 55 56 Modify section 2.8 (Vertex Arrays), p. 23 57 58 (insert before the final paragraph, p. 30) 59 60 The internal counter <instanceID> is a 32-bit integer value which 61 may be read by a vertex program as <vertex.instance>, as described 62 in section 2.X.3.2, or vertex shader as <gl_InstanceID>, as 63 described in section 2.15.4.2. The value of this counter is 64 always zero, except as noted below. 65 66 The command 67 68 void DrawArraysInstancedEXT(enum mode, int first, sizei count, 69 sizei primcount); 70 71 behaves identically to DrawArrays except that <primcount> 72 instances of the range of elements are executed and the value of 73 <instanceID> advances for each iteration. It has the same effect 74 as: 75 76 if (mode, count, or primcount is invalid) 77 generate appropriate error 78 else { 79 for (i = 0; i < primcount; i++) { 80 instanceID = i; 81 DrawArrays(mode, first, count); 82 } 83 instanceID = 0; 84 } 85 86 The command 87 88 void DrawElementsInstancedEXT(enum mode, sizei count, enum type, 89 const void *indices, sizei primcount); 90 91 behaves identically to DrawElements except that <primcount> 92 instances of the set of elements are executed, and the value of 93 <instanceID> advances for each iteration. It has the same effect 94 as: 95 96 if (mode, count, primcount, or type is invalid ) 97 generate appropriate error 98 else { 99 for (int i = 0; i < primcount; i++) { 100 instanceID = i; 101 DrawElements(mode, count, type, indices); 102 } 103 instanceID = 0; 104 } 105 106Additions to Chapter 5 of the OpenGL 2.0 Specification 107(Special Functions) 108 109 The error INVALID_OPERATION is generated if DrawArraysInstancedEXT 110 or DrawElementsInstancedEXT is called during display list 111 compilation. 112 113Dependencies on OpenGL ES 2.0 114 115 If the GL is OpenGL ES 2.0, all references to vertex programs and display lists 116 are deleted, and primcount is replaced by instanceCount in the function prototype 117 and pseudocode. 118 119 Add a new section in 2.10.5 called "Shader Inputs" between "Texture Access" and 120 "Validation" 121 122 "Besides having access to vertex attributes and uniform variables, 123 vertex shaders can access the read-only built-in variable 124 gl_InstanceIDEXT. The variable gl_InstanceIDEXT holds the integer 125 index of the current primitive in an instanced draw call. See also 126 section 7.1 of the OpenGL ES Shading Language Specification." 127 128 129 Additionally, the following is added to The OpenGL ES Shading Language Specification, 130 Version 1.00.17: 131 132 "Including the following line in a shader can be used to control the 133 language features described in this extension: 134 135 #extension GL_EXT_draw_instanced : <behavior> 136 137 where <behavior> is as specified in section 3.4. 138 139 A new preprocessor #define is added to the OpenGL Shading Language: 140 141 #define GL_EXT_draw_instanced 1 142 143 Change Section 7.1 "Vertex Shader Special Variables" 144 145 Add the following definitions to the list of built-in variable definitions: 146 147 highp int gl_InstanceIDEXT; // read-only 148 149 Add the following paragraph at the end of the section: 150 151 The variable gl_InstanceIDEXT is available as a read-only variable 152 from within vertex shaders and holds the integer index of the current 153 primitive in an instanced draw call (DrawArraysInstancedEXT, 154 DrawElementsInstancedEXT). If the current primitive does not come 155 from an instanced draw call, the value of gl_InstanceIDEXT is zero." 156 157 158Dependencies on NV_vertex_program4 159 160 If NV_vertex_program4 is not supported and the GL is not OpenGL ES 2.0, 161 all references to vertex.instance are deleted. 162 163Dependencies on EXT_gpu_shader4 164 165 If EXT_gpu_shader4 is not supported and the GL is not OpenGL ES 2.0, 166 all references to gl_InstanceID are deleted. 167 168Dependencies on OES_element_index_uint 169 170 If OES_element_index_uint is not supported and the GL is OpenGL ES 2.0, 171 omit UNSIGNED_INT and uint from the description of DrawElementsInstancedEXT. 172 173Errors 174 175 INVALID_ENUM is generated by DrawElementsInstancedEXT if <type> is 176 not one of UNSIGNED_BYTE, UNSIGNED_SHORT or UNSIGNED_INT. 177 178 INVALID_VALUE is generated by DrawArraysInstancedEXT if <first> is 179 less than zero. 180 181Issues 182 183 (1) Should instanceID be provided by this extension, or should it be 184 provided by EXT_gpu_shader4, thus creating a dependence on that 185 spec? 186 187 Resolved: While this extension could stand alone, its utility 188 would be limited without the additional functionality provided 189 by EXT_gpu_shader4; also, the spec language is cleaner if 190 EXT_gpu_shader4 assumes instanceID is always available, even 191 if its value is always zero without this extension. 192 193 For OpenGL ES 2.0: This extension does stand alone, introducing 194 gl_InstanceID in GLSL-ES 1.00. 195 196 (2) Should MultiDrawArrays and MultiDrawElements affect the value of 197 instanceID? 198 199 Resolved: No, this may cause implementation difficulties and 200 is considered unlikely to provide any real benefit. 201 202 (3) Should DrawArraysInstanced and DrawElementsInstanced be compiled 203 into display lists? 204 205 Resolved: No, calling these during display list compilation 206 generate INVALID_OPERATION. 207 208 (4) What is the maximum range of instances that gl_InstanceIDEXT can index 209 in an OpenGL ES 2.0 vertex shader? 210 211 Resolved: According to the The OpenGL ES Shading Language 212 1.00.17 Specification, section 4.5.2 Precision Qualifiers, highp integer 213 range is (-2^16, 2^16). So even though the DrawArraysInstancedEXT and 214 DrawElementsInstancedEXT take instanceCount as a 32-bit unsigned int, 215 the maximum instance the gl_InstanceIDEXT variable can index is 216 2^16 - 1. If Instance count exceeds 2^16 - 1, it results in an undefined 217 value due to integer overflow and it is possible that gl_InstanceIDEXT 218 wraps, or that it does not. 219 220Revision History 221 222 Rev. Date Author Changes 223 ---- -------- -------- ----------------------------------------- 224 1.5 05/09/08 gold Removed extraneous parameters to DrawArrays 225 and DrawElements in chapter 2 pseudocode 226 227 2.0 06/26/13 benj Add OpenGL ES 2.0 interactions 228 229