gallium/docs: Create a separate section for Sampler Views.

1 files changed, 35 insertions, 17 deletions

diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index ef3e463931..1f022570db 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -41,23 +41,6 @@ buffers, surfaces) are bound to the driver.
 
 * ``set_framebuffer_state``
 
-* ``set_fragment_sampler_views`` binds an array of sampler views to
-  fragment shader stage. Every binding point acquires a reference
-  to a respective sampler view and releases a reference to the previous
-  sampler view.
-
-* ``set_vertex_sampler_views`` binds an array of sampler views to vertex
-  shader stage. Every binding point acquires a reference to a respective
-  sampler view and releases a reference to the previous sampler view.
-
-* ``create_sampler_view`` creates a new sampler view. texture is associated
-  with the sampler view which results in sampler view holding a reference
-  to the texture. Format specified in template must be compatible
-  with texture format.
-
-* ``sampler_view_destroy`` destroys a sampler view and releases its reference
-  to associated texture.
-
 * ``set_vertex_buffers``
 
 
@@ -79,6 +62,41 @@ objects. They all follow simple, one-method binding calls, e.g.
 * ``set_viewport_state``
 
 
+Sampler Views
+^^^^^^^^^^^^^
+
+These are the means to bind textures to shader stages. To create one, specify
+its format, swizzle and LOD range in sampler view template.
+
+If texture format is different than template format, it is said the texture
+is being cast to another format. Casting can be done only between compatible
+formats, that is formats that have matching component order and sizes.
+
+Swizzle fields specify they way in which fetched texel components are placed
+in the result register. For example, swizzle_r specifies what is going to be
+placed in destination register x (AKA r).
+
+first_level and last_level fields of sampler view template specify the LOD
+range the texture is going to be constrained to.
+
+* ``set_fragment_sampler_views`` binds an array of sampler views to
+  fragment shader stage. Every binding point acquires a reference
+  to a respective sampler view and releases a reference to the previous
+  sampler view.
+
+* ``set_vertex_sampler_views`` binds an array of sampler views to vertex
+  shader stage. Every binding point acquires a reference to a respective
+  sampler view and releases a reference to the previous sampler view.
+
+* ``create_sampler_view`` creates a new sampler view. texture is associated
+  with the sampler view which results in sampler view holding a reference
+  to the texture. Format specified in template must be compatible
+  with texture format.
+
+* ``sampler_view_destroy`` destroys a sampler view and releases its reference
+  to associated texture.
+
+
 Clearing
 ^^^^^^^^