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
Any results written for a query are written according to a layout dependent on the query type.
Results for any query in queryPool
identified by firstQuery
and
queryCount
that is available are copied to dstBuffer
.
If VK_QUERY_RESULT_WITH_AVAILABILITY_BIT
is set, results for all
queries in queryPool
identified by firstQuery
and
queryCount
are copied to dstBuffer
, along with an extra
availability value written directly after the results of each query and
interpreted as an unsigned integer.
A value of zero indicates that the results are not yet available, otherwise
the query is complete and results are available.
Results for any available query written by this command are final and
represent the final result of the query.
If VK_QUERY_RESULT_PARTIAL_BIT
is set, then for any query that is
unavailable, an intermediate result between zero and the final result value
is written for that query.
Otherwise, any result written by this command is undefined.
If VK_QUERY_RESULT_64_BIT
is set, results and availability
values for all queries are written as an array of 64-bit values.
If the queryPool
was created with
VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR
, results for each query are
written as an array of the type indicated by
VkPerformanceCounterKHR::storage
for the counter being queried.
Otherwise, results and availability
values are written as an array of 32-bit values.
If an unsigned integer query’s value overflows the result type, the value
may either wrap or saturate.
If a signed integer query’s value overflows the result type, the value is
undefined.
If a floating point query’s value is not representable as the result type,
the value is undefined.
This command defines an execution dependency between other query commands that reference the same query.
The first synchronization scope
includes all commands which reference the queries in queryPool
indicated by query
that occur earlier in
submission order.
If flags
does not include VK_QUERY_RESULT_WAIT_BIT
,
vkCmdWriteTimestamp2KHR,
vkCmdEndQuery, and vkCmdWriteTimestamp are excluded from this
scope.
The second synchronization scope
includes all commands which reference the queries in queryPool
indicated by query
that occur later in
submission order.
The operation of this command happens after the first scope and happens before the second scope.
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.
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.