VK_KHR_shared_presentable_image(3)

# VK_KHR_shared_presentable_image(3) Manual Page

## Name

VK_KHR_shared_presentable_image - device extension

Loading… please wait.

## 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
Vulkan Version 1.1

## Contact

- Alon Or-bach [GitHub]alonorbach

## 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

- vkGetSwapchainStatusKHR

## New Structures

- Extending VkSurfaceCapabilities2KHR:

  - VkSharedPresentSurfaceCapabilitiesKHR

## New Enum Constants

- `VK_KHR_SHARED_PRESENTABLE_IMAGE_EXTENSION_NAME`

- `VK_KHR_SHARED_PRESENTABLE_IMAGE_SPEC_VERSION`

- Extending VkImageLayout:

  - `VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR`

- Extending VkPresentModeKHR:

  - `VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR`

  - `VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR`

- Extending VkStructureType:

  - `VK_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 VkSwapchainKHR 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 VkSwapchainCreateInfoKHR be ignored, or required to be compatible values?

RESOLVED: `minImageCount` must be 1, and `presentMode` should be set to either `VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR` or `VK_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 `VK_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: vkQueuePresentKHR to act as API to trigger a refresh, as will allow combination with other compatible extensions to vkQueuePresentKHR.

8) How should an application detect a `VK_ERROR_OUT_OF_DATE_KHR` error on a swapchain using the `VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR` present mode?

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

9) What should subsequent calls to vkQueuePresentKHR for `VK_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 `VK_SHARING_MODE_EXCLUSIVE` after it has been presented.

11) How should vkQueueSubmit behave if a command buffer uses an image from a `VK_ERROR_OUT_OF_DATE_KHR` swapchain?

RESOLVED: vkQueueSubmit is expected to return the `VK_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

No cross-references are available

## 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.

## Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0