registry/vulkan/chapters/VK_GOOGLE_display_timing/PresentTimeInfo.txt

// Copyright (c) 2018-2020 Google LLC
//
// SPDX-License-Identifier: CC-BY-4.0


[open,refpage='VkPresentTimesInfoGOOGLE',desc='The earliest time each image should be presented',type='structs']
--
When the `apiext:VK_GOOGLE_display_timing` extension is enabled, additional
fields can: be specified that allow an application to specify the earliest
time that an image should be displayed.
This allows an application to avoid stutter that is caused by an image being
displayed earlier than planned.
Such stuttering can occur with both fixed and variable-refresh-rate
displays, because stuttering occurs when the geometry is not correctly
positioned for when the image is displayed.
An application can: instruct the presentation engine that an image should
not be displayed earlier than a specified time by adding a
sname:VkPresentTimesInfoGOOGLE structure to the pname:pNext chain of the
sname:VkPresentInfoKHR structure.

The sname:VkPresentTimesInfoGOOGLE structure is defined as:

include::{generated}/api/structs/VkPresentTimesInfoGOOGLE.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:swapchainCount is the number of swapchains being presented to by
    this command.
  * pname:pTimes is `NULL` or a pointer to an array of
    sname:VkPresentTimeGOOGLE elements with pname:swapchainCount entries.
    If not `NULL`, each element of pname:pTimes contains the earliest time
    to present the image corresponding to the entry in the
    sname:VkPresentInfoKHR::pname:pImageIndices array.

.Valid Usage
****
  * [[VUID-VkPresentTimesInfoGOOGLE-swapchainCount-01247]]
    pname:swapchainCount must: be the same value as
    sname:VkPresentInfoKHR::pname:swapchainCount, where
    sname:VkPresentInfoKHR is included in the pname:pNext chain of this
    sname:VkPresentTimesInfoGOOGLE structure
****

include::{generated}/validity/structs/VkPresentTimesInfoGOOGLE.txt[]
--

[open,refpage='VkPresentTimeGOOGLE',desc='The earliest time image should be presented',type='structs']
--
The sname:VkPresentTimeGOOGLE structure is defined as:

include::{generated}/api/structs/VkPresentTimeGOOGLE.txt[]

  * pname:presentID is an application-provided identification value, that
    can: be used with the results of
    flink:vkGetPastPresentationTimingGOOGLE, in order to uniquely identify
    this present.
    In order to be useful to the application, it should: be unique within
    some period of time that is meaningful to the application.
  * pname:desiredPresentTime specifies that the image given should: not be
    displayed to the user any earlier than this time.
    pname:desiredPresentTime is a time in nanoseconds, relative to a
    monotonically-increasing clock (e.g. `CLOCK_MONOTONIC` (see
    clock_gettime(2)) on Android and Linux).
    A value of zero specifies that the presentation engine may: display the
    image at any time.
    This is useful when the application desires to provide pname:presentID,
    but does not need a specific pname:desiredPresentTime.
--