C Specification
To retrieve status and results for a set of queries, call:
VkResult vkGetQueryPoolResults(
VkDevice device,
VkQueryPool queryPool,
uint32_t firstQuery,
uint32_t queryCount,
size_t dataSize,
void* pData,
VkDeviceSize stride,
VkQueryResultFlags flags);
Parameters
-
deviceis the logical device that owns the query pool. -
queryPoolis the query pool managing the queries containing the desired results. -
firstQueryis the initial query index. -
queryCountis the number of queries to read. -
dataSizeis the size in bytes of the buffer pointed to bypData. -
pDatais a pointer to a user-allocated buffer where the results will be written -
strideis the stride in bytes between results for individual queries withinpData. -
flagsis a bitmask of VkQueryResultFlagBits specifying how and when results are returned.
Description
The range of queries read is defined by [firstQuery,
firstQuery + queryCount - 1].
For pipeline statistics queries, each query index in the pool contains one
integer value for each bit that is enabled in
VkQueryPoolCreateInfo::pname pipelineStatistics when the pool is
created.
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.
The behavior when not all queries are available, is described
below.
If VK_QUERY_RESULT_64_BIT is not set and the result overflows a 32-bit
value, the value may either wrap or saturate.
Similarly, if VK_QUERY_RESULT_64_BIT is set and the result overflows a
64-bit value, the value may either wrap or saturate.
If VK_QUERY_RESULT_WAIT_BIT is set, Vulkan will wait for each query to
be in the available state before retrieving the numerical results for that
query.
In this case, vkGetQueryPoolResults is guaranteed to succeed and
return VK_SUCCESS if the queries become available in a finite time
(i.e. if they have been issued and not reset).
If queries will never finish (e.g. due to being reset but not issued), then
vkGetQueryPoolResults may not return in finite time.
If VK_QUERY_RESULT_WAIT_BIT and VK_QUERY_RESULT_PARTIAL_BIT are
both not set then no result values are written to pData for queries
that are in the unavailable state at the time of the call, and
vkGetQueryPoolResults returns VK_NOT_READY.
However, availability state is still written to pData for those
queries if VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set.
|
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 |
|
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. |
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 to pData for
that query.
VK_QUERY_RESULT_PARTIAL_BIT must not be used if the pool’s
queryType is VK_QUERY_TYPE_TIMESTAMP.
If VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is set, the final integer
value written for each query is non-zero if the query’s status was available
or zero if the status was unavailable.
When VK_QUERY_RESULT_WITH_AVAILABILITY_BIT is used, implementations
must guarantee that if they return a non-zero availability value then the
numerical results must be valid, assuming the results are not reset by a
subsequent command.
|
Note
Satisfying this guarantee may require careful ordering by the application, e.g. to read the availability status before reading the results. |
See Also
VkDevice, 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.
Copyright
Copyright (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.