3 files changed, 69 insertions, 33 deletions

diff --git a/src/gallium/docs/source/cso/blend.rst b/src/gallium/docs/source/cso/blend.rst
index 55c0f32885..c74396284c 100644
--- a/src/gallium/docs/source/cso/blend.rst
+++ b/src/gallium/docs/source/cso/blend.rst
@@ -28,7 +28,7 @@ logicop_enable
 logicop_func
    The logic operation to use if logic ops are enabled. One of PIPE_LOGICOP.
 dither
-   Whether dithering is enabled.
+   Whether dithering is enabled. Note: Dithering is implementation-dependent.
 rt
    Contains the per-rendertarget blend state.
 
diff --git a/src/gallium/docs/source/cso/rasterizer.rst b/src/gallium/docs/source/cso/rasterizer.rst
index ccd9136a2e..56a601a8d0 100644
--- a/src/gallium/docs/source/cso/rasterizer.rst
+++ b/src/gallium/docs/source/cso/rasterizer.rst
@@ -7,7 +7,7 @@ The rasterizer state controls the rendering of points, lines and triangles.
 Attributes include polygon culling state, line width, line stipple,
 multisample state, scissoring and flat/smooth shading.
 
-Members
+Shading
 -------
 
 flatshade
@@ -46,6 +46,49 @@ There are several important exceptions to the specification of this rule.
   second vertex, not the first. This permits each segment of the fan to have
   a different color.
 
+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. If any bit is set, then
+point_smooth and point_quad_rasterization are ignored; point smoothing is
+disabled and points are always rasterized as quads. If enabled, the four
+vertices of the resulting quad will be assigned texture coordinates,
+according to sprite_coord_mode.
+
+sprite_coord_mode
+^^^^^^^^^^^^^^^^^
+
+Specifies how the value for each shader output should be computed when drawing
+point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will
+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.
+
+.. note::
+
+    When geometry shaders are available, a special geometry shader could be
+    used instead of this functionality, to convert incoming points into quads
+    with the proper texture coordinates.
+
+point_quad_rasterization
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Determines if points should be rasterized as quads or points. Certain APIs,
+like Direct3D, always use quad rasterization for points, regardless of
+whether point sprites are enabled or not. If this state is enabled, point
+smoothing and antialiasing are disabled. If it is disabled, point sprite
+coordinates are not generated.
+
+.. note::
+
+   Some renderers always internally translate points into quads; this state
+   still affects those renderers by overriding other rasterization state.
+
 Other Members
 ^^^^^^^^^^^^^
 
@@ -107,37 +150,6 @@ point_size_per_vertex
     Whether vertices have a point size element.
 point_size
     The size of points, if not specified per-vertex.
-sprite_coord_enable
-    Specifies if a coord has its texture coordinates replaced or not. This
-    is a packed bitfield containing the enable for all coords - if all are 0
-    point sprites are effectively disabled, though points may still be
-    rendered slightly different according to point_quad_rasterization.
-    If any coord is non-zero, point_smooth should be disabled, and
-    point_quad_rasterization enabled.
-    If enabled, the four vertices of the resulting quad will be assigned
-    texture coordinates, according to sprite_coord_mode.
-sprite_coord_mode
-    Specifies how the value for each shader output should be computed when
-    drawing sprites, for each coord which has sprite_coord_enable set.
-    For PIPE_SPRITE_COORD_LOWER_LEFT, the lower left vertex will have
-    coordinate (0,0,0,1).
-    For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left vertex will have
-    coordinate (0,0,0,1).
-    This state is needed by :ref:`Draw` because that's where each
-    point vertex is converted into four quad vertices.  There's no other
-    place to emit the new vertex texture coordinates which are required for
-    sprite rendering.
-    Note that when geometry shaders are available, this state could be
-    removed.  A special geometry shader defined by the state tracker could
-    convert the incoming points into quads with the proper texture coords.
-point_quad_rasterization
-    This determines if points should be rasterized as quads or points.
-    d3d always uses quad rasterization for points, regardless if point sprites
-    are enabled or not, but OGL has different rules. If point_quad_rasterization
-    is set, point_smooth should be disabled, and points will be rendered as
-    squares even if multisample is enabled.
-    sprite_coord_enable should be zero if point_quad_rasterization is not
-    enabled.
 
 scissor
     Whether the scissor test is enabled.
diff --git a/src/gallium/docs/source/cso/velems.rst b/src/gallium/docs/source/cso/velems.rst
new file mode 100644
index 0000000000..92cde014fb
--- /dev/null
+++ b/src/gallium/docs/source/cso/velems.rst
@@ -0,0 +1,24 @@
+.. _vertexelements:
+
+Vertex Elements
+===============
+
+This state controls format etc. of the input attributes contained
+in the pipe_vertex_buffer(s). There's one pipe_vertex_element array member
+for each input attribute.
+
+Members
+-------
+
+src_offset
+    The byte offset of the attribute in the buffer given by
+    vertex_buffer_index for the first vertex.
+instance_divisor
+    The instance data rate divisor, used for instancing.
+    0 means this is per-vertex data, n means per-instance data used for
+    n consecutive instances (n > 0).
+vertex_buffer_index
+    The vertex buffer this attribute lives in. Several attributes may
+    live in the same vertex buffer.
+src_format
+    The format of the attribute data. One of the PIPE_FORMAT tokens.