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

Vulkan.Extensions.VK_KHR_shared_presentable_image

Description

Name

VK_KHR_shared_presentable_image - device extension

VK_KHR_shared_presentable_image

Name String
VK_KHR_shared_presentable_image
Extension Type
Device extension
Registered Extension Number
112
Revision
1
Ratification Status
Ratified
Extension and Version Dependencies
VK_KHR_swapchain and VK_KHR_get_surface_capabilities2 and

VK_KHR_get_physical_device_properties2      or

Version 1.1

Contact

Other Extension Metadata

Last Modified Date
2017-03-20
IP Status
No known IP claims.
Contributors
  • Alon Or-bach, Samsung Electronics
  • Ian Elliott, Google
  • Jesse Hall, Google
  • Pablo Ceballos, Google
  • Chris Forbes, Google
  • Jeff Juliano, NVIDIA
  • James Jones, NVIDIA
  • Daniel Rakos, AMD
  • Tobias Hector, Imagination Technologies
  • Graham Connor, Imagination Technologies
  • Michael Worcester, Imagination Technologies
  • Cass Everitt, Oculus
  • Johannes Van Waveren, Oculus

Description

This extension extends VK_KHR_swapchain to enable creation of a shared presentable image. This allows the application to use the image while the presention engine is accessing it, in order to reduce the latency between rendering and presentation.

New Commands

New Structures

New Enum Constants

Issues

1) Should we allow a Vulkan WSI swapchain to toggle between normal usage and shared presentation usage?

RESOLVED: No. WSI swapchains are typically recreated with new properties instead of having their properties changed. This can also save resources, assuming that fewer images are needed for shared presentation, and assuming that most VR applications do not need to switch between normal and shared usage.

2) Should we have a query for determining how the presentation engine refresh is triggered?

RESOLVED: Yes. This is done via which presentation modes a surface supports.

3) Should the object representing a shared presentable image be an extension of a SwapchainKHR or a separate object?

RESOLVED: Extension of a swapchain due to overlap in creation properties and to allow common functionality between shared and normal presentable images and swapchains.

4) What should we call the extension and the new structures it creates?

RESOLVED: Shared presentable image / shared present.

5) Should the minImageCount and presentMode values of the SwapchainCreateInfoKHR be ignored, or required to be compatible values?

RESOLVED: minImageCount must be set to 1, and presentMode should be set to either PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR.

6) What should the layout of the shared presentable image be?

RESOLVED: After acquiring the shared presentable image, the application must transition it to the IMAGE_LAYOUT_SHARED_PRESENT_KHR layout prior to it being used. After this initial transition, any image usage that was requested during swapchain creation can be performed on the image without layout transitions being performed.

7) Do we need a new API for the trigger to refresh new content?

RESOLVED: queuePresentKHR to act as API to trigger a refresh, as will allow combination with other compatible extensions to queuePresentKHR.

8) How should an application detect a ERROR_OUT_OF_DATE_KHR error on a swapchain using the PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR present mode?

RESOLVED: Introduce getSwapchainStatusKHR to allow applications to query the status of a swapchain using a shared presentation mode.

9) What should subsequent calls to queuePresentKHR for PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR swapchains be defined to do?

RESOLVED: State that implementations may use it as a hint for updated content.

10) Can the ownership of a shared presentable image be transferred to a different queue?

RESOLVED: No. It is not possible to transfer ownership of a shared presentable image obtained from a swapchain created using SHARING_MODE_EXCLUSIVE after it has been presented.

11) How should queueSubmit behave if a command buffer uses an image from a ERROR_OUT_OF_DATE_KHR swapchain?

RESOLVED: queueSubmit is expected to return the ERROR_DEVICE_LOST error.

12) Can Vulkan provide any guarantee on the order of rendering, to enable beam chasing?

RESOLVED: This could be achieved via use of render passes to ensure strip rendering.

Version History

  • Revision 1, 2017-03-20 (Alon Or-bach)

    • Internal revisions

See Also

SharedPresentSurfaceCapabilitiesKHR, getSwapchainStatusKHR

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

getSwapchainStatusKHR Source #

Arguments

:: forall io. MonadIO io 
=> Device

device is the device associated with swapchain.

-> SwapchainKHR

swapchain is the swapchain to query.

-> io Result 

vkGetSwapchainStatusKHR - Get a swapchain’s status

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_shared_presentable_image, Device, SwapchainKHR

data SharedPresentSurfaceCapabilitiesKHR Source #

VkSharedPresentSurfaceCapabilitiesKHR - Structure describing capabilities of a surface for shared presentation

Valid Usage (Implicit)

See Also

VK_KHR_shared_presentable_image, ImageUsageFlags, StructureType

Constructors

SharedPresentSurfaceCapabilitiesKHR 

Fields

Instances

Instances details
Storable SharedPresentSurfaceCapabilitiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_shared_presentable_image

Show SharedPresentSurfaceCapabilitiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_shared_presentable_image

Eq SharedPresentSurfaceCapabilitiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_shared_presentable_image

FromCStruct SharedPresentSurfaceCapabilitiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_shared_presentable_image

ToCStruct SharedPresentSurfaceCapabilitiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_shared_presentable_image

Zero SharedPresentSurfaceCapabilitiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_shared_presentable_image

type KHR_SHARED_PRESENTABLE_IMAGE_EXTENSION_NAME = "VK_KHR_shared_presentable_image" 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

newtype PresentModeKHR Source #

VkPresentModeKHR - Presentation mode supported for a surface

Description

The supported ImageUsageFlagBits of the presentable images of a swapchain created for a surface may differ depending on the presentation mode, and can be determined as per the table below:

Presentation modeImage usage flags
PRESENT_MODE_IMMEDIATE_KHRSurfaceCapabilitiesKHR::supportedUsageFlags
PRESENT_MODE_MAILBOX_KHRSurfaceCapabilitiesKHR::supportedUsageFlags
PRESENT_MODE_FIFO_KHRSurfaceCapabilitiesKHR::supportedUsageFlags
PRESENT_MODE_FIFO_RELAXED_KHRSurfaceCapabilitiesKHR::supportedUsageFlags
PRESENT_MODE_SHARED_DEMAND_REFRESH_KHRSharedPresentSurfaceCapabilitiesKHR::sharedPresentSupportedUsageFlags
PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHRSharedPresentSurfaceCapabilitiesKHR::sharedPresentSupportedUsageFlags

Presentable image usage queries

Note

For reference, the mode indicated by PRESENT_MODE_FIFO_KHR is equivalent to the behavior of {wgl|glX|egl}SwapBuffers with a swap interval of 1, while the mode indicated by PRESENT_MODE_FIFO_RELAXED_KHR is equivalent to the behavior of {wgl|glX}SwapBuffers with a swap interval of -1 (from the {WGL|GLX}_EXT_swap_control_tear extensions).

See Also

VK_KHR_surface, LatencySurfaceCapabilitiesNV, SurfacePresentModeCompatibilityEXT, SurfacePresentModeEXT, SwapchainCreateInfoKHR, SwapchainPresentModeInfoEXT, SwapchainPresentModesCreateInfoEXT, getPhysicalDeviceSurfacePresentModes2EXT, getPhysicalDeviceSurfacePresentModesKHR

Constructors

PresentModeKHR Int32 

Bundled Patterns

pattern PRESENT_MODE_IMMEDIATE_KHR :: PresentModeKHR

PRESENT_MODE_IMMEDIATE_KHR specifies that the presentation engine does not wait for a vertical blanking period to update the current image, meaning this mode may result in visible tearing. No internal queuing of presentation requests is needed, as the requests are applied immediately.

pattern PRESENT_MODE_MAILBOX_KHR :: PresentModeKHR

PRESENT_MODE_MAILBOX_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal single-entry queue is used to hold pending presentation requests. If the queue is full when a new presentation request is received, the new request replaces the existing entry, and any images associated with the prior entry become available for reuse by the application. One request is removed from the queue and processed during each vertical blanking period in which the queue is non-empty.

pattern PRESENT_MODE_FIFO_KHR :: PresentModeKHR

PRESENT_MODE_FIFO_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during each vertical blanking period in which the queue is non-empty. This is the only value of presentMode that is required to be supported.

pattern PRESENT_MODE_FIFO_RELAXED_KHR :: PresentModeKHR

PRESENT_MODE_FIFO_RELAXED_KHR specifies that the presentation engine generally waits for the next vertical blanking period to update the current image. If a vertical blanking period has already passed since the last update of the current image then the presentation engine does not wait for another vertical blanking period for the update, meaning this mode may result in visible tearing in this case. This mode is useful for reducing visual stutter with an application that will mostly present a new image before the next vertical blanking period, but may occasionally be late, and present a new image just after the next vertical blanking period. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue, and one request is removed from the beginning of the queue and processed during or after each vertical blanking period in which the queue is non-empty.

pattern PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR :: PresentModeKHR

PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine periodically updates the current image on its regular refresh cycle. The application is only required to make one initial presentation request, after which the presentation engine must update the current image without any need for further presentation requests. The application can indicate the image contents have been updated by making a presentation request, but this does not guarantee the timing of when it will be updated. This mode may result in visible tearing if rendering to the image is not timed correctly.

pattern PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR :: PresentModeKHR

PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine is only required to update the current image after a new presentation request is received. Therefore the application must make a presentation request whenever an update is required. However, the presentation engine may update the current image at any point, meaning this mode may result in visible tearing.

Instances

Instances details
Storable PresentModeKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Read PresentModeKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Show PresentModeKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Eq PresentModeKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Ord PresentModeKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Zero PresentModeKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface