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