1// Copyright (c) 2014-2018 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 5include::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 16This extension provides an API to create a swapchain directly on a device's 17display without any underlying window system. 18 19=== New Object Types 20 21None 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 32None 33 34=== New Structures 35 36 * slink:VkDisplayPresentInfoKHR 37 38=== New Functions 39 40 * flink:vkCreateSharedSwapchainsKHR 41 42=== Issues 43 441) Should swapchains sharing images each hold a reference to the images, or 45should it be up to the application to destroy the swapchains and images in 46an order that avoids the need for reference counting? 47 48*RESOLVED*: Take a reference. 49The lifetime of presentable images is already complex enough. 50 512) Should the pname:srcRect/pname:dstRect parameters be specified as part of 52the present command, or at swapchain creation time? 53 54*RESOLVED*: As part of the presentation command. 55This allows moving and scaling the image on the screen without the need to 56respecify the mode or create a new swapchain and presentable images. 57 583) Should pname:srcRect/pname:dstRect be specified as rects, or separate 59offset/extent values? 60 61*RESOLVED*: As rects. 62Specifying them separately might make it easier for hardware to expose 63support for one but not the other, but in such cases applications must just 64take care to obey the reported capabilities and not use non-zero offsets or 65extents that require scaling, as appropriate. 66 674) How can applications create multiple swapchains that use the same images? 68 69*RESOLVED*: By calling flink:vkCreateSharedSwapchainsKHR. 70 71An earlier resolution used flink:vkCreateSwapchainKHR, chaining multiple 72slink:VkSwapchainCreateInfoKHR structures through pname:pNext. 73In order to allow each swapchain to also allow other extension structs, a 74level of indirection was used: slink:VkSwapchainCreateInfoKHR::pname:pNext 75pointed to a different structure, which had both an pname:sType/pname:pNext 76for additional extensions, and also had a pointer to the next 77slink:VkSwapchainCreateInfoKHR structure. 78The number of swapchains to be created could only be found by walking this 79linked list of alternating structures, and the pname:pSwapchains out 80parameter was reinterpreted to be an array of slink:VkSwapchainKHR handles. 81 82Another option considered was a method to specify a "`shared`" swapchain 83when creating a new swapchain, such that groups of swapchains using the same 84images could be built up one at a time. 85This was deemed unusable because drivers need to know all of the displays an 86image will be used on when determining which internal formats and layouts to 87use for that image. 88 89=== Examples 90 91[NOTE] 92.Note 93==== 94The example code for the `<<VK_KHR_display>>` and `VK_KHR_display_swapchain` 95extensions was removed from the appendix after revision 1.0.43. 96The display swapchain creation example code was ported to the cube demo that 97is shipped with the official Khronos SDK, and is being kept up-to-date in 98that location (see: 99https://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. 144