1Name 2 3 ARB_shader_draw_parameters 4 5Name Strings 6 7 GL_ARB_shader_draw_parameters 8 9Contact 10 11 Graham Sellers (graham.sellers 'at' amd.com) 12 13Contributors 14 15 Piers Daniell, NVIDIA 16 Daniel Rakos, AMD 17 Christophe Riccio, OpenGL Garden (!) 18 Daniel Koch, NVIDIA 19 20Notice 21 22 Copyright (c) 2013 The Khronos Group Inc. Copyright terms at 23 http://www.khronos.org/registry/speccopyright.html 24 25Specification Update Policy 26 27 Khronos-approved extension specifications are updated in response to 28 issues and bugs prioritized by the Khronos OpenGL Working Group. For 29 extensions which have been promoted to a core Specification, fixes will 30 first appear in the latest version of that core Specification, and will 31 eventually be backported to the extension document. This policy is 32 described in more detail at 33 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 34 35Status 36 37 Complete. Approved by the ARB on June 3, 2013. 38 Ratified by the Khronos Board of Promoters on July 19, 2013. 39 40Version 41 42 Last Modified Date: 29 May 2017 43 Revision: 4 44 45Number 46 47 ARB Extension #156 48 49Dependencies 50 51 OpenGL 3.1 is required. 52 53 This extension is written against Version 4.3 of the Core Profile OpenGL 54 Specification, dated February 14, 2013 and Version 4.30 of the OpenGL 55 Shading Language Specification, dated February 7, 2013. 56 57 The presence of the GL_ARB_multi_draw_indirect extension affects the 58 definition of this extension. 59 60 The GL_ARB_indirect_parameters extension affects the definition of this 61 extension. 62 63Overview 64 65 In unextended GL, vertex shaders have inputs named gl_VertexID and 66 gl_InstanceID, which contain, respectively the index of the vertex and 67 instance. The value of gl_VertexID is the implicitly passed index of the 68 vertex being processed, which includes the value of baseVertex, for those 69 commands that accept it. Meanwhile, gl_InstanceID is the integer index 70 of the current instance being processed, but, even for commands that 71 accept a baseInstance parameter, it does not include the value of this 72 argument. Furthermore, the equivalents to these variables in other 73 graphics APIs do not necessarily follow these conventions. The reason for 74 this inconsistency is that there are legitimate use cases for both 75 inclusion and exclusion of the baseVertex or baseInstance parameters 76 in gl_VertexID and gl_InstanceID, respectively. 77 78 Rather than change the semantics of either built-in variable, this 79 extension adds two new built-in variables to the GL shading language, 80 gl_BaseVertexARB and gl_BaseInstanceARB, which contain the values passed 81 in the baseVertex and baseInstance parameters, respectively. Shaders 82 provided by the application may use these variables to offset gl_VertexID 83 or gl_InstanceID if desired, or use them for any other purpose. 84 85 Additionally, this extension adds a further built-in variable, gl_DrawID 86 to the shading language. This variable contains the index of the draw 87 currently being processed by a Multi* variant of a drawing command (such 88 as MultiDrawElements or MultiDrawArraysIndirect). 89 90New Procedures and Functions 91 92 None. 93 94New Tokens 95 96 None. 97 98IP Status 99 100 No known IP claims. 101 102Additions to Chapter 10 of the OpenGL Core Profile Specification, "Vertex 103Specification and Drawing Commands" 104 105 Add the following after the pseudo-code describing MultiDrawArrays on 106 p.310: 107 108 The index of the draw (<i> in the above pseudo-code) may be read by 109 a vertex shader as <gl_DrawIDARB>, as described in Section 11.1.3.9. 110 111 Add the following after the pseudo-code describing MultiDrawArraysIndirect 112 on p.311: 113 114 The index of the draw (<i> in the above pseudo-code) may be read by 115 a vertex shader as <gl_DrawIDARB>, as described in Section 11.1.3.9. 116 117 Add the following after the pseudo-code describing MultiDrawElements on 118 p.313: 119 120 The index of the draw (<i> in the above pseudo-code) may be read by 121 a vertex shader as <gl_DrawIDARB>, as described in Section 11.1.3.9. 122 123 Add the following after the pseudo-code describing 124 MultiDrawElementsIndirect on p.316: 125 126 The index of the draw (<i> in the above pseudo-code) may be read by 127 a vertex shader as <gl_DrawIDARB>, as described in Section 11.1.3.9. 128 129 Add the following after the pseudo-code describing 130 MultiDrawElementsBaseVertex on p.316: 131 132 The index of the draw (<i> in the above pseudo-code) may be read by 133 a vertex shader as <gl_DrawIDARB>, as described in Section 11.1.3.9. 134 135Additions to Chapter 11 of the OpenGL Core Profile Specification, "Programmable 136Vertex Processing" 137 138 In Section 11.1.1, "Vertex Attributes", in the description of 139 GetActiveAttrib, state that gl_DrawIDARB is enumerated: 140 141 For GetActiveAttrib, all active vertex shader input variables are 142 enumerated, including the special built-in inputs gl_VertexID, 143 gl_BaseVertexARB, gl_InstanceID, gl_BaseInstanceARB, and gl_DrawIDARB. 144 145 Replace the paragraphs describing gl_VertexID and gl_InstanceID in Section 146 11.1.3.9, "Shader Inputs" with the following: 147 148 Besides having access to vertex attributes and uniform variables, 149 vertex shaders can access the read-only built-in variables gl_VertexID, 150 gl_InstanceID, gl_BaseVertexARB, gl_BaseInstanceARB and gl_DrawIDARB. 151 152 <gl_VertexID> holds ... (retain original language) 153 154 <gl_BaseVertexARB> holds the integer value passed to the <baseVertex> 155 parameter to the command that resulted in the current shader invocation. 156 In the case where the command has no <baseVertex> parameter, the value 157 of <gl_BaseVertexARB> is zero. 158 159 <gl_InstanceID> holds ... (retain original language) 160 161 <gl_BaseInstanceARB> holds the integer value passed to the 162 <baseInstance> parameter to the command that resulted in the current 163 shader invocation. In the case where the command has no <baseInstance> 164 parameter, the value of <gl_BaseInstanceARB> is zero. 165 166 Add the following paragraph after the above discussion of <gl_InstanceID>: 167 168 <gl_DrawIDARB> holds the integer draw number the current draw being 169 processed by the shader invocation. It is dynamically uniform. In 170 MultiDraw* variants, this is the zero-based index of the draw within the 171 list of draws processed by the command. In non-MultiDraw* commands, the 172 value of <gl_DrawIDARB> is always zero. 173 174Errors 175 176 None. 177 178New State 179 180 None. 181 182Modifications to Chapter 7 of the OpenGL Shading Language Specification, 183Version 4.30. 184 185 Including the following line in a shader can be used to control the 186 language features described in this extension: 187 188 #extension GL_ARB_shader_draw_parameters : <behavior> 189 190 where <behavior> is as described in Section 3.3. 191 192 A new preprocessor #define is added to the OpenGL Shading Language: 193 194 #define GL_ARB_shader_draw_parameters 1 195 196 In Section 7.1, "Built-in Language Variables", add the following to the 197 list of input variables to a vertex shader, p.110: 198 199 in int gl_DrawIDARB; 200 in int gl_BaseVertexARB; 201 in int gl_BaseInstanceARB; 202 203 Add the following paragraph after the description of gl_InstanceID, p.114: 204 205 The variable <gl_DrawIDARB> is a vertex language input variable that 206 holds the integer index of the drawing command to which the current vertex 207 belongs (see "Shader Inputs" in section 11.1.3.9 of the OpenGL Graphics 208 System Specification). If the vertex is not invoked by a Multi* form of 209 a draw command, then the value of gl_DrawIDARB is zero. 210 211 The variable <gl_BaseVertexARB> is a vertex language input variable 212 that holds the integer value passed to the <baseVertex> parameter of the 213 command that resulted in the current shader invocation (see "Shader Inputs" 214 in section 11.1.3.9 of the OpenGL Graphics System Specification). 215 216 The variable <gl_BaseInstanceARB> is a vertex language input variable 217 that holds the integer value passed to the <baseInstance> parameter of 218 the command that resulted in the current shader invocation (see "Shader 219 Inputs" in section 11.1.3.9 of the OpenGL Graphics System Specification). 220 221Usage Examples 222 223--- Example 1 --- 224--- Using a different transformation matrix per draw --- 225--- Some draws can share the same matrix --- 226 227 layout(binding = INDIRECTION) uniform indirection 228 { 229 int Transform[MAX_DRAW]; 230 } Indirection; 231 232 layout(binding = TRANSFORM0) uniform transform 233 { 234 mat4 MVP[MAX_DRAW]; 235 } Transform; 236 237 layout(location = POSITION) in vec3 Position; 238 layout(location = TEXCOORD) in vec3 Texcoord; 239 240 out gl_PerVertex 241 { 242 vec4 gl_Position; 243 }; 244 245 out block 246 { 247 vec2 Texcoord; 248 } Out; 249 250 void main() 251 { 252 Out.Texcoord = Texcoord.st; 253 gl_Position = Transform.MVP[Indirection.Transform[gl_DrawIDARB]] * 254 vec4(Position, 1.0); 255 } 256 257Dependencies on GL_ARB_multi_draw_indirect 258 259 If GL_ARB_multi_draw_indirect is not supported, remove the language added 260 after the pseudo-code describing MultiDrawArraysIndirect and 261 MultiDrawElementsIndirect. 262 263Dependencies on GL_ARB_indirect_parameters 264 265 Whilst not a true dependency, it should be noted that the additional 266 commands introduced by ARB_indirect_parameters affect the value of 267 gl_DrawIDARB. 268 269Issues 270 271 1) - 272 273 2) - 274 275 3) What is the value of gl_DrawIDARB for non-Multi* draws? 276 277 RESOLVED: Zero. 278 279 4) Do we need language to clarify that gl_DrawIDARB is a dynamically 280 uniform expression? 281 282 RESOLVED: Yes, this allows accessing resources per-draw. 283 284 5) - 285 286 6) - 287 288Revision History 289 290 Rev. Date Author Changes 291 ---- -------- -------- ----------------------------------------- 292 293 1 05/16/2013 gsellers Initial draft 294 2 05/29/2013 gsellers Add descriptions of gl_BaseVertexARB and 295 gl_BaseInstanceARB. 296 Document pseudo-dependency on 297 ARB_indirect_parameters. 298 3 06/05/2013 gsellers Remove controls over gl_VertexID and 299 gl_InstanceID, leaving only the 300 gl_BaseVertexARB and gl_BaseInstanceARB 301 variables. gl_DrawIDARB is unmodified. 302 Issues 1, 2, 5 and 6 become non-issues as 303 a result. 304 4 05/29/2017 dgkoch remove edit reference to non-existant 305 MultiDrawElementsInstancedBaseInstance function. 306 Fix typos. 307 308