Merge remote branch 'origin/master' into gallium_draw_llvm

5 files changed, 124 insertions, 39 deletions

diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index 9080addba44..4608e97adbb 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -24,6 +24,7 @@ CSO objects handled by the context object:
 * :ref:`Depth, Stencil, & Alpha`: ``*_depth_stencil_alpha_state``
 * :ref:`Shader`: These have two sets of methods. ``*_fs_state`` is for
   fragment shaders, and ``*_vs_state`` is for vertex shaders.
+* :ref:`Vertex Elements`: ``*_vertex_elements_state``
 
 
 Resource Binding State
@@ -60,7 +61,6 @@ objects. They all follow simple, one-method binding calls, e.g.
   not have the scissor test enabled, then the scissor bounds never need to
   be set since they will not be used.
 * ``set_viewport_state``
-* ``set_vertex_elements``
 
 
 Clearing
diff --git a/src/gallium/docs/source/cso/rasterizer.rst b/src/gallium/docs/source/cso/rasterizer.rst
index 24cc78c68de..ccd9136a2eb 100644
--- a/src/gallium/docs/source/cso/rasterizer.rst
+++ b/src/gallium/docs/source/cso/rasterizer.rst
@@ -10,18 +10,6 @@ multisample state, scissoring and flat/smooth shading.
 Members
 -------
 
-bypass_vs_clip_and_viewport
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Whether the entire TCL pipeline should be bypassed. This implies that
-vertices are pre-transformed for the viewport, and will not be run
-through the vertex shader.
-
-.. note::
-   
-   Implementations may still clip away vertices that are not in the viewport
-   when this is set.
-
 flatshade
 ^^^^^^^^^
 
diff --git a/src/gallium/docs/source/cso/sampler.rst b/src/gallium/docs/source/cso/sampler.rst
index 77979fc44d1..9bbb784de8e 100644
--- a/src/gallium/docs/source/cso/sampler.rst
+++ b/src/gallium/docs/source/cso/sampler.rst
@@ -13,38 +13,97 @@ Members
 -------
 
 wrap_s
-    How to wrap the S coordinate. One of PIPE_TEX_WRAP.
+    How to wrap the S coordinate. One of PIPE_TEX_WRAP_*.
 wrap_t
-    How to wrap the T coordinate. One of PIPE_TEX_WRAP.
+    How to wrap the T coordinate. One of PIPE_TEX_WRAP_*.
 wrap_r
-    How to wrap the R coordinate. One of PIPE_TEX_WRAP.
+    How to wrap the R coordinate. One of PIPE_TEX_WRAP_*.
+
+The wrap modes are:
+
+* ``PIPE_TEX_WRAP_REPEAT``: Standard coord repeat/wrap-around mode.
+* ``PIPE_TEX_WRAP_CLAMP_TO_EDGE``: Clamp coord to edge of texture, the border
+  color is never sampled.
+* ``PIPE_TEX_WRAP_CLAMP_TO_BORDER``: Clamp coord to border of texture, the
+  border color is sampled when coords go outside the range [0,1].
+* ``PIPE_TEX_WRAP_CLAMP``: The coord is clamped to the range [0,1] before
+  scaling to the texture size.  This corresponds to the legacy OpenGL GL_CLAMP
+  texture wrap mode.  Historically, this mode hasn't acted consistantly across
+  all graphics hardware.  It sometimes acts like CLAMP_TO_EDGE or
+  CLAMP_TO_BORDER.  The behaviour may also vary depending on linear vs.
+  nearest sampling mode.
+* ``PIPE_TEX_WRAP_MIRROR_REPEAT``: If the integer part of the coordinate
+  is odd, the coord becomes (1 - coord).  Then, normal texture REPEAT is
+  applied to the coord.
+* ``PIPE_TEX_WRAP_MIRROR_CLAMP_TO_EDGE``: First, the absolute value of the
+  coordinate is computed.  Then, regular CLAMP_TO_EDGE is applied to the coord.
+* ``PIPE_TEX_WRAP_MIRROR_CLAMP_TO_BORDER``: First, the absolute value of the
+  coordinate is computed.  Then, regular CLAMP_TO_BORDER is applied to the
+  coord.
+* ``PIPE_TEX_WRAP_MIRROR_CLAMP``: First, the absolute value of the coord is
+  computed.  Then, regular CLAMP is applied to the coord.
+
+
 min_img_filter
-    The filter to use when minifying texels. One of PIPE_TEX_FILTER.
+    The image filter to use when minifying texels. One of PIPE_TEX_FILTER_*.
+mag_img_filter
+    The image filter to use when magnifying texels. One of PIPE_TEX_FILTER_*.
+
+The texture image filter modes are:
+
+* ``PIPE_TEX_FILTER_NEAREST``: One texel is fetched from the texture image
+  at the texture coordinate.
+* ``PIPE_TEX_FILTER_LINEAR``: Two, four or eight texels (depending on the
+  texture dimensions; 1D/2D/3D) are fetched from the texture image and
+  linearly weighted and blended together.
+
 min_mip_filter
     The filter to use when minifying mipmapped textures. One of
-    PIPE_TEX_FILTER.
-mag_img_filter
-    The filter to use when magnifying texels. One of PIPE_TEX_FILTER.
+    PIPE_TEX_MIPFILTER_*.
+
+The texture mip filter modes are:
+
+* ``PIPE_TEX_MIPFILTER_NEAREST``: A single mipmap level/image is selected
+  according to the texture LOD (lambda) value.
+* ``PIPE_TEX_MIPFILTER_LINEAR``: The two mipmap levels/images above/below
+  the texture LOD value are sampled from.  The results of sampling from
+  those two images are blended together with linear interpolation.
+* ``PIPE_TEX_MIPFILTER_NONE``: Mipmap filtering is disabled.  All texels
+  are taken from the level 0 image.
+
+
 compare_mode
-    If set to PIPE_TEX_COMPARE_R_TO_TEXTURE, texture output is computed
-    according to compare_func, using r coord and the texture value as operands.
+    If set to PIPE_TEX_COMPARE_R_TO_TEXTURE, the result of texture sampling
+    is not a color but a true/false value which is the result of comparing the
+    sampled texture value (typically a Z value from a depth texture) to the
+    texture coordinate's R component.
     If set to PIPE_TEX_COMPARE_NONE, no comparison calculation is performed.
 compare_func
-    How the comparison is computed. One of PIPE_FUNC.
+    The inequality operator used when compare_mode=1.  One of PIPE_FUNC_x.
 normalized_coords
-    Whether the texture coordinates are normalized. If normalized, they will
-    always be in [0, 1]. If not, they will be in the range of each dimension
-    of the loaded texture.
+    If set, the incoming texture coordinates (nominally in the range [0,1])
+    will be scaled by the texture width, height, depth to compute texel
+    addresses.  Otherwise, the texture coords are used as-is (they are not
+    scaled by the texture dimensions).
+    When normalized_coords=0, only a subset of the texture wrap modes are
+    allowed: PIPE_TEX_WRAP_CLAMP, PIPE_TEX_WRAP_CLAMP_TO_EDGE and
+    PIPE_TEX_WRAP_CLAMP_TO_BORDER.
 lod_bias
-    The bias to apply to the level of detail.
+    Bias factor which is added to the computed level of detail.
+    The normal level of detail is computed from the partial derivatives of
+    the texture coordinates and/or the fragment shader TEX/TXB/TXL
+    instruction.
 min_lod
-    Minimum level of detail, used to clamp LoD after bias.
+    Minimum level of detail, used to clamp LOD after bias.  The LOD values
+    correspond to mipmap levels where LOD=0 is the level 0 mipmap image.
 max_lod
-    Maximum level of detail, used to clamp LoD after bias.
+    Maximum level of detail, used to clamp LOD after bias.
 border_color
-    RGBA color used for out-of-bounds coordinates.
+    RGBA color used for texel coordinates that are outside the [0,width-1],
+    [0, height-1] or [0, depth-1] ranges.
 max_anisotropy
-    Maximum filtering to apply anisotropically to textures. Setting this to
-    0 disables anisotropic filtering. Any other setting enables anisotropic
-    filtering, however it's not unexpected some drivers only will change their
-    filtering with a setting of 2 and higher.
+    Maximum anistropy ratio to use when sampling from textures.  For example,
+    if max_anistropy=4, a region of up to 1 by 4 texels will be sampled.
+    Set to zero to disable anisotropic filtering.  Any other setting enables
+    anisotropic filtering, however it's not unexpected some drivers only will
+    change their filtering with a setting of 2 and higher.
diff --git a/src/gallium/docs/source/cso/velems.rst b/src/gallium/docs/source/cso/velems.rst
new file mode 100644
index 00000000000..8e758fae103
--- /dev/null
+++ b/src/gallium/docs/source/cso/velems.rst
@@ -0,0 +1,24 @@
+.. _vertex,elements
+
+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.
diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst
index 27f65522b69..e78634e59e9 100644
--- a/src/gallium/docs/source/screen.rst
+++ b/src/gallium/docs/source/screen.rst
@@ -147,16 +147,30 @@ These flags determine the possible roles a texture may be used for during its
 lifetime. Texture usage flags are cumulative and may be combined to create a
 texture that can be used as multiple things.
 
-* ``RENDER_TARGET``: A colorbuffer or pixelbuffer.
+* ``RENDER_TARGET``: A color buffer or pixel buffer which will be rendered to.
 * ``DISPLAY_TARGET``: A sharable buffer that can be given to another process.
-* ``PRIMARY``: A frontbuffer or scanout buffer.
-* ``DEPTH_STENCIL``: A depthbuffer, stencilbuffer, or Z buffer. Gallium does
-  not explicitly provide for stencil-only buffers, so any stencilbuffer
-  validated here is implicitly also a depthbuffer.
+* ``PRIMARY``: A front color buffer or scanout buffer.
+* ``DEPTH_STENCIL``: A depth (Z) buffer or stencil buffer.  Gallium does
+  not explicitly provide for stencil-only buffers, so any stencil buffer
+  validated here is implicitly also a depth buffer.
 * ``SAMPLER``: A texture that may be sampled from in a fragment or vertex
   shader.
 * ``DYNAMIC``: A texture that will be mapped frequently.
 
+
+PIPE_TEXTURE_GEOM
+^^^^^^^^^^^^^^^^^
+
+These flags are used when querying whether a particular pipe_format is
+supported by the driver (with the `is_format_supported` function).
+Some formats may only be supported for certain kinds of textures.
+For example, a compressed format might only be used for POT textures.
+
+* ``PIPE_TEXTURE_GEOM_NON_SQUARE``: The texture may not be square
+* ``PIPE_TEXTURE_GEOM_NON_POWER_OF_TWO``: The texture dimensions may not be
+  powers of two.
+
+
 Methods
 -------