From 6c1549a77dd76dc737e40c417fd3b4f9802a33d8 Mon Sep 17 00:00:00 2001 From: Brian Paul Date: Thu, 21 Jan 2010 11:52:36 -0700 Subject: gallium/docs: document conditional rendering --- src/gallium/docs/source/context.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) (limited to 'src/gallium/docs/source/context.rst') diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index d394f5b4f1..b7b625d25e 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -149,6 +149,42 @@ Queries can be created with ``create_query`` and deleted with use ``end_query`` to stop the query. Finally, ``get_query_result`` is used to retrieve the results. +A common type of query is the occlusion query which counts the number of +fragments/pixels which are written to the framebuffer (and not culled by +Z/stencil/alpha testing or shader KILL instructions). + + +Conditional Rendering +^^^^^^^^^^^^^^^^^^^^^ + +A drawing command can be skipped depending on the outcome of a query +(typically an occlusion query). The ``render_condition`` function specifies +the query which should be checked prior to rendering anything. + +If ``render_condition`` is called with ``query`` = NULL, conditional +rendering is disabled and drawing takes place normally. + +If ``render_condition`` is called with a non-null ``query`` subsequent +drawing commands will be predicated on the outcome of the query. If +the query result is zero subsequent drawing commands will be skipped. + +If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the +query to complete before deciding whether to render. + +If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet +completed, the drawing command will be executed normally. If the query +has completed, drawing will be predicated on the outcome of the query. + +If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or +PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above +for the non-REGION modes but in the case that an occulusion query returns +a non-zero result, regions which were occluded may be ommitted by subsequent +drawing commands. This can result in better performance with some GPUs. +Normally, if the occlusion query returned a non-zero result subsequent +drawing happens normally so fragments may be generated, shaded and +processed even where they're known to be obscured. + + Flushing ^^^^^^^^ -- cgit v1.2.3 From 8cf1af45075a1bf8c302a513566b7ef2314264b7 Mon Sep 17 00:00:00 2001 From: Corbin Simpson Date: Mon, 25 Jan 2010 01:12:30 -0800 Subject: gallium-docs: Add note on scissor. --- src/gallium/docs/source/context.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'src/gallium/docs/source/context.rst') diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index b7b625d25e..78b01cc9cb 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -54,7 +54,10 @@ objects. They all follow simple, one-method binding calls, e.g. * ``set_blend_color`` * ``set_clip_state`` * ``set_polygon_stipple`` -* ``set_scissor_state`` +* ``set_scissor_state`` sets the bounds for the scissor test, which culls + pixels before blending to render targets. If the :ref:`Rasterizer` does + not have the scissor test enabled, then the scissor bounds never need to + be set since they will not be used. * ``set_viewport_state`` * ``set_vertex_elements`` -- cgit v1.2.3 From 98f3f1c695f232120541670a8b5a355003ce3cc8 Mon Sep 17 00:00:00 2001 From: Brian Paul Date: Fri, 29 Jan 2010 12:36:26 -0700 Subject: gallium: document pipe_context::get_query_result() --- src/gallium/docs/source/context.rst | 12 +++++++++--- src/gallium/include/pipe/p_context.h | 5 +++++ 2 files changed, 14 insertions(+), 3 deletions(-) (limited to 'src/gallium/docs/source/context.rst') diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index 78b01cc9cb..a7669575b9 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -148,9 +148,15 @@ 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. +``destroy_query``. To start a query, use ``begin_query``, and when finished, +use ``end_query`` to end the query. + +``get_query_result`` is used to retrieve the results of a query. If +the ``wait`` parameter is TRUE, then the ``get_query_result`` call +will block until the results of the query are ready (and TRUE will be +returned). Otherwise, if the ``wait`` parameter is FALSE, the call +will not block and the return value will be TRUE if the query has +completed or FALSE otherwise. A common type of query is the occlusion query which counts the number of fragments/pixels which are written to the framebuffer (and not culled by diff --git a/src/gallium/include/pipe/p_context.h b/src/gallium/include/pipe/p_context.h index f3ee095448..f1e6a60e04 100644 --- a/src/gallium/include/pipe/p_context.h +++ b/src/gallium/include/pipe/p_context.h @@ -122,6 +122,11 @@ struct pipe_context { void (*begin_query)(struct pipe_context *pipe, struct pipe_query *q); void (*end_query)(struct pipe_context *pipe, struct pipe_query *q); + /** + * Get results of a query. + * \param wait if true, this query will block until the result is ready + * \return TRUE if results are ready, FALSE otherwise + */ boolean (*get_query_result)(struct pipe_context *pipe, struct pipe_query *q, boolean wait, -- cgit v1.2.3