Vulkan.Extensions.VK_KHR_shared_presentable_image

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

Extension and Version Dependencies

• Requires Vulkan 1.0
• Requires VK_KHR_swapchain
• Requires VK_KHR_get_physical_device_properties2
• Requires VK_KHR_get_surface_capabilities2

Contact

• Alon Or-bach @alonorbach%0A<<Here describe the issue or question you have about the VK_KHR_shared_presentable_image extension> >

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

• getSwapchainStatusKHR

New Structures

• Extending SurfaceCapabilities2KHR:

  • SharedPresentSurfaceCapabilitiesKHR

New Enum Constants

• KHR_SHARED_PRESENTABLE_IMAGE_EXTENSION_NAME

• KHR_SHARED_PRESENTABLE_IMAGE_SPEC_VERSION

• Extending ImageLayout:

  • IMAGE_LAYOUT_SHARED_PRESENT_KHR

• Extending PresentModeKHR:

  • PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
  • PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR

• Extending StructureType:

  • STRUCTURE_TYPE_SHARED_PRESENT_SURFACE_CAPABILITIES_KHR

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.

Documentation

getSwapchainStatusKHR

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
• Both of device, and swapchain must have been created, allocated, or retrieved from the same Instance

Host Synchronization

• Host access to swapchain must be externally synchronized

Return Codes

Success

• SUCCESS
• SUBOPTIMAL_KHR

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_DEVICE_LOST
• ERROR_OUT_OF_DATE_KHR
• ERROR_SURFACE_LOST_KHR
• ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT

See Also

VK_KHR_shared_presentable_image, Device, SwapchainKHR

data SharedPresentSurfaceCapabilitiesKHR

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

• sharedPresentSupportedUsageFlags :: ImageUsageFlags

  sharedPresentSupportedUsageFlags is a bitmask of ImageUsageFlagBits representing the ways the application can use the shared presentable image from a swapchain created with PresentModeKHR set to PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR for the surface on the specified device. IMAGE_USAGE_COLOR_ATTACHMENT_BIT must be included in the set but implementations may support additional usages.

Instances

Eq SharedPresentSurfaceCapabilitiesKHR

Defined in Vulkan.Extensions.VK_KHR_shared_presentable_image

Methods

(==) :: SharedPresentSurfaceCapabilitiesKHR -> SharedPresentSurfaceCapabilitiesKHR -> Bool

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

Show SharedPresentSurfaceCapabilitiesKHR

Defined in Vulkan.Extensions.VK_KHR_shared_presentable_image

Methods

showsPrec :: Int -> SharedPresentSurfaceCapabilitiesKHR -> ShowS

show :: SharedPresentSurfaceCapabilitiesKHR -> String

showList :: [SharedPresentSurfaceCapabilitiesKHR] -> ShowS

Storable SharedPresentSurfaceCapabilitiesKHR

Defined in Vulkan.Extensions.VK_KHR_shared_presentable_image

Methods

sizeOf :: SharedPresentSurfaceCapabilitiesKHR -> Int

alignment :: SharedPresentSurfaceCapabilitiesKHR -> Int

peekElemOff :: Ptr SharedPresentSurfaceCapabilitiesKHR -> Int -> IO SharedPresentSurfaceCapabilitiesKHR

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

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

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

peek :: Ptr SharedPresentSurfaceCapabilitiesKHR -> IO SharedPresentSurfaceCapabilitiesKHR

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

FromCStruct SharedPresentSurfaceCapabilitiesKHR

Defined in Vulkan.Extensions.VK_KHR_shared_presentable_image

Methods

peekCStruct :: Ptr SharedPresentSurfaceCapabilitiesKHR -> IO SharedPresentSurfaceCapabilitiesKHR

ToCStruct SharedPresentSurfaceCapabilitiesKHR

Defined in Vulkan.Extensions.VK_KHR_shared_presentable_image

Methods

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

pokeCStruct :: Ptr SharedPresentSurfaceCapabilitiesKHR -> SharedPresentSurfaceCapabilitiesKHR -> IO b -> IO b

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

pokeZeroCStruct :: Ptr SharedPresentSurfaceCapabilitiesKHR -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero SharedPresentSurfaceCapabilitiesKHR

Defined in Vulkan.Extensions.VK_KHR_shared_presentable_image

Methods

zero :: SharedPresentSurfaceCapabilitiesKHR

type KHR_SHARED_PRESENTABLE_IMAGE_SPEC_VERSION = 1

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

type KHR_SHARED_PRESENTABLE_IMAGE_EXTENSION_NAME = "VK_KHR_shared_presentable_image"

pattern KHR_SHARED_PRESENTABLE_IMAGE_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 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, SwapchainCreateInfoKHR, acquireFullScreenExclusiveModeEXT, acquireNextImageKHR, createSharedSwapchainsKHR, createSwapchainKHR, destroySwapchainKHR, getPastPresentationTimingGOOGLE, getRefreshCycleDurationGOOGLE, getSwapchainCounterEXT, getSwapchainImagesKHR, getSwapchainStatusKHR, queuePresentKHR, releaseFullScreenExclusiveModeEXT, setHdrMetadataEXT, setLocalDimmingAMD, waitForPresentKHR

Constructors

SwapchainKHR Word64

Instances

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

Show SwapchainKHR

Defined in Vulkan.Extensions.Handles

Methods

showsPrec :: Int -> SwapchainKHR -> ShowS

show :: SwapchainKHR -> String

showList :: [SwapchainKHR] -> ShowS

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

Zero SwapchainKHR

Defined in Vulkan.Extensions.Handles

Methods

zero :: SwapchainKHR

HasObjectType SwapchainKHR

Defined in Vulkan.Extensions.Handles

Methods

objectTypeAndHandle :: SwapchainKHR -> (ObjectType, Word64)

IsHandle SwapchainKHR

Defined in Vulkan.Extensions.Handles

newtype PresentModeKHR

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 mode	Image usage flags
PRESENT_MODE_IMMEDIATE_KHR	SurfaceCapabilitiesKHR::supportedUsageFlags
PRESENT_MODE_MAILBOX_KHR	SurfaceCapabilitiesKHR::supportedUsageFlags
PRESENT_MODE_FIFO_KHR	SurfaceCapabilitiesKHR::supportedUsageFlags
PRESENT_MODE_FIFO_RELAXED_KHR	SurfaceCapabilitiesKHR::supportedUsageFlags
PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR	SharedPresentSurfaceCapabilitiesKHR::sharedPresentSupportedUsageFlags
PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR	SharedPresentSurfaceCapabilitiesKHR::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, SwapchainCreateInfoKHR, 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 re-use 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

Eq PresentModeKHR

Defined in Vulkan.Extensions.VK_KHR_surface

Methods

(==) :: PresentModeKHR -> PresentModeKHR -> Bool

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

Ord PresentModeKHR

Defined in Vulkan.Extensions.VK_KHR_surface

Methods

compare :: PresentModeKHR -> PresentModeKHR -> Ordering

(<) :: PresentModeKHR -> PresentModeKHR -> Bool

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

(>) :: PresentModeKHR -> PresentModeKHR -> Bool

(>=) :: PresentModeKHR -> PresentModeKHR -> Bool

max :: PresentModeKHR -> PresentModeKHR -> PresentModeKHR

min :: PresentModeKHR -> PresentModeKHR -> PresentModeKHR

Read PresentModeKHR

Defined in Vulkan.Extensions.VK_KHR_surface

Methods

readsPrec :: Int -> ReadS PresentModeKHR

readList :: ReadS [PresentModeKHR]

readPrec :: ReadPrec PresentModeKHR

readListPrec :: ReadPrec [PresentModeKHR]

Show PresentModeKHR

Defined in Vulkan.Extensions.VK_KHR_surface

Methods

showsPrec :: Int -> PresentModeKHR -> ShowS

show :: PresentModeKHR -> String

showList :: [PresentModeKHR] -> ShowS

Storable PresentModeKHR

Defined in Vulkan.Extensions.VK_KHR_surface

Methods

sizeOf :: PresentModeKHR -> Int

alignment :: PresentModeKHR -> Int

peekElemOff :: Ptr PresentModeKHR -> Int -> IO PresentModeKHR

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

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

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

peek :: Ptr PresentModeKHR -> IO PresentModeKHR

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

Zero PresentModeKHR

Defined in Vulkan.Extensions.VK_KHR_surface

Methods

zero :: PresentModeKHR