| Name |
| |
| ANGLE_instanced_arrays |
| |
| Name Strings |
| |
| GL_ANGLE_instanced_arrays |
| |
| Contributors |
| |
| Contributors to ARB_instanced_arrays |
| Nicolas Capens, TransGaming Inc. |
| James Helferty, TransGaming Inc. |
| Kenneth Russell, Google Inc. |
| Vangelis Kokkevis, Google Inc. |
| |
| Contact |
| |
| Daniel Koch, TransGaming Inc. (daniel 'at' transgaming.com) |
| |
| Status |
| |
| Implemented in ANGLE r976. |
| |
| Version |
| |
| Last Modified Date: February 8, 2012 |
| Author Revision: 3 |
| |
| Number |
| |
| OpenGL ES Extension #109 |
| |
| Dependencies |
| |
| OpenGL ES 2.0 is required. |
| |
| This extension is written against the OpenGL ES 2.0 Specification. |
| |
| Overview |
| |
| A common use case in GL for some applications is to be able to |
| draw the same object, or groups of similar objects that share |
| vertex data, primitive count and type, multiple times. This |
| extension provides a means of accelerating such use cases while |
| restricting the number of API calls, and keeping the amount of |
| duplicate data to a minimum. |
| |
| This extension introduces an array "divisor" for generic |
| vertex array attributes, which when non-zero specifies that the |
| attribute is "instanced." An instanced attribute does not |
| advance per-vertex as usual, but rather after every <divisor> |
| conceptual draw calls. |
| |
| (Attributes which aren't instanced are repeated in their entirety |
| for every conceptual draw call.) |
| |
| By specifying transform data in an instanced attribute or series |
| of instanced attributes, vertex shaders can, in concert with the |
| instancing draw calls, draw multiple instances of an object with |
| one draw call. |
| |
| IP Status |
| |
| No known IP claims. |
| |
| New Tokens |
| |
| Accepted by the <pname> parameters of GetVertexAttribfv and |
| GetVertexAttribiv: |
| |
| VERTEX_ATTRIB_ARRAY_DIVISOR_ANGLE 0x88FE |
| |
| New Procedures and Functions |
| |
| void DrawArraysInstancedANGLE(enum mode, int first, sizei count, |
| sizei primcount); |
| |
| void DrawElementsInstancedANGLE(enum mode, sizei count, enum type, |
| const void *indices, sizei primcount); |
| |
| void VertexAttribDivisorANGLE(uint index, uint divisor); |
| |
| Additions to Chapter 2 of the OpenGL ES 2.0 Specification |
| (OpenGL ES Operation) |
| |
| Modify section 2.8 (Vertex Arrays), p. 21 |
| |
| After description of EnableVertexAttribArray / DisableVertexAttribArray |
| add the following: |
| |
| "The command |
| |
| void VertexAttribDivisorANGLE(uint index, uint divisor); |
| |
| modifies the rate at which generic vertex attributes advance when |
| rendering multiple instances of primitives in a single draw call |
| (see DrawArraysInstancedANGLE and DrawElementsInstancedANGLE below). |
| If <divisor> is zero, the attribute at slot <index> advances once |
| per vertex. If <divisor> is non-zero, the attribute advances once |
| per <divisor> instances of the primitives being rendered. |
| An attribute is referred to as "instanced" if its <divisor> value is |
| non-zero." |
| |
| Replace the text describing DrawArrays and DrawElements in the |
| "Transferring Array Elements" subsection of 2.8, from the second paragraph |
| through the end of the section with the following: |
| |
| "The command |
| |
| void DrawArraysOneInstance( enum mode, int first, sizei count, int instance ); |
| |
| does not exist in the GL, but is used to describe functionality in |
| the rest of this section. This function constructs a sequence of |
| geometric primitives by transferring elements <first> through <first> + |
| <count> - 1 of each enabled non-instanced array to the GL. <mode> |
| specifies what kind of primitives are constructed, as defined in section |
| 2.6.1. |
| |
| If an enabled vertex attribute array is instanced (it has a non-zero |
| attribute <divisor> as specified by VertexAttribDivisorANGLE), the element |
| that is transferred to the GL is given by: |
| |
| floor( <instance> / <divisor> ). |
| |
| If an array corresponding to a generic attribute required by a vertex shader |
| is not enabled, then the corresponding element is taken from the current |
| generic attribute state (see section 2.7). |
| |
| If an array corresponding to a generic attribute required by a vertex shader |
| is enabled, the corresponding current generic attribute value is unaffected |
| by the execution of DrawArraysOneInstance. |
| |
| Specifying <first> < 0 results in undefined behavior. Generating the error |
| INVALID_VALUE is recommended in this case. |
| |
| The command |
| |
| void DrawArrays( enum mode, int first, sizei count ); |
| |
| is equivalent to the command sequence |
| |
| DrawArraysOneInstance(mode, first, count, 0); |
| |
| The command |
| |
| void DrawArraysInstancedANGLE(enum mode, int first, sizei count, |
| sizei primcount); |
| |
| behaves identically to DrawArrays except that <primcount> |
| instances of the range of elements are executed, and the |
| <instance> advances for each iteration. Instanced attributes that |
| have <divisor> N, (where N > 0, as specified by |
| VertexAttribDivisorANGLE) advance once every N instances. |
| |
| It has the same effect as: |
| |
| if (mode, count, or primcount is invalid) |
| generate appropriate error |
| else { |
| for (i = 0; i < primcount; i++) { |
| DrawArraysOneInstance(mode, first, count, i); |
| } |
| } |
| |
| The command |
| |
| void DrawElementsOneInstance( enum mode, sizei count, enum type, |
| void *indices, int instance ); |
| |
| does not exist in the GL, but is used to describe functionality in |
| the rest of this section. This command constructs a sequence of |
| geometric primitives by successively transferring the <count> elements |
| whose indices are stored in the currently bound element array buffer |
| (see section 2.9.2) at the offset defined by <indices> to the GL. |
| The <i>-th element transferred by DrawElementsOneInstance will be taken |
| from element <indices>[i] of each enabled non-instanced array. |
| <type> must be one of UNSIGNED_BYTE, UNSIGNED_SHORT, or UNSIGNED_INT, |
| indicating that the index values are of GL type ubyte, ushort, or uint |
| respectively. <mode> specifies what kind of primitives are constructed, |
| as defined in section 2.6.1. |
| |
| If an enabled vertex attribute array is instanced (it has a non-zero |
| attribute <divisor> as specified by VertexAttribDivisorANGLE), the element |
| that is transferred to the GL is given by: |
| |
| floor( <instance> / <divisor> ); |
| |
| If an array corresponding to a generic attribute required by a vertex |
| shader is not enabled, then the corresponding element is taken from the |
| current generic attribute state (see section 2.7). Otherwise, if an array |
| is enabled, the corresponding current generic attribute value is |
| unaffected by the execution of DrawElementsOneInstance. |
| |
| The command |
| |
| void DrawElements( enum mode, sizei count, enum type, |
| const void *indices); |
| |
| behaves identically to DrawElementsOneInstance with the <instance> |
| parameter set to zero; the effect of calling |
| |
| DrawElements(mode, count, type, indices); |
| |
| is equivalent to the command sequence: |
| |
| if (mode, count or type is invalid ) |
| generate appropriate error |
| else |
| DrawElementsOneInstance(mode, count, type, indices, 0); |
| |
| The command |
| |
| void DrawElementsInstancedANGLE(enum mode, sizei count, enum type, |
| const void *indices, sizei primcount); |
| |
| behaves identically to DrawElements except that <primcount> |
| instances of the set of elements are executed and the instance |
| advances between each set. Instanced attributes are advanced as they do |
| during the execution of DrawArraysInstancedANGLE. It has the same effect as: |
| |
| if (mode, count, primcount, or type is invalid ) |
| generate appropriate error |
| else { |
| for (int i = 0; i < primcount; i++) { |
| DrawElementsOneInstance(mode, count, type, indices, i); |
| } |
| } |
| |
| If the number of supported generic vertex attributes (the value of |
| MAX_VERTEX_ATTRIBS) is <n>, then the client state required to implement |
| vertex arrays consists of <n> boolean values, <n> memory pointers, <n> |
| integer stride values, <n> symbolic constants representing array types, |
| <n> integers representing values per element, <n> boolean values |
| indicating normalization, and <n> integers representing vertex attribute |
| divisors. |
| |
| In the initial state, the boolean values are each false, the memory |
| pointers are each NULL, the strides are each zero, the array types are |
| each FLOAT, the integers representing values per element are each four, |
| and the divisors are each zero." |
| |
| Additions to Chapter 3 of the OpenGL ES 2.0 Specification (Rasterization) |
| |
| None |
| |
| Additions to Chapter 4 of the OpenGL ES 2.0 Specification (Per-Fragment |
| Operations and the Framebuffer) |
| |
| None |
| |
| Additions to Chapter 5 of the OpenGL ES 2.0 Specification (Special Functions) |
| |
| None |
| |
| Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State |
| Requests) |
| |
| In section 6.1.8, add VERTEX_ATTRIB_ARRAY_DIVISOR_ANGLE to the list of |
| pnames accepted by GetVertexAttribfv and GetVertexAttribiv. |
| |
| Additions to the AGL/EGL/GLX/WGL Specifications |
| |
| None |
| |
| Dependencies on OES_element_index_uint |
| |
| If OES_element_index_uint is not supported, removed all references |
| to UNSIGNED_INT indices and the associated GL data type uint in |
| the description of DrawElementsOneInstance. |
| |
| Errors |
| |
| INVALID_VALUE is generated by VertexAttribDivisorANGLE if <index> |
| is greater than or equal to MAX_VERTEX_ATTRIBS. |
| |
| INVALID_ENUM is generated by DrawElementsInstancedANGLE if <type> is |
| not one of UNSIGNED_BYTE, UNSIGNED_SHORT or UNSIGNED_INT. |
| |
| INVALID_VALUE is generated by DrawArraysInstancedANGLE if <first>, |
| <count>, or <primcount> is less than zero. |
| |
| INVALID_ENUM is generated by DrawArraysInstancedANGLE or |
| DrawElementsInstancedANGLE if <mode> is not one of the modes described in |
| section 2.6.1. |
| |
| INVALID_VALUE is generated by DrawElementsInstancedANGLE if <count> or |
| <primcount> is less than zero. |
| |
| INVALID_OPERATION is generated by DrawArraysInstancedANGLE or |
| DrawElementsInstancedANGLE if there is not at least one enabled |
| vertex attribute array that has a <divisor> of zero and is bound to an |
| active generic attribute value in the program used for the draw command. |
| |
| New State |
| |
| Changes to table 6.7, p. 268 (Vertex Array Data) |
| |
| Initial |
| Get Value Type Get Command Value Description Sec. |
| --------- ----- ----------- ------- ----------- ---- |
| VERTEX_ATTRIB_ARRAY_DIVISOR_ANGLE 8*xZ+ GetVertexAttrib 0 Instance Divisor 2.8 |
| |
| Issues |
| |
| 1) Should vertex attribute zero be instance-able? |
| |
| Resolved: Yes. |
| Discussion: In Direct3D 9 stream 0 must be specified as indexed data |
| and it cannot be instanced. In ANGLE we can work around this by |
| remapping any other stream that does have indexed data (ie a zero |
| attribute divisor) to stream 0 in D3D9. This works because the HLSL |
| vertex shader matches attributes against the stream by using the |
| shader semantic index. |
| |
| 2) Can all vertex attributes be instanced simultaneously? |
| |
| Resolved: No |
| Discussion: In rare cases it is possible for no attribute to have a |
| divisor of 0, meaning that all attributes are instanced and none of |
| them are regularly indexed. This in turn means each instance can only |
| have a single position element, and so it only actually renders |
| something when rendering point primitives. This is not a very |
| meaningful way of using instancing (which is likely why D3D restricts |
| stream 0 to be indexed regularly for position data in the first place). |
| We could implement it by drawing these points one at a time (essentially |
| emulating instancing), but it would not be very efficient and there |
| seems to be little-to-no value in doing so. |
| |
| If all of the enabled vertex attribute arrays that are bound to active |
| generic attributes in the program have a non-zero divisor, the draw |
| call should return INVALID_OPERATION. |
| |
| 3) Direct3D 9 only supports instancing for DrawIndexedPrimitive which |
| corresponds to DrawElementsInstanced. Should we support |
| DrawArraysInstanced? |
| |
| Resolved: Yes |
| Discussion: This can be supported easily enough by simply manufacturing |
| a linear index buffer of sufficient size and using that to do indexed |
| D3D9 drawing. |
| |
| 4) How much data is needed in a buffer for an instanced attribute? |
| |
| Resolved: Where stride is the value passed to VertexAttribPointer: |
| |
| if stride > 0 |
| size = stride * ceil(primcount / divisor); |
| else |
| size = elementsize * ceil(primcount / divisor); |
| |
| Revision History |
| |
| #3 February 8, 2012 dgkoch |
| - clarify Issue 3 and the error condition for no indexed attributes |
| #2 January 24, 2012 dgkoch |
| - fix typos, add clarifications, and more errors |
| #1 January 17, 2012 dgkoch |
| - initial GLES2 version from ARB_instanced_arrays |
