Package org.lwjgl.vulkan

Class GOOGLEDisplayTiming

java.lang.Object
org.lwjgl.vulkan.GOOGLEDisplayTiming
public class GOOGLEDisplayTiming extends Object
This device extension allows an application that uses the VK_KHR_swapchain extension to obtain information about the presentation engine’s display, to obtain timing information about each present, and to schedule a present to happen no earlier than a desired time. An application can use this to minimize various visual anomalies (e.g. stuttering).

Traditional game and real-time animation applications need to correctly position their geometry for when the presentable image will be presented to the user. To accomplish this, applications need various timing information about the presentation engine’s display. They need to know when presentable images were actually presented, and when they could have been presented. Applications also need to tell the presentation engine to display an image no sooner than a given time. This allows the application to avoid stuttering, so the animation looks smooth to the user.

This extension treats variable-refresh-rate (VRR) displays as if they are fixed-refresh-rate (FRR) displays.

Examples
Note

The example code for the this extension (like the VK_KHR_surface and VK_GOOGLE_display_timing extensions) is contained in the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: https://github.com/KhronosGroup/Vulkan-Tools/blob/main/cube/cube.c ).

Name String
VK_GOOGLE_display_timing
Extension Type
Device extension
Registered Extension Number
93
Revision
1
Extension and Version Dependencies
VK_KHR_swapchain
Contact
Other Extension Metadata
Last Modified Date
2017-02-14
IP Status
No known IP claims.
Contributors
  • Ian Elliott, Google
  • Jesse Hall, Google

  • Field Details

    • VK_GOOGLE_DISPLAY_TIMING_SPEC_VERSION

      public static final int VK_GOOGLE_DISPLAY_TIMING_SPEC_VERSION
      The extension specification version.
      See Also:

    • VK_GOOGLE_DISPLAY_TIMING_EXTENSION_NAME

      public static final String VK_GOOGLE_DISPLAY_TIMING_EXTENSION_NAME
      The extension name.
      See Also:

    • VK_STRUCTURE_TYPE_PRESENT_TIMES_INFO_GOOGLE

      public static final int VK_STRUCTURE_TYPE_PRESENT_TIMES_INFO_GOOGLE
      Extends VkStructureType.
      See Also:

  • Method Details

    • nvkGetRefreshCycleDurationGOOGLE

      public static int nvkGetRefreshCycleDurationGOOGLE(org.lwjgl.vulkan.VkDevice device, long swapchain, long pDisplayTimingProperties)
      Unsafe version of: GetRefreshCycleDurationGOOGLE

    • vkGetRefreshCycleDurationGOOGLE

      public static int vkGetRefreshCycleDurationGOOGLE(org.lwjgl.vulkan.VkDevice device, long swapchain, VkRefreshCycleDurationGOOGLE pDisplayTimingProperties)
      Obtain the RC duration of the PE’s display.
      C Specification

      To query the duration of a refresh cycle (RC) for the presentation engine’s display, call:

      
 VkResult vkGetRefreshCycleDurationGOOGLE(
     VkDevice                                    device,
     VkSwapchainKHR                              swapchain,
     VkRefreshCycleDurationGOOGLE*               pDisplayTimingProperties);
      Valid Usage (Implicit)
      • device must be a valid VkDevice handle
      • swapchain must be a valid VkSwapchainKHR handle
      • pDisplayTimingProperties must be a valid pointer to a VkRefreshCycleDurationGOOGLE structure
      • swapchain must have been created, allocated, or retrieved from device
      Host Synchronization
      • Host access to swapchain must be externally synchronized
      Return Codes
      On success, this command returns
      On failure, this command returns
      See Also

      VkRefreshCycleDurationGOOGLE

      Parameters:
      device - the device associated with swapchain.
      swapchain - the swapchain to obtain the refresh duration for.
      pDisplayTimingProperties - a pointer to a VkRefreshCycleDurationGOOGLE structure.

    • nvkGetPastPresentationTimingGOOGLE

      public static int nvkGetPastPresentationTimingGOOGLE(org.lwjgl.vulkan.VkDevice device, long swapchain, long pPresentationTimingCount, long pPresentationTimings)
      Unsafe version of: GetPastPresentationTimingGOOGLE
      Parameters:
      pPresentationTimingCount - a pointer to an integer related to the number of VkPastPresentationTimingGOOGLE structures to query, as described below.

    • vkGetPastPresentationTimingGOOGLE

      public static int vkGetPastPresentationTimingGOOGLE(org.lwjgl.vulkan.VkDevice device, long swapchain, IntBuffer pPresentationTimingCount, @Nullable VkPastPresentationTimingGOOGLE.Buffer pPresentationTimings)
      Obtain timing of a previously-presented image.
      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 QueuePresentKHR 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);
      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, and INCOMPLETE will be returned instead of SUCCESS, to indicate that not all the available timing records 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
      • swapchain must have been created, allocated, or retrieved from device
      Host Synchronization
      • Host access to swapchain must be externally synchronized
      Return Codes
      On success, this command returns
      On failure, this command returns
      See Also

      VkPastPresentationTimingGOOGLE

      Parameters:
      device - the device associated with swapchain.
      swapchain - the swapchain to obtain presentation timing information duration for.
      pPresentationTimingCount - a pointer to an integer related to the number of VkPastPresentationTimingGOOGLE structures to query, as described below.
      pPresentationTimings - either NULL or a pointer to an array of VkPastPresentationTimingGOOGLE structures.

    • vkGetPastPresentationTimingGOOGLE

      public static int vkGetPastPresentationTimingGOOGLE(org.lwjgl.vulkan.VkDevice device, long swapchain, int[] pPresentationTimingCount, @Nullable VkPastPresentationTimingGOOGLE.Buffer pPresentationTimings)
      Array version of: GetPastPresentationTimingGOOGLE