gallium/docs: added new pipeline.txt diagram

This diagram shows the rendering pipeline with an emphasis on
the inputs/outputs for each stage.  Some stages emit new vertex
attributes and others consume some attributes.

1 files changed, 128 insertions, 0 deletions

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.