// Copyright (c) 2014-2017 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

[[VK_KHR_shared_presentable_image]]
== VK_KHR_shared_presentable_image

*Name String*::
    +VK_KHR_shared_presentable_image+
*Extension Type*::
    Device extension
*Registered Extension Number*::
    112
*Last Modified Date*::
    2017-03-20
*Revision*::
    1
*IP Status*::
    No known IP claims.
*Dependencies*::
  - This extension is written against version 1.0 of the Vulkan API.
  - This extension requires +VK_KHR_swapchain+.
  - This extension requires +VK_KHR_surface+.
  - This extension requires +VK_KHR_get_physical_device_properties2+.
  - This extension requires +VK_KHR_get_surface_capabilities2+.
*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
*Contacts*::
  - Alon Or-bach, Samsung Electronics

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 Object Types

None.

=== New Enum Constants

  * Extending elink:VkPresentModeKHR:
  ** ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
  ** ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR

  * Extending elink:VkImageLayout:
  ** ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_SHARED_PRESENT_SURFACE_CAPABILITIES_KHR


=== New Enums

None.

=== New Structures

  * slink:VkSharedPresentSurfaceCapabilitiesKHR

=== New Functions

  * flink:vkGetSwapchainStatusKHR


=== 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 set to 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 intial 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 CONTINUOUS_REFRESH
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
an OUT_OF_DATE 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