Merge branch 'gallium-newclear'

Conflicts:
	src/gallium/state_trackers/python/p_context.i

1 files changed, 20 insertions, 7 deletions

diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index 89c02b1b703..27d352b7a39 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -102,14 +102,29 @@ the LOD range the texture is going to be constrained to.
 Clearing
 ^^^^^^^^
 
+Clear is one of the most difficult concepts to nail down to a single
+interface (due to both different requirements from APIs and also driver/hw
+specific differences).
+
 ``clear`` initializes some or all of the surfaces currently bound to
 the framebuffer to particular RGBA, depth, or stencil values.
+Currently, this does not take into account color or stencil write masks (as
+used by GL), and always clears the whole surfaces (no scissoring as used by
+GL clear or explicit rectangles like d3d9 uses). It can, however, also clear
+only depth or stencil in a combined depth/stencil surface, if the driver
+supports PIPE_CAP_DEPTHSTENCIL_CLEAR_SEPARATE.
+If a surface includes several layers/slices (XXX: not yet...) then all layers
+will be cleared.
 
-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.  
+``clear_render_target`` clears a single color rendertarget with the specified
+color value. While it is only possible to clear one surface at a time (which can
+include several layers), this surface need not be bound to the framebuffer.
+
+``clear_depth_stencil``clears a single depth, stencil or depth/stencil surface
+with the specified depth and stencil values (for combined depth/stencil buffers,
+is is also possible to only clear one or the other part). While it is only
+possible to clear one surface at a time (which can include several layers),
+this surface need not be bound to the framebuffer.
 
 
 Drawing
@@ -266,8 +281,6 @@ These methods operate directly on ``pipe_resource`` 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.
 
-``resource_fill_region`` performs a fill operation on a section of a resource.
-
 ``resource_copy_region`` blits a region of a subresource of a resource to a
 region of another subresource of a resource, provided that both resources have the
 same format. The source and destination may be the same resource, but overlapping