Mesa (master): gallium: clear interface changes
Roland Scheidegger
sroland at kemper.freedesktop.org
Thu Jun 3 15:47:34 UTC 2010
Module: Mesa
Branch: master
Commit: 0cd70b554cb0bb9280f83fddf4f1451fddd37230
URL: http://cgit.freedesktop.org/mesa/mesa/commit/?id=0cd70b554cb0bb9280f83fddf4f1451fddd37230
Author: Roland Scheidegger <sroland at vmware.com>
Date: Fri May 28 23:57:47 2010 +0200
gallium: clear interface changes
clears were a bit limited in gallium:
- no scissoring (OGL only) nor explicit rectangle list (d3d9)
- no color/stencil masks (OGL only)
- no separate depth/stencil clears (d3d9/d3d10/OGL)
- cannot really clear single color buffer (only with resource_fill_region)
Additionally, d3d can clear surfaces not currently bound to the framebuffer.
It is, however, not easy to find some common ground what a clear should be able
to do, due to both API requirements and also hw differences (a case which might
be able to use a special clear path on one hw might need a "normal" quad render
on another).
Hence several clear methods are provided, and a driver should implement all of
them.
- clear: slightly modified to also be able to clear only depth or stencil in a
combined depth/stencil surface. This is however optional based on driver
capability though ideally it wouldn't be optional. AFAIK this is in fact
something used by applications quite a bit.
Otherwise, for now still doesn't allow clearing with scissors/mask (or single
color buffers)
- clearRT: clears a single (potentially unbound) color surface. This was formerly
roughly known as resource_fill_region. mesa st will not currently use this,
though potentially would be useful for GL ClearBuffer.
- clearDS: similar to above except for depth stencil surfaces.
Note that clearDS/clearRT currently handle can handle partial clear. This might
change however.
---
src/gallium/docs/d3d11ddi.txt | 2 +-
src/gallium/docs/source/context.rst | 27 +++++++++++++++++------
src/gallium/include/pipe/p_context.h | 39 ++++++++++++++++++++++-----------
src/gallium/include/pipe/p_defines.h | 6 +++-
4 files changed, 51 insertions(+), 23 deletions(-)
diff --git a/src/gallium/docs/d3d11ddi.txt b/src/gallium/docs/d3d11ddi.txt
index d9c2b44..e3368fd 100644
--- a/src/gallium/docs/d3d11ddi.txt
+++ b/src/gallium/docs/d3d11ddi.txt
@@ -79,7 +79,7 @@ set_clip_state
set_polygon_stipple
+ Gallium supports polygon stipple
-resource_fill_region
+clearRT/clearDS
+ Gallium supports subrectangle fills of surfaces, D3D10 only supports full clears of views
* DirectX 10/11 DDI functions and Gallium equivalents
diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index 89c02b1..037afb0 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.
+``clearRT`` 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.
+
+``clearDS``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
diff --git a/src/gallium/include/pipe/p_context.h b/src/gallium/include/pipe/p_context.h
index 6b72983..51f5240 100644
--- a/src/gallium/include/pipe/p_context.h
+++ b/src/gallium/include/pipe/p_context.h
@@ -257,17 +257,6 @@ struct pipe_context {
unsigned width, unsigned height);
/**
- * Fill a region of a resource with a constant value.
- * Resources with nr_samples > 1 are not allowed.
- */
- void (*resource_fill_region)(struct pipe_context *pipe,
- struct pipe_resource *dst,
- struct pipe_subresource subdst,
- unsigned dstx, unsigned dsty, unsigned dstz,
- unsigned width, unsigned height,
- unsigned value);
-
- /**
* Resolve a multisampled resource into a non-multisampled one.
* Source and destination must have the same size and same format.
*/
@@ -290,9 +279,33 @@ struct pipe_context {
*/
void (*clear)(struct pipe_context *pipe,
unsigned buffers,
- const float *rgba,
+ const float *rgba,
double depth,
- unsigned stencil);
+ unsigned stencil);
+
+ /**
+ * Clear a color rendertarget surface.
+ * \param rgba pointer to an array of one float for each of r, g, b, a.
+ */
+ void (*clearRT)(struct pipe_context *pipe,
+ struct pipe_surface *dst,
+ const float *rgba,
+ unsigned dstx, unsigned dsty,
+ unsigned width, unsigned height);
+
+ /**
+ * Clear a depth-stencil surface.
+ * \param clear_flags bitfield of PIPE_CLEAR_DEPTH/STENCIL values.
+ * \param depth depth clear value in [0,1].
+ * \param stencil stencil clear value
+ */
+ void (*clearDS)(struct pipe_context *pipe,
+ struct pipe_surface *dst,
+ unsigned clear_flags,
+ double depth,
+ unsigned stencil,
+ unsigned dstx, unsigned dsty,
+ unsigned width, unsigned height);
/** Flush rendering
* \param flags bitmask of PIPE_FLUSH_x tokens)
diff --git a/src/gallium/include/pipe/p_defines.h b/src/gallium/include/pipe/p_defines.h
index b54a6ef..420649c 100644
--- a/src/gallium/include/pipe/p_defines.h
+++ b/src/gallium/include/pipe/p_defines.h
@@ -189,9 +189,10 @@ enum pipe_texture_target {
*/
/** All color buffers currently bound */
#define PIPE_CLEAR_COLOR (1 << 0)
+#define PIPE_CLEAR_DEPTH (1 << 1)
+#define PIPE_CLEAR_STENCIL (1 << 2)
/** Depth/stencil combined */
-#define PIPE_CLEAR_DEPTHSTENCIL (1 << 1)
-
+#define PIPE_CLEAR_DEPTHSTENCIL (PIPE_CLEAR_DEPTH | PIPE_CLEAR_STENCIL)
/**
* Transfer object usage flags
@@ -453,6 +454,7 @@ enum pipe_cap {
PIPE_CAP_INDEP_BLEND_ENABLE,
/** different blend funcs per rendertarget */
PIPE_CAP_INDEP_BLEND_FUNC,
+ PIPE_CAP_DEPTHSTENCIL_CLEAR_SEPARATE,
PIPE_CAP_TGSI_FS_COORD_ORIGIN_UPPER_LEFT,
PIPE_CAP_TGSI_FS_COORD_ORIGIN_LOWER_LEFT,
PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_HALF_INTEGER,
More information about the mesa-commit
mailing list