VKCMDBEGINQUERY(3)

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 indicating constraints on the types of queries that can be performed. Bits which can be set include:

    typedef enum VkQueryControlFlagBits {
        VK_QUERY_CONTROL_PRECISE_BIT = 0x00000001,
    } VkQueryControlFlagBits;

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.

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

    • 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

    • Each of commandBuffer and queryPool must have been created, allocated or retrieved from the same VkDevice

    • The query identified by queryPool and query must currently not be active

    • The query identified by queryPool and query must be unavailable

    • 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

    • queryPool must have been created with a queryType that differs from that of any other queries that have been made active, and are currently still active within commandBuffer

    • 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 created 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 created 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 created from must support compute operations

HOST SYNCHRONIZATION

    • Host access to commandBuffer must be externally synchronized

COMMAND PROPERTIES
Command Buffer Levels | Render Pass Scope | Supported Queue Types
Primary Secondary | Both | GRAPHICS COMPUTE

SEE ALSO

VkCommandBuffer, VkQueryControlFlags, VkQueryPool

DOCUMENT NOTES

For more information, see the Vulkan Specification at URL

https://www.khronos.org/registry/vulkan/specs/1.0/xhtml/vkspec.html#vkCmdBeginQuery

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification,not directly.

COPYRIGHT

Copyright (c) 2014-2016 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.

AUTHOR

Khronos Group
    Author.