1  // Copyright (c) 2014-2019 Khronos Group. This work is licensed under a
  2  // Creative Commons Attribution 4.0 International License; see
  3  // http://creativecommons.org/licenses/by/4.0/
  4  
  5  include::meta/VK_KHR_display_swapchain.txt[]
  6  
  7  *Last Modified Date*::
  8      2017-03-13
  9  *IP Status*::
 10      No known IP claims.
 11  *Contributors*::
 12    - James Jones, NVIDIA
 13    - Jeff Vigil, Qualcomm
 14    - Jesse Hall, Google
 15  
 16  This extension provides an API to create a swapchain directly on a device's
 17  display without any underlying window system.
 18  
 19  === New Object Types
 20  
 21  None
 22  
 23  === New Enum Constants
 24  
 25    * Extending elink:VkStructureType:
 26    ** ename:VK_STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR
 27    * Extending elink:VkResult:
 28    ** ename:VK_ERROR_INCOMPATIBLE_DISPLAY_KHR
 29  
 30  === New Enums
 31  
 32  None
 33  
 34  === New Structures
 35  
 36    * slink:VkDisplayPresentInfoKHR
 37  
 38  === New Functions
 39  
 40    * flink:vkCreateSharedSwapchainsKHR
 41  
 42  === Issues
 43  
 44  1) Should swapchains sharing images each hold a reference to the images, or
 45  should it be up to the application to destroy the swapchains and images in
 46  an order that avoids the need for reference counting?
 47  
 48  *RESOLVED*: Take a reference.
 49  The lifetime of presentable images is already complex enough.
 50  
 51  2) Should the pname:srcRect/pname:dstRect parameters be specified as part of
 52  the present command, or at swapchain creation time?
 53  
 54  *RESOLVED*: As part of the presentation command.
 55  This allows moving and scaling the image on the screen without the need to
 56  respecify the mode or create a new swapchain and presentable images.
 57  
 58  3) Should pname:srcRect/pname:dstRect be specified as rects, or separate
 59  offset/extent values?
 60  
 61  *RESOLVED*: As rects.
 62  Specifying them separately might make it easier for hardware to expose
 63  support for one but not the other, but in such cases applications must just
 64  take care to obey the reported capabilities and not use non-zero offsets or
 65  extents that require scaling, as appropriate.
 66  
 67  4) How can applications create multiple swapchains that use the same images?
 68  
 69  *RESOLVED*: By calling flink:vkCreateSharedSwapchainsKHR.
 70  
 71  An earlier resolution used flink:vkCreateSwapchainKHR, chaining multiple
 72  slink:VkSwapchainCreateInfoKHR structures through pname:pNext.
 73  In order to allow each swapchain to also allow other extension structs, a
 74  level of indirection was used: slink:VkSwapchainCreateInfoKHR::pname:pNext
 75  pointed to a different structure, which had both an pname:sType/pname:pNext
 76  for additional extensions, and also had a pointer to the next
 77  slink:VkSwapchainCreateInfoKHR structure.
 78  The number of swapchains to be created could only be found by walking this
 79  linked list of alternating structures, and the pname:pSwapchains out
 80  parameter was reinterpreted to be an array of slink:VkSwapchainKHR handles.
 81  
 82  Another option considered was a method to specify a "`shared`" swapchain
 83  when creating a new swapchain, such that groups of swapchains using the same
 84  images could be built up one at a time.
 85  This was deemed unusable because drivers need to know all of the displays an
 86  image will be used on when determining which internal formats and layouts to
 87  use for that image.
 88  
 89  === Examples
 90  
 91  [NOTE]
 92  .Note
 93  ====
 94  The example code for the `<<VK_KHR_display>>` and `VK_KHR_display_swapchain`
 95  extensions was removed from the appendix after revision 1.0.43.
 96  The display swapchain creation example code was ported to the cube demo that
 97  is shipped with the official Khronos SDK, and is being kept up-to-date in
 98  that location (see:
 99  https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c).
100  ====
101  
102  === Version History
103  
104   * Revision 1, 2015-07-29 (James Jones)
105     - Initial draft
106  
107   * Revision 2, 2015-08-21 (Ian Elliott)
108     - Renamed this extension and all of its enumerations, types, functions,
109       etc.
110       This makes it compliant with the proposed standard for Vulkan
111       extensions.
112     - Switched from "revision" to "version", including use of the
113       VK_MAKE_VERSION macro in the header file.
114  
115   * Revision 3, 2015-09-01 (James Jones)
116     - Restore single-field revision number.
117  
118   * Revision 4, 2015-09-08 (James Jones)
119     - Allow creating multiple swap chains that share the same images using a
120       single call to vkCreateSwapChainKHR().
121  
122   * Revision 5, 2015-09-10 (Alon Or-bach)
123     - Removed underscores from SWAP_CHAIN in two enums.
124  
125   * Revision 6, 2015-10-02 (James Jones)
126     - Added support for smart panels/buffered displays.
127  
128   * Revision 7, 2015-10-26 (Ian Elliott)
129     - Renamed from VK_EXT_KHR_display_swapchain to VK_KHR_display_swapchain.
130  
131   * Revision 8, 2015-11-03 (Daniel Rakos)
132     - Updated sample code based on the changes to VK_KHR_swapchain.
133  
134   * Revision 9, 2015-11-10 (Jesse Hall)
135     - Replaced VkDisplaySwapchainCreateInfoKHR with
136       vkCreateSharedSwapchainsKHR, changing resolution of issue #4.
137  
138   * Revision 10, 2017-03-13 (James Jones)
139     - Closed all remaining issues.
140       The specification and implementations have been shipping with the
141       proposed resolutions for some time now.
142     - Removed the sample code and noted it has been integrated into the
143       official Vulkan SDK cube demo.