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

include::meta/VK_KHR_shared_presentable_image.txt[]

*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

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 slink: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 pname:minImageCount and pname:presentMode values of the
slink:VkSwapchainCreateInfoKHR be ignored, or required to be compatible
values?

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

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

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

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

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

*RESOLVED*: flink:vkQueueSubmit is expected to return the
ename: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