C Specification

To request a timestamp, call:

// Provided by VK_VERSION_1_0
void vkCmdWriteTimestamp(
    VkCommandBuffer                             commandBuffer,
    VkPipelineStageFlagBits                     pipelineStage,
    VkQueryPool                                 queryPool,
    uint32_t                                    query);

Parameters

  • commandBuffer is the command buffer into which the command will be recorded.

  • pipelineStage is one of the VkPipelineStageFlagBits, specifying a stage of the pipeline.

  • queryPool is the query pool that will manage the timestamp.

  • query is the query within the query pool that will contain the timestamp.

Description

vkCmdWriteTimestamp latches the value of the timer when all previous commands have completed executing as far as the specified pipeline stage, and writes the timestamp value to memory. When the timestamp value is written, the availability status of the query is set to available.

Note

If an implementation is unable to detect completion and latch the timer at any specific stage of the pipeline, it may instead do so at any logically later stage.

Timestamps may only be meaningfully compared if they are written by commands submitted to the same queue.

Note

An example of such a comparison is determining the execution time of a sequence of commands.

If vkCmdWriteTimestamp is called while executing a render pass instance that has multiview enabled, the timestamp uses N consecutive query indices in the query pool (starting at query) where N is the number of bits set in the view mask of the subpass the command is executed in. The resulting query values are determined by an implementation-dependent choice of one of the following behaviors:

  • The first query is a timestamp value and (if more than one bit is set in the view mask) zero is written to the remaining queries. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the difference between the first query written by each command.

  • All N queries are timestamp values. If two timestamps are written in the same subpass, the sum of the execution time of all views between those commands is the sum of the difference between corresponding queries written by each command. The difference between corresponding queries may be the execution time of a single view.

In either case, the application can sum the differences between all N queries to determine the total execution time.

Valid Usage
  • VUID-vkCmdWriteTimestamp-pipelineStage-04074
    pipelineStage must be a valid stage for the queue family that was used to create the command pool that commandBuffer was allocated from

  • VUID-vkCmdWriteTimestamp-pipelineStage-04075
    If the geometry shaders feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_GEOMETRY_SHADER_BIT

  • VUID-vkCmdWriteTimestamp-pipelineStage-04076
    If the tessellation shaders feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_TESSELLATION_CONTROL_SHADER_BIT or VK_PIPELINE_STAGE_TESSELLATION_EVALUATION_SHADER_BIT

  • VUID-vkCmdWriteTimestamp-pipelineStage-04077
    If the conditional rendering feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_CONDITIONAL_RENDERING_BIT_EXT

  • VUID-vkCmdWriteTimestamp-pipelineStage-04078
    If the fragment density map feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_FRAGMENT_DENSITY_PROCESS_BIT_EXT

  • VUID-vkCmdWriteTimestamp-pipelineStage-04079
    If the transform feedback feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_TRANSFORM_FEEDBACK_BIT_EXT

  • VUID-vkCmdWriteTimestamp-pipelineStage-04080
    If the mesh shaders feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_MESH_SHADER_BIT_NV or VK_PIPELINE_STAGE_TASK_SHADER_BIT_NV

  • VUID-vkCmdWriteTimestamp-pipelineStage-04081
    If the shading rate image feature is not enabled, pipelineStage must not be VK_PIPELINE_STAGE_SHADING_RATE_IMAGE_BIT_NV

  • VUID-vkCmdWriteTimestamp-queryPool-01416
    queryPool must have been created with a queryType of VK_QUERY_TYPE_TIMESTAMP

  • VUID-vkCmdWriteTimestamp-queryPool-00828
    The query identified by queryPool and query must be unavailable

  • VUID-vkCmdWriteTimestamp-timestampValidBits-00829
    The command pool’s queue family must support a non-zero timestampValidBits

  • VUID-vkCmdWriteTimestamp-None-00830
    All queries used by the command must be unavailable

  • VUID-vkCmdWriteTimestamp-query-00831
    If vkCmdWriteTimestamp 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

Valid Usage (Implicit)
  • VUID-vkCmdWriteTimestamp-commandBuffer-parameter
    commandBuffer must be a valid VkCommandBuffer handle

  • VUID-vkCmdWriteTimestamp-pipelineStage-parameter
    pipelineStage must be a valid VkPipelineStageFlagBits value

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

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

  • VUID-vkCmdWriteTimestamp-commandBuffer-cmdpool
    The VkCommandPool that commandBuffer was allocated from must support transfer, graphics, or compute operations

  • VUID-vkCmdWriteTimestamp-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 Pipeline Type

Primary
Secondary

Both

Transfer
Graphics
Compute

Transfer

See Also

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 (c) 2014-2020 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0