1Name
2
3    ANGLE_multi_draw
4
5Name Strings
6
7    GL_ANGLE_multi_draw
8
9Contributors
10
11    Austin Eng, Google Inc.
12    Kai Ninomiya, Google Inc.
13    Kenneth Russell, Google Inc.
14    Contributors to the EXT_multi_draw_arrays specification
15    Contributors to the ARB_shader_draw_parameters specification
16
17Contact
18
19    Austin Eng (enga 'at' google.com)
20
21Status
22
23    Incomplete
24
25Version
26
27    Last Modified Date: October 24, 2018
28    Author Revision: 1
29
30Number
31
32    OpenGL ES Extension XX
33
34Dependencies
35
36    OpenGL ES 2.0 is required.
37
38    This extension is written against the OpenGL ES 2.0 specification,
39    the OpenGL ES 3.0 specification, and the OpenGL ES Shading Language 3.0
40    specification.
41
42    The presence of the GL_ANGLE_instanced_arrays or GL_EXT_instanced_arrays
43    extensions affects the definition of this extension.
44
45Overview
46
47    This extension exposes the Multi* draw call variants in
48    EXT_multi_draw_arrays functionality in addition to the vertex shader builtin
49    gl_DrawID exposed by ARB_shader_draw_parameters for OpenGL.
50
51    These functions behave identically to the standard functions
52    DrawArrays() and DrawElements() except they handle multiple lists of
53    vertices in one call. Their main purpose is to allow one function call
54    to render more than one primitive such as triangle strip, triangle fan,
55    etc.
56
57    Additionally, this extension adds a further built-in variable, gl_DrawID
58    to the shading language. This variable contains the index of the draw
59    currently being processed by a Multi* variant of a drawing command.
60
61IP Status
62
63    No known IP claims.
64
65New Procedures and Functions
66
67    void MultiDrawArraysANGLE(enum mode,
68                              const GLint* firsts,
69                              const GLsizei* counts,
70                              const GLsizei drawcount);
71
72    void MultiDrawElementsANGLE(enum mode,
73                                const GLint* counts,
74                                GLenum type,
75                                const GLvoid* const* indices,
76                                const GLsizei drawcount);
77
78    void MultiDrawArraysInstancedANGLE(enum mode,
79                                       const GLint* firsts,
80                                       const GLsizei* counts,
81                                       const GLsizei* instanceCounts,
82                                       const GLsizei drawcount);
83
84    void MultiDrawElementsInstancedANGLE(enum mode,
85                                         const GLint* counts,
86                                         GLenum type,
87                                         const GLvoid* const* indices,
88                                         const GLsizei* instanceCounts,
89                                         const GLsizei drawcount);
90
91New Tokens
92
93    None.
94
95Additions to Chapter 2 of the OpenGL ES 2.0 Specification
96
97    Section 2.8 Vertex Arrays:
98
99    The command
100
101      void MultiDrawArraysANGLE(GLenum mode,
102              const GLint* firsts,
103              const GLsizei *counts,
104              GLsizei drawcount)
105
106    Behaves identically to DrawArrays except that a list of arrays is
107    specified instead. The number of lists is specified in the drawcount
108    parameter. It has the same effect as:
109
110      for(i=0; i<drawcount; i++) {
111        if (*(counts+i)>0) DrawArrays(mode, *(firsts+i), *(counts+i));
112      }
113
114    The index of the draw (<i> in the above pseudo-code) may be read by
115    a vertex shader as <gl_DrawID>.
116
117    The command
118
119      void MultiDrawElementsANGLE(GLenum mode,
120                GLsizei* counts,
121                GLenum type,
122                const GLvoid* const* indices,
123                GLsizei drawcount)
124
125    Behaves identically to DrawElements except that a list of arrays is
126    specified instead. The number of lists is specified in the drawcount
127    parameter. It has the same effect as:
128
129      for(i=0; i<drawcount; i++) {
130          if (*(counts+i)>0) {
131              DrawElements(mode, *(counts+i), type, *(indices+i));
132          }
133      }
134
135    The index of the draw (<i> in the above pseudo-code) may be read by
136    a vertex shader as <gl_DrawID>.
137
138Additions to Chapter 2 of the OpenGL ES 3.0 Specification
139
140    Section 2.9.3 Drawing Commands:
141
142    The command
143
144      void MultiDrawArraysInstancedANGLE(
145              GLenum mode,
146              const GLint* firsts,
147              const GLsizei *counts,
148              const GLsizei* instanceCounts,
149              GLsizei drawcount)
150
151    Behaves identically to DrawArraysInstanced except that a list of arrays is
152    specified instead. The number of lists is specified in the drawcount
153    parameter. It has the same effect as:
154
155      for(i=0; i<drawcount; i++) {
156        if (*(counts+i)>0) DrawArraysInstanced(mode, *(firsts+i), *(counts+i),
157              *(instanceCounts+1));
158      }
159
160    The index of the draw (<i> in the above pseudo-code) may be read by
161    a vertex shader as <gl_DrawID>.
162
163    The command
164
165      void MultiDrawElementsInstancedANGLE(
166                GLenum mode,
167                GLsizei* counts,
168                GLenum type,
169                const GLvoid* const* indices,
170                const GLsizei* instanceCounts,
171                GLsizei drawcount)
172
173    Behaves identically to DrawElementsInstanced except that a list of arrays is
174    specified instead. The number of lists is specified in the drawcount
175    parameter. It has the same effect as:
176
177      for(i=0; i<drawcount; i++) {
178          if (*(counts+i)>0) {
179              DrawElementsInstanced(mode, *(counts+i), type,
180                                    *(indices+i), *(instanceCounts+1));
181          }
182      }
183
184    The index of the draw (<i> in the above pseudo-code) may be read by
185    a vertex shader as <gl_DrawID>.
186
187Errors
188
189    The error INVALID_VALUE is generated by the new functions if <drawcount>
190    is less than 0.
191
192    MultiDrawArraysANGLE, MultiDrawElementsANGLE,
193    MultiDrawArraysInstancedANGLE, and MultiDrawElementsInstancedANGLE generate
194    the same errors as DrawArrays, DrawElements, DrawArraysInstanced,
195    and DrawElementsInstanced, respectively, for any draw <i> where an error
196    is generated. If any call would produce an error, no drawing is performed.
197
198Modifications to the OpenGL ES Shading Language Specification, Version 3.00
199
200    Including the following line in a shader can be used to control the
201    language featured described in this extension:
202
203      #extension GL_ANGLE_multi_draw : <behavior>
204
205    where <behavior> is as specified in section 3.5.
206
207    A new preprocessor #define is added to the OpenGL ES Shading Language:
208
209      #define GL_ANGLE_multi_draw 1
210
211Dependencies on GL_ANGLE_instanced_arrays
212
213    If GL_ANGLE_instanced_arrays or GL_EXT_instanced_arrays is enabled,
214    append the lanuage in "Additions to Chapter 2 of the OpenGL ES 3.0
215    Specification, Section 2.9.3 Drawing Commands" to the language in
216    "Additions to Chapter 2 of the OpenGL ES 2.0 Specification, Section
217    2.8 Vertex Arrays".
218
219    If GL_ANGLE_instanced_arrays or GL_EXT_instanced_arrays is not enabled
220    and the context is less than a OpenGL ES 3.0 context, the error
221    INVALID_OPERATION is generated by any call to the functions
222    MultiDrawArraysInstancedANGLE and MultiDrawElementsInstancedANGLE.
223
224Issues
225    None
226
227Revision History
228
229    Rev.    Date    Author       Changes
230    ----  --------  ----------   --------------------------------------------
231    1     10/24/18   Austin Eng  First revision.
232    2     10/25/18   Austin Eng  Second revision. Add instanced variants
233