Merge branch 'sprite-coord'

2 files changed, 141 insertions, 5 deletions

diff --git a/src/gallium/docs/source/cso/rasterizer.rst b/src/gallium/docs/source/cso/rasterizer.rst
index ee3419ccfc..d547055096 100644
--- a/src/gallium/docs/source/cso/rasterizer.rst
+++ b/src/gallium/docs/source/cso/rasterizer.rst
@@ -124,17 +124,24 @@ Points
 sprite_coord_enable
 ^^^^^^^^^^^^^^^^^^^
 
-Specifies if a texture unit has its texture coordinates replaced or not. This
-is a packed bitfield containing the enable for all texcoords -- if all bits
-are zero, point sprites are effectively disabled. 
+Controls automatic texture coordinate generation for rendering sprite points.
+
+When bit k in the sprite_coord_enable bitfield is set, then generic
+input k to the fragment shader will get an automatically computed
+texture coordinate.
+
+The texture coordinate will be of the form (s, t, 0, 1) where s varies
+from 0 to 1 from left to right while t varies from 0 to 1 according to
+the state of 'sprite_coord_mode' (see below).
 
 If any bit is set, then point_smooth MUST be disabled (there are no
 round sprites) and point_quad_rasterization MUST be true (sprites are
 always rasterized as quads).  Any mismatch between these states should
 be considered a bug in the state-tracker.
 
-If enabled, the four vertices of the resulting quad will be assigned
-texture coordinates, according to sprite_coord_mode.
+This feature is implemented in the :ref:`Draw` module but may also be
+implemented natively by GPUs or implemented with a geometry shader.
+
 
 sprite_coord_mode
 ^^^^^^^^^^^^^^^^^
@@ -145,6 +152,7 @@ have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left
 vertex will have coordinates (0,0,0,1).
 This state is used by :ref:`Draw` to generate texcoords.
 
+
 point_quad_rasterization
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/src/gallium/docs/source/pipeline.txt b/src/gallium/docs/source/pipeline.txt
new file mode 100644
index 0000000000..fd1fbe9c76
--- /dev/null
+++ b/src/gallium/docs/source/pipeline.txt
@@ -0,0 +1,128 @@
+XXX this could be converted/formatted for Sphinx someday.
+XXX do not use tabs in this file.
+
+
+
+            position                     ]
+            primary/secondary colors     ]
+            generics (normals,           ]
+               texcoords, fog)           ] User vertices / arrays
+            point size                   ]
+            edge flag                    ]
+            primitive ID                 } System-generated values
+            vertex ID                    }
+              | | |
+              V V V
+      +-------------------+
+      |  Vertex shader    |
+      +-------------------+
+              | | |
+              V V V
+            position
+            clip distance
+            generics
+            front/back & primary/secondary colors
+            point size
+            edge flag
+            primitive ID
+              | | |
+              V V V
+      +------------------------+
+      |     Geometry shader    |
+      | (consume vertex ID)    |
+      | (may change prim type) |
+      +------------------------+
+              | | |
+              V V V
+            [...]
+            fb layer
+              | | |
+              V V V
+      +--------------------------+
+      |         Clipper          |
+      | (consume clip distances) |
+      +--------------------------+
+              | | |
+              V V V
+      +-------------------+
+      |  Polygon Culling  |
+      +-------------------+
+              | | |
+              V V V
+      +-----------------------+
+      |    Choose front or    |
+      |    back face color    |
+      | (consume other color) |
+      +-----------------------+
+              | | |
+              V V V
+            [...]
+            primary/secondary colors only
+              | | |
+              V V V
+      +-------------------+
+      |   Polygon Offset  |
+      +-------------------+
+              | | |
+              V V V
+      +----------------------+
+      | Unfilled polygons    |
+      | (consume edge flags) |
+      | (change prim type)   |
+      +----------------------+
+              | | |
+              V V V
+            position
+            generics
+            primary/secondary colors
+            point size
+            primitive ID
+            fb layer
+              | | |
+              V V V
+  +---------------------------------+ 
+  | Optional Draw module helpers    |
+  | * Polygon Stipple               |
+  | * Line Stipple                  |
+  | * Line AA/smooth (as tris)      |
+  | * Wide lines (as tris)          |
+  | * Wide points/sprites (as tris) |
+  | * Point AA/smooth (as tris)     |
+  | (NOTE: these stages may emit    |
+  |  new/extra generic attributes   |
+  |  such as texcoords)             |
+  +---------------------------------+
+              | | |
+              V V V
+            position                     ]
+            generics (+ new/extra ones)  ]
+            primary/secondary colors     ] Software rast vertices
+            point size                   ]
+            primitive ID                 ]
+            fb layer                     ]
+              | | |
+              V V V
+      +---------------------+
+      | Triangle/Line/Point |
+      |    Rasterization    |
+      +---------------------+
+              | | |
+              V V V
+            generic attribs
+            primary/secondary colors
+            primitive ID
+            fragment win coord pos   } System-generated values
+            front/back face flag     }
+              | | |
+              V V V
+      +-------------------+
+      |  Fragment shader  |
+      +-------------------+
+              | | |
+              V V V
+            zero or more colors
+            zero or one Z value
+
+
+NOTE: The instance ID is not shown.  It can be imagined to be a global variable
+accessible to all shader stages.