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.