C Specification

The implementation will maintain a limited amount of history of timing information about previous presents. Because of the asynchronous nature of the presentation engine, the timing information for a given vkQueuePresentKHR command will become available some time later. These time values can be asynchronously queried, and will be returned if available. All time values are in nanoseconds, relative to a monotonically-increasing clock (e.g. CLOCK_MONOTONIC (see clock_gettime(2)) on Android and Linux).

To asynchronously query the presentation engine, for newly-available timing information about one or more previous presents to a given swapchain, call:

VkResult vkGetPastPresentationTimingGOOGLE(
    VkDevice                                    device,
    VkSwapchainKHR                              swapchain,
    uint32_t*                                   pPresentationTimingCount,
    VkPastPresentationTimingGOOGLE*             pPresentationTimings);

Parameters

  • device is the device associated with swapchain.

  • swapchain is the swapchain to obtain presentation timing information duration for.

  • pPresentationTimingCount is a pointer to an integer related to the number of VkPastPresentationTimingGOOGLE structures to query, as described below.

  • pPresentationTimings is either NULL or a pointer to an array of VkPastPresentationTimingGOOGLE structures.

Description

If pPresentationTimings is NULL, then the number of newly-available timing records for the given swapchain is returned in pPresentationTimingCount. Otherwise, pPresentationTimingCount must point to a variable set by the user to the number of elements in the pPresentationTimings array, and on return the variable is overwritten with the number of structures actually written to pPresentationTimings. If the value of pPresentationTimingCount is less than the number of newly-available timing records, at most pPresentationTimingCount structures will be written. If pPresentationTimingCount is smaller than the number of newly-available timing records for the given swapchain, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

Valid Usage (Implicit)
  • device must be a valid VkDevice handle

  • swapchain must be a valid VkSwapchainKHR handle

  • pPresentationTimingCount must be a valid pointer to a uint32_t value

  • If the value referenced by pPresentationTimingCount is not 0, and pPresentationTimings is not NULL, pPresentationTimings must be a valid pointer to an array of pPresentationTimingCount VkPastPresentationTimingGOOGLE structures

  • Both of device, and swapchain must have been created, allocated, or retrieved from the same VkInstance

Host Synchronization
  • Host access to swapchain must be externally synchronized

Return Codes
On success, this command returns
  • VK_SUCCESS

  • VK_INCOMPLETE

On failure, this command returns
  • VK_ERROR_DEVICE_LOST

  • VK_ERROR_OUT_OF_DATE_KHR

  • VK_ERROR_SURFACE_LOST_KHR

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-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.