vkGetPastPresentationTimingEXT(3)

# vkGetPastPresentationTimingEXT(3) Manual Page

## Name

vkGetPastPresentationTimingEXT - Obtain timing of previously-presented images

## C Specification

Because of the asynchronous nature of the presentation engine, the timing information for a given vkQueuePresentKHR command may only becomes available some time after the presentation has occurred. These time values should be asynchronously queried, and are returned if available. All time values are in nanoseconds, according to the time-domain being used.

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

    // Provided by VK_EXT_present_timing
    VkResult vkGetPastPresentationTimingEXT(
        VkDevice                                    device,
        const VkPastPresentationTimingInfoEXT*      pPastPresentationTimingInfo,
        VkPastPresentationTimingPropertiesEXT*      pPastPresentationTimingProperties);

## Parameters

- `device` is the device associated with `swapchain`.

- `pPastPresentationTimingInfo` is a pointer to an instance of the VkPastPresentationTimingInfoEXT structure.

- `pPastPresentationTimingProperties` is a pointer to an instance of the VkPastPresentationTimingPropertiesEXT structure.

## Description

If upon return the value of `VkPastPresentationTimingPropertiesEXT`::`presentationTimingCount` is less than the number of available timing records for the given `VkPastPresentationTimingInfoEXT`::`swapchain`, VK_INCOMPLETE is returned instead of VK_SUCCESS to indicate that not all the available values were returned.

Upon return, zero or more slots of the `swapchain` internal timing results queue, equal to the number of entries written to `VkPastPresentationTimingPropertiesEXT`::`pPresentationTimings` for which `reportComplete` is VK_TRUE, are made available for future `vkQueuePresentKHR` calls. Elements of `pPresentationTimings` are arranged in ascending order of present ids.

Timing information may become available out of order with regards to their associated vkQueuePresentKHR order. VK_PAST_PRESENTATION_TIMING_ALLOW_OUT_OF_ORDER_RESULTS_BIT_EXT can be set in `VkPastPresentationTimingInfoEXT`::`flags` to allow `vkGetPastPresentationTimingEXT` to return results in that same order. Otherwise, results are returned in the order of their associated vkQueuePresentKHR calls.

There is no requirement for any precise timing relationship between the completion of a present stage and the availability of any associated timing information. However, results must be made available in finite time.

As an exception to the normal rules for objects which are externally synchronized, `swapchain` may be simultaneously used by other threads in calls to functions other than vkDestroySwapchainKHR and vkCreateSwapchainKHR with `swapchain` used as an `oldSwapchain`. Access to the swapchain timing information must be atomic within the implementation.

Valid Usage

- VUID-vkGetPastPresentationTimingEXT-flags-12230
  If VK_PAST_PRESENTATION_TIMING_ALLOW_OUT_OF_ORDER_RESULTS_BIT_EXT is set in `VkPastPresentationTimingInfoEXT`::`flags`, the `presentStageCount` value of each element of `VkPastPresentationTimingPropertiesEXT`::`pPresentationTimings` must be at least the maximum number of present stages set in VkPresentTimingInfoEXT::`presentStageQueries` among all vkQueuePresentKHR calls, with a non-zero `presentStageQueries`, for which complete results have not been returned yet by a previous call

- VUID-vkGetPastPresentationTimingEXT-flags-12231
  If VK_PAST_PRESENTATION_TIMING_ALLOW_OUT_OF_ORDER_RESULTS_BIT_EXT is not set in `VkPastPresentationTimingInfoEXT`::`flags`, the `presentStageCount` value of each element of `VkPastPresentationTimingPropertiesEXT`::`pPresentationTimings` must be at least the number of present stages set in `VkPresentTimingInfoEXT`::`presentStageQueries` for the earliest call to `vkQueuePresentKHR`, with a non-zero `presentStageQueries`, that corresponds to that element’s index and for which complete results have not been returned yet by a previous call

Valid Usage (Implicit)

- VUID-vkGetPastPresentationTimingEXT-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkGetPastPresentationTimingEXT-pPastPresentationTimingInfo-parameter
  `pPastPresentationTimingInfo` must be a valid pointer to a valid VkPastPresentationTimingInfoEXT structure

- VUID-vkGetPastPresentationTimingEXT-pPastPresentationTimingProperties-parameter
  `pPastPresentationTimingProperties` must be a valid pointer to a VkPastPresentationTimingPropertiesEXT structure

Return Codes

On success, this command returns

  - VK_INCOMPLETE

  - VK_SUCCESS

On failure, this command returns

  - VK_ERROR_DEVICE_LOST

  - VK_ERROR_OUT_OF_DATE_KHR

  - VK_ERROR_SURFACE_LOST_KHR

  - VK_ERROR_UNKNOWN

  - VK_ERROR_VALIDATION_FAILED

## See Also

VK_EXT_present_timing, VkDevice, VkPastPresentationTimingInfoEXT, VkPastPresentationTimingPropertiesEXT

## 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

Copyright 2014-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0