Timestamps provide applications with a mechanism for timing the execution
of commands. A timestamp is an integer value generated by the
VkPhysicalDevice
. Unlike other queries, timestamps do not operate over
a range, and so do not use vkCmdBeginQuery
or vkCmdEndQuery
. The
mechanism is built around a set of commands that allow the application to
tell the VkPhysicalDevice
to write timestamp values to a
query pool and then either read timestamp values on the
host (using vkGetQueryPoolResults
) or copy timestamp values to a
VkBuffer
(using vkCmdCopyQueryPoolResults
). The application can
then compute differences between timestamps to determine execution time.
The number of valid bits in a timestamp value is determined by the
VkQueueFamilyProperties
::timestampValidBits
property of the
queue on which the timestamp is written. Timestamps are supported on any
queue which reports a non-zero value for timestampValidBits
via
vkGetPhysicalDeviceQueueFamilyProperties
.
If the timestampComputeAndGraphics
limit is VK_TRUE
, timestamps
are supported by every queue family that supports either
graphics or compute operations (see VkQueueFamilyProperties
).
The number of nanoseconds it takes for a timestamp value to be
incremented by 1 can be obtained from
VkPhysicalDeviceLimits
::timestampPeriod
after a call to
vkGetPhysicalDeviceProperties
.
To request a timestamp, call:
void vkCmdWriteTimestamp( VkCommandBuffer commandBuffer, VkPipelineStageFlagBits pipelineStage, VkQueryPool queryPool, uint32_t query);
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.
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. |
vkCmdCopyQueryPoolResults
can then be called to copy the timestamp
value from the query pool into buffer memory, with ordering and
synchronization behavior equivalent to how other queries operate. Timestamp
values can also be retrieved from the query pool using
vkGetQueryPoolResults
. As with other queries, the query must be reset
using vkCmdResetQueryPool
before requesting the timestamp value be
written to it.
While vkCmdWriteTimestamp
can be called inside or outside of a render
pass instance, vkCmdCopyQueryPoolResults
must only be called outside
of a render pass instance.