1// Copyright 2014-2023 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5include::{generated}/meta/{refprefix}VK_KHR_surface.adoc[] 6 7=== Other Extension Metadata 8 9*Last Modified Date*:: 10 2016-08-25 11*IP Status*:: 12 No known IP claims. 13*Contributors*:: 14 - Patrick Doane, Blizzard 15 - Ian Elliott, LunarG 16 - Jesse Hall, Google 17 - James Jones, NVIDIA 18 - David Mao, AMD 19 - Norbert Nopper, Freescale 20 - Alon Or-bach, Samsung 21 - Daniel Rakos, AMD 22 - Graham Sellers, AMD 23 - Jeff Vigil, Qualcomm 24 - Chia-I Wu, LunarG 25 - Faith Ekstrand, Intel 26 27=== Description 28 29The `VK_KHR_surface` extension is an instance extension. 30It introduces slink:VkSurfaceKHR objects, which abstract native platform 31surface or window objects for use with Vulkan. 32It also provides a way to determine whether a queue family in a physical 33device supports presenting to particular surface. 34 35Separate extensions for each platform provide the mechanisms for creating 36slink:VkSurfaceKHR objects, but once created they may be used in this and 37other platform-independent extensions, in particular the 38`apiext:VK_KHR_swapchain` extension. 39 40include::{generated}/interfaces/VK_KHR_surface.adoc[] 41 42ifndef::VKSC_VERSION_1_0[] 43=== Examples 44 45[NOTE] 46.Note 47==== 48The example code for the `VK_KHR_surface` and `apiext:VK_KHR_swapchain` 49extensions was removed from the appendix after revision 1.0.29. 50This WSI example code was ported to the cube demo that is shipped with the 51official Khronos SDK, and is being kept up-to-date in that location (see: 52https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c). 53==== 54endif::VKSC_VERSION_1_0[] 55 56=== Issues 57 581) Should this extension include a method to query whether a physical device 59supports presenting to a specific window or native surface on a given 60platform? 61 62*RESOLVED*: Yes. 63Without this, applications would need to create a device instance to 64determine whether a particular window can be presented to. 65Knowing that a device supports presentation to a platform in general is not 66sufficient, as a single machine might support multiple seats, or instances 67of the platform that each use different underlying physical devices. 68Additionally, on some platforms, such as the X Window System, different 69drivers and devices might be used for different windows depending on which 70section of the desktop they exist on. 71 722) Should the flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, 73flink:vkGetPhysicalDeviceSurfaceFormatsKHR, and 74flink:vkGetPhysicalDeviceSurfacePresentModesKHR functions be in this 75extension and operate on physical devices, rather than being in 76`apiext:VK_KHR_swapchain` (i.e. device extension) and being dependent on 77slink:VkDevice? 78 79*RESOLVED*: Yes. 80While it might be useful to depend on sname:VkDevice (and therefore on 81enabled extensions and features) for the queries, Vulkan was released only 82with the slink:VkPhysicalDevice versions. 83Many cases can be resolved by a Valid Usage statement, and/or by a separate 84pname:pNext chain version of the query struct specific to a given extension 85or parameters, via extensible versions of the queries: 86ifdef::VK_EXT_full_screen_exclusive[flink:vkGetPhysicalDeviceSurfacePresentModes2EXT,] 87flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR, and 88flink:vkGetPhysicalDeviceSurfaceFormats2KHR. 89 903) Should Vulkan support Xlib or XCB as the API for accessing the X Window 91System platform? 92 93*RESOLVED*: Both. 94XCB is a more modern and efficient API, but Xlib usage is deeply ingrained 95in many applications and likely will remain in use for the foreseeable 96future. 97Not all drivers necessarily need to support both, but including both as 98options in the core specification will probably encourage support, which 99should in turn ease adoption of the Vulkan API in older codebases. 100Additionally, the performance improvements possible with XCB likely will not 101have a measurable impact on the performance of Vulkan presentation and other 102minimal window system interactions defined here. 103 1044) Should the GBM platform be included in the list of platform enums? 105 106*RESOLVED*: Deferred, and will be addressed with a platform-specific 107extension to be written in the future. 108 109=== Version History 110 111 * Revision 1, 2015-05-20 (James Jones) 112 ** Initial draft, based on LunarG KHR spec, other KHR specs, patches 113 attached to bugs. 114 115 * Revision 2, 2015-05-22 (Ian Elliott) 116 ** Created initial Description section. 117 ** Removed query for whether a platform requires the use of a queue for 118 presentation, since it was decided that presentation will always be 119 modeled as being part of the queue. 120 ** Fixed typos and other minor mistakes. 121 122 * Revision 3, 2015-05-26 (Ian Elliott) 123 ** Improved the Description section. 124 125 * Revision 4, 2015-05-27 (James Jones) 126 ** Fixed compilation errors in example code. 127 128 * Revision 5, 2015-06-01 (James Jones) 129 ** Added issues 1 and 2 and made related spec updates. 130 131 * Revision 6, 2015-06-01 (James Jones) 132 ** Merged the platform type mappings table previously removed from 133 VK_KHR_swapchain with the platform description table in this spec. 134 ** Added issues 3 and 4 documenting choices made when building the initial 135 list of native platforms supported. 136 137 * Revision 7, 2015-06-11 (Ian Elliott) 138 ** Updated table 1 per input from the KHR TSG. 139 ** Updated issue 4 (GBM) per discussion with Daniel Stone. 140 He will create a platform-specific extension sometime in the future. 141 142 * Revision 8, 2015-06-17 (James Jones) 143 ** Updated enum-extending values using new convention. 144 ** Fixed the value of VK_SURFACE_PLATFORM_INFO_TYPE_SUPPORTED_KHR. 145 146 * Revision 9, 2015-06-17 (James Jones) 147 ** Rebased on Vulkan API version 126. 148 149 * Revision 10, 2015-06-18 (James Jones) 150 ** Marked issues 2 and 3 resolved. 151 152 * Revision 11, 2015-06-23 (Ian Elliott) 153 ** Examples now show use of function pointers for extension functions. 154 ** Eliminated extraneous whitespace. 155 156 * Revision 12, 2015-07-07 (Daniel Rakos) 157 ** Added error section describing when each error is expected to be 158 reported. 159 ** Replaced the term "`queue node index`" with "`queue family index`" in 160 the spec as that is the agreed term to be used in the latest version of 161 the core header and spec. 162 ** Replaced bool32_t with VkBool32. 163 164 * Revision 13, 2015-08-06 (Daniel Rakos) 165 ** Updated spec against latest core API header version. 166 167 * Revision 14, 2015-08-20 (Ian Elliott) 168 ** Renamed this extension and all of its enumerations, types, functions, 169 etc. 170 This makes it compliant with the proposed standard for Vulkan 171 extensions. 172 ** Switched from "`revision`" to "`version`", including use of the 173 VK_MAKE_VERSION macro in the header file. 174 ** Did miscellaneous cleanup, etc. 175 176 * Revision 15, 2015-08-20 (Ian Elliott--porting a 2015-07-29 change from 177 James Jones) 178 ** Moved the surface transform enums here from VK_WSI_swapchain so they 179 could be reused by VK_WSI_display. 180 181 * Revision 16, 2015-09-01 (James Jones) 182 ** Restore single-field revision number. 183 184 * Revision 17, 2015-09-01 (James Jones) 185 ** Fix example code compilation errors. 186 187 * Revision 18, 2015-09-26 (Jesse Hall) 188 ** Replaced VkSurfaceDescriptionKHR with the VkSurfaceKHR object, which is 189 created via layered extensions. 190 Added VkDestroySurfaceKHR. 191 192 * Revision 19, 2015-09-28 (Jesse Hall) 193 ** Renamed from VK_EXT_KHR_swapchain to VK_EXT_KHR_surface. 194 195 * Revision 20, 2015-09-30 (Jeff Vigil) 196 ** Add error result VK_ERROR_SURFACE_LOST_KHR. 197 198 * Revision 21, 2015-10-15 (Daniel Rakos) 199 ** Updated the resolution of issue #2 and include the surface capability 200 queries in this extension. 201 ** Renamed SurfaceProperties to SurfaceCapabilities as it better reflects 202 that the values returned are the capabilities of the surface on a 203 particular device. 204 ** Other minor cleanup and consistency changes. 205 206 * Revision 22, 2015-10-26 (Ian Elliott) 207 ** Renamed from VK_EXT_KHR_surface to VK_KHR_surface. 208 209 * Revision 23, 2015-11-03 (Daniel Rakos) 210 ** Added allocation callbacks to vkDestroySurfaceKHR. 211 212 * Revision 24, 2015-11-10 (Jesse Hall) 213 ** Removed VkSurfaceTransformKHR. 214 Use VkSurfaceTransformFlagBitsKHR instead. 215 ** Rename VkSurfaceCapabilitiesKHR member maxImageArraySize to 216 maxImageArrayLayers. 217 218 * Revision 25, 2016-01-14 (James Jones) 219 ** Moved VK_ERROR_NATIVE_WINDOW_IN_USE_KHR from the VK_KHR_android_surface 220 to the VK_KHR_surface extension. 221 222 * 2016-08-23 (Ian Elliott) 223 ** Update the example code, to not have so many characters per line, and 224 to split out a new example to show how to obtain function pointers. 225 226 * 2016-08-25 (Ian Elliott) 227 ** A note was added at the beginning of the example code, stating that it 228 will be removed from future versions of the appendix. 229