vulkan-3.26.1: Bindings to the Vulkan graphics API.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Vulkan.Extensions.VK_KHR_present_wait

Description

Name

VK_KHR_present_wait - device extension

VK_KHR_present_wait

Name String
VK_KHR_present_wait
Extension Type
Device extension
Registered Extension Number
249
Revision
1
Ratification Status
Ratified
Extension and Version Dependencies
VK_KHR_swapchain and VK_KHR_present_id
Contact

Other Extension Metadata

Last Modified Date
2019-05-15
IP Status
No known IP claims.
Contributors
  • Keith Packard, Valve
  • Ian Elliott, Google
  • Tobias Hector, AMD
  • Daniel Stone, Collabora

Description

This device extension allows an application that uses the VK_KHR_swapchain extension to wait for present operations to complete. An application can use this to monitor and control the pacing of the application by managing the number of outstanding images yet to be presented.

New Commands

New Structures

New Enum Constants

Issues

1) When does the wait finish?

RESOLVED. The wait will finish when the present is visible to the user. There is no requirement for any precise timing relationship between the presentation of the image to the user, but implementations should signal the wait as close as possible to the presentation of the first pixel in the new image to the user.

2) Should this use fences or other existing synchronization mechanism.

RESOLVED. Because display and rendering are often implemented in separate drivers, this extension will provide a separate synchronization API.

3) Should this extension share present identification with other extensions?

RESOLVED. Yes. A new extension, VK_KHR_present_id, should be created to provide a shared structure for presentation identifiers.

4) What happens when presentations complete out of order wrt calls to vkQueuePresent? This could happen if the semaphores for the presentations were ready out of order.

OPTION A: Require that when a PresentId is set that the driver ensure that images are always presented in the order of calls to vkQueuePresent.

OPTION B: Finish both waits when the earliest present completes. This will complete the later present wait earlier than the actual presentation. This should be the easiest to implement as the driver need only track the largest present ID completed. This is also the 'natural' consequence of interpreting the existing vkWaitForPresentKHR specificationn.

OPTION C: Finish both waits when both have completed. This will complete the earlier presentation later than the actual presentation time. This is allowed by the current specification as there is no precise timing requirement for when the presentId value is updated. This requires slightly more complexity in the driver as it will need to track all outstanding presentId values.

Version History

  • Revision 1, 2019-02-19 (Keith Packard)

    • Initial version

See Also

PhysicalDevicePresentWaitFeaturesKHR, waitForPresentKHR

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.

Synopsis

Documentation

waitForPresentKHR Source #

Arguments

:: forall io. MonadIO io 
=> Device

device is the device associated with swapchain.

-> SwapchainKHR

swapchain is the non-retired swapchain on which an image was queued for presentation.

-> ("presentId" ::: Word64)

presentId is the presentation presentId to wait for.

-> ("timeout" ::: Word64)

timeout is the timeout period in units of nanoseconds. timeout is adjusted to the closest value allowed by the implementation-dependent timeout accuracy, which may be substantially longer than one nanosecond, and may be longer than the requested period.

-> io Result 

vkWaitForPresentKHR - Wait for presentation

Description

waitForPresentKHR waits for the presentId associated with swapchain to be increased in value so that it is at least equal to presentId.

For PRESENT_MODE_MAILBOX_KHR (or other present mode where images may be replaced in the presentation queue) any wait of this type associated with such an image must be signaled no later than a wait associated with the replacing image would be signaled.

When the presentation has completed, the presentId associated with the related pSwapchains entry will be increased in value so that it is at least equal to the value provided in the PresentIdKHR structure.

There is no requirement for any precise timing relationship between the presentation of the image to the user and the update of the presentId value, but implementations should make this as close as possible to the presentation of the first pixel in the next image being presented to the user.

The call to waitForPresentKHR will block until either the presentId associated with swapchain is greater than or equal to presentId, or timeout nanoseconds passes. When the swapchain becomes OUT_OF_DATE, the call will either return SUCCESS (if the image was delivered to the presentation engine and may have been presented to the user) or will return early with status ERROR_OUT_OF_DATE_KHR (if the image was not presented to the user).

As an exception to the normal rules for objects which are externally synchronized, the swapchain passed to waitForPresentKHR may be simultaneously used by other threads in calls to functions other than destroySwapchainKHR. Access to the swapchain data associated with this extension must be atomic within the implementation.

Valid Usage

  • swapchain must not be in the retired state

Valid Usage (Implicit)

  • device must be a valid Device handle
  • swapchain must be a valid SwapchainKHR handle
  • swapchain must have been created, allocated, or retrieved from device

Host Synchronization

  • Host access to swapchain must be externally synchronized

Return Codes

Success
Failure

See Also

VK_KHR_present_wait, Device, SwapchainKHR

waitForPresentKHRSafe Source #

Arguments

:: forall io. MonadIO io 
=> Device

device is the device associated with swapchain.

-> SwapchainKHR

swapchain is the non-retired swapchain on which an image was queued for presentation.

-> ("presentId" ::: Word64)

presentId is the presentation presentId to wait for.

-> ("timeout" ::: Word64)

timeout is the timeout period in units of nanoseconds. timeout is adjusted to the closest value allowed by the implementation-dependent timeout accuracy, which may be substantially longer than one nanosecond, and may be longer than the requested period.

-> io Result 

A variant of waitForPresentKHR which makes a *safe* FFI call

data PhysicalDevicePresentWaitFeaturesKHR Source #

VkPhysicalDevicePresentWaitFeaturesKHR - Structure indicating support for present wait

Members

This structure describes the following feature:

Description

If the PhysicalDevicePresentWaitFeaturesKHR structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. PhysicalDevicePresentWaitFeaturesKHR can also be used in the pNext chain of DeviceCreateInfo to selectively enable these features.

Valid Usage (Implicit)

See Also

VK_KHR_present_wait, Bool32, StructureType

Constructors

PhysicalDevicePresentWaitFeaturesKHR 

Fields

Instances

Instances details
Storable PhysicalDevicePresentWaitFeaturesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_present_wait

Show PhysicalDevicePresentWaitFeaturesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_present_wait

Eq PhysicalDevicePresentWaitFeaturesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_present_wait

FromCStruct PhysicalDevicePresentWaitFeaturesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_present_wait

ToCStruct PhysicalDevicePresentWaitFeaturesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_present_wait

Zero PhysicalDevicePresentWaitFeaturesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_present_wait

pattern KHR_PRESENT_WAIT_SPEC_VERSION :: forall a. Integral a => a Source #

type KHR_PRESENT_WAIT_EXTENSION_NAME = "VK_KHR_present_wait" Source #

pattern KHR_PRESENT_WAIT_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a Source #

newtype SwapchainKHR Source #

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, getLatencyTimingsNV, getPastPresentationTimingGOOGLE, getRefreshCycleDurationGOOGLE, getSwapchainCounterEXT, getSwapchainImagesKHR, getSwapchainStatusKHR, latencySleepNV, queuePresentKHR, releaseFullScreenExclusiveModeEXT, setHdrMetadataEXT, setLatencyMarkerNV, setLatencySleepModeNV, setLocalDimmingAMD, waitForPresentKHR

Constructors

SwapchainKHR Word64 

Instances

Instances details
Storable SwapchainKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Show SwapchainKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Eq SwapchainKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Ord SwapchainKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

HasObjectType SwapchainKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

IsHandle SwapchainKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Zero SwapchainKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles