gallium: interface changes necessary to implement transform feedback (v5)

Namely:
- EXT_transform_feedback
- ARB_transform_feedback2
- ARB_transform_feedback_instanced

The old interface was not useful for OpenGL and had to be reworked.

This interface was originally designed for OpenGL, but additional
changes have been made in order to make st/d3d1x support easier.

The most notable change is the stream-out info must be linked
with a vertex or geometry shader and cannot be set independently.
This is due to limitations of existing hardware (special shader
instructions must be used to write into stream-out buffers),
and it's also how OpenGL works (stream outputs must be specified
prior to linking shaders).

Other than that, each stream output buffer has a "view" into it that
internally maintains the number of bytes which have been written
into it. (one buffer can be bound in several different transform
feedback objects in OpenGL, so we must be able to have several views
around) The set_stream_output_targets function contains a parameter
saying whether new data should be appended or not.

Also, the view can optionally be used to provide the vertex
count for draw_vbo. Note that the count is supposed to be stored
in device memory and the CPU never gets to know its value.

OpenGL way | Gallium way
------------------------------------
BeginTF    = set_so_targets(append_bitmask = 0)
PauseTF    = set_so_targets(num_targets = 0)
ResumeTF   = set_so_targets(append_bitmask = ~0)
EndTF      = set_so_targets(num_targets = 0)
DrawTF     = use pipe_draw_info::count_from_stream_output

v2: * removed the reset_stream_output_targets function
    * added a parameter append_bitmask to set_stream_output_targets,
      each bit specifies whether new data should be appended to each
      buffer or not.
v3: * added PIPE_CAP_STREAM_OUTPUT_PAUSE_RESUME for ARB_tfb2,
      note that the draw-auto subset is always required (for d3d10),
      only the pause/resume functionality is limited if the CAP is not
      advertised
v4: * update gallium/docs
v5: * compactified struct pipe_stream_output_info, updated dump/trace

1 files changed, 41 insertions, 20 deletions

diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index 391139fb0ef..b2872cd282f 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -54,8 +54,6 @@ buffers, surfaces) are bound to the driver.
 
 * ``set_index_buffer``
 
-* ``set_stream_output_buffers``
-
 
 Non-CSO State
 ^^^^^^^^^^^^^
@@ -139,6 +137,47 @@ cube, and 3d textures otherwise they are 0.
 * ``surface_destroy`` destroys a surface and releases its reference to the
   associated resource.
 
+Stream output targets
+^^^^^^^^^^^^^^^^^^^^^
+
+Stream output, also known as transform feedback, allows writing the primitives
+produced by the vertex pipeline to buffers. This is done after the geometry
+shader or vertex shader if no geometry shader is present.
+
+The stream output targets are views into buffer resources which can be bound
+as stream outputs and specify a memory range where it's valid to write
+primitives. The pipe driver must implement memory protection such that any
+primitives written outside of the specified memory range are discarded.
+
+Two stream output targets can use the same resource at the same time, but
+with a disjoint memory range.
+
+Additionally, the stream output target internally maintains the offset
+into the buffer which is incremented everytime something is written to it.
+The internal offset is equal to how much data has already been written.
+It can be stored in device memory and the CPU actually doesn't have to query
+it.
+
+The stream output target can be used in a draw command to provide
+the vertex count. The vertex count is derived from the internal offset
+discussed above.
+
+* ``create_stream_output_target`` create a new target.
+
+* ``stream_output_target_destroy`` destroys a target. Users of this should
+  use pipe_so_target_reference instead.
+
+* ``set_stream_output_targets`` binds stream output targets. The parameter
+  append_bitmask is a bitmask, where the i-th bit specifies whether new
+  primitives should be appended to the i-th buffer (writing starts at
+  the internal offset), or whether writing should start at the beginning
+  (the internal offset is effectively set to 0).
+
+NOTE: The currently-bound vertex or geometry shader must be compiled with
+the properly-filled-in structure pipe_stream_output_info describing which
+outputs should be written to buffers and how. The structure is part of
+pipe_shader_state.
+
 Clearing
 ^^^^^^^^
 
@@ -394,24 +433,6 @@ The interfaces to these calls are likely to change to make it easier
 for a driver to batch multiple blits with the same source and
 destination.
 
-
-Stream Output
-^^^^^^^^^^^^^
-
-Stream output, also known as transform feedback allows writing the results of the
-vertex pipeline (after the geometry shader or vertex shader if no geometry shader
-is present) to be written to a buffer created with a ``PIPE_BIND_STREAM_OUTPUT``
-flag.
-
-First a stream output state needs to be created with the
-``create_stream_output_state`` call. It specific the details of what's being written,
-to which buffer and with what kind of a writemask.
-
-Then target buffers needs to be set with the call to ``set_stream_output_buffers``
-which sets the buffers and the offsets from the start of those buffer to where
-the data will be written to.
-
-
 Transfers
 ^^^^^^^^^