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.