| Name |
| |
| EXT_instanced_arrays |
| |
| Name Strings |
| |
| GL_EXT_instanced_arrays |
| |
| Contributors |
| |
| Contributors to ARB_instanced_arrays desktop OpenGL extension |
| from which this extension borrows heavily |
| Abhijit Bhelande, Apple |
| Benj Lipchak, Apple |
| |
| Contact |
| |
| Benj Lipchak, Apple (lipchak 'at' apple.com) |
| |
| Status |
| |
| Complete |
| |
| Version |
| |
| Last Modified Date: June 26, 2013 |
| Revision: 2 |
| |
| Number |
| |
| OpenGL ES Extension #156 |
| |
| Dependencies |
| |
| OpenGL ES 2.0 is required. |
| |
| This extension is written against the OpenGL ES 2.0 Specification. |
| |
| OES_element_index_uint affects the definition of this extension. |
| |
| 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 |
| reducing 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_EXT 0x88FE |
| |
| New Procedures and Functions |
| |
| void VertexAttribDivisorEXT(uint index, uint divisor); |
| void DrawArraysInstancedEXT(enum mode, int first, sizei count, |
| sizei instanceCount); |
| void DrawElementsInstancedEXT(enum mode, sizei count, enum type, |
| const void *indices, sizei instanceCount); |
| |
| Additions to Chapter 2 of the OpenGL ES 2.0 Specification |
| |
| Modify section 2.8 (Vertex Arrays), p. 21 |
| |
| (insert before section Transferring Array Elements, p. 21) |
| |
| "The command |
| |
| void VertexAttribDivisorEXT(uint index, uint divisor); |
| |
| modifies the rate at which generic vertex attributes advance, which is |
| useful when rendering multiple instances of primitives in a single draw call |
| (see DrawArraysInstancedEXT and DrawElementsInstancedEXT 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. |
| |
| An INVALID_VALUE error is generated if <index> is greater than or equal to |
| the value of MAX_VERTEX_ATTRIBS." |
| |
| (replace all occurrences of "DrawArrays or DrawElements" with "DrawArrays, |
| DrawElements, or the other Draw* commands", for example the first sentence |
| of Transferring Array Elements, p. 21) |
| |
| "When an array element i is transferred to the GL by DrawArrays, |
| DrawElements, or the other Draw* commands described below, each generic |
| attribute is expanded to four components." |
| |
| (replace second through fourth paragraphs of Transferring Array Elements) |
| |
| "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 command constructs a sequence of geometric primitives |
| by successively transferring elements for <count> vertices. Elements <first> |
| through <first> + <count> − 1 of each enabled non-instanced array are |
| transferred 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 |
| <divisor> as specified by VertexAttribDivisorEXT), the element that is |
| transferred to the GL, for all vertices, is given by: |
| |
| floor(instance / divisor) |
| |
| If an array corresponding to a generic attribute 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 |
| 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 DrawArraysInstancedEXT(enum mode, int first, sizei count, |
| sizei instanceCount); |
| |
| behaves identically to DrawArrays except that <instanceCount> instances of |
| the range of elements are executed and the value of <instance> advances |
| for each iteration. Those attributes that have non-zero values for |
| <divisor>, as specified by VertexAttribDivisorEXT, advance once every |
| <divisor> instances. It has the same effect as: |
| |
| if (mode, count, or instanceCount is invalid) |
| generate appropriate error |
| else { |
| for (i = 0; i < instanceCount; i++) { |
| DrawArraysOneInstance(mode, first, count, i); |
| } |
| } |
| |
| The command |
| |
| void DrawElementsOneInstance(enum mode, sizei count, enum type, |
| const 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 elements for <count> vertices. The ith element |
| transferred by DrawElementsOneInstance will be taken from element |
| <indices>[i] of each enabled non-instanced array, where <indices> specifies |
| the location in memory of the first index of the element array being |
| specified. <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 |
| <divisor> as specified by VertexAttribDivisorEXT), the element that is |
| transferred to the GL, for all vertices, is given by: |
| |
| floor(instance / divisor) |
| |
| If an array corresponding to a generic attribute 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 DrawElementsInstancedEXT(enum mode, sizei count, enum type, |
| const void *indices, sizei instanceCount); |
| |
| behaves identically to DrawElements except that <instanceCount> instances of |
| the set of elements are executed and the value of <instance> advances |
| between each set. Instanced attributes are advanced as they do during |
| execution of DrawArraysInstancedEXT. It has the same effect as: |
| |
| if (mode, count, instanceCount, or type is invalid) |
| generate appropriate error |
| else { |
| for (int i = 0; i < instanceCount; i++) { |
| DrawElementsOneInstance(mode, count, type, indices, i); |
| } |
| } |
| |
| (append to first sentence of last paragraph of Transferring Array Elements) |
| |
| "..., and n integers representing vertex attribute divisors." |
| |
| (append to last sentence of last paragraph of Transferring Array Elements) |
| |
| "..., the divisors are each zero." |
| |
| Additions to Chapter 6 of the OpenGL ES 2.0 Specification (State and State |
| Requests) |
| |
| In section 6.1.8, add to the list of pnames accepted by GetVertexAttrib*v: |
| VERTEX_ATTRIB_ARRAY_DIVISOR_EXT |
| |
| Dependencies on OES_element_index_uint |
| |
| If OES_element_index_uint is not supported, remove references to |
| UNSIGNED_INT as a valid <type> for DrawElements*. |
| |
| Errors |
| |
| INVALID_VALUE is generated by VertexAttribDivisorEXT if <index> |
| is greater than or equal to MAX_VERTEX_ATTRIBS. |
| |
| INVALID_ENUM is generated by DrawElementsInstancedEXT if <type> is |
| not one of UNSIGNED_BYTE, UNSIGNED_SHORT or UNSIGNED_INT. |
| |
| INVALID_VALUE is generated by DrawArraysInstancedEXT if <first>, |
| <count>, or <instanceCount> is less than zero. |
| |
| INVALID_VALUE is generated by DrawElementsInstancedEXT if <count> or |
| <instanceCount> is less than zero. |
| |
| INVALID_ENUM is generated by DrawArraysInstancedEXT or |
| DrawElementsInstancedEXT if <mode> is not one of the kinds of primitives |
| accepted by DrawArrays and DrawElements. |
| |
| |
| New State |
| |
| Changes to table 6.2, p. 136 (Vertex Array Data) |
| Initial |
| Get Value Type Get Command Value Description Sec. |
| --------- ---- ----------- ------- ----------- ---- |
| VERTEX_ATTRIB_ARRAY_DIVISOR_EXT 16* x Z+ GetVertexAttribiv 0 Vertex attrib array 2.8 |
| instance divisor |
| Issues |
| |
| None |
| |
| Revision History |
| |
| #1 November 11 2012, Abhijit Bhelande and Benj Lipchak |
| - initial conversion from ARB to APPLE for ES2 |
| #2 June 26 2013, Benj Lipchak |
| - promotion from APPLE to EXT |