Mesa (master): gallium: add new query types and missing documentation

[Christoph Bumiller]

Module: Mesa
Branch: master
Commit: 10f67c070b6af7000b31d0b08442f5ee38645344
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=10f67c070b6af7000b31d0b08442f5ee38645344

Author: Christoph Bumiller <e0425955 at student.tuwien.ac.at>
Date:   Thu Oct 20 18:03:23 2011 +0200

gallium: add new query types and missing documentation

---

 src/gallium/docs/source/context.rst  |   63 ++++++++++++++++++++++++++++++---
 src/gallium/include/pipe/p_defines.h |   19 ++++++----
 2 files changed, 68 insertions(+), 14 deletions(-)

diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index 3faf801..391139f 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -235,8 +235,7 @@ Queries
 ^^^^^^^
 
 Queries gather some statistic from the 3D pipeline over one or more
-draws.  Queries may be nested, though no state tracker currently
-exercises this.  
+draws.  Queries may be nested, though only d3d1x currently exercises this.
 
 Queries can be created with ``create_query`` and deleted with
 ``destroy_query``. To start a query, use ``begin_query``, and when finished,
@@ -249,21 +248,73 @@ 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.
 
-The most common type of query is the occlusion query,
-``PIPE_QUERY_OCCLUSION_COUNTER``, which counts the number of fragments which
+The interface currently includes the following types of queries:
+
+``PIPE_QUERY_OCCLUSION_COUNTER`` counts the number of fragments which
 are written to the framebuffer without being culled by
 :ref:`Depth, Stencil, & Alpha` testing or shader KILL instructions.
 The result is an unsigned 64-bit integer.
+This query can be used with ``render_condition``.
+
 In cases where a boolean result of an occlusion query is enough,
 ``PIPE_QUERY_OCCLUSION_PREDICATE`` should be used. It is just like
 ``PIPE_QUERY_OCCLUSION_COUNTER`` except that the result is a boolean
 value of FALSE for cases where COUNTER would result in 0 and TRUE
 for all other cases.
+This query can be used with ``render_condition``.
 
-Another type of query, ``PIPE_QUERY_TIME_ELAPSED``, returns the amount of
-time, in nanoseconds, the context takes to perform operations.
+``PIPE_QUERY_TIME_ELAPSED`` returns the amount of time, in nanoseconds,
+the context takes to perform operations.
 The result is an unsigned 64-bit integer.
 
+``PIPE_QUERY_TIMESTAMP`` returns a device/driver internal timestamp,
+scaled to nanoseconds, recorded after all commands issued prior to
+``end_query`` have been processed.
+This query does not require a call to ``begin_query``.
+The result is an unsigned 64-bit integer.
+
+``PIPE_QUERY_TIMESTAMP_DISJOINT`` can be used to check whether the
+internal timer resolution is good enough to distinguish between the
+events at ``begin_query`` and ``end_query``.
+The result is a 64-bit integer specifying the timer resolution in Hz,
+followed by a boolean value indicating whether the timer has incremented.
+
+``PIPE_QUERY_PRIMITIVES_GENERATED`` returns a 64-bit integer indicating
+the number of primitives processed by the pipeline.
+
+``PIPE_QUERY_PRIMITIVES_EMITTED`` returns a 64-bit integer indicating
+the number of primitives written to stream output buffers.
+
+``PIPE_QUERY_SO_STATISTICS`` returns 2 64-bit integers corresponding to
+the results of
+``PIPE_QUERY_PRIMITIVES_EMITTED`` and
+``PIPE_QUERY_PRIMITIVES_GENERATED``, in this order.
+
+``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` returns a boolean value indicating
+whether the stream output targets have overflowed as a result of the
+commands issued between ``begin_query`` and ``end_query``.
+This query can be used with ``render_condition``.
+
+``PIPE_QUERY_GPU_FINISHED`` returns a boolean value indicating whether
+all commands issued before ``end_query`` have completed. However, this
+does not imply serialization.
+This query does not require a call to ``begin_query``.
+
+``PIPE_QUERY_PIPELINE_STATISTICS`` returns an array of the following
+64-bit integers:
+Number of vertices read from vertex buffers.
+Number of primitives read from vertex buffers.
+Number of vertex shader threads launched.
+Number of geometry shader threads launched.
+Number of primitives generated by geometry shaders.
+Number of primitives forwarded to the rasterizer.
+Number of primitives rasterized.
+Number of fragment shader threads launched.
+Number of tessellation control shader threads launched.
+Number of tessellation evaluation shader threads launched.
+If a shader type is not supported by the device/driver,
+the corresponding values should be set to 0.
+
 Gallium does not guarantee the availability of any query types; one must
 always check the capabilities of the :ref:`Screen` first.
 
diff --git a/src/gallium/include/pipe/p_defines.h b/src/gallium/include/pipe/p_defines.h
index 447df35..5196591 100644
--- a/src/gallium/include/pipe/p_defines.h
+++ b/src/gallium/include/pipe/p_defines.h
@@ -375,14 +375,17 @@ enum pipe_transfer_usage {
  * Query object types
  */
 #define PIPE_QUERY_OCCLUSION_COUNTER     0
-#define PIPE_QUERY_PRIMITIVES_GENERATED  1
-#define PIPE_QUERY_PRIMITIVES_EMITTED    2
-#define PIPE_QUERY_TIME_ELAPSED          3
-#define PIPE_QUERY_SO_STATISTICS         5
-#define PIPE_QUERY_GPU_FINISHED          6
-#define PIPE_QUERY_TIMESTAMP_DISJOINT    7
-#define PIPE_QUERY_OCCLUSION_PREDICATE   8
-#define PIPE_QUERY_TYPES                 9
+#define PIPE_QUERY_OCCLUSION_PREDICATE   1
+#define PIPE_QUERY_TIMESTAMP             2
+#define PIPE_QUERY_TIMESTAMP_DISJOINT    3
+#define PIPE_QUERY_TIME_ELAPSED          4
+#define PIPE_QUERY_PRIMITIVES_GENERATED  5
+#define PIPE_QUERY_PRIMITIVES_EMITTED    6
+#define PIPE_QUERY_SO_STATISTICS         7
+#define PIPE_QUERY_SO_OVERFLOW_PREDICATE 8
+#define PIPE_QUERY_GPU_FINISHED          9
+#define PIPE_QUERY_PIPELINE_STATISTICS  10
+#define PIPE_QUERY_TYPES                11
 
 
 /**