diff options
author | Christoph Bumiller <[email protected]> | 2011-10-20 18:03:23 +0200 |
---|---|---|
committer | Christoph Bumiller <[email protected]> | 2011-10-20 18:03:23 +0200 |
commit | 10f67c070b6af7000b31d0b08442f5ee38645344 (patch) | |
tree | de752d63ad14ce1aeb99f8eb36d2cb44d0058bce /src/gallium/docs/source | |
parent | c0cd9471173cd2287d74f5a536577348c789da5d (diff) |
gallium: add new query types and missing documentation
Diffstat (limited to 'src/gallium/docs/source')
-rw-r--r-- | src/gallium/docs/source/context.rst | 63 |
1 files changed, 57 insertions, 6 deletions
diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index 3faf801b4b1..391139fb0ef 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. |