Package org.lwjgl.vulkan

Class GOOGLEDisplayTiming

  • public class GOOGLEDisplayTiming
extends java.lang.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/master/cube/cube.c ).

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

    • Field Detail

      • VK_GOOGLE_DISPLAY_TIMING_SPEC_VERSION

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

      • VK_GOOGLE_DISPLAY_TIMING_EXTENSION_NAME

        public static final java.lang.String VK_GOOGLE_DISPLAY_TIMING_EXTENSION_NAME
        The extension name.
        See Also:
        Constant Field Values

      • VK_STRUCTURE_TYPE_PRESENT_TIMES_INFO_GOOGLE

        public static final int VK_STRUCTURE_TYPE_PRESENT_TIMES_INFO_GOOGLE
        Extends VkStructureType.
        See Also:
        Constant Field Values

    • Method Detail

      • nvkGetRefreshCycleDurationGOOGLE

        public static int nvkGetRefreshCycleDurationGOOGLE​(VkDevice device,
                                                   long swapchain,
                                                   long pDisplayTimingProperties)
        Unsafe version of: GetRefreshCycleDurationGOOGLE

      • vkGetRefreshCycleDurationGOOGLE

        public static int vkGetRefreshCycleDurationGOOGLE​(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
        • 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
        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 an instance of the VkRefreshCycleDurationGOOGLE structure.

      • nvkGetPastPresentationTimingGOOGLE

        public static int nvkGetPastPresentationTimingGOOGLE​(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​(VkDevice device,
                                                    long swapchain,
                                                    java.nio.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. If pPresentationTimingCount is smaller than the number of newly-available timing records for the given swapchain, INCOMPLETE will be returned instead of 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
        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.