4 files changed, 175 insertions, 52 deletions

diff --git a/src/gallium/docs/source/cso/blend.rst b/src/gallium/docs/source/cso/blend.rst
index c74396284cc..7bde10c1245 100644
--- a/src/gallium/docs/source/cso/blend.rst
+++ b/src/gallium/docs/source/cso/blend.rst
@@ -14,21 +14,74 @@ in other modern and legacy drawing APIs.
 
 XXX blurb about dual-source blends
 
+Logical Operations
+------------------
+
+Logical operations, also known as logicops, lops, or rops, are supported.
+Only two-operand logicops are available. When logicops are enabled, all other
+blend state is ignored, including per-render-target state, so logicops are
+performed on all render targets.
+
+.. warning::
+   The blend_enable flag is ignored for all render targets when logical
+   operations are enabled.
+
+For a source component `s` and destination component `d`, the logical
+operations are defined as taking the bits of each channel of each component,
+and performing one of the following operations per-channel:
+
+* ``CLEAR``: 0
+* ``NOR``: :math:`\lnot(s \lor d)`
+* ``AND_INVERTED``: :math:`\lnot s \land d`
+* ``COPY_INVERTED``: :math:`\lnot s`
+* ``AND_REVERSE``: :math:`s \land \lnot d`
+* ``INVERT``: :math:`\lnot d`
+* ``XOR``: :math:`s \oplus d`
+* ``NAND``: :math:`\lnot(s \land d)`
+* ``AND``: :math:`s \land d`
+* ``EQUIV``: :math:`\lnot(s \oplus d)`
+* ``NOOP``: :math:`d`
+* ``OR_INVERTED``: :math:`\lnot s \lor d`
+* ``COPY``: :math:`s`
+* ``OR_REVERSE``: :math:`s \lor \lnot d`
+* ``OR``: :math:`s \lor d`
+* ``SET``: 1
+
+.. note::
+   The logical operation names and definitions match those of the OpenGL API,
+   and are similar to the ROP2 and ROP3 definitions of GDI. This is
+   intentional, to ease transitions to Gallium.
+
 Members
 -------
 
+These members affect all render targets.
+
+dither
+%%%%%%
+
+Whether dithering is enabled.
+
+.. note::
+   Dithering is completely implementation-dependent. It may be ignored by
+   drivers for any reason, and some render targets may always or never be
+   dithered depending on their format or usage flags.
+
+logicop_enable
+%%%%%%%%%%%%%%
+
+Whether the blender should perform a logicop instead of blending.
+
+logicop_func
+%%%%%%%%%%%%
+
+The logicop to use. One of ``PIPE_LOGICOP``.
+
 independent_blend_enable
    If enabled, blend state is different for each render target, and
    for each render target set in the respective member of the rt array.
    If disabled, blend state is the same for all render targets, and only
    the first member of the rt array contains valid data.
-logicop_enable
-   Enables logic ops. Cannot be enabled at the same time as blending, and
-   is always the same for all render targets.
-logicop_func
-   The logic operation to use if logic ops are enabled. One of PIPE_LOGICOP.
-dither
-   Whether dithering is enabled. Note: Dithering is implementation-dependent.
 rt
    Contains the per-rendertarget blend state.
 
diff --git a/src/gallium/docs/source/cso/velems.rst b/src/gallium/docs/source/cso/velems.rst
index 92cde014fb8..978ad4a2434 100644
--- a/src/gallium/docs/source/cso/velems.rst
+++ b/src/gallium/docs/source/cso/velems.rst
@@ -3,9 +3,44 @@
 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.
+This state controls the format of the input attributes contained in
+pipe_vertex_buffers. There is one pipe_vertex_element array member for each
+input attribute.
+
+Input Formats
+-------------
+
+Gallium supports a diverse range of formats for vertex data. Drivers are
+guaranteed to support 32-bit floating-point vectors of one to four components.
+Additionally, they may support the following formats:
+
+* Integers, signed or unsigned, normalized or non-normalized, 8, 16, or 32
+  bits wide
+* Floating-point, 16, 32, or 64 bits wide
+
+At this time, support for varied vertex data formats is limited by driver
+deficiencies. It is planned to support a single uniform set of formats for all
+Gallium drivers at some point.
+
+Rather than attempt to specify every small nuance of behavior, Gallium uses a
+very simple set of rules for padding out unspecified components. If an input
+uses less than four components, it will be padded out with the constant vector
+``(0, 0, 0, 1)``.
+
+Fog, point size, the facing bit, and edgeflags, all are in the standard format
+of ``(x, 0, 0, 1)``, and so only the first component of those inputs is used.
+
+Position
+%%%%%%%%
+
+Vertex position may be specified with two to four components. Using less than
+two components is not allowed.
+
+Colors
+%%%%%%
+
+Colors, both front- and back-facing, may omit the alpha component, only using
+three components. Using less than three components is not allowed.
 
 Members
 -------
diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst
index 48d9d570b6f..e3ef49c862c 100644
--- a/src/gallium/docs/source/screen.rst
+++ b/src/gallium/docs/source/screen.rst
@@ -36,7 +36,9 @@ The integer capabilities:
   bound.
 * ``OCCLUSION_QUERY``: Whether occlusion queries are available.
 * ``TIMER_QUERY``: Whether timer queries are available.
-* ``TEXTURE_SHADOW_MAP``: XXX
+* ``TEXTURE_SHADOW_MAP``: indicates whether the fragment shader hardware
+  can do the depth texture / Z comparison operation in TEX instructions
+  for shadow testing.
 * ``MAX_TEXTURE_2D_LEVELS``: The maximum number of mipmap levels available
   for a 2D texture.
 * ``MAX_TEXTURE_3D_LEVELS``: The maximum number of mipmap levels available
@@ -55,7 +57,13 @@ The integer capabilities:
   from color blend equations, in :ref:`Blend` state.
 * ``SM3``: Whether the vertex shader and fragment shader support equivalent
   opcodes to the Shader Model 3 specification. XXX oh god this is horrible
-* ``MAX_PREDICATE_REGISTERS``: XXX
+* ``MAX_PREDICATE_REGISTERS``: indicates the number of predicate registers
+  available.  Predicate register may be set as a side-effect of ALU
+  instructions to indicate less than, greater than or equal to zero.
+  Later instructions can use a predicate register to control writing to
+  each channel of destination registers.  NOTE: predicate registers have
+  not been fully implemented in Gallium at this time.  See the
+  GL_NV_fragment_program extension for more info (look for "condition codes").
 * ``MAX_COMBINED_SAMPLERS``: The total number of samplers accessible from
   the vertex and fragment shader, inclusive.
 * ``MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
diff --git a/src/gallium/docs/source/tgsi.rst b/src/gallium/docs/source/tgsi.rst
index ecab7cb8097..e588c5b7bd8 100644
--- a/src/gallium/docs/source/tgsi.rst
+++ b/src/gallium/docs/source/tgsi.rst
@@ -1286,6 +1286,8 @@ wrapping rules.
 Declaration Semantic
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
+  Vertex and fragment shader input and output registers may be labeled
+  with semantic information consisting of a name and index.
 
   Follows Declaration token if Semantic bit is set.
 
@@ -1306,90 +1308,115 @@ Declaration Semantic
 TGSI_SEMANTIC_POSITION
 """"""""""""""""""""""
 
-Position, sometimes known as HPOS or WPOS for historical reasons, is the
-location of the vertex in space, in ``(x, y, z, w)`` format. ``x``, ``y``, and ``z``
-are the Cartesian coordinates, and ``w`` is the homogenous coordinate and used
-for the perspective divide, if enabled.
+For vertex shaders, TGSI_SEMANTIC_POSITION indicates the vertex shader
+output register which contains the homogeneous vertex position in the clip
+space coordinate system.  After clipping, the X, Y and Z components of the
+vertex will be divided by the W value to get normalized device coordinates.
 
-As a vertex shader output, position should be scaled to the viewport. When
-used in fragment shaders, position will be in window coordinates. The convention
-used depends on the FS_COORD_ORIGIN and FS_COORD_PIXEL_CENTER properties.
+For fragment shaders, TGSI_SEMANTIC_POSITION is used to indicate that
+fragment shader input contains the fragment's window position.  The X
+component starts at zero and always increases from left to right.
+The Y component starts at zero and always increases but Y=0 may either
+indicate the top of the window or the bottom depending on the fragment
+coordinate origin convention (see TGSI_PROPERTY_FS_COORD_ORIGIN).
+The Z coordinate ranges from 0 to 1 to represent depth from the front
+to the back of the Z buffer.  The W component contains the reciprocol
+of the interpolated vertex position W component.
 
-XXX additionally, is there a way to configure the perspective divide? it's
-accelerated on most chipsets AFAIK...
+Fragment shaders may also declare an output register with
+TGSI_SEMANTIC_POSITION.  Only the Z component is writable.  This allows
+the fragment shader to change the fragment's Z position.
 
-Position, if not specified, usually defaults to ``(0, 0, 0, 1)``, and can
-be partially specified as ``(x, y, 0, 1)`` or ``(x, y, z, 1)``.
 
-XXX usually? can we solidify that?
 
 TGSI_SEMANTIC_COLOR
 """""""""""""""""""
 
-Colors are used to, well, color the primitives. Colors are always in
-``(r, g, b, a)`` format.
+For vertex shader outputs or fragment shader inputs/outputs, this
+label indicates that the resister contains an R,G,B,A color.
+
+Several shader inputs/outputs may contain colors so the semantic index
+is used to distinguish them.  For example, color[0] may be the diffuse
+color while color[1] may be the specular color.
+
+This label is needed so that the flat/smooth shading can be applied
+to the right interpolants during rasterization.
+
 
-If alpha is not specified, it defaults to 1.
 
 TGSI_SEMANTIC_BCOLOR
 """"""""""""""""""""
 
 Back-facing colors are only used for back-facing polygons, and are only valid
 in vertex shader outputs. After rasterization, all polygons are front-facing
-and COLOR and BCOLOR end up occupying the same slots in the fragment, so
-all BCOLORs effectively become regular COLORs in the fragment shader.
+and COLOR and BCOLOR end up occupying the same slots in the fragment shader,
+so all BCOLORs effectively become regular COLORs in the fragment shader.
+
 
 TGSI_SEMANTIC_FOG
 """""""""""""""""
 
-The fog coordinate historically has been used to replace the depth coordinate
-for generation of fog in dedicated fog blocks. Gallium, however, does not use
-dedicated fog acceleration, placing it entirely in the fragment shader
-instead.
+Vertex shader inputs and outputs and fragment shader inputs may be
+labeled with TGSI_SEMANTIC_FOG to indicate that the register contains
+a fog coordinate in the form (F, 0, 0, 1).  Typically, the fragment
+shader will use the fog coordinate to compute a fog blend factor which
+is used to blend the normal fragment color with a constant fog color.
+
+Only the first component matters when writing from the vertex shader;
+the driver will ensure that the coordinate is in this format when used
+as a fragment shader input.
 
-The fog coordinate should be written in ``(f, 0, 0, 1)`` format. Only the first
-component matters when writing from the vertex shader; the driver will ensure
-that the coordinate is in this format when used as a fragment shader input.
 
 TGSI_SEMANTIC_PSIZE
 """""""""""""""""""
 
-PSIZE, or point size, is used to specify point sizes per-vertex. It should
-be in ``(s, 0, 0, 1)`` format, where ``s`` is the (possibly clamped) point size.
-Only the first component matters when writing from the vertex shader.
+Vertex shader input and output registers may be labeled with
+TGIS_SEMANTIC_PSIZE to indicate that the register contains a point size
+in the form (S, 0, 0, 1).  The point size controls the width or diameter
+of points for rasterization.  This label cannot be used in fragment
+shaders.
 
 When using this semantic, be sure to set the appropriate state in the
 :ref:`rasterizer` first.
 
+
 TGSI_SEMANTIC_GENERIC
 """""""""""""""""""""
 
-Generic semantics are nearly always used for texture coordinate attributes,
-in ``(s, t, r, q)`` format. ``t`` and ``r`` may be unused for certain kinds
-of lookups, and ``q`` is the level-of-detail bias for biased sampling.
+All vertex/fragment shader inputs/outputs not labeled with any other
+semantic label can be considered to be generic attributes.  Typical
+uses of generic inputs/outputs are texcoords and user-defined values.
 
-These attributes are called "generic" because they may be used for anything
-else, including parameters, texture generation information, or anything that
-can be stored inside a four-component vector.
 
 TGSI_SEMANTIC_NORMAL
 """"""""""""""""""""
 
-Vertex normal; could be used to implement per-pixel lighting for legacy APIs
-that allow mixing fixed-function and programmable stages.
+Indicates that a vertex shader input is a normal vector.  This is
+typically only used for legacy graphics APIs.
+
 
 TGSI_SEMANTIC_FACE
 """"""""""""""""""
 
-FACE is the facing bit, to store the facing information for the fragment
-shader. ``(f, 0, 0, 1)`` is the format. The first component will be positive
-when the fragment is front-facing, and negative when the component is
-back-facing.
+This label applies to fragment shader inputs only and indicates that
+the register contains front/back-face information of the form (F, 0,
+0, 1).  The first component will be positive when the fragment belongs
+to a front-facing polygon, and negative when the fragment belongs to a
+back-facing polygon.
+
 
 TGSI_SEMANTIC_EDGEFLAG
 """"""""""""""""""""""
 
-XXX no clue
+For vertex shaders, this sematic label indicates that an input or
+output is a boolean edge flag.  The register layout is [F, x, x, x]
+where F is 0.0 or 1.0 and x = don't care.  Normally, the vertex shader
+simply copies the edge flag input to the edgeflag output.
+
+Edge flags are used to control which lines or points are actually
+drawn when the polygon mode converts triangles/quads/polygons into
+points or lines.
+
 
 
 Properties