Mesa (gallium-docs): gallium/docs: extend the context docs a little

Keith Whitwell keithw at
Mon Dec 21 15:44:41 PST 2009

Module: Mesa
Branch: gallium-docs
Commit: f3347fe397cb917dbfc18f87795a5187f2763019

Author: Keith Whitwell <keithw at>
Date:   Mon Dec 21 23:44:32 2009 +0000

gallium/docs: extend the context docs a little


 src/gallium/docs/source/context.rst |   79 ++++++++++++++++++++++++++++-------
 1 files changed, 63 insertions(+), 16 deletions(-)

diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index 6470e8f..21f5f91 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -25,6 +25,21 @@ CSO objects handled by the context object:
 * :ref:`Shader`: These have two sets of methods. ``*_fs_state`` is for
   fragment shaders, and ``*_vs_state`` is for vertex shaders.
+Resource Binding State
+This state describes how resources in various flavours (textures,
+buffers, surfaces) are bound to the driver.
+* ``set_constant_buffer``
+* ``set_framebuffer_state``
+* ``set_fragment_sampler_textures``
+* ``set_vertex_sampler_textures``
+* ``set_vertex_buffers``
 Non-CSO State
@@ -35,47 +50,79 @@ objects. They all follow simple, one-method binding calls, e.g.
 * ``set_edgeflags``
 * ``set_blend_color``
 * ``set_clip_state``
-* ``set_constant_buffer``
-* ``set_framebuffer_state``
 * ``set_polygon_stipple``
 * ``set_scissor_state``
 * ``set_viewport_state``
-* ``set_fragment_sampler_textures``
-* ``set_vertex_sampler_textures``
-* ``set_vertex_buffers``
 * ``set_vertex_elements``
+``clear`` initializes some or all of the surfaces currently bound to
+the framebuffer to particular RGBA, depth, or stencil values.
+Clear is one of the most difficult concepts to nail down to a single
+interface and it seems likely that we will want to add additional
+clear paths, for instance clearing surfaces not bound to the
+framebuffer, or read-modify-write clears such as depth-only or
+stencil-only clears of packed depth-stencil buffers.  
+Queries gather some statistic from the 3D pipeline over one or more
+draws.  Queries may be nested, though no state tracker currently
+exercises this.  
 Queries can be created with ``create_query`` and deleted with
 ``destroy_query``. To enable a query, use ``begin_query``, and when finished,
 use ``end_query`` to stop the query. Finally, ``get_query_result`` is used
 to retrieve the results.
-VBO Drawing
+Resource Busy Queries
-Surface Drawing
 These methods emulate classic blitter controls. They are not guaranteed to be
 available; if they are set to NULL, then they are not present.
+These methods operate directly on ``pipe_surface`` objects, and stand
+apart from any 3D state in the context.  Blitting functionality may be
+moved to a separate abstraction at some point in the future.
 ``surface_fill`` performs a fill operation on a section of a surface.
 ``surface_copy`` blits a region of a surface to a region of another surface,
 provided that both surfaces are the same format. The source and destination
 may be the same surface, and overlapping blits are permitted.
-``clear`` initializes entire buffers to an RGBA, depth, or stencil value,
-depending on the formats of the buffers. Use ``set_framebuffer_state`` to
-specify the buffers to clear.
+The interfaces to these calls are likely to change to make it easier
+for a driver to batch multiple blits with the same source and

More information about the mesa-commit mailing list