xref: /third_party/openGLES/extensions/ARB/ARB_transform_feedback_instanced.txt

Name

    ARB_transform_feedback_instanced

Name Strings

    GL_ARB_transform_feedback_instanced

Contact

    Graham Sellers, AMD (graham.sellers 'at' amd.com)

Contributors

    XXX

Notice

    Copyright (c) 2011-2013 The Khronos Group Inc. Copyright terms at
        http://www.khronos.org/registry/speccopyright.html

Specification Update Policy

    Khronos-approved extension specifications are updated in response to
    issues and bugs prioritized by the Khronos OpenGL Working Group. For
    extensions which have been promoted to a core Specification, fixes will
    first appear in the latest version of that core Specification, and will
    eventually be backported to the extension document. This policy is
    described in more detail at
        https://www.khronos.org/registry/OpenGL/docs/update_policy.php

Status

    Complete. Approved by the ARB on 2011/06/20.
    Approved by the Khronos Promoters on 2011/07/29.

Version

    Last Modified Date: December 15th, 2010
    Revision: 2

Number

    ARB Extension #109

Dependencies

    OpenGL 4.0 or the ARB_transform_feedback2 extension is required.

    OpenGL 3.1 or the ARB_draw_instanced extension is required.

    This extension interacts with the ARB_transform_feedback3 extension.

    This extension is written against the OpenGL 4.1 (Core Profile) specification.

Overview

    Multiple instances of geometry may be specified to the GL by calling
    functions such as DrawArraysInstanced and DrawElementsInstanced. Further,
    the results of a transform feedback operation may be returned to the GL
    by calling DrawTransformFeedback, or DrawTransformFeedbackStream. However,
    it is not presently possible to draw multiple instances of data
    transform feedback without using a query and the resulting round trip from
    server to client.

    This extension adds functionality to draw multiple instances of the result
    of a transform feedback operation.

New Procedures and Functions

    void DrawTransformFeedbackInstanced(enum mode, uint id, sizei primcount);
    void DrawTransformFeedbackStreamInstanced(enum mode, uint id, uint stream, sizei primcount);

New Tokens

    None.

Additions to Chapter 2 of the OpenGL 4.1 (Core Profile) Specification
(OpenGL Operation)

Modify Section 2.17.3, "Transform Feedback Draw Operations"

    ... The number of vertices captured from each vertex stream during transform
    feedback is stored in the corresponding transform feedback object and may
    be used in conjunction with the commands

        void DrawTransformFeedback(enum mode, uint id);
        void DrawTransformFeedbackInstanced(enum mode, uint id, sizei primcount);
        void DrawTransformFeedbackStream(enum mode, uint id, uint stream);
        void DrawTransformFeedbackStreamInstanced(enum mode, uint id, uint stream, sizei primcount);

    to replay the captured vertices.

        DrawTransformFeedbackStreamInstanced is equivalent to calling
    DrawArraysInstanced with <mode> as specified, <first> set to zero, <count>
    set to the number of vertices captured from the vertex stream numbered
    <stream> the last time transform was active on the transform feedback
    object named <id>, and <primcount> as specified. The error INVALID_VALUE
    is generated if <stream> is greater than or equal to the value of
    MAX_VERTEX_STREAMS. Calling DrawTransformFeedbackInstanced is equivalent
    to calling DrawTransformFeedbackStreamInstanced with <stream> set to zero.
    Calling DrawTransformFeedbackStream is equivalent to calling
    DrawTransformFeedbackStreamInstanced with <primcount> set to one. Finally,
    calling DrawTransformFeedback is equivalent to calling
    DrawTransformFeedbackStreamInstanced with <stream> set to zero and
    <primcount> set to one.

Additions to Chapter 3 of the OpenGL 4.1 (Core Profile) Specification
(Rasterization)

    None.

Additions to Chapter 4 of the OpenGL 4.1 (Core Profile) Specification
(Per-Fragment Operations and the Framebuffer)

    None.

Additions to Chapter 5 of the OpenGL 4.1 (Core Profile) Specification
(Special Functions)

    None.

Additions to Chapter 6 of the OpenGL 4.1 (Core Profile) Specification
(State and State Requests)

    None.

Errors

    INVALID_ENUM is generated by DrawTransformFeedbackStreamInstanced if <mode>
    is not an accepted value.

    INVALID_VALUE is generated by DrawTransformFeedbackStreamInstanced if
    <stream> is greater than or equal to the value of MAX_VERTEX_STREAMS.

    INVALID_VALUE is generated by DrawTransformFeedbackStreamInstanced if
    <id> is not the name of a transform feedback object.

    INVALID_OPERATION is generated by DrawTransformFeedbackStreamInstanced if a
    non-zero buffer object name is bound to an enabled array and the buffer
    object's data store is currently mapped.

    INVALID_OPERATION is generated by DrawTransformFeedbackStreamInstanced if a
    geometry shader is active and mode is incompatible with the input primitive
    type of the geometry shader in the currently installed program object.

    INVALID_OPERATION is generated if by DrawTransformFeedbackStreamInstanced if
    mode is PATCHES and no tessellation control shader is active.

    INVALID_OPERATION is generated if by DrawTransformFeedbackStreamInstanced if
    glEndTransformFeedback has never been called while the transform feedback
    object named by id was bound.

    Other errors generated by DrawElements, DrawArrays or other drawing commands
    (for example, due to framebuffer incompleteness) may be generated by
    DrawTransformFeedbackStreamInstanced.

Dependencies on OpenGL 4.0 and GL_ARB_transform_feedback3

    If the GL version is less than 4.0, and if GL_ARB_transform_feedback3 is
    not supported, this extension only adds DrawTransformFeedbackInstanced
    (not DrawTransformFeedbackStreamInstanced). In that case, remove all
    references to DrawTransformFeedbackStreamInstanced and instead define
    DrawTransformFeedback in terms of DrawTransformFeedbackInstanced.

Issues

    1) Do I need OpenGL 3.1, OpenGL 4.0 or ARB_transform_feedback3?

    If you have ARB_draw_transform_feedback3 or OpenGL 4.0, you're good to go.
    You need at least OpenGL 3.1 _with_ ARB_transform_feedback3.

    2) Do we need a DrawTransformFeedbackStreamInstancedBaseInstance when both
    this extension and ARB_base_instance are present?

    Perhaps. That's a bit wordy. Not adding it for now. How about in
    ARB_transform_feedback_instanced2?

Revision History

    Rev.    Date    Author    Changes
    ----  --------  --------  -----------------------------------------
     2    12/15/10  gsellers  Address comments from bmerry (bug 6961)
     1    09/23/10  gsellers  Initial revision