From 0cd70b554cb0bb9280f83fddf4f1451fddd37230 Mon Sep 17 00:00:00 2001 From: Roland Scheidegger Date: Fri, 28 May 2010 23:57:47 +0200 Subject: [PATCH] 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, -- 2.7.4