C Specification

The VkPresentTimingInfoEXT structure is defined as:

// Provided by VK_EXT_present_timing
typedef struct VkPresentTimingInfoEXT {
    VkStructureType                sType;
    const void*                    pNext;
    VkPresentTimingInfoFlagsEXT    flags;
    uint64_t                       targetTime;
    uint64_t                       timeDomainId;
    VkPresentStageFlagsEXT         presentStageQueries;
    VkPresentStageFlagsEXT         targetTimeDomainPresentStage;
} VkPresentTimingInfoEXT;

Members

  • sType is a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • flags is a bitmask of VkPresentTimingInfoFlagBitsEXT specifying options for how to interpret the timing information.

  • targetTime is zero or a value specifying the target present time or duration, in nanoseconds, of the presentation request.

  • timeDomainId is the id of the time domain used to specify the absolute target present time and the timing results obtained in a subsequent vkGetPastPresentationTimingEXT call for the current presentation request.

  • presentStageQueries is a valid VkPresentStageFlagsEXT value indicating which present stages the presentation engine will collect timing information for.

  • targetTimeDomainPresentStage is a valid VkPresentStageFlagsEXT specifying a single present stage used to interpret targetTime.

Description

If targetTime is not zero, the implementation attempts to align the VK_PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT present stage of that presentation request with the time specified in targetTime according to the time domain used. If VK_PRESENT_TIMING_INFO_PRESENT_AT_NEAREST_REFRESH_CYCLE_BIT_EXT is not set in flags, it indicates that the application would strictly prefer the image to not be visible before targetTime has lapsed.

If targetTime is not zero and timeDomainId is associated with a VK_TIME_DOMAIN_PRESENT_STAGE_LOCAL_EXT time domain, targetTimeDomainPresentStage is used to specify which present stage’s time domain targetTime is specified for. Otherwise, targetTimeDomainPresentStage is ignored.

Note

Some platforms, due to hardware or system limitations, may not be able to accurately time targetTime with the actual physical event of the image becoming visible on the display. However, those timing capabilities may still be useful and result in improved animation quality.

As such, the presentAtAbsoluteTime and presentAtRelativeTime features do not provide a strict guarantee regarding the completion of the VK_PRESENT_STAGE_IMAGE_FIRST_PIXEL_VISIBLE_BIT_EXT present stage relative to the targetTime, and implementations must strive to make it as consistent and accurate as possible.
Note

Applications that specify an absolute present time should regularly rebase their calculations for their next target time on the feedback from vkGetPastPresentationTimingEXT to compensate for accumulated precision errors or potential clock drift. It is recommended that when targeting the time of a vertical blanking period, applications set VK_PRESENT_TIMING_INFO_PRESENT_AT_NEAREST_REFRESH_CYCLE_BIT_EXT to allow the implementation to compensate for small precision errors that may cause an image to be displayed one refresh cycle later than intended.
Valid Usage

  • VUID-VkPresentTimingInfoEXT-targetTime-12236
    If targetTime is not zero and flags does not contain VK_PRESENT_TIMING_INFO_PRESENT_AT_RELATIVE_TIME_BIT_EXT, the presentAtAbsoluteTime feature must be enabled

  • VUID-VkPresentTimingInfoEXT-targetTime-12237
    If targetTime is not zero and flags contains VK_PRESENT_TIMING_INFO_PRESENT_AT_RELATIVE_TIME_BIT_EXT, the presentAtRelativeTime feature must be enabled

  • VUID-VkPresentTimingInfoEXT-timeDomainId-12238
    If timeDomainId is associated with a VK_TIME_DOMAIN_PRESENT_STAGE_LOCAL_EXT time domain, and targetTime is not zero, targetTimeDomainPresentStage must be a single VkPresentStageFlagsEXT value

Valid Usage (Implicit)

  • VUID-VkPresentTimingInfoEXT-sType-sType
    sType must be VK_STRUCTURE_TYPE_PRESENT_TIMING_INFO_EXT

  • VUID-VkPresentTimingInfoEXT-pNext-pNext
    pNext must be NULL

  • VUID-VkPresentTimingInfoEXT-flags-parameter
    flags must be a valid combination of VkPresentTimingInfoFlagBitsEXT values

  • VUID-VkPresentTimingInfoEXT-presentStageQueries-parameter
    presentStageQueries must be a valid combination of VkPresentStageFlagBitsEXT values

  • VUID-VkPresentTimingInfoEXT-targetTimeDomainPresentStage-parameter
    targetTimeDomainPresentStage must be a valid combination of VkPresentStageFlagBitsEXT values

See Also

VK_EXT_present_timing, VkPresentStageFlagsEXT, VkPresentTimingInfoFlagsEXT, VkPresentTimingsInfoEXT, VkStructureType

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-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0