C Specification
To copy query statuses and numerical results directly to buffer memory, call:
// Provided by VK_VERSION_1_0
void vkCmdCopyQueryPoolResults(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t firstQuery,
uint32_t queryCount,
VkBuffer dstBuffer,
VkDeviceSize dstOffset,
VkDeviceSize stride,
VkQueryResultFlags flags);
Parameters
-
commandBuffer
is the command buffer into which this command will be recorded. -
queryPool
is the query pool managing the queries containing the desired results. -
firstQuery
is the initial query index. -
queryCount
is the number of queries.firstQuery
andqueryCount
together define a range of queries. -
dstBuffer
is a VkBuffer object that will receive the results of the copy command. -
dstOffset
is an offset intodstBuffer
. -
stride
is the stride in bytes between results for individual queries withindstBuffer
. The required size of the backing memory fordstBuffer
is determined as described above for vkGetQueryPoolResults. -
flags
is a bitmask of VkQueryResultFlagBits specifying how and when results are returned.
Description
vkCmdCopyQueryPoolResults
is guaranteed to see the effect of previous
uses of vkCmdResetQueryPool
in the same queue, without any additional
synchronization.
Thus, the results will always reflect the most recent use of the query.
flags
has the same possible values described above for the flags
parameter of vkGetQueryPoolResults, but the different style of
execution causes some subtle behavioral differences.
Because vkCmdCopyQueryPoolResults
executes in order with respect to
other query commands, there is less ambiguity about which use of a query is
being requested.
Results for all requested occlusion queries, pipeline statistics queries,
transform feedback queries,
primitives generated queries,
and timestamp queries are written as 64-bit unsigned integer values if
VK_QUERY_RESULT_64_BIT
is set or 32-bit unsigned integer values
otherwise.
Performance queries store results in a tightly packed array whose type is
determined by the unit
member of the corresponding
VkPerformanceCounterKHR.
If neither of VK_QUERY_RESULT_WAIT_BIT
and
VK_QUERY_RESULT_WITH_AVAILABILITY_BIT
are set, results are only
written out for queries in the available state.
If VK_QUERY_RESULT_WAIT_BIT
is set, the implementation will wait for
each query’s status to be in the available state before retrieving the
numerical results for that query.
This is guaranteed to reflect the most recent use of the query on the same
queue, assuming that the query is not being simultaneously used by other
queues.
If the query does not become available in a finite amount of time (e.g. due
to not issuing a query since the last reset), a VK_ERROR_DEVICE_LOST
error may occur.
Similarly, if VK_QUERY_RESULT_WITH_AVAILABILITY_BIT
is set and
VK_QUERY_RESULT_WAIT_BIT
is not set, the availability is guaranteed to
reflect the most recent use of the query on the same queue, assuming that
the query is not being simultaneously used by other queues.
As with vkGetQueryPoolResults
, implementations must guarantee that if
they return a non-zero availability value, then the numerical results are
valid.
If VK_QUERY_RESULT_PARTIAL_BIT
is set, VK_QUERY_RESULT_WAIT_BIT
is not set, and the query’s status is unavailable, an intermediate result
value between zero and the final result value is written for that query.
VK_QUERY_RESULT_PARTIAL_BIT
must not be used if the pool’s
queryType
is VK_QUERY_TYPE_TIMESTAMP
.
vkCmdCopyQueryPoolResults
is considered to be a transfer operation,
and its writes to buffer memory must be synchronized using
VK_PIPELINE_STAGE_TRANSFER_BIT
and VK_ACCESS_TRANSFER_WRITE_BIT
before using the results.
See Also
VK_VERSION_1_0, VkBuffer, VkCommandBuffer, VkDeviceSize
, VkQueryPool, VkQueryResultFlags
Document Notes
For more information, see the Vulkan Specification
This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.