xref: /third_party/openGLES/extensions/NV/NV_transform_feedback.txt

Name

    NV_transform_feedback

Name Strings

    GL_NV_transform_feedback

Contributors

    Cliff Woolley
    Nick Carter

Contact

    Barthold Lichtenbelt (blichtenbelt 'at' nvidia.com)
    Pat Brown (pbrown 'at' nvidia.com)
    Eric Werness (ewerness 'at' nvidia.com)

Status

    Shipping for GeForce 8 Series (November 2006) 

Version

    Last Modified Date:         03/09/2011
    NVIDIA Revision:            18

Number

    341

Dependencies

    OpenGL 1.5 is required.

    This extension interacts with EXT_timer_query.

    NV_vertex_program4, NV_geometry_program4 and NV_gpu_program4 affect this
    extension.

    EXT_geometry_shader4 trivially interacts with this extension.

    This extension has an OpenGL Shading Language component.  As such it
    interacts with ARB_shader_objects and OpenGL 2.0.

    This extension is written against the OpenGL 2.0 specification.

Overview

    This extension provides a new mode to the GL, called transform feedback,
    which records vertex attributes of the primitives processed by the GL.
    The selected attributes are written into buffer objects, and can be
    written with each attribute in a separate buffer object or with all
    attributes interleaved into a single buffer object.  If a geometry program
    or shader is active, the primitives recorded are those emitted by the
    geometry program.  Otherwise, transform feedback captures primitives whose
    vertex are transformed by a vertex program or shader, or by fixed-function
    vertex processing.  In either case, the primitives captured are those
    generated prior to clipping.  Transform feedback mode is capable of
    capturing transformed vertex data generated by fixed-function vertex
    processing, outputs from assembly vertex or geometry programs, or varying
    variables emitted from GLSL vertex or geometry shaders.

    The vertex data recorded in transform feedback mode is stored into buffer
    objects as an array of vertex attributes.  The regular representation and
    the use of buffer objects allows the recorded data to be processed
    directly by the GL without requiring CPU intervention to copy data.  In
    particular, transform feedback data can be used for vertex arrays (via
    vertex buffer objects), as the source for pixel data (via pixel buffer
    objects), as program constant data (via the NV_parameter_buffer_object or
    EXT_bindable_uniform extension), or via any other extension that makes use
    of buffer objects.

    This extension introduces new query object support to allow transform
    feedback mode to operate asynchronously.  Query objects allow applications
    to determine when transform feedback results are complete, as well as the
    number of primitives processed and written back to buffer objects while in
    transform feedback mode.  This extension also provides a new rasterizer
    discard enable, which allows applications to use transform feedback to
    capture vertex attributes without rendering anything.

New Procedures and Functions

    void BindBufferRangeNV(enum target, uint index, uint buffer,
                           intptr offset, sizeiptr size)
    void BindBufferOffsetNV(enum target, uint index, uint buffer,
                            intptr offset)
    void BindBufferBaseNV(enum target, uint index, uint buffer)
    void TransformFeedbackAttribsNV(sizei count, const int *attribs,
                                    enum bufferMode)
    void TransformFeedbackVaryingsNV(uint program, sizei count,
                                     const int *locations,
                                     enum bufferMode)
    void BeginTransformFeedbackNV(enum primitiveMode)
    void EndTransformFeedbackNV()

    int GetVaryingLocationNV(uint program, const char *name)
    void GetActiveVaryingNV(uint program, uint index,
                            sizei bufSize, sizei *length, sizei *size,
                            enum *type, char *name)
    void ActiveVaryingNV(uint program, const char *name)
    void GetTransformFeedbackVaryingNV(uint program, uint index,
                                       int *location)

    void GetIntegerIndexedvEXT(enum param, uint index, int *values);
    void GetBooleanIndexedvEXT(enum param, uint index, boolean *values);

    (Note: These indexed query functions are provided in the EXT_draw_buffers2
    extension.  The boolean query is not useful for any queryable value in
    this extension, but is supported for completeness and consistency with
    base GL typed "Get" functions.)


New Tokens

    Accepted by the <target> parameters of BindBuffer, BufferData,
    BufferSubData, MapBuffer, UnmapBuffer, GetBufferSubData,
    GetBufferPointerv, BindBufferRangeNV, BindBufferOffsetNV and
    BindBufferBaseNV:

      TRANSFORM_FEEDBACK_BUFFER_NV                      0x8C8E

    Accepted by the <param> parameter of GetIntegerIndexedvEXT and
    GetBooleanIndexedvEXT:

      TRANSFORM_FEEDBACK_BUFFER_START_NV                0x8C84
      TRANSFORM_FEEDBACK_BUFFER_SIZE_NV                 0x8C85
      TRANSFORM_FEEDBACK_RECORD_NV                      0x8C86

    Accepted by the <param> parameter of GetIntegerIndexedvEXT and
    GetBooleanIndexedvEXT, and by the <pname> parameter of GetBooleanv,
    GetDoublev, GetIntegerv, and GetFloatv:

      TRANSFORM_FEEDBACK_BUFFER_BINDING_NV              0x8C8F

    Accepted by the <bufferMode> parameter of TransformFeedbackAttribsNV and
    TransformFeedbackVaryingsNV:

      INTERLEAVED_ATTRIBS_NV                            0x8C8C
      SEPARATE_ATTRIBS_NV                               0x8C8D

    Accepted by the <target> parameter of BeginQuery, EndQuery, and
    GetQueryiv:

      PRIMITIVES_GENERATED_NV                           0x8C87
      TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN_NV          0x8C88

    Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, and by
    the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and
    GetDoublev:

      RASTERIZER_DISCARD_NV                             0x8C89

    Accepted by the <pname> parameter of GetBooleanv, GetDoublev, GetIntegerv,
    and GetFloatv:

      MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTS_NV  0x8C8A
      MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV        0x8C8B
      MAX_TRANSFORM_FEEDBACK_SEPARATE_COMPONENTS_NV     0x8C80
      TRANSFORM_FEEDBACK_ATTRIBS_NV                     0x8C7E

    Accepted by the <pname> parameter of GetProgramiv:

      ACTIVE_VARYINGS_NV                                0x8C81
      ACTIVE_VARYING_MAX_LENGTH_NV                      0x8C82
      TRANSFORM_FEEDBACK_VARYINGS_NV                    0x8C83

   Accepted by the <pname> parameter of GetBooleanv, GetDoublev, GetIntegerv,
   GetFloatv, and GetProgramiv:

      TRANSFORM_FEEDBACK_BUFFER_MODE_NV                 0x8C7F

   Accepted by the <attribs> parameter of TransformFeedbackAttribsNV:

      BACK_PRIMARY_COLOR_NV                             0x8C77
      BACK_SECONDARY_COLOR_NV                           0x8C78
      TEXTURE_COORD_NV                                  0x8C79
      CLIP_DISTANCE_NV                                  0x8C7A
      VERTEX_ID_NV                                      0x8C7B
      PRIMITIVE_ID_NV                                   0x8C7C
      GENERIC_ATTRIB_NV                                 0x8C7D
      POINT_SIZE                                        0x0B11
      FOG_COORDINATE                                    0x8451
      SECONDARY_COLOR_NV                                0x852D
      PRIMARY_COLOR                                     0x8577
      POSITION                                          0x1203
      LAYER_NV                                          0x8DAA

      (note:  POINT_SIZE, FOG_COORDINATE, PRIMARY_COLOR, and POSITION are
       defined in the core OpenGL specification; SECONDARY_COLOR_NV is defined
       in NV_register_combiners.)

    Returned by the <type> parameter of GetActiveVaryingNV:

      UNSIGNED_INT_VEC2_EXT                             0x8DC6
      UNSIGNED_INT_VEC3_EXT                             0x8DC7
      UNSIGNED_INT_VEC4_EXT                             0x8DC8

      (note:  All three of these are defined in the EXT_gpu_shader4
      extension.)

Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL
Operation)

    Insert three new sections between Sections 2.11, Coordinate Transforms and
    2.12, Clipping:

    (Move the "Asynchronous Queries" language out of Section 4.1.7)

    Section 2.X, Asynchronous Queries

    Asynchronous queries provide a mechanism to return information about the
    processing of a sequence of GL commands.  There are two query types
    supported by the GL.  Transform feedback queries (section 2.Y) returns
    information on the number of vertices and primitives processed by the GL
    and written to one or more buffer objects.  Occlusion queries (section
    4.1.7.1) count the number of fragments or samples that pass the depth
    test.

    The results of asynchronous queries are not returned by the GL immediately
    after the completion of the last command in the set; subsequent commands
    can be processed while the query results are not complete.  When
    available, the query results are stored in an associated query object.
    The commands described in section 6.1.12 provide mechanisms to determine
    when query results are available and return the actual results of the
    query.  The name space for query objects is the unsigned integers, with
    zero reserved by the GL.

    Each type of query supported by the GL has an active query object name. If
    the active query object name for a query type is non-zero, the GL is
    currently tracking the information corresponding to that query type and
    the query results will be written into the corresponding query object.  If
    the active query object for a query type name is zero, no such information
    is being tracked.

    A query object is created by calling

      void BeginQuery(enum target, uint id);

    with an unused name <id>.  <target> indicates the type of query to be
    performed; valid values of <target> are defined in subsequent
    sections. When a query object is created, the name <id> is marked as used
    and associated with a new query object.

    BeginQuery sets the active query object name for the query type given by
    <target> to <id>.  If BeginQuery is called with an <id> of zero, if the
    active query object name for <target> is non-zero, or if <id> is the
    active query object name for any query type, the error INVALID OPERATION
    is generated.

    The command

      void EndQuery(enum target);

    marks the end of the sequence of commands to be tracked for the query type
    given by <target>.  The active query object for <target> is updated to
    indicate that query results are not available, and the active query object
    name for <target> is reset to zero.  When the commands issued prior to
    EndQuery have completed and a final query result is available, the query
    object, active when EndQuery is, called is updated by the GL.  The query
    object is updated to indicate that the query results are available and to
    contain the query result.  If the active query object name for <target> is
    zero when EndQuery is called, the error INVALID_OPERATION is generated.

   The command

      void GenQueries(sizei n, uint *ids);

    returns <n> previously unused query object names in <ids>. These names are
    marked as used, but no object is associated with them until the first time
    they are used by BeginQuery.

    Query objects are deleted by calling

      void DeleteQueries(sizei n, const uint *ids);

    <ids> contains <n> names of query objects to be deleted. After a query
    object is deleted, its name is again unused.  Unused names in <ids> are
    silently ignored.

    Calling either GenQueries or DeleteQueries while any query of any target
    is active causes an INVALID_OPERATION error to be generated.

    Query objects contain two pieces of state:  a single bit indicating
    whether a query result is available, and an integer containing the query
    result value.  The number of bits used to represent the query result is
    implementation-dependent.  In the initial state of a query object, the
    result is available and its value is zero.

    The necessary state for each query type is an unsigned integer holding the
    active query object name (zero if no query object is active), and any
    state necessary to keep the current results of an asynchronous query in
    progress.

    Section 2.Y, Transform Feedback

    In 'transform feedback' mode the vertices of transformed primitives are
    written out to one or more buffer objects. The vertices are fed back after
    the geometry shader stage, if it exists, or otherwise after vertex
    processing right before clipping (section 2.12) but after color
    clamping. Optionally the transformed vertices can be discarded after being
    stored into one or more buffer objects, or they can be passed on down to
    the clipping stage for further processing.

    Transform feedback is started and finished by calling

      void BeginTransformFeedbackNV(enum primitiveMode)

    and

      void EndTransformFeedbackNV(),

    respectively. Transform feedback is said to be active after a call to
    BeginTransformFeedbackNV and inactive after a call to
    EndTransformFeedbackNV. Transform feedback is initially inactive.
    Transform feedback is performed after color clamping, but immediately
    before clipping in the OpenGL pipeline. <primitiveMode> is one of
    TRIANGLES, LINES, or POINTS, and specifies the output type of primitives
    that will be recorded into the buffer objects bound for transform feedback
    (see below). <primitiveMode> places a restriction on the primitive types
    that may be rendered during an instance of transform feedback. See table
    X.1.

      Transform Feedback
      primitiveMode               allowed render primitive modes
      ----------------------      ---------------------------------
      POINTS                       POINTS
      LINES                        LINES, LINE_LOOP, and LINE_STRIP
      TRIANGLES                    TRIANGLES, TRIANGLE_STRIP,
                                   TRIANGLE_FAN, QUADS, QUAD_STRIP,
                                   and POLYGON

    Table X.1 Legal combinations between the transform feedback primitive
    mode, as passed to BeginTransformFeedbackNV and the current primitive
    mode.

    If a geometry program or geometry shader is active, the output primitive
    type of the currently active program is used as the render primitive in
    table X.1, otherwise the Begin mode is used.

    Quads and polygons will be tessellated and recorded as triangles (the
    order of tessellation within a primitive is undefined); primitives
    specified in strips or fans will be assembled and recorded as individual
    primitives. Incomplete primitives are not recorded. Begin or any operation
    that implicitly calls Begin (such as DrawElements) will generate
    INVALID_OPERATION if the begin mode is not an allowed begin mode for the
    current transform feedback buffer state. If a geometry program or geometry
    shader is active, its output primitive mode is used for the error check
    instead of the begin mode.

    It is an invalid operation error to call BeginTransformFeedbackNV,
    TransformFeedbackVaryingsNV, TransformFeedbackAttribsNV, or UseProgram or
    LinkProgram on the currently active program object while transform
    feedback is active.  It is an invalid operation error to call
    EndTransformFeedbackNV while transform feedback is inactive.

    Transform feedback can operate in either INTERLEAVED_ATTRIBS_NV or
    SEPARATE_ATTRIBS_NV mode. In the INTERLEAVED_ATTRIBS_NV mode, several
    vertex attributes can be written, interleaved, into a single buffer
    object.  In the SEPARATE_ATTRIBS_NV mode, vertex attributes are recorded,
    non-interleaved, into several buffer objects simultaneously.

    It is an INVALID_OPERATION error to call BeginTransformFeedbackNV if there
    is no buffer object bound to index 0 (see the description of the
    BindBuffer* commands below) in INTERLEAVED_ATTRIBS_NV mode. It is also an
    INVALID_OPERATION error to call BeginTransformFeedbackNV if the number of
    buffer objects bound in SEPARATE_ATTRIBS_NV mode is less than the number
    of buffer objects required, as given by the current transform feedback
    state.  It is also an INVALID_OPERATION error to call
    BeginTransformFeedbackNV if no attributes are specified to be captured in
    either separate or interleaved mode.

    Buffer objects are made to be targets of transform feedback by calling one
    of

      void BindBufferRangeNV(enum target, uint index, uint buffer,
                             intptr offset, sizeiptr size)
      void BindBufferOffsetNV(enum target, uint index, uint buffer,
                              intptr offset)
      void BindBufferBaseNV(enum target, uint index, uint buffer)

    where <target> is set to TRANSFORM_FEEDBACK_BUFFER_NV. Any of the three
    BindBuffer* commands perform the equivalent of BindBuffer(target,
    buffer). <buffer> specifies which buffer object to bind to the target at
    index number <index>. <index> exists for use with the SEPARATE_ATTRIBS_NV
    mode and must be less than the value of
    MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV.  <offset> specifies a starting
    offset into the buffer object <buffer>.  <size> specifies the number of
    elements that can be written during transform feedback mode. This is
    useful to prevent the GL from writing past a certain position in the
    buffer object. Both <offset> and <size> are in basic machine units. The
    error INVALID_VALUE is generated if the value of <size> is less than or
    equal to zero.  The error INVALID_VALUE is generated if <offset> or <size>
    are not word-aligned. The error INVALID_OPERATION is generated when any of
    the BindBuffer* commands is called while transform feedback is active.

    BindBufferBaseNV is equivalent to calling BindBufferOffsetNV with an
    <offset> of 0. BindBufferOffsetNV is the equivalent of calling
    BindBufferRangeNV with <size> = sizeof(buffer) - <offset> and rounding
    <size> down so that it is word-aligned.

    If recording the vertices of a primitive to the buffer objects being used
    for transform feedback purposes would result in either exceeding the
    limits of any buffer object's size, or in exceeding the end position
    <offset> + <size> - 1, as set by BindBufferRangeNV, then no vertices of
    the primitive are recorded, and the counter corresponding to the
    asynchronous query target TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN_NV (see
    Section 2.Z) is not incremented.

    Two methods exist to specify which transformed vertex attributes are
    streamed to one, or more, buffer objects in transform feedback mode.  If
    an OpenGL Shading Language vertex and/or geometry shader is active, then
    the state set with the TransformFeedbackVaryingsNV() command determines
    which attributes to record. If neither a vertex nor geometry shader is
    active, the state set with the TransformFeedbackAttribsNV() command
    determines which attributes to record.

    When a program object containing a vertex shader and/or geometry shader is
    active, the set of vertex attributes recorded in transform feedback mode
    is specified by

      void TransformFeedbackVaryingsNV(uint program, sizei count,
                                       const int *locations, 
                                       enum bufferMode)

    This command sets the transform feedback state for <program> and specifies
    which varying variables to record when transform feedback is active. The
    array <locations> contains <count> locations of active varying variables,
    as queried with GetActiveVaryingNV(), to stream to a buffer object. See
    section 2.15.3. <bufferMode> is one of INTERLEAVED_ATTRIBS_NV or
    SEPARATE_ATTRIBS_NV.  The error INVALID_OPERATION is generated if any
    value in <locations> does not reference an active varying variable, or if
    any value in <locations> appears more than once in the array. The same
    error is generated if <program> has not been linked successfully. The
    program object's state value TRANSFORM_FEEDBACK_BUFFER_MODE_NV will be set
    to <bufferMode> and the program object's state value
    TRANSFORM_FEEDBACK_VARYINGS_NV set to <count>. These values can be queried
    with GetProgramiv (see section 6.1.14).

    In the INTERLEAVED_ATTRIBS_NV mode, varying variables are written,
    interleaved, into one buffer object. This is the buffer object bound to
    index 0. Varying variables are written out to that buffer object in the
    order that they appear in the array <locations>. The error
    INVALID_OPERATION is generated if the total number of components of all
    varying variables specified in the array <locations> is greater than
    MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTS_NV.

    In the SEPARATE_ATTRIBS_NV mode, varying variables are recorded,
    non-interleaved, into several buffer objects simultaneously. The first
    varying variable in the array <locations> is written to the buffer bound
    to index 0. The last varying variable is written to the buffer object
    bound to index <count> - 1. No more than
    MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV buffer objects can be written
    to simultaneously. The error INVALID_VALUE is generated if <count> is
    greater than that limit. Furthermore, the number of components for each
    varying variable in the array <locations> cannot exceed
    MAX_TRANSFORM_FEEDBACK_SEPARATE_COMPONENTS_NV. The error INVALID_VALUE is
    generated if any varying variable in <locations> exceeds this limit.

    It is not necessary to (re-)link <program> after calling
    TransformFeedbackVaryingsNV(). Changes to the transform feedback state
    will be picked up right away after calling TransformFeedbackVaryingsNV().

    The value for any attribute specified to be streamed to a buffer object
    but not actually written by a vertex or geometry shader is undefined.

    When neither a vertex nor geometry shader is active, the vertex attributes
    produced by fixed-function vertex processing or an assembly vertex or
    geometry program can be recorded in transform feedback mode.  The set of
    attributes to record is specified by

      void TransformFeedbackAttribsNV(sizei count, const int *attribs,
                                      enum bufferMode)

    This command specifies which attributes to record into one, or more,
    buffer objects. The value TRANSFORM_FEEDBACK_BUFFER_MODE_NV will be set
    to <bufferMode> and the value TRANSFORM_FEEDBACK_ATTRIBS_NV set to
    <count>.  The array <attribs> contains an interleaved representation of
    the attributes desired to be fed back containing 3*count values. For
    attrib i, the value at 3*i+0 is the enum corresponding to the attrib, as
    given in table X.2. The value at 3*i+1 is the number of components of the
    provided attrib to be fed back and is between 1 and 4. The value at 3*i+2
    is the index for attribute enumerants corresponding to more than one real
    attribute. For an attribute enumerant corresponding to only one attribute,
    the index is ignored. For an attribute enumerant corresponding to more
    than one attribute, the error INVALID_VALUE is generated if the index
    value is outside the allowable range for that attribute.

                               permitted            GPU_program_4
     attrib                    sizes     index?     result name
     ---------------------     --------  --------   --------------
     POSITION                  1,2,3,4     no       position
     PRIMARY_COLOR             1,2,3,4     no       color.front.primary
     SECONDARY_COLOR_NV        1,2,3,4     no       color.front.secondary
     BACK_PRIMARY_COLOR_NV     1,2,3,4     no       color.back.primary
     BACK_SECONDARY_COLOR_NV   1,2,3,4     no       color.back.secondary
     FOG_COORDINATE            1           no       fogcoord
     POINT_SIZE                1           no       pointsize
     TEXTURE_COORD_NV          1,2,3,4     yes      texcoord[index]
     CLIP_DISTANCE_NV          1           yes      clip[index]
     VERTEX_ID_NV              1           no       vertexid
     PRIMITIVE_ID_NV           1           no       primid
     GENERIC_ATTRIB_NV         1,2,3,4     yes      attrib[index]
     LAYER_NV                  1           no       layer

    Table X.2:  Transform Feedback Attribute Specifiers.The 'attrib' column
    specifies which attribute to record. The 'permitted sizes' column
    indicates how many components of the attribute can be recorded. The
    'index' column indicates if the attribute is indexed.  The 'gpu program 4'
    column shows which result variable of a vertex or geometry program
    corresponds to the attribute to record.

    The TransformFeedbackAttribsNV() command sets transform feedback state
    which is used both when the GL is in fixed-function vertex processing
    mode, as well as when an assembly vertex and/or geometry program is
    active.

    The parameter <bufferMode> has the same meaning as described for
    TransformFeedbackVaryingsNV(). Attributes are either written interleaved,
    or into separate buffer objects, in the same manner as described earlier
    for TransformFeedbackVaryingsNV().

    In the INTERLEAVED_ATTRIBS_NV mode, the error INVALID_VALUE is generated
    if the sum of the values of elements 3*i+1 in the array <attribs> is
    greater than MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTS_NV.

    In the SEPARATE_ATTRIBS_NV mode, no more than
    MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV buffer objects can be written
    to simultaneously. The error INVALID_VALUE is generated if <count> is
    greater than that limit.

    The error INVALID_OPERATION is generated if any attribute appears more
    than once in the array <attribs>.

    The value for any attribute specified to be streamed to a buffer object
    but not actually written by a vertex or geometry program is undefined.
    The values of PRIMITIVE_ID_NV or LAYER_NV for a vertex is defined if and
    only if a geometry program is active and that program writes to the result
    variables "result.primid" or "result.layer", respectively.  The value of
    VERTEX_ID_NV is only defined if and only if a vertex program is active, no
    geometry program is active, and the vertex program writes to the output
    attribute "result.id".

    Section 2.Z, Primitive Queries
 
    Primitive queries use query objects to track the number of primitives
    generated by the GL and to track the number of primitives written to
    transform feedback buffers.

    When BeginQuery is called with a <target> of PRIMITIVES_GENERATED_NV, the
    primitives-generated count maintained by the GL is set to zero. When the
    generated primitive query is active, the primitives-generated count is
    incremented every time a primitive reaches the Discarding Rasterization
    stage (see Section 3.x) right before rasterization. This counter counts
    the number of primitives emitted by a geometry shader, if active, possibly
    further tessellated into separate primitives during the transform-feedback
    stage, if active.

    When BeginQuery is called with a <target> of
    TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN_NV, the transform-feedback-
    primitives-written count maintained by the GL is set to zero. When the
    transform feedback primitive written query is active, the
    transform-feedback-primitives-written count is incremented every time a
    primitive is recorded into a buffer object. If transform feedback is not
    active, this counter is not incremented. If the primitive does not fit in
    the buffer object, the counter is not incremented.

    These two queries can be used together to determine if all primitives have
    been written to the bound feedback buffers; if both queries are run
    simultaneously and the query results are equal, all primitives have been
    written to the buffer(s). If the number of primitives written is less than
    the number of primitives generated, the buffer is full.

    Modify section 2.15.3 "Shader Variables", page 75.

    Change the second sentence in the first paragraph on p. 84 as follows:

    . . . or read by a fragment shader, will count against this limit.  The
    transformed vertex position (gl_Position) does not count against this
    limit.

    Add the following paragraphs on p.84:

    A varying variable is considered active if it is determined by the linker
    that the varying will actually be used when the executable code in a
    program object is executed. The linker will make this determination
    regardless of the transform-feedback state set with the
    TransformFeedbackVaryingsNV() command. In cases where the linker cannot
    make a conclusive determination, the varying will be considered active. It
    is possible to override this determination and force the linker to
    consider a varying variable as active by calling ActiveVaryingNV(). This
    can be useful in transform feedback mode if there are varying variables to
    be recorded but not otherwise needed.

    To find the location of an active varying variable, call

      int GetVaryingLocationNV(uint program, const char *name)

    This command will return the location of varying variable <name>.  <name>
    is a null-terminated string without whitespace. If <name> is not the name
    of an active varying variable in <program>, -1 is returned. Locations for
    both user-defined as well as built-in varying variables can be queried. If
    <program> has not been successfully linked, the error INVALID_OPERATION is
    generated. After a program is linked, the location will not change, unless
    the program is re- linked. A valid name cannot be any portion of a single
    vector or matrix, but can be a single element of an array or the whole
    array.  Note that varying variables cannot be structures.

    To determine the set of active varying variables used by a program object,
    and their data types, use the command:

      void GetActiveVaryingNV(uint program, uint index,
                              sizei bufSize, sizei *length, sizei *size,
                              enum *type, char *name);

    This command provides information about the varying selected by
    <index>. An <index> of 0 selects the first active varying variable, and an
    <index> of ACTIVE_VARYINGS_NV-1 selects the last active varying
    variable. The value of ACTIVE_VARYINGS_NV can be queried with
    GetProgramiv (see section 6.1.14). If <index> is greater than or equal to
    ACTIVE_VARYINGS_NV, the error INVALID_VALUE is generated.  The parameter
    <program> is the name of a program object for which the command
    LinkProgram has been issued in the past. It is not necessary for <program>
    to have been linked successfully. The link could have failed because the
    number of active varying variables exceeded the limit.

    The name of the selected varying is returned as a null-terminated string
    in <name>. The actual number of characters written into <name>, excluding
    the null terminator, is returned in <length>. If <length> is NULL, no
    length is returned. The maximum number of characters that may be written
    into <name>, including the null terminator, is specified by <bufSize>. The
    returned varying name can be the name of a user defined varying variable
    or the name of a built- in varying (which begin with the prefix "gl_", see
    the OpenGL Shading Language specification for a complete list). The length
    of the longest varying name in program is given by
    ACTIVE_VARYING_MAX_LENGTH_NV, which can be queried with GetProgramiv (see
    section 6.1.14).

    For the selected varying variable, its type is returned into <type>.  The
    size of the varying is returned into <size>. The value in <size> is in
    units of the type returned in <type>. The type returned can be any of
    FLOAT, FLOAT_VEC2, FLOAT_VEC3, FLOAT_VEC4, INT, INT_VEC2, INT_VEC3,
    INT_VEC4, UNSIGNED_INT, UNSIGNED_INT_VEC2_EXT, UNSIGNED_INT_VEC3_EXT,
    UNSIGNED_INT_VEC4_EXT, FLOAT_MAT2, FLOAT_MAT3, or FLOAT_MAT4. If an error
    occurred, the return parameters <length>, <size>, <type> and <name> will
    be unmodified. This command will return as much information about active
    varying variables as possible. If no information is available, <length>
    will be set to zero and <name> will be an empty string. This situation
    could arise if GetActiveVaryingNV is issued after a failed link.

    To force the linker to mark a varying variable as active, call

      void ActiveVaryingNV(uint program, const char *name)

    to specify that the varying variable <name> in <program> should be marked
    as active when the program is next linked. In particular, it does not
    modify the list of active varying variables in a program object that has
    already been linked. For any varying variable in <program> not passed to
    ActiveVaryingNV, the linker will determine their active status. <name>
    must be a null-terminated string without whitespace. A valid name cannot
    be an element of an array, or any portion of a single vector or
    matrix. ActiveVaryingNV may be issued before any shader objects are
    attached to <program>. Hence, <name> can contain any string, including a
    name that is never used as a varying variable in any shader object. Such
    names are ignored by the GL.

    The application is advised to force any varying variable live that it
    needs for transform feedback purposes. The set of active varying variables
    are linker dependent.

Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization)

   (Add new section 3.X, Discarding Rasterization)

    Primitives can be optionally discarded before rasterization by calling
    Enable and Disable with RASTERIZER_DISCARD_NV. When enabled, primitives
    are discarded right before the rasterization stage, but after the optional
    transform feedback stage. When disabled, primitives are passed through to
    the rasterization stage to be processed normally. RASTERIZER_DISCARD_NV
    applies to the DrawPixels, CopyPixels, Bitmap, Clear and Accum commands as
    well.

Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment
Operations and the Frame Buffer)

    (Replace section 4.1.7, "Occlusion Queries", p. 204, with the following)

    Occlusion queries use query objects to track the number of fragments or
    samples that pass the depth test.  An occlusion query can be started and
    finished by calling BeginQuery and EndQuery, respectively, with a <target>
    of SAMPLES_PASSED.

    When an occlusion query starts, the samples-passed count maintained by the
    GL is set to zero.  When an occlusion query is active, the samples-passed
    count is incremented for each fragment that passes the depth test.  If the
    value of SAMPLE BUFFERS is 0, then the samples- passed count is
    incremented by 1 for each fragment. If the value of SAMPLE BUFFERS is 1,
    then the samples-passed count is incremented by the number of samples
    whose coverage bit is set. However, implementations, at their discretion,
    may instead increase the samples-passed count by the value of SAMPLES if
    any sample in the fragment is covered.  When an occlusion query finishes
    and all fragments generated by the commands issued prior to EndQuery have
    been generated, the samples-passed count is written to the corresponding
    query object as the query result value, and the query result for that
    object is marked as available.

    If the samples-passed count overflows, (i.e., exceeds the value 2^n - 1,
    where n is the number of bits in the samples-passed count), its value
    becomes undefined.  It is recommended, but not required, that
    implementations handle this overflow case by saturating at 2^n - 1 and
    incrementing no further.

Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions)

    (Add to section 5.4, Display Lists p. 237)

    On p. 241, add the following to the list of vertex buffer object commands
    not compiled into a display list: BindBufferRangeNV, BindBufferOffsetNV,
    BindBufferBaseNV, TransformFeedbackAttribsNV,
    TransformFeedbackVaryingsNV, and ActiveVaryingNV.

Additions to Chapter 6 of the OpenGL 2.0 Specification (State and State
Requests)

    Modify the second paragraph of section 6.1.1 (Simple Queries) p244 to read
    as follows:

    ...<data> is a pointer to a scalar or array of the indicated type in which
    to place the returned data. The commands

      void GetIntegerIndexedvEXT(enum param, uint index, int *values);
      void GetBooleanIndexedvEXT(enum param, uint index, boolean *values);

    are used to query indexed state.  <target> is the name of the indexed
    state and <index> is the index of the particular element being queried.
    <data> is a pointer to a scalar or array of the indicated type in which to
    place the returned data. In addition ...

   (Replace Section 6.1.12, Occlusion Queries, p. 254)

    Section 6.1.12, Asynchronous Queries

    The command

      boolean IsQuery(uint id);

    returns TRUE if <id> is the name of a query object. If <id> is zero, or if
    <id> is a non-zero value that is not the name of a query object, IsQuery
    returns FALSE.

    Information about a query target can be queried with the command

      void GetQueryiv(enum target, enum pname, int *params);

    <target> identifies the query target and can be SAMPLES_PASSED for
    occlusion queries or PRIMITIVES_GENERATED_NV and
    TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN_NV for primitive queries.

    If <pname> is CURRENT_QUERY, the name of the currently active query for
    <target>, or zero if no query is active, will be placed in <params>.

    If <pname> is QUERY_COUNTER_BITS, the implementation-dependent number of
    bits used to hold the query result for <target> will be placed in
    params. The number of query counter bits may be zero, in which case the
    counter contains no useful information.

    For primitive queries (PRIMITIVES_GENERATED_NV and
    TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN_NV) if the number of bits is
    non-zero, the minimum number of bits allowed is 32.

    For occlusion queries (SAMPLES_PASSED), if the number of bits is non-
    zero, the minimum number of bits allowed is a function of the
    implementation's maximum viewport dimensions (MAX_VIEWPORT_DIMS).  The
    counter must be able to represent at least two overdraws for every pixel
    in the viewport. The formula to compute the allowable minimum value (where
    n is the minimum number of bits) is:

      n = min(32, ceil(log_2(maxViewportWidth *
                             maxViewportHeight * 2))).

    The state of a query object can be queried with the commands

      void GetQueryObjectiv(uint id, enum pname, int *params);
      void GetQueryObjectuiv(uint id, enum pname, uint *params);

    If <id> is not the name of a query object, or if the query object named by
    <id> is currently active, then an INVALID_OPERATION error is generated.

    If <pname> is QUERY_RESULT, then the query object's result value is
    returned as a single integer in <params>.  If the value is so large in
    magnitude that it cannot be represented with the requested type, then the
    nearest value representable using the requested type is returned.  If the
    number of query counter bits for any <target> is zero, then the result is
    returned as a single integer with a value of 0.

    There may be an indeterminate delay before the above query returns.  If
    <pname> is QUERY_RESULT_AVAILABLE, FALSE is returned if such a delay would
    be required, TRUE is returned otherwise. It must always be true that if
    any query object returns a result available of TRUE, all queries of the
    same type issued prior to that query must also return TRUE.

    Querying the state for any given query object forces the corresponding
    query to complete within a finite amount of time.

    If multiple queries are issued using the same object name prior to calling
    GetQueryObject[u]iv, the result and availability information returned will
    always be from the last query issued.  The results from any queries before
    the last one will be lost if they are not retrieved before starting a new
    query on the same <target> and <id>.

    (Add to Section 6.1.13, Buffer Objects, p. 255)

    Add the following paragraph to the bottom of this section, p. 256.

    To query which buffer objects are the target(s) when transform feedback is
    active, call GetIntegerIndexedvEXT() with <param> set to
    TRANSFORM_FEEDBACK_BUFFER_BINDING_NV. <index> has to be in the range 0 to
    MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV - 1, otherwise the error
    INVALID_VALUE is generated. The name of the buffer object bound to <index>
    is returned in <values>. If no buffer object is bound for <index>, zero is
    returned in <values>.

    To query the starting offset or size of the range of each buffer object
    binding used for transform feedback, call GetIntegerIndexedvEXT() with
    <param> set to TRANSFORM_FEEDBACK_BUFFER_START_NV or
    TRANSFORM_FEEDBACK_BUFFER_SIZE_NV respectively.  The error INVALID_VALUE
    is generated if <index> not in the range 0 to
    MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV - 1.  If the parameter
    (starting offset or size) was not specified when the buffer object was
    bound, or if no buffer object is bound to <index>, zero is returned.

    (Add a new Section 6.1.14 "Transform Feedback " and rename 6.1.14 to
    6.1.15)

    To query the attributes to stream to a buffer object when neither an
    OpenGL Shading Language vertex nor geometry shader is active, call
    GetIntegerIndexedvEXT() with <param> set to
    TRANSFORM_FEEDBACK_RECORD_NV. This will return three values in <values>
    for each <index>. The first value returned is the attribute.  The second
    value the number of components of the attribute, and the third value the
    index of the attribute, if applicable. If the attribute is not indexed,
    the third component will return 0. The parameter <index> has to be in the
    range 0 to TRANSFORM_FEEDBACK_ATTRIBS_NV - 1, otherwise the error
    INVALID_VALUE is generated. If no data exists for <index> 0 is returned
    three times in <values>.

    To query the attributes to stream to a buffer object when a vertex and/or
    geometry shader is active, use the command
    GetTransformFeedbackVaryingNV(), as explained in section 6.1.14.

    (add to Section 6.1.14, Shader and Program Queries, p. 256)

    Add the following paragraph to the bottom of page 257:

    If <pname> is TRANSFORM_FEEDBACK_BUFFER_MODE_NV, the buffer mode,
    used when transform feedback is active, is returned. It can be one of
    SEPARATE_ATTRIBS_NV or INTERLEAVED_ATTRIBS_NV. If <pname> is
    TRANSFORM_FEEDBACK_VARINGS_NV, the number of varying variables to stream
    to one, or more, buffer objects are returned. If <pname> is
    ACTIVE_VARYINGS_NV, the number of active varying variables is
    returned. If no active varyings exist, 0 is returned. If <pname> is
    ACTIVE_VARYINGS_MAX_LENGTH_NV, the length of the longest active varying
    name, including a null terminator, is returned. If no active varying
    variable exists, 0 is returned.

    The command

      void GetTransformFeedbackVaryingNV(uint program, uint index,
                                         int *location)

    returns, for each <index>, the location of a varying variable to stream to
    a buffer object in <location>. The <index> element of the array
    <locations>, as passed to TransformFeedbackVaryingsNV, is
    returned. <index> has to be in the program object specific range 0 to
    TRANSFORM_FEEDBACK_VARYINGS_NV - 1, otherwise the error INVALID_VALUE is
    generated. If no location exists for <index>, -1 is returned. If <program>
    is not the name of a program object, or if program object has not been
    linked successfully, the error INVALID_OPERATION is generated.

Additions to Appendix A of the OpenGL 2.0 Specification (Invariance)

    None.

Additions to the AGL/GLX/WGL Specifications

    None.

GLX Protocol

    UNDER DEVELOPMENT

Interactions with EXT_timer_query

    EXT_timer_query is the first extension to generalize the BeginQuery and
    EndQuery mechanism introduced by ARB_occlusion_query and OpenGL 1.5 to
    cover an additional query type.  This extension is the second.  This
    extension is written against the OpenGL 2.0 specification and uses most of
    the modifications in the EXT_timer_query specification.  If
    EXT_timer_query is supported, timer queries need to be added as a third
    query type.

Dependencies on NV_geometry_program4 and EXT_geometry_shader4

    If NV_geometry_program4 is not supported, delete the reference to the
    output primitive type in Section 2.Y.  Delete the reference to
    PRIMITIVE_ID_NV and LAYER_NV.

    If EXT_geometry_shader4 is not supported, delete any reference to a
    geometry shader.

Dependencies on NV_vertex_program4 and NV_gpu_program4

    If NV_vertex_program4 is not supported, delete any reference to
    VERTEX_ID_NV.  If NV_gpu_program4 is not supported, table X.2 needs to
    refer to the "result" variables defined in the ARB_vertex_program
    specification instead.

Interactions with ARB_shader_objects and OpenGL 2.0

    If neither ARB_shader_objects nor OpenGL 2.0 is supported, all references
    to shader and program objects, as well as varying variables, should be
    removed.  This also means that functions including
    TransformFeedbackVaryingsNV, GetVaryingLocationNV, GetActiveVaryingNV,
    ActiveVaryingNV, and GetTransformFeedbackVaryingNV will not be
    supported, and enums that are relevant only in the context of shader and
    program objects will not be accepted.

Errors

    The error INVALID_OPERATION is generated by BeginQuery if called with an
    <id> of zero, if the active query object name for <target> is non- zero,
    or if <id> is the active query object name for any query type.

    The error INVALID_OPERATION is generated by EndQuery if the active query
    object name for <target> is zero.

    The error INVALID_OPERATION is generated if Begin, or any command that
    performs an explicit Begin, is called when:

      * A geometry program or shader is not active AND the begin mode does not
        match the allowed begin modes for the current transform feedback state
        as given by table X.1.

      * A geometry program or shader is active AND the output primitive type
        (of the geometry program / shader) does not match the allowed begin
        modes for the current transform feedback state as given by table X.1.

    The error INVALID_OPERATION is generated by BeginTransformFeedbackNV if
    there is no buffer object bound to index 0 in INTERLEAVED_ATTRIBS_NV
    mode.

    The error INVALID_OPERATION is generated by BeginTransformFeedbackNV if
    the number of buffer objects bound in SEPARATE_ATTRIBS_NV mode is less
    than the number of buffer objects required, as given by the current
    transform feedback state.

    The error INVALID_OPERATION is generated by BeginTransformFeedbackNV if
    no attributes are specified to be captured.

    The error INVALID_OPERATION is generated by BeginTransformFeedbackNV,
    TransformFeedbackVaryingsNV, TransformFeedbackAttribsNV, or UseProgram or
    LinkProgram, called on the currently in use program object, while
    transform feedback is active.

    The error INVALID_OPERATION is generated by EndTransformFeedbackNV while
    transform feedback is inactive.

    The error INVALID_OPERATION is generated by BindBufferRangeNV,
    BindBufferOffsetNV or BindBufferBaseNV if <target> is
    TRANSFORM_FEEDBACK_BUFFER_NV and <index> is greater or equal
    than MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV.

    The error INVALID_VALUE is generated by BindBufferRangeNV if the value of
    <size> <= 0.

    The error INVALID_VALUE is generated by BindBufferRangeNV or
    BindBufferOffsetNV if <start> or <end> are not word-aligned.

    The error INVALID_OPERATION is generated when any of the BindBuffer*
    commands is called while transform feedback is active.

    The error INVALID_OPERATION is generated by TransformFeedbackVaryingsNV
    commands if any location appears more than once in the array <locations.

    The error INVALID_OPERATION is generated by TransformFeedbackVaryingsNV
    if any location in <locations> references a non-existing varying variable.

    The error INVALID_OPERATION is generated by TransformFeedbackVaryingsNV
    if <program> has not been linked successfully.

    The error INVALID_OPERATION is generated by TransformFeedbackVaryingsNV
    in INTERLEAVED_ATTRIBS_NV mode if the total number of components of all
    varying variables specified in the array <locations> is greater than
    MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTS_NV.

    The error INVALID_VALUE is generated by TransformFeedbackVaryingsNV or
    TransformFeedbackAttribsNV in SEPARATE_ATTRIBS_NV mode if <count> is
    greater than MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV.

    The error INVALID_VALUE is generated by TransformFeedbackVaryingsNV in
    SEPARATE_ATTRIBS_NV mode if the number of components for each varying
    variable in the array <locations> is greater than
    MAX_TRANSFORM_FEEDBACK_SEPARATE_COMPONENTS_NV.

    The error INVALID_VALUE is generated by TransformFeedbackAttribsNV in
    INTERLEAVED_ATTRIBS_NV mode if the sum of the values of the components of
    the attributes in the array <attribs> is greater than
    MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTS_NV.

    The error INVALID_OPERATION is generated by TransformFeedbackAttribsNV if
    an enum value is specified more than once in the array <attribs>.

    The error INVALID_OPERATION is generated by TransformFeedbackAttribsNV if
    the number of components for each attribute in the array <attribs> is
    outside the range [0,4].

    The error INVALID_VALUE is generated by TransformFeedbackAttribsNV if the
    index value is in the array <attribs> is outside the allowable range for
    an attribute enumerant corresponding to more than one real attribute.

    The error INVALID_OPERATION is generated by GetVaryingLocationNV if
    <program> is not the name of a program object or if <program> has not been
    linked successfully.

    The error INVALID_OPERATION is generated by GetActiveVaryingNV or
    ActiveVaryingNV if <program> is not the name of a program object.

    The error INVALID_VALUE is generated by GetActiveVaryingNV if <index> is
    greater than or equal to ACTIVE_VARYINGS_NV.

    The error INVALID_VALUE is generated by GetIntegerIndexedvEXT() or
    GetBooleanIndexedv() with <param> set to TRANSFORM_FEEDBACK_RECORD_NV if
    <index> is greater than or equal to TRANSFORM_FEEDBACK_ATTRIBS_NV.

    The error INVALID_VALUE is generated by GetIntegerIndexedvEXT() or
    GetBooleanIndexedvEXT() with <param> set to
    TRANSFORM_FEEDBACK_BUFFER_BINDING_NV if <index> is greater than or equal
    to MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV.

    The error INVALID_VALUE is generated by GetTransformFeedbackVaryingsNV if
    <index> is greater than the program object specific value
    TRANSFORM_FEEDBACK_VARYINGS_NV - 1.

    The error INVALID_OPERATION is generated by
    GetTransformFeedbackVaryingsNV if <program> is not the name of a program
    object, or if program object has not been linked successfully.

New State

    (Add a new table:  Table 6.X,  Transform Feedback State)

    Get Value             Type    Get Command     Init. Value  Description                Sec    Attrib
    ------------------    ------  --------------  ------------ -------------------------  -----  ------
    TRANSFORM_FEEDBACK_   Z2      GetIntegerv     INTERLEAVED_  Transform feedback mode   2.Y      -
      BUFFER_MODE_NV                              ATTRIBS_NV
    TRANSFORM_FEEDBACK_   Z2      GetIntegerv          0        Number of attributes to   2.Y      -
      ATTRIBS_NV                                                capture in transform
                                                                feedback mode
    TRANSFORM_FEEDBACK_   Z+      GetIntegerv          0        Buffer object bound to    6.1.13   -
      BUFFER_BINDING_NV                                         generic bind point for
                                                                transform feedback.
    TRANSFORM_FEEDBACK_   nx3*Z+  GetInteger-          0        Name, component count,    6.1.14   -
      RECORD_NV                   IndexedvEXT                   and index of each 
                                                                attribute captured
    TRANSFORM_FEEDBACK_   nxZ+    GetInteger-          0        Buffer object bound to    6.1.13   -
      BUFFER_BINDING_NV           IndexedvEXT                   each transform feedback
                                                                attribute stream.
    TRANSFORM_FEEDBACK_   nxZ+    GetInteger-          0        Start offset of binding   6.1.13   -
      BUFFER_START_NV             IndexedvEXT                   range for each transform
                                                                feedback attrib. stream
    TRANSFORM_FEEDBACK_   nxZ+    GetInteger-          0        Size of binding range     6.1.13   -
      BUFFER_SIZE_NV              IndexedvEXT                   for each transform
                                                                feedback attrib. stream

   (Modify Table 6.37, p 298, updating the query object state to cover
   transform feedback.)

    Get Value         Type  Get Command       Init. Value  Description                Sec    Attribute
    ----------------  ----  ----------------  -----------  -------------------------  -----  ---------
    CURRENT_QUERY     3xZ+  GetQueryiv        0            Active query object name   2.X        -
                                                           (occlusion, timer, xform
                                                            feedback)
    QUERY_RESULT      3xZ+  GetQueryObjectiv  0            Query object result        2.X        -
                                                           (samples passed, Time
                                                           elapsed, feedback data amount)
    QUERY_RESULT_AVAILABLE  3xZ+  GetQueryObjectiv  TRUE   Query object result        2.X        -
                                                             available?

   (Modify Table 6.29, p. 290, Program Object State. Add the following state.)

    Get Value           Type  Get Command   Init. Value  Description                 Sec    Attribute
    ----------------    ----  ------------  -----------  -------------------------   -----  ---------
   ACTIVE_VARYINGS_NV   Z+    GetProgramiv       0       Number of active varyings   2.15.3     -
   ACTIVE_VARYING_MAX_  Z+    GetProgramiv       0       Maximum active varying      2.15.3     -
     LENGTH_NV                                           name length
   TRANSFORM_FEEDBACK_  Z2    GetProgramiv  INTERLEAVED_ Transform feedback mode     6.1.14     -
     BUFFER_MODE_NV                         ATTRIBS_NV   for the program
   TRANSFORM_FEEDBACK_  Z+    GetProgramiv       0       Number of varyings to       6.1.14     -
     VARYINGS_NV                                         stream to buffer object(s)
        -               nxZ+  GetVarying-        -       Location of each active     2.15.3     -
                              LocationNV                 varying variable
        -               Z+    GetActive-          -      Size of each active         2.15.3     -
                              VaryingNV                  varying variable
        -               Z+    GetActive-          -      Type of each active         2.15.3     -
                              VaryingNV                  varying variable
        -               0+x-  GetActive-          -      Name of each active         2.15.3     -
                        char  VaryingNV                  varying variable
        -               Z+    GetTransform-       -      Varying location for one    6.1.14     -
                              Feedback-                  of the multiple varyings
                              VaryingNV                  to capture

New Implementation Dependent State

   (Modify Table 6.34, p. 295.  Update the query object state to cover
   transform feedback.)

    Get Value               Type Get Command  Minimum Value  Description                  Sec     Attribute
    --------------------    ---- -----------  -------------  --------------------------   ------  ---------
    QUERY_COUNTER_BITS      2xZ+ GetQueryiv   see 6.1.12     Asynchronous query counter   6.1.12    -
                                                             bits (occlusion, timer, 
                                                             transform feedback queries)

   (Add a new table, Table 6.X. Transform Feedback State.)

   NOTE:  In the "GetValue" columns below, MXFB stands for
   "MAX_TRANSFORM_FEEDBACK".

    Get Value               Type Get Command  Minimum Value  Description                  Sec     Attribute
    --------------------    ---- -----------  -------------  --------------------------   ------  ---------
    MXFB_INTERLEAVED_       Z+   GetIntegerv  64             Max number of components to  2.Y       -
    COMPONENTS_NV                                            write to a single buffer in
                                                             interleaved mode
    MXFB_SEPARATE_          Z+   GetIntegerv  4              Max number of separate       2.Y       -
    ATTRIBS_NV                                               attributes or varyings that
                                                             can be captured in transform
                                                             feedback
    MXFB_SEPARATE           Z+   GetIntegerv  4              Max number of components     2.Y       -
    COMPONENTS_NV                                            per attribute or varying 
                                                             in separate mode

Issues

    1. How does transform feedback differ from core GL feedback?

      * Transform feedback writes vertex data to buffer objects, which allows
        the data returned to be used directly by vertex pulling.  GL feedback
        mode writes vertex data to a buffer in system memory.

      * Transform feedback is done after transformation, but prior to
        clipping.  The primitives returned contain the original transformed
        vertices produced by vertex or geometry program execution, and does
        not contain any primitives inserted by clipping.

      * Transform feedback supports only a single basic output primitive type
        (points, lines, or triangles), while core GL feedback mode supports
        all primitive types.  Since only one primitive type is supported, the
        data returned does not contain tokens describing each primitive being
        fed back.  Primitive tokens make the data returned by GL feedback mode
        irregular and unsuitable for vertex pulling.

    2. What should this extension be called?

      RESOLVED: The current name is "NV_transform_feedback", playing off the
      fact that it is transformed primitives that are handled and the
      similarities to GL feedback mode.

    3. What happens if you bind a buffer for transform feedback that is
       currently bound for other purposes?  Should we somehow detect this case
       and produce an error?

      !!! NBC I feel strongly that we should follow the precedent for
      Map/Unmap. The reason that MapBuffer and UnmapBuffer are a precedent
      here is because while a buffer object is in the mapped state, no GL
      commands are allowed to operate on the buffer object's data.  So by
      analogy, while a buffer is being used for transform feedback, no other
      GL commands should be allowed to operate on the buffer object's data.
      This includes initiating any rendering which would cause the GL to
      source data from an active transform feedback buffer object.

      UNRESOLVED

    4. Should this extension include any new buffer object binding targets, or
       should it overload ARRAY_BUFFER, or should we skip the binding target
       altogether in favor of a buffer object name accepted directly by the
       new GL commands?

      RESOLVED: There are new binding points for XFB along with a new API
      (BindBufferBase etc) to set the internal binding points. A new binding
      point, TRANSFORM_FEEDBACK_BUFFER_NV is also introduced.

    5. Previous buffer object extensions provided a way to have existing GL
       commands reference a buffer object instead of a user-supplied buffer.
       Should the new commands introduced here allow referencing a
       user-supplied buffer in addition to a buffer object?

      RESOLVED: No. A program can get the contents of the feedback buffer back
      to the CPU using MapBuffer and GetBufferSubData

    6. Is BeginTransformFeedback really necessary? Could the query just
       initiate the transform feedback mode?

      RESOLUTION: Using BeginTransformFeedback and EndTransformFeedback gives
      a clean place to spec all of the transform-feedback-specific issues
      without cluttering up the query language. Also, the queries don't have
      to be done at the same time as beginning and ending the feedback
      process.

    7. What usage enums should be provided to glBufferData for use in
       conjunction with transform feedback?

      RESOLVED: STREAM_COPY or STREAM_READ are expected to be the most common
      usages. If a buffer object is being written by the GL through transform
      feedback, and the contents of the buffer object are subsequently being
      consumed by the GL (e.g. by being used as a vertex buffer object), then
      this is a *_COPY usage. If the buffer object is being written by the GL
      through transform feedback, but is being consumed by the application
      (e.g. being mapped for read), this is a *_READ usage.  The temporal
      (STREAM, STATIC, or DYNAMIC) component of the usage enum is determined
      by the ratio between how often the contents of the buffer object are
      modified and how often operations that source data from the buffer
      object occur.

    8. What should the behavior be when a buffer object is the active target
       of transform feedback, and it is deleted via DeleteBuffers?

      RESOLVED: Deletion is deferred until the EndTransformFeedback if
      transform feedback is active.

    9. Should we allow more buffers to be bound than are used?

      RESOLVED: Yes. The extra buffers are not in the way and can stay bound.

    10. Should we allow feedback to buffer lists with holes (i.e. 0 and 2
        bound)?

      RESOLVED: No. This makes for an ugly API with the potential for bugs,
      without any real benefit. The application can as well bind all buffers
      needed to incremented indices. It is an invalid operation to not have a
      buffer bound where one is required.

    11. Why only one feedback primitive mode per feedback invocation?

      RESOLVED: Having primitive tokens breaks up the stream and makes it less
      amenable to being read back in as a vertex buffer. Also, mixing multiple
      primitive types makes the counting of primitives less clear for the
      application.

    12. Is RasterPos fed back?

      RESOLVED: No.

    13. Is DrawPixels/CopyPixels/Bitmap fed back?

      RESOLVED: No. Rasterization occurs as normal, but there is no
      output to the feedback buffer. This is consistent with taking a
      tap out of the pipe before clipping.

    14. Why do we need new BindBuffer* functions?

      RESOLVED: All previous buffer object extensions have been retrofits of
      existing pointer-based APIs. New extensions built assuming buffer
      objects don't have that history, so need a new API. The functionality of
      these new functions combines the functionality of BindBuffer, to set the
      external bind point used by calls like MapBuffer and BufferSubData, with
      the functionality to set an internal bind point like VertexAttribPointer
      does.

   15. How do the transform feedback indices, passed to the BindBuffer*
       commands, work with multiple bindings?

      RESOLVED: The same way that they work with vertex arrays. There is one
      external bind point, TRANSFORM_FEEDBACK_BUFFER_NV. There are n internal
      bind points, selected with the <index> parameter to the BindBuffer*
      commands, where n is some implementation dependent limit. The
      BindBuffer* commands take the buffer passed and bind it to the external
      bind point, as well as to the selected internal bind point.

      For example:

        BindBufferOffsetNV(TRANSFORM_FEEDBACK_BUFFER_NV, 0, 1, 12); 
        // XFB index 0 points at buffer 1 with offset 12

        BindBuffer(TRANSFORM_FEEDBACK_BUFFER_NV, 2); 
        // Buffer 2 is now bound to the external bind point. XFB index 0 still
        // points at buffer 1

        MapBuffer(TRANSFORM_FEEDBACK_BUFFER_NV, ...); 
        // Maps buffer 2

    16. How are quads/quadstrips/polygons tessellated into triangles?

      RESOLVED: In an implementation-dependent manner. OpenGL doesn't define
      quads or polygons in terms of triangles, so there is no one correct way
      to do it, and different GPUs may implement the behavior differently. A
      quad may be split into two triangles in several different ways, and an
      application may not rely on this behavior.

    17. How does this extension interact with display lists?

      RESOLVED: Just like the VBO extension, none of the BindBuffer* commands
      are compiled into a display list.

    18. Does polygon mode state affect the logic that determines if the
        transform feed back primitive mode and the render mode states are
        valid at the start of transform feedback mode?

      RESOLVED: PolygonMode has no influence on the BeginTransFormFeedback
      primitiveMode check since it is performed later, in raster.

    19. What to do with incomplete primitives?

      RESOLVED: If there is no room to store one or more vertices of a
      primitive in a buffer object, none of the vertices in that primitive are
      written to the buffer. If a partial primitive enters transform feedback
      (i.e. only two vertices sent in triangles mode), none of the vertices in
      that primitive are written to the buffer object.

    20. Why does TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN_NV have a
        TRANSFORM_FEEDBACK prefix but PRIMITIVES_GENERATED_NV doesn't?

      RESOLVED: The number of primitives generated is independent of any
      feedback that is active. The number of primitives that are written is
      only valid for transform feedback - another extension could conceivably
      have a different way of writing out primitives that would require a
      similar but distinct token.

    21. When a GLSL vertex shader is active, what happens in transform
        feedback mode if non-active varying variables are specified?

      DISCUSSION: Active varying variables are varying variables, declared in
      the shader, that the linker determined are actually needed. As an
      optimization, the linker can discard the ones declared, but not
      needed. If non-active varying variables need to be fed into a buffer
      object, the linker should not perform this optimization.

      There are three suggested resolutions to this problem:

        1. The set of varying variables that need to be streamed to a buffer
           object in transform feedback mode are set as a property of the
           program object, and are taken into account during the link step.
           This means that changing the set means the application will have to
           re-link the program object in order to have the change take effect.

        2. The set of varying variables that need to be streamed to a buffer
           object in transform feedback mode are specified after the program
           object has been linked. This is the most flexible option from the
           applications perspective, but this might mean that a) specifying
           this set could force the GL to re-link 'under the covers', and b)
           could mean that the GL runs out of varying variable slots because
           the combined total of the set of active varyings and the varyings
           to stream in transform feedback mode is too large.

        3. This solution is a hybrid of the above two approaches. The set of
           potential varying variables that need to be streamed to a buffer
           object are set as a property of the program object. These varying
           variables are marked as active by the application and therefore
           cannot be eliminated during the link step. However, a sub-set of
           varying variables to actually stream to a buffer object can be
           changed without the application having to re-link the program
           object. This approach gives the application flexibility to change
           the set of varying variables to stream, while it eliminates the
           need for the GL to compile 'under the covers'.

      RESOLUTION: Option 3 offers a good compromise, and therefore we'll go
      with that.

    22. Given option 3 in the previous resolution, how to specify that a
        varying variable has to be considered active by the linker?

      DISCUSSION: There are two approaches to the application specifying which
      varying variables are active. We can either provide a simple flag that
      specifies that all varying variables are considered active, or we can
      provide a more complex mechanism where the application can specify an
      individual varying variable as being active.

      RESOLUTION: RESOLVED. The 'all or nothing' flag is a simple idea, but
      has a drawback when used with a 'uber-shader' that implements many paths
      to achieve an effect, but only one path is used during any run of the
      shader. In this case, a lot more varying variables might be flagged as
      active then really is necessary, running the risk of running out of
      resources. Therefore, we'll provide a mechanism for the application to
      specify on a per varying variable basis if it is active.

    23. Given the discussion in the previous issues, should a
        GetActiveVarying() command be added, modeled after the existing
        getActiveUniform() command?

      DISCUSSION: Such a command will return the list of active uniforms,
      after the program object has been linked. As per issue 22's resolution,
      the complete set of varying variables that could be streamed to a buffer
      object needs to be specified before the program object is linked.

      It can be useful to an application to stream out a subset of the active
      varying variables or to find out the whole set of active varyings,
      especially since the set can be implementation dependent.

      RESOLUTION: YES.

    24. What is proper use of the command ActiveVaryingNV()?

      RESOLVED: The application is well advised to force any varying variable
      live that it needs for transform feedback purposes. The set of active
      varying variables are linker dependent. For example, if a program object
      has no fragment shader, then the LinkProgram command cannot typically
      determine which built-in varying variables, output by a geometry or
      vertex shader, are active. This is because the fragment processing state
      can change, and therefore such a determination cannot be made until a
      render command is issued. Furthermore, any user-defined varyings are
      likely to be marked as non-active if there is no fragment shader because
      they are guaranteed to have no effect on fixed-function fragment
      processing. If there is both a vertex (or geometry) and fragment shader
      in a program object, the application can probably deduce what will be an
      active varying variable, or not. But beware of any (static) flow-control
      that the linker can use to do cross vertex- fragment optimization to
      cull any varying variables.

    25. Are primitives sent down the pipeline after transform feedback, or
        discarded?

      RESOLVED: Primitives can be optionally discarded before rasterization by
      calling Enable and Disable with RASTERIZER_DISCARD_NV. When enabled,
      primitives are discarded after vertex attributes are recorded into the
      buffer objects bound to transform feedback.  When disabled, primitives
      are passed through to the rasterization stage to be clipped and
      rasterized normally. All rasterization operations are discarded, not
      just those that are fed back into the buffer.

      This applies to DrawPixels, CopyPixels, Bitmap, Clear, Accum as well.

    26. If a varying is declared as an array, is the whole array streamed out?

      RESOLVED: No, the application has to specify which elements of an array
      it wants to stream out. Implementations might not be able to stream out
      a large number of components to a single buffer object.  If that is the
      case, the application can stream each element of an array to a different
      buffer object in TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS mode.

    27. Is it possible to capture attributes when using the fixed-function
        pipeline?

      RESOLVED: Yes, there is nothing that precludes this. The application is
      responsible for sending down the needed vertex attributes and setting
      the GL state, as desired, for the attributes it wants to stream to a
      buffer object. Note that VERTEX_ID_NV is not defined in fixed-function.

    28. Is it possible to record hardware-generated primitive ID values that
        would be available to a pixel shader?

      RESOLVED:  Transform feedback can only record the primitive ID values
      emitted per-vertex by a geometry shader or program.  While each
      primitive recorded for transform-feedback has a well-defined primitive
      ID, transform feedback is only capable of recording the attributes of
      individual vertices.

    29.  Does transform feedback support the ability to capture per-vertex
         layer outputs, as provided by EXT_geometry_shader4 and
         NV_geometry_program4?

      RESOLVED:  Yes.  For GLSL shaders, it is sufficient to reference the
      built-in varying "gl_Layer".  For assembly geometry programs, the
      original version of the spec did not provide an enum allowing you to
      name "result.layer" in TransformFeedbackAttribsNV.  This was an
      oversight in the original spec, which was fixed by version 14.  An
      updated driver will be required to take advantage of this capability;
      NVIDIA drivers supporting this extension published prior to February
      2008 will not be able to capture "result.layer".  The value captured for
      LAYER_NV will be undefined unless a geometry program that writes
      "result.layer" is active.

Revision History

      Rev.    Date    Author    Changes
      ----  --------  --------  -----------------------------------------
       18   03/09/11  mjk       Minor typo fixes.

       17   01/28/11  pbrown    Change return value for start/size queries
                                when no buffer bound from -1 to zero, to
                                match state tables (Bug 7318), as done by
                                Jon Leech in related EXT/ARB extensions and
                                the core API specification.

       16   08/17/08  pbrown    Remove a non-existent function from the
                                set of functions that can generate invalid
                                operation errors while XFB is active.

       15   02/20/08  pbrown    Fix incorrect minimum for MAX_TRANSFORM_
                                FEEDBACK_SEPARATE_COMPONENTS_NV.  Should be
                                4, not 16.

       14   02/04/08  pbrown    Fixed a problem with the spec where we were
                                unable to record "result.layer" using the
                                assembly interface.  Added a new enum to 
                                address.

       13   11/28/07  pbrown    Specified the captured primitive ID to be
                                undefined unless a geometry shader emits it
                                as a vertex output.  XFB can only record
                                per-vertex data.

       12   09/27/07  pbrown    Removed incorrect error description from
                                the errors section -- buffer objects don't
                                need to be bound before calling Transform-
                                Feedback{Attribs,Varyings}NV, just before
                                BeginTransformFeedbackNV.

       11   08/28/07  pbrown    Added an error calling BeginTransformFeedback
                                if no attributes would be captured (i.e.,
                                attribute count is 0 for ASM or no attributes
                                specified in the active GLSL program).

       10   02/09/07  pbrown    Updated status section (now released).

        9   10/23/06  pbrown    Fixed prototype for GetIntegerIndexedEXT and
                                GetBooleanIndexedEXT:  <index> is unsigned.

        8   10/19/06  pbrown    Removed stray addition of GetFloatIndexedvEXT
                                and GetDoubleIndexedvEXT.  Minor wording
                                fixes.

        7   10/17/06  pbrown    Rename from EXT to NV while working on
                                standardizing a functional subset extension
                                that will be named EXT_transform_feedback.  We
                                expect that the EXT should be equivalent to
                                the NV, except that it (a) removes support for
                                non-GLSL usage, (b) removes the ability to
                                change the set of varyings captured without
                                relinking.  NVIDIA expects to support both the
                                NV and EXT forms of this extension going
                                forward.  Fix state table formatting.  Removed
                                GetFloatIndexedvEXT and GetDoubleIndexedvEXT,
                                which are not needed by this and related
                                extensions.

        6   09/11/06  pbrown    Fix bad prototype for GetActiveVaryingEXT
                                and bad references to "GetActiveVaryingsEXT".
                                Fix enum names for INTERLEAVED_ATTRIBS_EXT and
                                SEPARATE_ATTRIBS_EXT (no TRANSFORM_ FEEDBACK
                                prefix).  Remove erroneous state table entries
                                that were obsoleted by the introduction of the
                                TRANSFORM_FEEDBACK_RECORD_EXT query.
       
        5   08/31/06  pbrown    Fix miscellaneous spec errata.   Record enum
                                values that weren't documented in previous
                                spec versions.  Use correct function names for
                                indexed "Get" functions.  Clarify that GLSL
                                interactions mean that some functions and
                                enums defined here aren't supported if GLSL
                                isn't supported.  Fixed the double-assignment
                                of several TransformFeedbackAttribsEXT enums
                                and re-packed that portion of the enum range.
                                Clarify that several new functions are
                                non-listable.  Fix the query tokens for buffer
                                object range bindings to match the API
                                (start/size, not start/end).

        4   08/30/06  pbrown    Reformatting as a plaintext document 
                                instead of an exported MS Word document.

        3   07/26/06  barthold  Forgot a few changes w.r.t. version 2.

        2   07/14/06  barthold  Change BindBufferRangeEXT to take an
                                offset and size parameter. Change 
                                BindBufferOffsetEXT to take an offset
                                parameter.

        1             barthold  Internal spec development.