The Tor Browser: gfx/angle/extensions/ANGLE_instanced_arrays.txt@6474c204b198 (annotated)

gfx/angle/extensions/ANGLE_instanced_arrays.txt@6474c204b198 (annotated)

gfx/angle/extensions/ANGLE_instanced_arrays.txt

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 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
 .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
 ) 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.
 ) 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.
 ) 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.
 ) 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

The Tor Browser / annotate

gfx/angle/extensions/ANGLE_instanced_arrays.txt@6474c204b198 (annotated)

gfx/angle/extensions/ANGLE_instanced_arrays.txt