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