| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
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
KHR_PRESENT_WAIT_SPEC_VERSIONExtending
StructureType:
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
- waitForPresentKHR :: forall io. MonadIO io => Device -> SwapchainKHR -> ("presentId" ::: Word64) -> ("timeout" ::: Word64) -> io Result
- waitForPresentKHRSafe :: forall io. MonadIO io => Device -> SwapchainKHR -> ("presentId" ::: Word64) -> ("timeout" ::: Word64) -> io Result
- data PhysicalDevicePresentWaitFeaturesKHR = PhysicalDevicePresentWaitFeaturesKHR {
- presentWait :: Bool
- type KHR_PRESENT_WAIT_SPEC_VERSION = 1
- pattern KHR_PRESENT_WAIT_SPEC_VERSION :: forall a. Integral a => a
- type KHR_PRESENT_WAIT_EXTENSION_NAME = "VK_KHR_present_wait"
- pattern KHR_PRESENT_WAIT_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a
- newtype SwapchainKHR = SwapchainKHR Word64
Documentation
Arguments
| :: forall io. MonadIO io | |
| => Device |
|
| -> SwapchainKHR |
|
| -> ("presentId" ::: Word64) |
|
| -> ("timeout" ::: Word64) |
|
| -> 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
- The presentWait feature must be enabled
Valid Usage (Implicit)
-
devicemust be a validDevicehandle
-
swapchainmust be a validSwapchainKHRhandle -
swapchainmust have been created, allocated, or retrieved fromdevice
Host Synchronization
- Host access to
swapchainmust be externally synchronized
Return Codes
See Also
waitForPresentKHRSafe Source #
Arguments
| :: forall io. MonadIO io | |
| => Device |
|
| -> SwapchainKHR |
|
| -> ("presentId" ::: Word64) |
|
| -> ("timeout" ::: Word64) |
|
| -> 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
Constructors
| PhysicalDevicePresentWaitFeaturesKHR | |
Fields
| |
Instances
type KHR_PRESENT_WAIT_SPEC_VERSION = 1 Source #
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 |