vkCmdBeginQuery(3)

# vkCmdBeginQuery(3) Manual Page

## Name

vkCmdBeginQuery - Begin a query

## C Specification

To begin a query, call:

    void vkCmdBeginQuery(
        VkCommandBuffer                             commandBuffer,
        VkQueryPool                                 queryPool,
        uint32_t                                    query,
        VkQueryControlFlags                         flags);

## Parameters

- `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.

## Description

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.

Valid Usage

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

- All queries used by the command must be unavailable

- The `queryType` used to create `queryPool` must not be `VK_QUERY_TYPE_TIMESTAMP`

- If the precise occlusion queries 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`

- `query` must be less than the number of queries in `queryPool`

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

- 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

- 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

- `commandBuffer` must not be a protected command buffer

- 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`

- 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

- If the `queryType` used to create `queryPool` was `VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT` then `VkPhysicalDeviceTransformFeedbackPropertiesEXT`::`transformFeedbackQueries` must be supported

- 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`

- 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`

- 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

- 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

Valid Usage (Implicit)

- `commandBuffer` must be a valid VkCommandBuffer handle

- `queryPool` must be a valid VkQueryPool handle

- `flags` must be a valid combination of VkQueryControlFlagBits values

- `commandBuffer` must be in the recording state

- The `VkCommandPool` that `commandBuffer` was allocated from must support graphics, or compute operations

- Both of `commandBuffer`, and `queryPool` must have been created, allocated, or retrieved from the same VkDevice

Host Synchronization

- Host access to `commandBuffer` must be externally synchronized

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

Command Properties

Command Buffer Levels | Render Pass Scope | Supported Queue Types | Pipeline Type
--- | --- | --- | ---
Primary Secondary | Both | Graphics Compute |

## See Also

VkCommandBuffer, VkQueryControlFlags, VkQueryPool

## 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-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.