// Copyright (c) 2014-2017 The Khronos Group Inc.
// Copyright notice at https://www.khronos.org/registry/speccopyright.html

[[VK_KHR_display_swapchain]]
== VK_KHR_display_swapchain

*Name String*::
    +VK_KHR_display_swapchain+
*Extension Type*::
    Device extension
*Registered Extension Number*::
    4
*Status*::
    Draft.
*Last Modified Date*::
    2017-03-13
*Revision*::
    10
*IP Status*::
    No known IP claims.
*Dependencies*::
  - This extension is written against version 1.0 of the Vulkan API.
  - Requires +VK_KHR_swapchain+.
  - Requires +VK_KHR_display+.
*Contributors*::
  - James Jones, NVIDIA
  - Jeff Vigil, Qualcomm
  - Jesse Hall, Google
*Contacts*::
  - James Jones (jajones 'at' nvidia.com)

This extension provides an API to create a swapchain directly on a device's
display without any underlying window system.

=== New Object Types

None

=== New Enum Constants

  * Extending ename:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR
  * Extending ename:VkResult:
  ** ename:VK_ERROR_INCOMPATIBLE_DISPLAY_KHR

=== New Enums

None

=== New Structures

  * slink:VkDisplayPresentInfoKHR

=== New Functions

  * flink:vkCreateSharedSwapchainsKHR

=== Issues

1) Should swapchains sharing images each hold a reference to the images, or
should it be up to the application to destroy the swapchains and images in
an order that avoids the need for reference counting?

*RESOLVED*: Take a reference.
The lifetime of presentable images is already complex enough.

2) Should the srcRect/dstRect parameters be specified as part of the present
command, or at swapchain creation time?

*RESOLVED*: As part of the presentation command.
This allows moving and scaling the image on the screen without the need to
respecify the mode or create a new swapchain and presentable images.

3) Should srcRect/dstRect be specified as rects, or separate offset/extent
values?

*RESOLVED*: As rects.
Specifying them separately might make it easier for hardware to expose
support for one but not the other, but in such cases applications must just
take care to obey the reported capabilities and not use non-zero offsets or
extents that require scaling, as appropriate.

4) How can applications create multiple swapchains that use the same images?

*RESOLVED*: By calling flink:vkCreateSharedSwapchainsKHR.

An earlier resolution used flink:vkCreateSwapchainKHR, chaining multiple
slink:VkSwapchainCreateInfoKHR structures through pname:pNext.
In order to allow each swapchain to also allow other extension structs, a
level of indirection was used: slink:VkSwapchainCreateInfoKHR::pname:pNext
pointed to a different structure, which had both an pname:sType/pname:pNext
for additional extensions, and also had a pointer to the next
slink:VkSwapchainCreateInfoKHR structure.
The number of swapchains to be created could only be found by walking this
linked list of alternating structures, and the pSwapchains out parameter was
reinterpreted to be an array of slink:VkSwapchainKHR handles.

Another option considered was a method to specify a "`shared`" swapchain
when creating a new swapchain, such that groups of swapchains using the same
images could be built up one at a time.
This was deemed unusable because drivers need to know all of the displays an
image will be used on when determining which internal formats and layouts to
use for that image.

=== Examples

[NOTE]
.Note
====
The example code for the +VK_KHR_display+ and +VK_KHR_display_swapchain+
extensions was removed from the appendix after revision 1.0.43.
The display swapchain creation example code was ported to the cube demo that
is shipped with the official Khronos SDK, and is being kept up-to-date in
that location (see:
https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/master/demos/cube.c).
====

=== Version History

 * Revision 1, 2015-07-29 (James Jones)
   - Initial draft

 * Revision 2, 2015-08-21 (Ian Elliott)
   - Renamed this extension and all of its enumerations, types, functions,
     etc.
     This makes it compliant with the proposed standard for Vulkan
     extensions.
   - Switched from "revision" to "version", including use of the
     VK_MAKE_VERSION macro in the header file.

 * Revision 3, 2015-09-01 (James Jones)
   - Restore single-field revision number.

 * Revision 4, 2015-09-08 (James Jones)
   - Allow creating multiple swap chains that share the same images using a
     single call to vkCreateSwapChainKHR().

 * Revision 5, 2015-09-10 (Alon Or-bach)
   - Removed underscores from SWAP_CHAIN in two enums.

 * Revision 6, 2015-10-02 (James Jones)
   - Added support for smart panels/buffered displays.

 * Revision 7, 2015-10-26 (Ian Elliott)
   - Renamed from VK_EXT_KHR_display_swapchain to VK_KHR_display_swapchain.

 * Revision 8, 2015-11-03 (Daniel Rakos)
   - Updated sample code based on the changes to VK_KHR_swapchain.

 * Revision 9, 2015-11-10 (Jesse Hall)
   - Replaced ftext:VkDisplaySwapchainCreateInfoKHR with
     vkCreateSharedSwapchainsKHR, changing resolution of issue #4.

 * Revision 10, 2017-03-13 (James Jones)
   - Closed all remaining issues.
     The specification and implementations have been shipping with the
     proposed resolutions for some time now.
   - Removed the sample code and noted it has been integrated into the
     official Vulkan SDK cube demo.