org.lwjgl.vulkan

Class GOOGLEDisplayTiming

java.lang.Object

org.lwjgl.vulkan.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

• Requires Vulkan 1.0
• Requires VK_KHR_swapchain

Contact

• Ian Elliott ianelliottus

Last Modified Date

2017-02-14

IP Status

No known IP claims.

Contributors

• Ian Elliott, Google
• Jesse Hall, Google

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	VK_GOOGLE_DISPLAY_TIMING_EXTENSION_NAME The extension name.
static int	VK_GOOGLE_DISPLAY_TIMING_SPEC_VERSION The extension specification version.
static int	VK_STRUCTURE_TYPE_PRESENT_TIMES_INFO_GOOGLE Extends VkStructureType.

Method Summary

Modifier and Type	Method and Description
static int	nvkGetPastPresentationTimingGOOGLE(org.lwjgl.vulkan.VkDevice device, long swapchain, long pPresentationTimingCount, long pPresentationTimings) Unsafe version of: GetPastPresentationTimingGOOGLE
static int	nvkGetRefreshCycleDurationGOOGLE(org.lwjgl.vulkan.VkDevice device, long swapchain, long pDisplayTimingProperties) Unsafe version of: GetRefreshCycleDurationGOOGLE
static int	vkGetPastPresentationTimingGOOGLE(org.lwjgl.vulkan.VkDevice device, long swapchain, int[] pPresentationTimingCount, VkPastPresentationTimingGOOGLE.Buffer pPresentationTimings) Array version of: GetPastPresentationTimingGOOGLE
static int	vkGetPastPresentationTimingGOOGLE(org.lwjgl.vulkan.VkDevice device, long swapchain, java.nio.IntBuffer pPresentationTimingCount, VkPastPresentationTimingGOOGLE.Buffer pPresentationTimings) Obtain timing of a previously-presented image.
static int	vkGetRefreshCycleDurationGOOGLE(org.lwjgl.vulkan.VkDevice device, long swapchain, VkRefreshCycleDurationGOOGLE pDisplayTimingProperties) Obtain the RC duration of the PE's display.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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(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
• 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

• SUCCESS

On failure, this command returns

• ERROR_DEVICE_LOST
• ERROR_SURFACE_LOST_KHR

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

• SUCCESS
• INCOMPLETE

On failure, this command returns

• ERROR_DEVICE_LOST
• ERROR_OUT_OF_DATE_KHR
• ERROR_SURFACE_LOST_KHR

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