C Specification

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);

Parameters

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

Description

Calling vkCmdEndQuery is equivalent to calling vkCmdEndQueryIndexedEXT with the index parameter set to zero.

As queries operate asynchronously, ending a query does not immediately set the query’s status to available. A query is considered finished when the final results of the query are ready to be retrieved by vkGetQueryPoolResults and vkCmdCopyQueryPoolResults, and this is when the query’s status is set to available.

Once a query is ended the query must finish in finite time, unless the state of the query is changed using other commands, e.g. by issuing a reset of the query.

Valid Usage

  • VUID-vkCmdEndQuery-None-01923
    All queries used by the command must be active

  • VUID-vkCmdEndQuery-query-00810
    query must be less than the number of queries in queryPool

  • VUID-vkCmdEndQuery-commandBuffer-01886
    commandBuffer must not be a protected command buffer

  • VUID-vkCmdEndQuery-query-00812
    If vkCmdEndQuery is 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-vkCmdEndQuery-queryPool-03227
    If queryPool was created with a queryType of VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR and one or more of the counters used to create queryPool was VK_PERFORMANCE_COUNTER_SCOPE_COMMAND_BUFFER_KHR, the vkCmdEndQuery must be the last recorded command in commandBuffer

  • VUID-vkCmdEndQuery-queryPool-03228
    If queryPool was created with a queryType of VK_QUERY_TYPE_PERFORMANCE_QUERY_KHR and one or more of the counters used to create queryPool was VK_PERFORMANCE_COUNTER_SCOPE_RENDER_PASS_KHR, the vkCmdEndQuery must not be recorded within a render pass instance

Valid Usage (Implicit)

  • VUID-vkCmdEndQuery-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdEndQuery-queryPool-parameter
    queryPool must be a valid VkQueryPool handle

  • VUID-vkCmdEndQuery-commandBuffer-recording
    commandBuffer must be in the recording state

  • VUID-vkCmdEndQuery-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support graphics, compute, decode, or encode operations

  • VUID-vkCmdEndQuery-commonparent
    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

Primary
Secondary

Both

Graphics
Compute
Decode
Encode

See Also

VK_VERSION_1_0, VkCommandBuffer, 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 2014-2022 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0