C Specification
To retrieve status and results for a set of queries, call:
// Provided by VK_VERSION_1_0
VkResult vkGetQueryPoolResults(
VkDevice device,
VkQueryPool queryPool,
uint32_t firstQuery,
uint32_t queryCount,
size_t dataSize,
void* pData,
VkDeviceSize stride,
VkQueryResultFlags flags);
Parameters
-
device
is the logical device that owns the query pool. -
queryPool
is the query pool managing the queries containing the desired results. -
firstQuery
is the initial query index. -
queryCount
is the number of queries to read. -
dataSize
is the size in bytes of the buffer pointed to bypData
. -
pData
is a pointer to a user-allocated buffer where the results will be written -
stride
is the stride in bytes between results for individual queries withinpData
. -
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.
If no bits are set in flags
, and all requested queries are in the
available state, results are written as an array of 32-bit unsigned integer
values.
Behavior when not all queries are available is described
below.
If VK_QUERY_RESULT_WITH_AVAILABILITY_BIT
is set, results for all
queries in queryPool
identified by firstQuery
and
queryCount
are copied to pData
, along with an extra availability
or status
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.
The size of the availability
or status
values is 64 bits if VK_QUERY_RESULT_64_BIT
is set in flags
.
Otherwise, it is 32 bits.
If VK_QUERY_RESULT_WITH_STATUS_BIT_KHR
is set, results for all queries
in queryPool
identified by firstQuery
and queryCount
are
copied to pData
, along with an extra status value written directly
after the results of each query and interpreted as a signed integer.
A value of zero indicates that the results are not yet available.
Positive values indicate that the operations within the query completed
successfully, and the query results are valid.
Negative values indicate that the operations within the query completed
unsuccessfully.
VkQueryResultStatusKHR defines specific meaning for values returned here, though implementations are free to return other values.
If the status value written is negative, indicating that the operations within the query completed unsuccessfully, then all other results written by this command are undefined unless otherwise specified for any of the results of the used query type.
Note
If |
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, if returned,
availability
or status
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
or status
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.
If VK_QUERY_RESULT_WAIT_BIT
is set, this command defines an execution
dependency with any earlier commands that writes one of the identified
queries.
The first synchronization scope
includes all instances of vkCmdEndQuery,
vkCmdEndQueryIndexedEXT,
vkCmdWriteTimestamp2,
and vkCmdWriteTimestamp that reference any query in queryPool
indicated by firstQuery
and queryCount
.
The second synchronization scope
includes the host operations of this command.
If VK_QUERY_RESULT_WAIT_BIT
is not set, vkGetQueryPoolResults
may return VK_NOT_READY
if there are queries in the unavailable
state.
Note
Applications must take care to ensure that use of the
For example, if a query has been used previously and a command buffer
records the commands The above also applies when A similar situation can arise with the
|
Note
Applications can double-buffer query pool usage, with a pool per frame, and reset queries at the end of the frame in which they are read. |
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.