1Name 2 3 ARB_draw_instanced 4 5Name Strings 6 7 GL_ARB_draw_instanced 8 9Contributors 10 Michael Gold, NVIDIA 11 James Helferty, TransGaming Inc. 12 Daniel Koch, TransGaming Inc. 13 14Contact 15 16 James Helferty, TransGaming Inc. (james 'at' transgaming.com) 17 Daniel Koch, TransGaming Inc. (daniel 'at' transgaming.com) 18 19Notice 20 21 Copyright (c) 2008-2013 The Khronos Group Inc. Copyright terms at 22 http://www.khronos.org/registry/speccopyright.html 23 24Specification Update Policy 25 26 Khronos-approved extension specifications are updated in response to 27 issues and bugs prioritized by the Khronos OpenGL Working Group. For 28 extensions which have been promoted to a core Specification, fixes will 29 first appear in the latest version of that core Specification, and will 30 eventually be backported to the extension document. This policy is 31 described in more detail at 32 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 33 34IP Status 35 36 Unknown 37 38Status 39 40 Approved by the ARB on July 11, 2008 41 42Version 43 44 Last Modified Date: April 8, 2011 45 Author Revision: 5 46 47Number 48 49 ARB Extension #44 50 51Dependencies 52 53 OpenGL 2.0 is required. 54 55 The extension is written against the OpenGL 2.1 Specification. 56 57 EXT_gpu_shader4 or NV_vertex_program4 or OpenGL 3.0 is required. 58 59Overview 60 61 A common use case in GL for some applications is to be able to 62 draw the same object, or groups of similar objects that share 63 vertex data, primitive count and type, multiple times. This 64 extension provides a means of accelerating such use cases while 65 restricting the number of API calls, and keeping the amount of 66 duplicate data to a minimum. 67 68 This extension introduces two draw calls which are conceptually 69 equivalent to a series of draw calls. Each conceptual call in 70 this series is considered an "instance" of the actual draw call. 71 72 This extension also introduces a read-only built-in variable to 73 GLSL which contains the "instance ID." This variable initially 74 contains 0, but increases by one after each conceptual draw call. 75 76 By using the instance ID or multiples thereof as an index into 77 a uniform array containing transform data, vertex shaders can 78 draw multiple instances of an object with a single draw call. 79 80New Tokens 81 82 None 83 84New Procedures and Functions 85 86 void DrawArraysInstancedARB(enum mode, int first, sizei count, 87 sizei primcount); 88 void DrawElementsInstancedARB(enum mode, sizei count, enum type, 89 const void *indices, sizei primcount); 90 91Additions to Chapter 2 of the OpenGL 2.1 Specification 92(OpenGL Operation) 93 94 Modify section 2.8 (Vertex Arrays), p. 23 95 96 (insert before the final paragraph, p. 30) 97 98 The internal counter <instanceID> is a 32-bit integer value which 99 may be read by a vertex program as <vertex.instance>, as described 100 in section 2.X.3.2, or vertex shader as <gl_InstanceIDARB>, as 101 described in section 2.15.4.2. The value of this counter is 102 always zero, except as noted below. 103 104 The command 105 106 void DrawArraysInstancedARB(enum mode, int first, sizei count, 107 sizei primcount); 108 109 behaves identically to DrawArrays except that <primcount> 110 instances of the range of elements are executed and the value of 111 <instanceID> advances for each iteration. It has the same effect 112 as: 113 114 if (mode or count is invalid) 115 generate appropriate error 116 else { 117 for (i = 0; i < primcount; i++) { 118 instanceID = i; 119 DrawArrays(mode, first, count, i); 120 } 121 instanceID = 0; 122 } 123 124 The command 125 126 void DrawElementsInstancedARB(enum mode, sizei count, enum type, 127 const void *indices, sizei primcount); 128 129 behaves identically to DrawElements except that <primcount> 130 instances of the set of elements are executed, and the value of 131 <instanceID> advances for each iteration. It has the same effect 132 as: 133 134 if (mode, count, or type is invalid ) 135 generate appropriate error 136 else { 137 for (int i = 0; i < primcount; i++) { 138 instanceID = i; 139 DrawElements(mode, count, type, indices, i); 140 } 141 instanceID = 0; 142 } 143 144 Add a new section "2.15.4.2 Shader Inputs" before "Position 145 Invariance" 146 147 Besides having access to vertex attributes and uniform variables, vertex 148 shaders can access the read-only built-in variable gl_InstanceIDARB or 149 gl_InstanceID. The variables gl_InstanceIDARB and gl_InstanceID hold the 150 integer index of the current primitive in an instanced draw call. See 151 also section 7.1 of the OpenGL Shading Language Specification. 152 153Additions to Chapter 5 of the OpenGL 2.1 Specification 154(Special Functions) 155 156 The error INVALID_OPERATION is generated if DrawArraysInstancedARB 157 or DrawElementsInstancedARB is called during display list 158 compilation. 159 160Dependencies on NV_vertex_program4 161 162 If NV_vertex_program4 is not supported, all references to 163 vertex.instance are deleted. 164 165Errors 166 167 INVALID_ENUM is generated by DrawElementsInstancedARB if <type> is 168 not one of UNSIGNED_BYTE, UNSIGNED_SHORT or UNSIGNED_INT. 169 170 INVALID_VALUE is generated by DrawArraysInstancedARB if <first> is 171 less than zero. 172 173Modifications to The OpenGL Shading Language Specification, Version 1.10.59 174 175 Including the following line in a shader can be used to control the 176 language features described in this extension: 177 178 #extension GL_ARB_draw_instanced : <behavior> 179 180 where <behavior> is as specified in section 3.3. 181 182 A new preprocessor #define is added to the OpenGL Shading Language: 183 184 #define GL_ARB_draw_instanced 1 185 186 Change Section 7.1 "Vertex Shader Special Variables" 187 188 Add the following definitions to the list of built-in variable definitions: 189 190 int gl_InstanceIDARB; // read-only 191 int gl_InstanceID; // read-only 192 193 Add the following paragraph at the end of the section: 194 195 The variables gl_InstanceIDARB and gl_InstanceID are available as a 196 read-only variables from within vertex shaders and hold the integer index 197 of the current primitive in an instanced draw call 198 (DrawArraysInstancedARB, DrawElementsInstancedARB). If the current 199 primitive does not come from an instanced draw call, the values of 200 gl_InstanceIDARB and gl_InstanceID are zero. 201 202 203Issues 204 205 (1) Should instanceID be provided by this extension, or should it be 206 provided by the core OpenGL 3.0 (similarly to how it was done with 207 EXT_gpu_shader4)? 208 209 Resolved: Provide both instanceID and instanceIDARB. The original 210 intention was that instanceID and other language changes should be 211 provided by this extension and properly decorated with the ARB suffix. 212 However, many vendors shipped implementations that supported both, and 213 some applications came to depend on this out-of-spec behavior. It 214 appears that the EXT_gpu_shader4 incorrectly neglected to specify the 215 suffix EXT suffix for gl_InstanceID. 216 217 (2) Should MultiDrawArrays and MultiDrawElements affect the value of 218 instanceID? 219 220 Resolved: No, this may cause implementation difficulties and 221 is considered unlikely to provide any real benefit. 222 223 (3) Should DrawArraysInstanced and DrawElementsInstanced be compiled 224 into display lists? 225 226 Resolved: No, calling these during display list compilation 227 generate INVALID_OPERATION. 228 229 230Revision History 231 232 #5 April 8, 2011, Ian Romanick 233 - Fix typo "holds holds" 234 - Make both gl_InstanceID and gl_InstanceIDARB available to reflect 235 what vendors actually ship. 236 - Existence of gl_InstanceID and gl_InstanceIDARB do not depend on 237 OpenGL 3.0 or GL_EXT_gpu_shader4. 238 #4 July 8, 2008, jhelferty 239 - corrected dependency typo 240 - expanded Overview 241 #3 June 4, 2008, dgkoch 242 - merged instanceID and relevant language from the EXT_gpu_shader4 243 extension revision 13. 244 - renamed to InstanceID_ARB to properly follow conventions 245 - merged issues 1 & 4 246 #2 May 14 2008, jlheferty 247 - added contact, contributer information. 248 - bumped OpenGL spec written against to 2.1 249 - added issue 4 250 #1 May 12 2008, dgkoch 251 - initial conversion from EXT to ARB 252