1Name 2 3 NV_draw_instanced 4 5Name Strings 6 7 GL_NV_draw_instanced 8 9Contributors 10 Contributors to ARB_draw_instanced and EXT_gpu_shader4 11 Mathias Heyer, NVIDIA 12 Greg Roth, NVIDIA 13 14Contact 15 16 Greg Roth, NVIDIA (groth 'at' nvidia 'dot' com) 17 18Status 19 20 Complete 21 22Version 23 24 Last Modified Date: Aug 28, 2012 25 Author Revision: 3 26 27Number 28 29 OpenGL ES Extension #141 30 31Dependencies 32 33 OpenGL ES 2.0 is required. 34 35 The extension is written against the OpenGL ES 2.0.25 Specification. 36 37 Written based on the wording of The OpenGL ES Shading Language 38 1.00.14 Specification. 39 40 OES_element_index_uint affects the definition of this extension. 41 42Overview 43 44 A common use case in GL for some applications is to be able to 45 draw the same object, or groups of similar objects that share 46 vertex data, primitive count and type, multiple times. This 47 extension provides a means of accelerating such use cases while 48 limiting the number of required API calls, and keeping the amount 49 of duplicate data to a minimum. 50 51 This extension introduces two draw calls which are conceptually 52 equivalent to a series of draw calls. Each conceptual call in 53 this series is considered an "instance" of the actual draw call. 54 55 This extension also introduces a read-only built-in variable to 56 GLSL which contains the "instance ID." This variable initially 57 contains 0, but increases by one after each conceptual draw call. 58 59 By using the instance ID or multiples thereof as an index into 60 a uniform array containing transform data, vertex shaders can 61 draw multiple instances of an object with a single draw call. 62 63New Procedures and Functions 64 65 void DrawArraysInstancedNV(enum mode, int first, sizei count, 66 sizei primcount); 67 void DrawElementsInstancedNV(enum mode, sizei count, enum type, 68 const void *indices, sizei primcount); 69 70New Tokens 71 72 None 73 74Additions to Chapter 2 of the OpenGL ES 2.0.25 Specification 75(OpenGL ES Operation) 76 77 Modify section 2.8 (Vertex Arrays) 78 79 (Insert before the final paragraph) 80 81 The internal counter <instanceID> is a 32-bit integer value which 82 may be read by a vertex shader as <gl_InstanceIDNV>, as 83 described in section 2.10.5.2. The value of this counter is 84 always zero, except as noted below. 85 86 The command 87 88 void DrawArraysInstancedNV(enum mode, int first, sizei count, 89 sizei primcount); 90 91 behaves identically to DrawArrays except that <primcount> 92 instances of the range 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, or primcount is invalid) 97 generate appropriate error 98 else { 99 for (i = 0; i < primcount; i++) { 100 instanceID = i; 101 DrawArrays(mode, first, count); 102 } 103 instanceID = 0; 104 } 105 106 The command 107 108 void DrawElementsInstancedNV(enum mode, sizei count, enum type, 109 const void *indices, sizei primcount); 110 111 behaves identically to DrawElements except that <primcount> 112 instances of the set of elements are executed, and the value of 113 <instanceID> advances for each iteration. It has the same effect 114 as: 115 116 if (mode, count, primcount, or type is invalid ) 117 generate appropriate error 118 else { 119 for (int i = 0; i < primcount; i++) { 120 instanceID = i; 121 DrawElements(mode, count, type, indices); 122 } 123 instanceID = 0; 124 } 125 126 Add a new section 2.10.5.2 "Shader Inputs" after "Texture Access" in 127 Section 2.10.5 "Shader Execution". 128 129 Besides having access to vertex attributes and uniform variables, 130 vertex shaders can access the read-only built-in variable 131 gl_InstanceIDNV. The variable gl_InstanceIDNV holds the integer 132 index of the current primitive in an instanced draw call. See also 133 section 7.1 of the OpenGL ES Shading Language Specification. 134 135 136Modifications to The OpenGL ES Shading Language Specification, Version 1371.00.14 138 139 Including the following line in a shader can be used to control the 140 language features described in this extension: 141 142 #extension GL_NV_draw_instanced : <behavior> 143 144 where <behavior> is as specified in section 3.4. 145 146 A new preprocessor #define is added to the OpenGL Shading Language: 147 148 #define GL_NV_draw_instanced 1 149 150 Change Section 7.1 "Vertex Shader Special Variables" 151 152 Add the following paragraph after the description of gl_PointSize: 153 154 The variable gl_InstanceIDNV is available as a read-only variable 155 from within vertex shaders and holds the integer index of the 156 current primitive in an instanced draw call (DrawArraysInstancedNV, 157 DrawElementsInstancedNV). If the current primitive does not come 158 from an instanced draw call, the value of gl_InstanceIDNV is zero. 159 160 Add the following definitions to the list of built-in variable definitions: 161 162 int gl_InstanceIDNV; // read-only 163 164 165Dependencies on OES_element_index_uint 166 167 If OES_element_index_uint is not supported, removed all references 168 to UNSIGNED_INT indices and the associated GL data type uint in 169 the description of DrawElementsInstancedNV. 170 171Errors 172 173 INVALID_ENUM is generated by DrawElementsInstancedNV if <type> is 174 not one of UNSIGNED_BYTE, UNSIGNED_SHORT or UNSIGNED_INT. 175 176 INVALID_VALUE is generated by DrawArraysInstancedNV if <first>, 177 <count>, or <primcount> is less than zero. 178 179 INVALID_ENUM is generated by DrawArraysInstancedNV or 180 DrawElementsInstancedNV if <mode> is not one of the modes described in 181 section 2.6.1. 182 183 INVALID_VALUE is generated by DrawElementsInstancedNV if <count> or 184 <primcount> is less than zero. 185 186Issues 187 188 1) Should this exist as a separate extension from NV_instanced_arrays? 189 190 Resolved: Yes. Even though these extensions expose similar 191 functionality and together they represent a more cohesive extension 192 with slightly less tricky text in the process, keeping them separate 193 makes the relationship with the desktop extensions clear. 194 195Revision History 196 197 Rev. Date Author Changes 198 ---- ------------- --------- ---------------------------------------- 199 3 28 Aug 2012 groth Minor copy edits and corrections to spec references 200 2 19 Aug 2012 groth Correct illustrative code samples 201 1 12 Aug 2012 groth Initial GLES2 version from ARB_draw_instanced and EXT_gpu_shader4 202