17. Queries
Queries provide a mechanism to return information about the processing of a sequence of Vulkan commands. Query operations are asynchronous, and as such, their results are not returned immediately. Instead, their results, and their availability status are stored in a Query Pool. The state of these queries can be read back on the host, or copied to a buffer object on the device.
The supported query types are Occlusion Queries, Pipeline Statistics Queries, and Timestamp Queries.
17.1. Query Pools
Queries are managed using query pool objects. Each query pool is a collection of a specific number of queries of a particular type.
Query pools are represented by VkQueryPool
handles:
// Provided by VK_VERSION_1_0
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkQueryPool)
To create a query pool, call:
// Provided by VK_VERSION_1_0
VkResult vkCreateQueryPool(
VkDevice device,
const VkQueryPoolCreateInfo* pCreateInfo,
const VkAllocationCallbacks* pAllocator,
VkQueryPool* pQueryPool);
-
device
is the logical device that creates the query pool. -
pCreateInfo
is a pointer to a VkQueryPoolCreateInfo structure containing the number and type of queries to be managed by the pool. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter. -
pQueryPool
is a pointer to a VkQueryPool handle in which the resulting query pool object is returned.
The VkQueryPoolCreateInfo
structure is defined as:
// Provided by VK_VERSION_1_0
typedef struct VkQueryPoolCreateInfo {
VkStructureType sType;
const void* pNext;
VkQueryPoolCreateFlags flags;
VkQueryType queryType;
uint32_t queryCount;
VkQueryPipelineStatisticFlags pipelineStatistics;
} VkQueryPoolCreateInfo;
-
sType
is the type of this structure. -
pNext
isNULL
or a pointer to a structure extending this structure. -
flags
is reserved for future use. -
queryType
is a VkQueryType value specifying the type of queries managed by the pool. -
queryCount
is the number of queries managed by the pool. -
pipelineStatistics
is a bitmask of VkQueryPipelineStatisticFlagBits specifying which counters will be returned in queries on the new pool, as described below in Pipeline Statistics Queries.
pipelineStatistics
is ignored if queryType
is not
VK_QUERY_TYPE_PIPELINE_STATISTICS
.
// Provided by VK_VERSION_1_0
typedef VkFlags VkQueryPoolCreateFlags;
VkQueryPoolCreateFlags
is a bitmask type for setting a mask, but is
currently reserved for future use.
To destroy a query pool, call:
// Provided by VK_VERSION_1_0
void vkDestroyQueryPool(
VkDevice device,
VkQueryPool queryPool,
const VkAllocationCallbacks* pAllocator);
-
device
is the logical device that destroys the query pool. -
queryPool
is the query pool to destroy. -
pAllocator
controls host memory allocation as described in the Memory Allocation chapter.
Note
Applications can verify that |
Possible values of VkQueryPoolCreateInfo::queryType
, specifying
the type of queries managed by the pool, are:
// Provided by VK_VERSION_1_0
typedef enum VkQueryType {
VK_QUERY_TYPE_OCCLUSION = 0,
VK_QUERY_TYPE_PIPELINE_STATISTICS = 1,
VK_QUERY_TYPE_TIMESTAMP = 2,
} VkQueryType;
-
VK_QUERY_TYPE_OCCLUSION
specifies an occlusion query. -
VK_QUERY_TYPE_PIPELINE_STATISTICS
specifies a pipeline statistics query. -
VK_QUERY_TYPE_TIMESTAMP
specifies a timestamp query.
17.2. Query Operation
The operation of queries is controlled by the commands vkCmdBeginQuery, vkCmdEndQuery, vkCmdResetQueryPool, vkCmdCopyQueryPoolResults, vkCmdWriteTimestamp2, and vkCmdWriteTimestamp.
In order for a VkCommandBuffer
to record query management commands,
the queue family for which its VkCommandPool
was created must support
the appropriate type of operations (graphics, compute) suitable for the
query type of a given query pool.
Each query in a query pool has a status that is either unavailable or available, and also has state to store the numerical results of a query operation of the type requested when the query pool was created. Resetting a query via vkCmdResetQueryPool or vkResetQueryPool sets the status to unavailable and makes the numerical results undefined. A query is made available by the operation of vkCmdEndQuery, vkCmdWriteTimestamp2, or vkCmdWriteTimestamp. Both the availability status and numerical results can be retrieved by calling either vkGetQueryPoolResults or vkCmdCopyQueryPoolResults.
After query pool creation, each query must be reset before it is used. Queries must also be reset between uses.
If a logical device includes multiple physical devices, then each command that writes a query must execute on a single physical device, and any call to vkCmdBeginQuery must execute the corresponding vkCmdEndQuery command on the same physical device.
To reset a range of queries in a query pool on a queue, call:
// Provided by VK_VERSION_1_0
void vkCmdResetQueryPool(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t firstQuery,
uint32_t queryCount);
-
commandBuffer
is the command buffer into which this command will be recorded. -
queryPool
is the handle of the query pool managing the queries being reset. -
firstQuery
is the initial query index to reset. -
queryCount
is the number of queries to reset.
When executed on a queue, this command sets the status of query indices
[firstQuery
, firstQuery
+ queryCount
- 1] to
unavailable.
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 firstQuery
and queryCount
that occur earlier in
submission order.
The second synchronization scope
includes all commands which reference the queries in queryPool
indicated by firstQuery
and queryCount
that occur later in
submission order.
The operation of this command happens after the first scope and happens before the second scope.
To reset a range of queries in a query pool on the host, call:
// Provided by VK_VERSION_1_2
void vkResetQueryPool(
VkDevice device,
VkQueryPool queryPool,
uint32_t firstQuery,
uint32_t queryCount);
-
device
is the logical device that owns the query pool. -
queryPool
is the handle of the query pool managing the queries being reset. -
firstQuery
is the initial query index to reset. -
queryCount
is the number of queries to reset.
This command sets the status of query indices [firstQuery
,
firstQuery
+ queryCount
- 1] to unavailable.
Once queries are reset and ready for use, query commands can be issued to a command buffer. Occlusion queries and pipeline statistics queries count events - drawn samples and pipeline stage invocations, respectively - resulting from commands that are recorded between a vkCmdBeginQuery command and a vkCmdEndQuery command within a specified command buffer, effectively scoping a set of drawing and/or dispatching commands. Timestamp queries write timestamps to a query pool.
A query must begin and end in the same command buffer, although if it is a
primary command buffer, and the inheritedQueries
feature is enabled, it can execute secondary
command buffers during the query operation.
For a secondary command buffer to be executed while a query is active, it
must set the occlusionQueryEnable
, queryFlags
, and/or
pipelineStatistics
members of VkCommandBufferInheritanceInfo to
conservative values, as described in the Command
Buffer Recording section.
A query must either begin and end inside the same subpass of a render pass
instance, or must both begin and end outside of a render pass instance
(i.e. contain entire render pass instances).
If queries are used while executing a render pass instance that has
multiview enabled, the query uses N consecutive query indices in the
query pool (starting at query
) where N is the number of bits set
in the view mask in the subpass the query is used in.
How the numerical results of the query are distributed among the queries is
implementation-dependent.
For example, some implementations may write each view’s results to a
distinct query, while other implementations may write the total result to
the first query and write zero to the other queries.
However, the sum of the results in all the queries must accurately reflect
the total result of the query summed over all views.
Applications can sum the results from all the queries to compute the total
result.
Queries used with multiview rendering must not span subpasses, i.e. they must begin and end in the same subpass.
To begin a query, call:
// Provided by VK_VERSION_1_0
void vkCmdBeginQuery(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t query,
VkQueryControlFlags flags);
-
commandBuffer
is the command buffer into which this command will be recorded. -
queryPool
is the query pool that will manage the results of the query. -
query
is the query index within the query pool that will contain the results. -
flags
is a bitmask of VkQueryControlFlagBits specifying constraints on the types of queries that can be performed.
If the queryType
of the pool is VK_QUERY_TYPE_OCCLUSION
and
flags
contains VK_QUERY_CONTROL_PRECISE_BIT
, an implementation
must return a result that matches the actual number of samples passed.
This is described in more detail in Occlusion Queries.
After beginning a query, that query is considered active within the command buffer it was called in until that same query is ended. Queries active in a primary command buffer when secondary command buffers are executed are considered active for those secondary command buffers.
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.
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.
Bits which can be set in vkCmdBeginQuery::flags
, specifying
constraints on the types of queries that can be performed, are:
// Provided by VK_VERSION_1_0
typedef enum VkQueryControlFlagBits {
VK_QUERY_CONTROL_PRECISE_BIT = 0x00000001,
} VkQueryControlFlagBits;
-
VK_QUERY_CONTROL_PRECISE_BIT
specifies the precision of occlusion queries.
// Provided by VK_VERSION_1_0
typedef VkFlags VkQueryControlFlags;
VkQueryControlFlags
is a bitmask type for setting a mask of zero or
more VkQueryControlFlagBits.
To end a query after the set of desired drawing or dispatching commands is executed, call:
// Provided by VK_VERSION_1_0
void vkCmdEndQuery(
VkCommandBuffer commandBuffer,
VkQueryPool queryPool,
uint32_t query);
-
commandBuffer
is the command buffer into which this command will be recorded. -
queryPool
is the query pool that is managing the results of the query. -
query
is the query index within the query pool where the result is stored.
The command completes the query in queryPool
identified by
query
, and marks it as available.
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.
The second synchronization scope includes only the operation of this command.
An application can retrieve results either by requesting they be written
into application-provided memory, or by requesting they be copied into a
VkBuffer
.
In either case, the layout in memory is defined as follows:
-
The first query’s result is written starting at the first byte requested by the command, and each subsequent query’s result begins
stride
bytes later. -
Occlusion queries, pipeline statistics queries, and timestamp queries store results in a tightly packed array of unsigned integers, either 32- or 64-bits as requested by the command, storing the numerical results and, if requested, the availability status.
-
If
VK_QUERY_RESULT_WITH_AVAILABILITY_BIT
is used, the final element of each query’s result is an integer indicating whether the query’s result is available, with any non-zero value indicating that it is available. -
Occlusion queries write one integer value - the number of samples passed. Pipeline statistics queries write one integer value for each bit that is enabled in the
pipelineStatistics
when the pool is created, and the statistics values are written in bit order starting from the least significant bit. Timestamp queries write one integer value. -
If more than one query is retrieved and
stride
is not at least as large as the size of the array of values corresponding to a single query, the values written to memory are undefined.
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);
-
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.
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
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.
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 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,
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 |
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. |
Bits which can be set in vkGetQueryPoolResults::flags
and
vkCmdCopyQueryPoolResults::flags
, specifying how and when
results are returned, are:
// Provided by VK_VERSION_1_0
typedef enum VkQueryResultFlagBits {
VK_QUERY_RESULT_64_BIT = 0x00000001,
VK_QUERY_RESULT_WAIT_BIT = 0x00000002,
VK_QUERY_RESULT_WITH_AVAILABILITY_BIT = 0x00000004,
VK_QUERY_RESULT_PARTIAL_BIT = 0x00000008,
} VkQueryResultFlagBits;
-
VK_QUERY_RESULT_64_BIT
specifies the results will be written as an array of 64-bit unsigned integer values. If this bit is not set, the results will be written as an array of 32-bit unsigned integer values. -
VK_QUERY_RESULT_WAIT_BIT
specifies that Vulkan will wait for each query’s status to become available before retrieving its results. -
VK_QUERY_RESULT_WITH_AVAILABILITY_BIT
specifies that the availability status accompanies the results. -
VK_QUERY_RESULT_PARTIAL_BIT
specifies that returning partial results is acceptable.
// Provided by VK_VERSION_1_0
typedef VkFlags VkQueryResultFlags;
VkQueryResultFlags
is a bitmask type for setting a mask of zero or
more VkQueryResultFlagBits.
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);
-
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.
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.
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.
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
,
vkCmdWriteTimestamp2,
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.
Rendering operations such as clears, MSAA resolves, attachment load/store operations, and blits may count towards the results of queries. This behavior is implementation-dependent and may vary depending on the path used within an implementation. For example, some implementations have several types of clears, some of which may include vertices and some not.
17.3. Occlusion Queries
Occlusion queries track the number of samples that pass the per-fragment
tests for a set of drawing commands.
As such, occlusion queries are only available on queue families supporting
graphics operations.
The application can then use these results to inform future rendering
decisions.
An occlusion query is begun and ended by calling vkCmdBeginQuery
and
vkCmdEndQuery
, respectively.
When an occlusion query begins, the count of passing samples always starts
at zero.
For each drawing command, the count is incremented as described in
Sample Counting.
If flags
does not contain VK_QUERY_CONTROL_PRECISE_BIT
an
implementation may generate any non-zero result value for the query if the
count of passing samples is non-zero.
Note
Not setting Setting |
When an occlusion query finishes, the result for that query is marked as
available.
The application can then either copy the result to a buffer (via
vkCmdCopyQueryPoolResults
) or request it be put into host memory (via
vkGetQueryPoolResults
).
Note
If occluding geometry is not drawn first, samples can pass the depth test, but still not be visible in a final image. |
17.4. Pipeline Statistics Queries
Pipeline statistics queries allow the application to sample a specified set
of VkPipeline
counters.
These counters are accumulated by Vulkan for a set of either drawing or
dispatching commands while a pipeline statistics query is active.
As such, pipeline statistics queries are available on queue families
supporting either graphics or compute operations.
The availability of pipeline statistics queries is indicated by the
pipelineStatisticsQuery
member of the VkPhysicalDeviceFeatures
object (see vkGetPhysicalDeviceFeatures
and vkCreateDevice
for
detecting and requesting this query type on a VkDevice
).
A pipeline statistics query is begun and ended by calling
vkCmdBeginQuery
and vkCmdEndQuery
, respectively.
When a pipeline statistics query begins, all statistics counters are set to
zero.
While the query is active, the pipeline type determines which set of
statistics are available, but these must be configured on the query pool
when it is created.
If a statistic counter is issued on a command buffer that does not support
the corresponding operation, the value of that counter is undefined after
the query has been made available.
At least one statistic counter relevant to the operations supported on the
recording command buffer must be enabled.
Bits which can be set in
VkQueryPoolCreateInfo::pipelineStatistics
for query pools and in
VkCommandBufferInheritanceInfo::pipelineStatistics
for secondary
command buffers, individually enabling pipeline statistics counters, are:
// Provided by VK_VERSION_1_0
typedef enum VkQueryPipelineStatisticFlagBits {
VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_VERTICES_BIT = 0x00000001,
VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_PRIMITIVES_BIT = 0x00000002,
VK_QUERY_PIPELINE_STATISTIC_VERTEX_SHADER_INVOCATIONS_BIT = 0x00000004,
VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_INVOCATIONS_BIT = 0x00000008,
VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_PRIMITIVES_BIT = 0x00000010,
VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT = 0x00000020,
VK_QUERY_PIPELINE_STATISTIC_CLIPPING_PRIMITIVES_BIT = 0x00000040,
VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BIT = 0x00000080,
VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_CONTROL_SHADER_PATCHES_BIT = 0x00000100,
VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_EVALUATION_SHADER_INVOCATIONS_BIT = 0x00000200,
VK_QUERY_PIPELINE_STATISTIC_COMPUTE_SHADER_INVOCATIONS_BIT = 0x00000400,
} VkQueryPipelineStatisticFlagBits;
-
VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_VERTICES_BIT
specifies that queries managed by the pool will count the number of vertices processed by the input assembly stage. Vertices corresponding to incomplete primitives may contribute to the count. -
VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_PRIMITIVES_BIT
specifies that queries managed by the pool will count the number of primitives processed by the input assembly stage. If primitive restart is enabled, restarting the primitive topology has no effect on the count. Incomplete primitives may be counted. -
VK_QUERY_PIPELINE_STATISTIC_VERTEX_SHADER_INVOCATIONS_BIT
specifies that queries managed by the pool will count the number of vertex shader invocations. This counter’s value is incremented each time a vertex shader is invoked. -
VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_INVOCATIONS_BIT
specifies that queries managed by the pool will count the number of geometry shader invocations. This counter’s value is incremented each time a geometry shader is invoked. In the case of instanced geometry shaders, the geometry shader invocations count is incremented for each separate instanced invocation. -
VK_QUERY_PIPELINE_STATISTIC_GEOMETRY_SHADER_PRIMITIVES_BIT
specifies that queries managed by the pool will count the number of primitives generated by geometry shader invocations. The counter’s value is incremented each time the geometry shader emits a primitive. Restarting primitive topology using the SPIR-V instructionsOpEndPrimitive
orOpEndStreamPrimitive
has no effect on the geometry shader output primitives count. -
VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT
specifies that queries managed by the pool will count the number of primitives processed by the Primitive Clipping stage of the pipeline. The counter’s value is incremented each time a primitive reaches the primitive clipping stage. -
VK_QUERY_PIPELINE_STATISTIC_CLIPPING_PRIMITIVES_BIT
specifies that queries managed by the pool will count the number of primitives output by the Primitive Clipping stage of the pipeline. The counter’s value is incremented each time a primitive passes the primitive clipping stage. The actual number of primitives output by the primitive clipping stage for a particular input primitive is implementation-dependent but must satisfy the following conditions:-
If at least one vertex of the input primitive lies inside the clipping volume, the counter is incremented by one or more.
-
Otherwise, the counter is incremented by zero or more.
-
-
VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BIT
specifies that queries managed by the pool will count the number of fragment shader invocations. The counter’s value is incremented each time the fragment shader is invoked. -
VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_CONTROL_SHADER_PATCHES_BIT
specifies that queries managed by the pool will count the number of patches processed by the tessellation control shader. The counter’s value is incremented once for each patch for which a tessellation control shader is invoked. -
VK_QUERY_PIPELINE_STATISTIC_TESSELLATION_EVALUATION_SHADER_INVOCATIONS_BIT
specifies that queries managed by the pool will count the number of invocations of the tessellation evaluation shader. The counter’s value is incremented each time the tessellation evaluation shader is invoked. -
VK_QUERY_PIPELINE_STATISTIC_COMPUTE_SHADER_INVOCATIONS_BIT
specifies that queries managed by the pool will count the number of compute shader invocations. The counter’s value is incremented every time the compute shader is invoked. Implementations may skip the execution of certain compute shader invocations or execute additional compute shader invocations for implementation-dependent reasons as long as the results of rendering otherwise remain unchanged.
These values are intended to measure relative statistics on one implementation. Various device architectures will count these values differently. Any or all counters may be affected by the issues described in Query Operation.
Note
For example, tile-based rendering devices may need to replay the scene multiple times, affecting some of the counts. |
If a pipeline has rasterizerDiscardEnable
enabled, implementations
may discard primitives after the final
pre-rasterization shader
stage.
As a result, if rasterizerDiscardEnable
is enabled, the clipping input
and output primitives counters may not be incremented.
When a pipeline statistics query finishes, the result for that query is
marked as available.
The application can copy the result to a buffer (via
vkCmdCopyQueryPoolResults
), or request it be put into host memory (via
vkGetQueryPoolResults
).
// Provided by VK_VERSION_1_0
typedef VkFlags VkQueryPipelineStatisticFlags;
VkQueryPipelineStatisticFlags
is a bitmask type for setting a mask of
zero or more VkQueryPipelineStatisticFlagBits.
17.5. Timestamp Queries
Timestamps provide applications with a mechanism for timing the execution
of commands.
A timestamp is an integer value generated by the VkPhysicalDevice
.
Unlike other queries, timestamps do not operate over a range, and so do not
use vkCmdBeginQuery or vkCmdEndQuery.
The mechanism is built around a set of commands that allow the application
to tell the VkPhysicalDevice
to write timestamp values to a
query pool and then either read timestamp values on the
host (using vkGetQueryPoolResults) or copy timestamp values to a
VkBuffer
(using vkCmdCopyQueryPoolResults).
The application can then compute differences between timestamps to
determine execution time.
The number of valid bits in a timestamp value is determined by the
VkQueueFamilyProperties
::timestampValidBits
property of the
queue on which the timestamp is written.
Timestamps are supported on any queue which reports a non-zero value for
timestampValidBits
via vkGetPhysicalDeviceQueueFamilyProperties.
If the timestampComputeAndGraphics
limit is VK_TRUE
, timestamps are
supported by every queue family that supports either graphics or compute
operations (see VkQueueFamilyProperties).
The number of nanoseconds it takes for a timestamp value to be incremented
by 1 can be obtained from
VkPhysicalDeviceLimits
::timestampPeriod
after a call to
vkGetPhysicalDeviceProperties
.
To request a timestamp and write the value to memory, call:
// Provided by VK_VERSION_1_3
void vkCmdWriteTimestamp2(
VkCommandBuffer commandBuffer,
VkPipelineStageFlags2 stage,
VkQueryPool queryPool,
uint32_t query);
-
commandBuffer
is the command buffer into which the command will be recorded. -
stage
specifies a stage of the pipeline. -
queryPool
is the query pool that will manage the timestamp. -
query
is the query within the query pool that will contain the timestamp.
When vkCmdWriteTimestamp2
is submitted to a queue, it defines an
execution dependency on commands that were submitted before it, and writes a
timestamp to a query pool.
The first synchronization scope
includes all commands that occur earlier in
submission order.
The synchronization scope is limited to operations on the pipeline stage
specified by stage
.
The second synchronization scope includes only the timestamp write operation.
When the timestamp value is written, the availability status of the query is set to available.
Note
If an implementation is unable to detect completion and latch the timer
immediately after |
Comparisons between timestamps are not meaningful if the timestamps are written by commands submitted to different queues.
Note
An example of such a comparison is subtracting an older timestamp from a newer one to determine the execution time of a sequence of commands. |
If vkCmdWriteTimestamp2
is called while executing a render pass
instance that has multiview enabled, the timestamp uses N consecutive
query indices in the query pool (starting at query
) where N is
the number of bits set in the view mask of the subpass the command is
executed in.
The resulting query values are determined by an implementation-dependent
choice of one of the following behaviors:
-
The first query is a timestamp value and (if more than one bit is set in the view mask) zero is written to the remaining queries. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the difference between the first query written by each command.
-
All N queries are timestamp values. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the sum of the difference between corresponding queries written by each command. The difference between corresponding queries may be the execution time of a single view.
In either case, the application can sum the differences between all N queries to determine the total execution time.
To request a timestamp and write the value to memory, call:
// Provided by VK_VERSION_1_0
void vkCmdWriteTimestamp(
VkCommandBuffer commandBuffer,
VkPipelineStageFlagBits pipelineStage,
VkQueryPool queryPool,
uint32_t query);
-
commandBuffer
is the command buffer into which the command will be recorded. -
pipelineStage
is a VkPipelineStageFlagBits value, specifying a stage of the pipeline. -
queryPool
is the query pool that will manage the timestamp. -
query
is the query within the query pool that will contain the timestamp.
When vkCmdWriteTimestamp
is submitted to a queue, it defines an
execution dependency on commands that were submitted before it, and writes a
timestamp to a query pool.
The first synchronization scope
includes all commands that occur earlier in
submission order.
The synchronization scope is limited to operations on the pipeline stage
specified by pipelineStage
.
The second synchronization scope includes only the timestamp write operation.
When the timestamp value is written, the availability status of the query is set to available.
Note
If an implementation is unable to detect completion and latch the timer
immediately after |
Comparisons between timestamps are not meaningful if the timestamps are written by commands submitted to different queues.
Note
An example of such a comparison is subtracting an older timestamp from a newer one to determine the execution time of a sequence of commands. |
If vkCmdWriteTimestamp
is called while executing a render pass
instance that has multiview enabled, the timestamp uses N consecutive
query indices in the query pool (starting at query
) where N is
the number of bits set in the view mask of the subpass the command is
executed in.
The resulting query values are determined by an implementation-dependent
choice of one of the following behaviors:
-
The first query is a timestamp value and (if more than one bit is set in the view mask) zero is written to the remaining queries. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the difference between the first query written by each command.
-
All N queries are timestamp values. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the sum of the difference between corresponding queries written by each command. The difference between corresponding queries may be the execution time of a single view.
In either case, the application can sum the differences between all N queries to determine the total execution time.