Vulkan.Extensions.VK_GOOGLE_display_timing

Name

VK_GOOGLE_display_timing - device extension

VK_GOOGLE_display_timing

Name String

VK_GOOGLE_display_timing

Extension Type

Device extension

Registered Extension Number

93

Revision

1

Extension and Version Dependencies

• Requires support for Vulkan 1.0
• Requires VK_KHR_swapchain to be enabled for any device-level functionality

Contact

• Ian Elliott @ianelliottus%0A*Here describe the issue or question you have about the VK_GOOGLE_display_timing extension*

Other Extension Metadata

Last Modified Date

2017-02-14

IP Status

No known IP claims.

Contributors

• Ian Elliott, Google
• Jesse Hall, Google

Description

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.

New Commands

• getPastPresentationTimingGOOGLE

• getRefreshCycleDurationGOOGLE

New Structures

• PastPresentationTimingGOOGLE

• PresentTimeGOOGLE
• RefreshCycleDurationGOOGLE

• Extending PresentInfoKHR:

  • PresentTimesInfoGOOGLE

New Enum Constants

• GOOGLE_DISPLAY_TIMING_EXTENSION_NAME

• GOOGLE_DISPLAY_TIMING_SPEC_VERSION

• Extending StructureType:

  • STRUCTURE_TYPE_PRESENT_TIMES_INFO_GOOGLE

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 ).

Version History

• Revision 1, 2017-02-14 (Ian Elliott)

  • Internal revisions

See Also

PastPresentationTimingGOOGLE, PresentTimeGOOGLE, PresentTimesInfoGOOGLE, RefreshCycleDurationGOOGLE, getPastPresentationTimingGOOGLE, getRefreshCycleDurationGOOGLE

Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Documentation

getRefreshCycleDurationGOOGLE

Arguments

:: forall io. MonadIO io

=> Device

device is the device associated with swapchain.

-> SwapchainKHR

swapchain is the swapchain to obtain the refresh duration for.

-> io ("displayTimingProperties" ::: RefreshCycleDurationGOOGLE)

vkGetRefreshCycleDurationGOOGLE - Obtain the RC duration of the PE’s display

Valid Usage (Implicit)

• device must be a valid Device handle

• swapchain must be a valid SwapchainKHR handle
• pDisplayTimingProperties must be a valid pointer to a RefreshCycleDurationGOOGLE structure
• swapchain must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to swapchain must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_DEVICE_LOST
• ERROR_SURFACE_LOST_KHR

See Also

VK_GOOGLE_display_timing, Device, RefreshCycleDurationGOOGLE, SwapchainKHR

getPastPresentationTimingGOOGLE

Arguments

:: forall io. MonadIO io

=> Device

device is the device associated with swapchain.

-> SwapchainKHR

swapchain is the swapchain to obtain presentation timing information duration for.

-> io (Result, "presentationTimings" ::: Vector PastPresentationTimingGOOGLE)

vkGetPastPresentationTimingGOOGLE - Obtain timing of a previously-presented image

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 Device handle

• swapchain must be a valid SwapchainKHR 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 PastPresentationTimingGOOGLE structures
• swapchain must have been created, allocated, or retrieved from device

Host Synchronization

• Host access to swapchain must be externally synchronized

Return Codes

Success

• SUCCESS
• INCOMPLETE

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_DEVICE_LOST
• ERROR_OUT_OF_DATE_KHR
• ERROR_SURFACE_LOST_KHR

See Also

VK_GOOGLE_display_timing, Device, PastPresentationTimingGOOGLE, SwapchainKHR

data RefreshCycleDurationGOOGLE

VkRefreshCycleDurationGOOGLE - Structure containing the RC duration of a display

See Also

VK_GOOGLE_display_timing, getRefreshCycleDurationGOOGLE

Constructors

RefreshCycleDurationGOOGLE

Fields

• refreshDuration :: Word64

  refreshDuration is the number of nanoseconds from the start of one refresh cycle to the next.

Instances

Storable RefreshCycleDurationGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

sizeOf :: RefreshCycleDurationGOOGLE -> Int

alignment :: RefreshCycleDurationGOOGLE -> Int

peekElemOff :: Ptr RefreshCycleDurationGOOGLE -> Int -> IO RefreshCycleDurationGOOGLE

pokeElemOff :: Ptr RefreshCycleDurationGOOGLE -> Int -> RefreshCycleDurationGOOGLE -> IO ()

peekByteOff :: Ptr b -> Int -> IO RefreshCycleDurationGOOGLE

pokeByteOff :: Ptr b -> Int -> RefreshCycleDurationGOOGLE -> IO ()

peek :: Ptr RefreshCycleDurationGOOGLE -> IO RefreshCycleDurationGOOGLE

poke :: Ptr RefreshCycleDurationGOOGLE -> RefreshCycleDurationGOOGLE -> IO ()

Show RefreshCycleDurationGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

showsPrec :: Int -> RefreshCycleDurationGOOGLE -> ShowS

show :: RefreshCycleDurationGOOGLE -> String

showList :: [RefreshCycleDurationGOOGLE] -> ShowS

Eq RefreshCycleDurationGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

(==) :: RefreshCycleDurationGOOGLE -> RefreshCycleDurationGOOGLE -> Bool

(/=) :: RefreshCycleDurationGOOGLE -> RefreshCycleDurationGOOGLE -> Bool

FromCStruct RefreshCycleDurationGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

peekCStruct :: Ptr RefreshCycleDurationGOOGLE -> IO RefreshCycleDurationGOOGLE

ToCStruct RefreshCycleDurationGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

withCStruct :: RefreshCycleDurationGOOGLE -> (Ptr RefreshCycleDurationGOOGLE -> IO b) -> IO b

pokeCStruct :: Ptr RefreshCycleDurationGOOGLE -> RefreshCycleDurationGOOGLE -> IO b -> IO b

withZeroCStruct :: (Ptr RefreshCycleDurationGOOGLE -> IO b) -> IO b

pokeZeroCStruct :: Ptr RefreshCycleDurationGOOGLE -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero RefreshCycleDurationGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

zero :: RefreshCycleDurationGOOGLE

data PastPresentationTimingGOOGLE

VkPastPresentationTimingGOOGLE - Structure containing timing information about a previously-presented image

Description

The results for a given swapchain and presentID are only returned once from getPastPresentationTimingGOOGLE.

The application can use the PastPresentationTimingGOOGLE values to occasionally adjust its timing. For example, if actualPresentTime is later than expected (e.g. one refreshDuration late), the application may increase its target IPD to a higher multiple of refreshDuration (e.g. decrease its frame rate from 60Hz to 30Hz). If actualPresentTime and earliestPresentTime are consistently different, and if presentMargin is consistently large enough, the application may decrease its target IPD to a smaller multiple of refreshDuration (e.g. increase its frame rate from 30Hz to 60Hz). If actualPresentTime and earliestPresentTime are same, and if presentMargin is consistently high, the application may delay the start of its input-render-present loop in order to decrease the latency between user input and the corresponding present (always leaving some margin in case a new image takes longer to render than the previous image). An application that desires its target IPD to always be the same as refreshDuration, can also adjust features until actualPresentTime is never late and presentMargin is satisfactory.

See Also

VK_GOOGLE_display_timing, getPastPresentationTimingGOOGLE

Constructors

PastPresentationTimingGOOGLE

Fields

• presentID :: Word32

  presentID is an application-provided value that was given to a previous queuePresentKHR command via PresentTimeGOOGLE::presentID (see below). It can be used to uniquely identify a previous present with the queuePresentKHR command.

• desiredPresentTime :: Word64

  desiredPresentTime is an application-provided value that was given to a previous queuePresentKHR command via PresentTimeGOOGLE::desiredPresentTime. If non-zero, it was used by the application to indicate that an image not be presented any sooner than desiredPresentTime.

• actualPresentTime :: Word64

  actualPresentTime is the time when the image of the swapchain was actually displayed.

• earliestPresentTime :: Word64

  earliestPresentTime is the time when the image of the swapchain could have been displayed. This may differ from actualPresentTime if the application requested that the image be presented no sooner than PresentTimeGOOGLE::desiredPresentTime.

• presentMargin :: Word64

  presentMargin is an indication of how early the queuePresentKHR command was processed compared to how soon it needed to be processed, and still be presented at earliestPresentTime.

Instances

Storable PastPresentationTimingGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

sizeOf :: PastPresentationTimingGOOGLE -> Int

alignment :: PastPresentationTimingGOOGLE -> Int

peekElemOff :: Ptr PastPresentationTimingGOOGLE -> Int -> IO PastPresentationTimingGOOGLE

pokeElemOff :: Ptr PastPresentationTimingGOOGLE -> Int -> PastPresentationTimingGOOGLE -> IO ()

peekByteOff :: Ptr b -> Int -> IO PastPresentationTimingGOOGLE

pokeByteOff :: Ptr b -> Int -> PastPresentationTimingGOOGLE -> IO ()

peek :: Ptr PastPresentationTimingGOOGLE -> IO PastPresentationTimingGOOGLE

poke :: Ptr PastPresentationTimingGOOGLE -> PastPresentationTimingGOOGLE -> IO ()

Show PastPresentationTimingGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

showsPrec :: Int -> PastPresentationTimingGOOGLE -> ShowS

show :: PastPresentationTimingGOOGLE -> String

showList :: [PastPresentationTimingGOOGLE] -> ShowS

Eq PastPresentationTimingGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

(==) :: PastPresentationTimingGOOGLE -> PastPresentationTimingGOOGLE -> Bool

(/=) :: PastPresentationTimingGOOGLE -> PastPresentationTimingGOOGLE -> Bool

FromCStruct PastPresentationTimingGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

peekCStruct :: Ptr PastPresentationTimingGOOGLE -> IO PastPresentationTimingGOOGLE

ToCStruct PastPresentationTimingGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

withCStruct :: PastPresentationTimingGOOGLE -> (Ptr PastPresentationTimingGOOGLE -> IO b) -> IO b

pokeCStruct :: Ptr PastPresentationTimingGOOGLE -> PastPresentationTimingGOOGLE -> IO b -> IO b

withZeroCStruct :: (Ptr PastPresentationTimingGOOGLE -> IO b) -> IO b

pokeZeroCStruct :: Ptr PastPresentationTimingGOOGLE -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero PastPresentationTimingGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

zero :: PastPresentationTimingGOOGLE

data PresentTimesInfoGOOGLE

VkPresentTimesInfoGOOGLE - The earliest time each image should be presented

Valid Usage

• swapchainCount must be the same value as PresentInfoKHR::swapchainCount, where PresentInfoKHR is included in the pNext chain of this PresentTimesInfoGOOGLE structure

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PRESENT_TIMES_INFO_GOOGLE

• If pTimes is not NULL, pTimes must be a valid pointer to an array of swapchainCount PresentTimeGOOGLE structures
• swapchainCount must be greater than 0

See Also

VK_GOOGLE_display_timing, PresentTimeGOOGLE, StructureType

Constructors

PresentTimesInfoGOOGLE

Fields

• swapchainCount :: Word32

  swapchainCount is the number of swapchains being presented to by this command.

• times :: Vector PresentTimeGOOGLE

  pTimes is NULL or a pointer to an array of PresentTimeGOOGLE elements with swapchainCount entries. If not NULL, each element of pTimes contains the earliest time to present the image corresponding to the entry in the PresentInfoKHR::pImageIndices array.

Instances

Show PresentTimesInfoGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

showsPrec :: Int -> PresentTimesInfoGOOGLE -> ShowS

show :: PresentTimesInfoGOOGLE -> String

showList :: [PresentTimesInfoGOOGLE] -> ShowS

FromCStruct PresentTimesInfoGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

peekCStruct :: Ptr PresentTimesInfoGOOGLE -> IO PresentTimesInfoGOOGLE

ToCStruct PresentTimesInfoGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

withCStruct :: PresentTimesInfoGOOGLE -> (Ptr PresentTimesInfoGOOGLE -> IO b) -> IO b

pokeCStruct :: Ptr PresentTimesInfoGOOGLE -> PresentTimesInfoGOOGLE -> IO b -> IO b

withZeroCStruct :: (Ptr PresentTimesInfoGOOGLE -> IO b) -> IO b

pokeZeroCStruct :: Ptr PresentTimesInfoGOOGLE -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero PresentTimesInfoGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

zero :: PresentTimesInfoGOOGLE

data PresentTimeGOOGLE

VkPresentTimeGOOGLE - The earliest time image should be presented

Description

but does not need a specific pname:desiredPresentTime.

See Also

VK_GOOGLE_display_timing, PresentTimesInfoGOOGLE

Constructors

PresentTimeGOOGLE

Fields

• presentID :: Word32

  presentID is an application-provided identification value, that can be used with the results of getPastPresentationTimingGOOGLE, 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.

• desiredPresentTime :: Word64

  desiredPresentTime specifies that the image given should not be displayed to the user any earlier than this time. 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 presentID,

Instances

Storable PresentTimeGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

sizeOf :: PresentTimeGOOGLE -> Int

alignment :: PresentTimeGOOGLE -> Int

peekElemOff :: Ptr PresentTimeGOOGLE -> Int -> IO PresentTimeGOOGLE

pokeElemOff :: Ptr PresentTimeGOOGLE -> Int -> PresentTimeGOOGLE -> IO ()

peekByteOff :: Ptr b -> Int -> IO PresentTimeGOOGLE

pokeByteOff :: Ptr b -> Int -> PresentTimeGOOGLE -> IO ()

peek :: Ptr PresentTimeGOOGLE -> IO PresentTimeGOOGLE

poke :: Ptr PresentTimeGOOGLE -> PresentTimeGOOGLE -> IO ()

Show PresentTimeGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

showsPrec :: Int -> PresentTimeGOOGLE -> ShowS

show :: PresentTimeGOOGLE -> String

showList :: [PresentTimeGOOGLE] -> ShowS

Eq PresentTimeGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

(==) :: PresentTimeGOOGLE -> PresentTimeGOOGLE -> Bool

(/=) :: PresentTimeGOOGLE -> PresentTimeGOOGLE -> Bool

FromCStruct PresentTimeGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

peekCStruct :: Ptr PresentTimeGOOGLE -> IO PresentTimeGOOGLE

ToCStruct PresentTimeGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

withCStruct :: PresentTimeGOOGLE -> (Ptr PresentTimeGOOGLE -> IO b) -> IO b

pokeCStruct :: Ptr PresentTimeGOOGLE -> PresentTimeGOOGLE -> IO b -> IO b

withZeroCStruct :: (Ptr PresentTimeGOOGLE -> IO b) -> IO b

pokeZeroCStruct :: Ptr PresentTimeGOOGLE -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero PresentTimeGOOGLE

Defined in Vulkan.Extensions.VK_GOOGLE_display_timing

Methods

zero :: PresentTimeGOOGLE

type GOOGLE_DISPLAY_TIMING_SPEC_VERSION = 1

pattern GOOGLE_DISPLAY_TIMING_SPEC_VERSION :: forall a. Integral a => a

type GOOGLE_DISPLAY_TIMING_EXTENSION_NAME = "VK_GOOGLE_display_timing"

pattern GOOGLE_DISPLAY_TIMING_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a

newtype SwapchainKHR

VkSwapchainKHR - Opaque handle to a swapchain object

Description

A swapchain is an abstraction for an array of presentable images that are associated with a surface. The presentable images are represented by Image objects created by the platform. One image (which can be an array image for multiview/stereoscopic-3D surfaces) is displayed at a time, but multiple images can be queued for presentation. An application renders to the image, and then queues the image for presentation to the surface.

A native window cannot be associated with more than one non-retired swapchain at a time. Further, swapchains cannot be created for native windows that have a non-Vulkan graphics API surface associated with them.

Note

The presentation engine is an abstraction for the platform’s compositor or display engine.

The presentation engine may be synchronous or asynchronous with respect to the application and/or logical device.

Some implementations may use the device’s graphics queue or dedicated presentation hardware to perform presentation.

The presentable images of a swapchain are owned by the presentation engine. An application can acquire use of a presentable image from the presentation engine. Use of a presentable image must occur only after the image is returned by acquireNextImageKHR, and before it is released by queuePresentKHR. This includes transitioning the image layout and rendering commands.

An application can acquire use of a presentable image with acquireNextImageKHR. After acquiring a presentable image and before modifying it, the application must use a synchronization primitive to ensure that the presentation engine has finished reading from the image. The application can then transition the image’s layout, queue rendering commands to it, etc. Finally, the application presents the image with queuePresentKHR, which releases the acquisition of the image. The application can also release the acquisition of the image through releaseSwapchainImagesEXT, if the image is not in use by the device, and skip the present operation.

The presentation engine controls the order in which presentable images are acquired for use by the application.

Note

This allows the platform to handle situations which require out-of-order return of images after presentation. At the same time, it allows the application to generate command buffers referencing all of the images in the swapchain at initialization time, rather than in its main loop.

See Also

VK_KHR_swapchain, AcquireNextImageInfoKHR, BindImageMemorySwapchainInfoKHR, ImageSwapchainCreateInfoKHR, PresentInfoKHR, ReleaseSwapchainImagesInfoEXT, SwapchainCreateInfoKHR, acquireFullScreenExclusiveModeEXT, acquireNextImageKHR, createSharedSwapchainsKHR, createSwapchainKHR, destroySwapchainKHR, getPastPresentationTimingGOOGLE, getRefreshCycleDurationGOOGLE, getSwapchainCounterEXT, getSwapchainImagesKHR, getSwapchainStatusKHR, queuePresentKHR, releaseFullScreenExclusiveModeEXT, setHdrMetadataEXT, setLocalDimmingAMD, waitForPresentKHR

Constructors

SwapchainKHR Word64

Instances

Storable SwapchainKHR

Defined in Vulkan.Extensions.Handles

Methods

sizeOf :: SwapchainKHR -> Int

alignment :: SwapchainKHR -> Int

peekElemOff :: Ptr SwapchainKHR -> Int -> IO SwapchainKHR

pokeElemOff :: Ptr SwapchainKHR -> Int -> SwapchainKHR -> IO ()

peekByteOff :: Ptr b -> Int -> IO SwapchainKHR

pokeByteOff :: Ptr b -> Int -> SwapchainKHR -> IO ()

peek :: Ptr SwapchainKHR -> IO SwapchainKHR

poke :: Ptr SwapchainKHR -> SwapchainKHR -> IO ()

Show SwapchainKHR

Defined in Vulkan.Extensions.Handles

Methods

showsPrec :: Int -> SwapchainKHR -> ShowS

show :: SwapchainKHR -> String

showList :: [SwapchainKHR] -> ShowS

Eq SwapchainKHR

Defined in Vulkan.Extensions.Handles

Methods

(==) :: SwapchainKHR -> SwapchainKHR -> Bool

(/=) :: SwapchainKHR -> SwapchainKHR -> Bool

Ord SwapchainKHR

Defined in Vulkan.Extensions.Handles

Methods

compare :: SwapchainKHR -> SwapchainKHR -> Ordering

(<) :: SwapchainKHR -> SwapchainKHR -> Bool

(<=) :: SwapchainKHR -> SwapchainKHR -> Bool

(>) :: SwapchainKHR -> SwapchainKHR -> Bool

(>=) :: SwapchainKHR -> SwapchainKHR -> Bool

max :: SwapchainKHR -> SwapchainKHR -> SwapchainKHR

min :: SwapchainKHR -> SwapchainKHR -> SwapchainKHR

HasObjectType SwapchainKHR

Defined in Vulkan.Extensions.Handles

Methods

objectTypeAndHandle :: SwapchainKHR -> (ObjectType, Word64)

IsHandle SwapchainKHR

Defined in Vulkan.Extensions.Handles

Zero SwapchainKHR

Defined in Vulkan.Extensions.Handles

Methods

zero :: SwapchainKHR