1Name
2
3    ANGLE_base_vertex_base_instance
4
5Name Strings
6
7    GL_ANGLE_base_vertex_base_instance
8
9Contributors
10
11    Shrek Shao, Google Inc.
12    Contributors to the OES_draw_elements_base_vertex specification
13    Contributors to the EXT_draw_elements_base_vertex specification
14    Contributors to the EXT_multi_draw_arrays specification
15    Contributors to the ARB_shader_draw_parameters specification
16
17Contact
18
19    Shrek Shao (shrekshao 'at' google.com)
20
21Status
22
23    Incomplete
24
25Version
26
27    Last Modified Date: July 14, 2020
28    Author Revision: 2
29
30Number
31
32    OpenGL ES Extension XX
33
34Dependencies
35
36    OpenGL ES 3.1 is required.
37
38    This extension is written against the OpenGL ES 3.1 specification, the
39    OpenGL ES 3.2 specification, and the OpenGL ES Shading Language 3.0
40    specification.
41
42    GL_ANGLE_multi_draw is required.
43
44Overview
45
46    This extension exposes the *BaseVertex* draw call in
47    OES_draw_elements_base_vertex/EXT_draw_elements_base_vertex together with
48    their newly added *BaseInstance and MultiDraw* variants in addition to the
49    vertex shader builtins <gl_BaseVertex> and <gl_BaseInstance> exposed by
50    ARB_shader_draw_parameters for OpenGL.
51
52    *BaseInstance behaves identically to its counterpart draw calls except that
53    <instanceCount> instances of the range of elements are executed and the
54    value of <instance> advances for each iteration. Those attributes that have
55    non-zero values for <divisor>, as specified by VertexAttribDivisor, advance
56    once per <divisor> instances of the set(s) of vertices being rendered.
57    Additionally, <baseInstance> specifies the first element within the
58    instanced vertex attributes.
59
60    *BaseVertex* is equivalent to its counterpart draw calls except that
61    the value of the base vertex passed into the driver is <baseVertex> instead
62    of zero, and that <instances> of the set of elements are executed and the
63    value of <instance> advances between each set.
64
65    Additionally, <gl_BaseVertex> and <gl_BaseInstance> builtins are added
66    to the shading language.
67    For any *BaseVertex* draw call variant, the <baseVertex> of the draw may be
68    read by the vertex shader as <gl_BaseVertex>. For non *BaseVertex* calls,
69    the value of <gl_BaseVertex> is 0.
70    For any *BaseInstance draw call variant, the baseInstance of the draw may
71    be read by the vertex shader as <gl_BaseInstance>. For non *BaseInstance
72    calls, the value of <gl_BaseInstance> is 0.
73
74IP Status
75
76    No known IP claims.
77
78New Procedures and Functions
79
80    void DrawArraysInstancedBaseInstanceANGLE(enum mode,
81                                              GLint first,
82                                              GLsizei count,
83                                              GLsizei instanceCount,
84                                              GLuint baseInstance);
85
86    void DrawElementsInstancedBaseVertexBaseInstanceANGLE(GLenum mode,
87                                                        GLsizei count,
88                                                        GLenum type,
89                                                        const GLvoid *indices,
90                                                        GLsizei instanceCount,
91                                                        GLint baseVertex,
92                                                        GLuint baseInstance);
93
94    void MultiDrawArraysInstancedBaseInstanceANGLE(enum mode,
95                                                const GLint* firsts,
96                                                const GLsizei* counts,
97                                                const GLsizei* instanceCounts,
98                                                const GLuint* baseInstances,
99                                                const GLsizei drawcount);
100
101    void MultiDrawElementsInstancedBaseVertexBaseInstanceANGLE(enum mode,
102                                                const GLint* counts,
103                                                GLenum type,
104                                                const GLvoid* const* indices,
105                                                const GLsizei* instanceCounts,
106                                                const GLint* baseVertices,
107                                                const GLuint* baseInstances,
108                                                const GLsizei drawcount);
109
110New Tokens
111
112    None.
113
114Additions to Chapter 10 of the OpenGL ES 3.2 Specification
115
116    Section 10.5 Drawing Commands Using Vertex Arrays:
117
118    The command
119
120    void DrawArraysInstancedBaseInstanceANGLE (GLenum mode,
121        GLint first,
122        GLsizei count,
123        GLsizei instanceCount,
124        GLuint baseInstance);
125
126    Behaves identically to DrawArraysInstanced except that <baseInstance> is
127    passed down to DrawArraysOneInstance instead of zero.
128
129    The base index of the instance may be read by a vertex shader as
130    <gl_BaseInstance>.
131
132    The command
133
134    void MultiDrawArraysInstancedBaseInstanceANGLE(GLenum mode,
135        const GLint* firsts,
136        const GLsizei* counts,
137        const GLsizei* instanceCounts,
138        const GLuint* baseInstances,
139        GLsizei drawcount);
140
141    Behaves identically to DrawArraysInstancedBaseInstanceANGLE except that a
142    list of arrays is specified instead. The number of lists is specified in
143    the <drawcount> parameter. It has the same effect as:
144
145      for(i=0; i<drawcount; i++) {
146        if (*(counts+i)>0) DrawArraysInstancedBaseInstance(
147                mode,
148                *(counts+i),
149                *(instanceCounts+i),
150                *(firsts+i),
151                *(baseInstance+i)
152            );
153      }
154
155    The index of the draw (<i> in the above pseudo-code) may be read by
156    a vertex shader as <gl_DrawID> which is defined in GL_ANGLE_multi_draw.
157
158    The command
159
160    void DrawElementsInstancedBaseVertexBaseInstanceANGLE (GLenum mode,
161        GLsizei count,
162        GLenum type,
163        const GLvoid* indices,
164        GLsizei instanceCount,
165        GLint baseVertex,
166        GLuint baseInstance);
167
168    Behaves identically to DrawElementsInstanced except that <baseVertex> and
169    <baseInstance> are passed down to DrawElementsOneInstance instead of zero.
170
171    The base index of the vertex may be read by a vertex shader as
172    <gl_BaseVertex>. This value is also added to the <gl_VertexID>.
173
174    The base index of the instance may be read by a vertex shader as
175    <gl_BaseInstance>. Note that this value is not added to the
176    <gl_InstanceID>.
177
178    The command
179
180    void MultiDrawElementsInstancedBaseVertexBaseInstanceANGLE(GLenum mode,
181        const GLsizei* counts,
182        GLenum type,
183        const GLvoid* const* indices,
184        const GLsizei* instanceCounts,
185        const GLint* baseVertices,
186        const GLuint* baseInstances,
187        GLsizei drawcount);
188
189    Behaves identically to DrawElementsInstancedBaseVertexBaseInstanceANGLE
190    except that a list of arrays is specified instead. The number of lists is
191    specified in the <drawcount> parameter. It has the same effect as:
192
193      for(i=0; i<drawcount; i++) {
194        if (*(counts+i)>0) DrawElementsInstancedBaseVertexBaseInstanceANGLE(
195                mode,
196                *(counts+i),
197                type,
198                *(instanceCounts+i),
199                *(indices+i),
200                *(baseVertices+i),
201                *(baseInstances+i)
202            );
203      }
204
205    The index of the draw (<i> in the above pseudo-code) may be read by
206    a vertex shader as <gl_DrawID> which is defined in GL_ANGLE_multi_draw.
207
208Errors
209
210    DrawArraysInstancedBaseInstanceANGLE and
211    DrawElementsInstancedBaseVertexBaseInstanceANGLE
212    generate the same errors as DrawArraysInstanced and DrawElementsInstanced.
213
214    MultiDrawArraysInstancedBaseInstanceANGLE and
215    MultiDrawElementsInstancedBaseVertexBaseInstanceANGL
216    generate the same errors as DrawArraysInstanced and DrawElementsInstanced,
217    respectively, for any draw <i> where an error is generated. If any call
218    would produce an error, no drawing is performed.
219
220    The error INVALID_VALUE is generated by the MultiDraw* functions if
221    <drawcount> is less than zero.
222
223Modifications to the OpenGL ES Shading Language Specification, Version 3.00
224
225    Including the following line in a shader can be used to control the
226    language featured described in this extension:
227
228      #extension GL_ANGLE_base_vertex_base_instance : <behavior>
229
230    where <behavior> is as specified in section 3.5.
231
232    A new preprocessor #define is added to the OpenGL ES Shading Language:
233
234      #define GL_ANGLE_base_vertex_base_instance 1
235
236Dependencies on GL_OES_draw_elements_base_vertex and
237GL_EXT_draw_elements_base_vertex
238
239    If the OpenGL ES context version is less than 3.2, this extension is only
240    available when GL_OES_draw_elements_base_vertex or
241    GL_EXT_draw_elements_base_vertex are available.
242
243Issues
244
245    None
246
247Revision History
248
249    Rev.    Date    Author       Changes
250    ----  --------  ----------   --------------------------------------------
251    1     08/13/19   Shrek Shao   First revision.
252    2     07/14/20   Shrek Shao   Fix baseInstance type from GLint to GLuint.
253