vkCmdBeginQuery

To begin a query, call:

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.

Calling vkCmdBeginQuery is equivalent to calling vkCmdBeginQueryIndexedEXT with the index parameter set to zero.

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.

Furthermore, if the query is started within a video coding scope, the following command buffer states are initialized for the query type:

The active_query_index is set to the value specified by query.
The last activatable query index is also set to the value specified by query.

Each video coding operation stores a result to the query corresponding to the current active query index, followed by incrementing the active query index. If the active query index gets incremented past the last activatable query index, issuing any further video coding operations results in undefined: behavior.

In practice, this means that currently no more than a single video coding operation must be issued between a begin and end query pair.

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.

Valid Usage

VUID-vkCmdBeginQuery-None-00807

All queries used by the command must be unavailable

VUID-vkCmdBeginQuery-queryType-02804

The queryType used to create queryPool must not be VK_QUERY_TYPE_TIMESTAMP

VUID-vkCmdBeginQuery-queryType-04728

The queryType used to create queryPool must not be VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_KHR or VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_SIZE_KHR

VUID-vkCmdBeginQuery-queryType-06741

The queryType used to create queryPool must not be VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SIZE_KHR or VK_QUERY_TYPE_ACCELERATION_STRUCTURE_SERIALIZATION_BOTTOM_LEVEL_POINTERS_KHR

VUID-vkCmdBeginQuery-queryType-04729

The queryType used to create queryPool must not be VK_QUERY_TYPE_ACCELERATION_STRUCTURE_COMPACTED_SIZE_NV

VUID-vkCmdBeginQuery-queryType-00800

If the occlusionQueryPrecise feature is not enabled, or the queryType used to create queryPool was not VK_QUERY_TYPE_OCCLUSION, flags must not contain VK_QUERY_CONTROL_PRECISE_BIT

VUID-vkCmdBeginQuery-query-00802

query must be less than the number of queries in queryPool

VUID-vkCmdBeginQuery-queryType-00803

If the queryType used to create queryPool was VK_QUERY_TYPE_OCCLUSION, the VkCommandPool that commandBuffer was allocated from must support graphics operations

VUID-vkCmdBeginQuery-queryType-00804

If the queryType used to create queryPool was VK_QUERY_TYPE_PIPELINE_STATISTICS and any of the pipelineStatistics indicate graphics operations, the VkCommandPool that commandBuffer was allocated from must support graphics operations

VUID-vkCmdBeginQuery-queryType-00805

If the queryType used to create queryPool was VK_QUERY_TYPE_PIPELINE_STATISTICS and any of the pipelineStatistics indicate compute operations, the VkCommandPool that commandBuffer was allocated from must support compute operations

VUID-vkCmdBeginQuery-query-00808

If called within a render pass instance, the sum of query and the number of bits set in the current subpass’s view mask must be less than or equal to the number of queries in queryPool

VUID-vkCmdBeginQuery-queryType-07126

If the queryType used to create queryPool was VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR, then the VkCommandPool that commandBuffer was allocated from must have been created with a queue family index that supports result status queries, as indicated by VkQueueFamilyQueryResultStatusPropertiesKHR::queryResultStatusSupport

VUID-vkCmdBeginQuery-None-07127

If there is a bound video session, then there must be no active queries

VUID-vkCmdBeginQuery-None-08370

If there is a bound video session, then it must not have been created with VK_VIDEO_SESSION_CREATE_INLINE_QUERIES_BIT_KHR

VUID-vkCmdBeginQuery-queryType-07128

If the queryType used to create queryPool was VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR and there is a bound video session, then queryPool must have been created with a VkVideoProfileInfoKHR structure included in the pNext chain of VkQueryPoolCreateInfo identical to the one specified in VkVideoSessionCreateInfoKHR::pVideoProfile the bound video session was created with

VUID-vkCmdBeginQuery-queryType-07129

If the queryType used to create queryPool was VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR, then there must be a bound video session

VUID-vkCmdBeginQuery-queryType-07130

If the queryType used to create queryPool was VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR and there is a bound video session, then queryPool must have been created with a VkVideoProfileInfoKHR structure included in the pNext chain of VkQueryPoolCreateInfo identical to the one specified in VkVideoSessionCreateInfoKHR::pVideoProfile the bound video session was created with

VUID-vkCmdBeginQuery-queryType-07131

If the queryType used to create queryPool was not VK_QUERY_TYPE_RESULT_STATUS_ONLY_KHR or VK_QUERY_TYPE_VIDEO_ENCODE_FEEDBACK_KHR, then there must be no bound video session

VUID-vkCmdBeginQuery-queryPool-01922

queryPool must have been created with a queryType that differs from that of any queries that are active within commandBuffer

VUID-vkCmdBeginQuery-queryType-07070

If the queryType used to create queryPool was VK_QUERY_TYPE_MESH_PRIMITIVES_GENERATED_EXT the VkCommandPool that commandBuffer was allocated from must support graphics operations

VUID-vkCmdBeginQuery-queryType-02327

If the queryType used to create queryPool was VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT the VkCommandPool that commandBuffer was allocated from must support graphics operations

VUID-vkCmdBeginQuery-queryType-02328

If the queryType used to create queryPool was VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT then VkPhysicalDeviceTransformFeedbackPropertiesEXT::transformFeedbackQueriesmust be supported

VUID-vkCmdBeginQuery-queryType-06687

If the queryType used to create queryPool was VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT the VkCommandPool that commandBuffer was allocated from must support graphics operations

VUID-vkCmdBeginQuery-queryType-06688

If the queryType used to create queryPool was VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT then primitivesGeneratedQuerymust be enabled

VUID-vkCmdBeginQuery-queryPool-07289

If queryPool was created with a queryType of VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, then the VkQueryPoolPerformanceCreateInfoKHR::queueFamilyIndex

queryPool was created with must equal the queue family index of the VkCommandPool that commandBuffer was allocated from

VUID-vkCmdBeginQuery-queryPool-03223

If queryPool was created with a queryType of VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, the profiling lock must have been held before vkBeginCommandBuffer was called on commandBuffer

VUID-vkCmdBeginQuery-queryPool-03224

If queryPool was created with a queryType of VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR and one of the counters used to create queryPool was VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR, the query begin must be the first recorded command in commandBuffer

VUID-vkCmdBeginQuery-queryPool-03225

If queryPool was created with a queryType of VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR and one of the counters used to create queryPool was VK_PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR, the begin command must not be recorded within a render pass instance

VUID-vkCmdBeginQuery-queryPool-03226

If queryPool was created with a queryType of VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR and another query pool with a queryType VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR has been used within commandBuffer, its parent primary command buffer or secondary command buffer recorded within the same parent primary command buffer as commandBuffer, the performanceCounterMultipleQueryPools feature must be enabled

VUID-vkCmdBeginQuery-None-02863

If queryPool was created with a queryType of VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR, this command must not be recorded in a command buffer that, either directly or through secondary command buffers, also contains a vkCmdResetQueryPool command affecting the same query

Host Synchronization

Host access to commandBuffer must be externally synchronized
Host access to the VkCommandPool that commandBuffer was allocated from must be externally synchronized ::