| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
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
- Extension and Version Dependencies
- Requires support for Vulkan 1.0
- Requires
VK_KHR_swapchainto be enabled for any device-level functionality - Requires
VK_KHR_get_physical_device_properties2to be enabled for any device-level functionality - Requires
VK_KHR_get_surface_capabilities2to be enabled for any device-level functionality
- 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
KHR_SHARED_PRESENTABLE_IMAGE_SPEC_VERSIONExtending
ImageLayout:Extending
PresentModeKHR:Extending
StructureType:
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
- getSwapchainStatusKHR :: forall io. MonadIO io => Device -> SwapchainKHR -> io Result
- data SharedPresentSurfaceCapabilitiesKHR = 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 = SwapchainKHR Word64
- newtype PresentModeKHR where
- PresentModeKHR Int32
- pattern PRESENT_MODE_IMMEDIATE_KHR :: PresentModeKHR
- pattern PRESENT_MODE_MAILBOX_KHR :: PresentModeKHR
- pattern PRESENT_MODE_FIFO_KHR :: PresentModeKHR
- pattern PRESENT_MODE_FIFO_RELAXED_KHR :: PresentModeKHR
- pattern PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR :: PresentModeKHR
- pattern PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR :: PresentModeKHR
Documentation
getSwapchainStatusKHR Source #
Arguments
| :: forall io. MonadIO io | |
| => Device |
|
| -> SwapchainKHR |
|
| -> io Result |
vkGetSwapchainStatusKHR - Get a swapchain’s status
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
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
pattern KHR_SHARED_PRESENTABLE_IMAGE_SPEC_VERSION :: forall a. Integral a => a Source #
type KHR_SHARED_PRESENTABLE_IMAGE_EXTENSION_NAME = "VK_KHR_shared_presentable_image" Source #
pattern KHR_SHARED_PRESENTABLE_IMAGE_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,
getPastPresentationTimingGOOGLE,
getRefreshCycleDurationGOOGLE,
getSwapchainCounterEXT,
getSwapchainImagesKHR,
getSwapchainStatusKHR,
queuePresentKHR,
releaseFullScreenExclusiveModeEXT,
setHdrMetadataEXT,
setLocalDimmingAMD,
waitForPresentKHR
Constructors
| SwapchainKHR Word64 |
Instances
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 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,
SurfacePresentModeCompatibilityEXT,
SurfacePresentModeEXT,
SwapchainCreateInfoKHR,
SwapchainPresentModeInfoEXT,
SwapchainPresentModesCreateInfoEXT,
getPhysicalDeviceSurfacePresentModes2EXT,
getPhysicalDeviceSurfacePresentModesKHR
Constructors
| PresentModeKHR Int32 |
Bundled Patterns
| pattern PRESENT_MODE_IMMEDIATE_KHR :: PresentModeKHR |
|
| pattern PRESENT_MODE_MAILBOX_KHR :: PresentModeKHR |
|
| pattern PRESENT_MODE_FIFO_KHR :: PresentModeKHR |
|
| pattern PRESENT_MODE_FIFO_RELAXED_KHR :: PresentModeKHR |
|
| pattern PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR :: PresentModeKHR |
|
| pattern PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR :: PresentModeKHR |
|