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 draw or
dispatch commands while a pipeline statistics query is active.
As such, pipeline statistics queries are available on queue families
supporting either graphics or compute operations.
Further, 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, that counter is undefined after the query has
finished.
At least one statistic counter relevant to the operations supported on the
recording command buffer must be enabled.
The pipeline statistic counters are individually enabled for query pools
with VkQueryPoolCreateInfo
::pipelineStatistics
, and for
secondary command buffers with
VkCommandBufferInheritanceInfo
::pipelineStatistics
.
Bits which can be set in pipelineStatistics
include:
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;
These bits have the following meanings:
VK_QUERY_PIPELINE_STATISTIC_INPUT_ASSEMBLY_VERTICES_BIT
is set,
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
is
set, 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
is
set, 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
is
set, 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
is
set, 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 instructions
OpEndPrimitive
or OpEndStreamPrimitive
has no effect on the
geometry shader output primitives count.
VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT
is set,
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.
If VK_QUERY_PIPELINE_STATISTIC_CLIPPING_PRIMITIVES_BIT
is set,
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:
VK_QUERY_PIPELINE_STATISTIC_FRAGMENT_SHADER_INVOCATIONS_BIT
is
set, 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
is set, 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
is set, 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
is
set, 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 vertex processing 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
).