^^^^^^^
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,
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.
but overlapping blits are not permitted.
``resource_resolve`` resolves a multisampled resource into a non-multisampled
-one. Formats and dimensions must match. This function must be present if a driver
+one. Their formats must match. This function must be present if a driver
supports multisampling.
+The region that is to be resolved is described by ``pipe_resolve_info``, which
+provides a source and a destination rectangle.
+The source rectangle may be vertically flipped, but otherwise the dimensions
+of the rectangles must match, unless PIPE_CAP_SCALED_RESOLVE is supported,
+in which case scaling and horizontal flipping are allowed as well.
+The result of resolving depth/stencil values may be any function of the values at
+the sample points, but returning the value of the centermost sample is preferred.
The interfaces to these calls are likely to change to make it easier
for a driver to batch multiple blits with the same source and
projects / mesa.git / blobdiff