1// Copyright 2014-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[wsi]] 6= Window System Integration (WSI) 7 8This chapter discusses the window system integration (WSI) between the 9Vulkan API and the various forms of displaying the results of rendering to a 10user. 11Since the Vulkan API can: be used without displaying results, WSI is 12provided through the use of optional Vulkan extensions. 13This chapter provides an overview of WSI. 14See the appendix for additional details of each WSI extension, including 15which extensions must: be enabled in order to use each of the functions 16described in this chapter. 17 18 19== WSI Platform 20 21A platform is an abstraction for a window system, OS, etc. 22Some examples include MS Windows, Android, and Wayland. 23The Vulkan API may: be integrated in a unique manner for each platform. 24 25The Vulkan API does not define any type of platform object. 26Platform-specific WSI extensions are defined, each containing 27platform-specific functions for using WSI. 28Use of these extensions is guarded by preprocessor symbols as defined in the 29<<boilerplate-wsi-header,Window System-Specific Header Control>> appendix. 30 31In order for an application to be compiled to use WSI with a given platform, 32it must either: 33 34 * `#define` the appropriate preprocessor symbol prior to including the 35 `{full_header}` header file, or 36 * include `{core_header}` and any native platform headers, followed by the 37 appropriate platform-specific header. 38 39The preprocessor symbols and platform-specific headers are defined in the 40<<boilerplate-wsi-header-table, Window System Extensions and Headers>> 41table. 42 43Each platform-specific extension is an instance extension. 44The application must: enable instance extensions with fname:vkCreateInstance 45before using them. 46 47 48== WSI Surface 49 50[open,refpage='VkSurfaceKHR',desc='Opaque handle to a surface object',type='handles'] 51-- 52Native platform surface or window objects are abstracted by surface objects, 53which are represented by sname:VkSurfaceKHR handles: 54 55include::{generated}/api/handles/VkSurfaceKHR.adoc[] 56 57The `apiext:VK_KHR_surface` extension declares the sname:VkSurfaceKHR 58object, and provides a function for destroying sname:VkSurfaceKHR objects. 59Separate platform-specific extensions each provide a function for creating a 60sname:VkSurfaceKHR object for the respective platform. 61From the application's perspective this is an opaque handle, just like the 62handles of other Vulkan objects. 63 64ifdef::implementation-guide[] 65[NOTE] 66.Note 67==== 68On certain platforms, the Vulkan loader and ICDs may: have conventions that 69treat the handle as a pointer to a structure containing the 70platform-specific information about the surface. 71This will be described in the documentation for the loader-ICD interface, 72and in the `vk_icd.h` header file of the LoaderAndTools source-code 73repository. 74This does not affect the loader-layer interface; layers may: wrap 75sname:VkSurfaceKHR objects. 76==== 77endif::implementation-guide[] 78-- 79 80ifdef::editing-notes[] 81[NOTE] 82.editing-note 83==== 84TODO: Consider replacing the above note editing note with a pointer to the 85loader specification, when it exists. 86However, the information is not relevant to users of the API nor does it 87affect conformance of a Vulkan implementation. 88==== 89endif::editing-notes[] 90 91ifdef::VK_KHR_android_surface[] 92include::{chapters}/VK_KHR_android_surface/platformCreateSurface_android.adoc[] 93endif::VK_KHR_android_surface[] 94 95ifdef::VK_KHR_wayland_surface[] 96include::{chapters}/VK_KHR_wayland_surface/platformCreateSurface_wayland.adoc[] 97endif::VK_KHR_wayland_surface[] 98 99ifdef::VK_KHR_win32_surface[] 100include::{chapters}/VK_KHR_win32_surface/platformCreateSurface_win32.adoc[] 101endif::VK_KHR_win32_surface[] 102 103ifdef::VK_KHR_xcb_surface[] 104include::{chapters}/VK_KHR_xcb_surface/platformCreateSurface_xcb.adoc[] 105endif::VK_KHR_xcb_surface[] 106 107ifdef::VK_KHR_xlib_surface[] 108include::{chapters}/VK_KHR_xlib_surface/platformCreateSurface_xlib.adoc[] 109endif::VK_KHR_xlib_surface[] 110 111ifdef::VK_EXT_directfb_surface[] 112include::{chapters}/VK_EXT_directfb_surface/platformCreateSurface_directfb.adoc[] 113endif::VK_EXT_directfb_surface[] 114 115ifdef::VK_FUCHSIA_imagepipe_surface[] 116include::{chapters}/VK_FUCHSIA_imagepipe_surface/platformCreateSurface_imagepipe.adoc[] 117endif::VK_FUCHSIA_imagepipe_surface[] 118 119ifdef::VK_GGP_stream_descriptor_surface[] 120include::{chapters}/VK_GGP_stream_descriptor_surface/platformCreateSurface_streamdescriptor.adoc[] 121endif::VK_GGP_stream_descriptor_surface[] 122 123ifdef::VK_MVK_ios_surface[] 124include::{chapters}/VK_MVK_ios_surface/platformCreateSurface_ios.adoc[] 125endif::VK_MVK_ios_surface[] 126 127ifdef::VK_MVK_macos_surface[] 128include::{chapters}/VK_MVK_macos_surface/platformCreateSurface_macos.adoc[] 129endif::VK_MVK_macos_surface[] 130 131ifdef::VK_NN_vi_surface[] 132include::{chapters}/VK_NN_vi_surface/platformCreateSurface_vi.adoc[] 133endif::VK_NN_vi_surface[] 134 135ifdef::VK_EXT_metal_surface[] 136include::{chapters}/VK_EXT_metal_surface/platformCreateSurface_metal.adoc[] 137endif::VK_EXT_metal_surface[] 138 139ifdef::VK_QNX_screen_surface[] 140include::{chapters}/VK_QNX_screen_surface/platformCreateSurface_screen.adoc[] 141endif::VK_QNX_screen_surface[] 142 143 144=== Platform-Independent Information 145 146Once created, sname:VkSurfaceKHR objects can: be used in this and other 147extensions, in particular the `apiext:VK_KHR_swapchain` extension. 148 149Several WSI functions return ename:VK_ERROR_SURFACE_LOST_KHR if the surface 150becomes no longer available. 151After such an error, the surface (and any child swapchain, if one exists) 152should: be destroyed, as there is no way to restore them to a not-lost 153state. 154Applications may: attempt to create a new sname:VkSurfaceKHR using the same 155native platform window object, but whether such re-creation will succeed is 156platform-dependent and may: depend on the reason the surface became 157unavailable. 158A lost surface does not otherwise cause devices to be 159<<devsandqueues-lost-device,lost>>. 160 161[open,refpage='vkDestroySurfaceKHR',desc='Destroy a VkSurfaceKHR object',type='protos'] 162-- 163To destroy a sname:VkSurfaceKHR object, call: 164 165include::{generated}/api/protos/vkDestroySurfaceKHR.adoc[] 166 167 * pname:instance is the instance used to create the surface. 168 * pname:surface is the surface to destroy. 169 * pname:pAllocator is the allocator used for host memory allocated for the 170 surface object when there is no more specific allocator available (see 171 <<memory-allocation,Memory Allocation>>). 172 173Destroying a sname:VkSurfaceKHR merely severs the connection between Vulkan 174and the native surface, and does not imply destroying the native surface, 175closing a window, or similar behavior. 176 177.Valid Usage 178**** 179 * [[VUID-vkDestroySurfaceKHR-surface-01266]] 180 All sname:VkSwapchainKHR objects created for pname:surface must: have 181 been destroyed prior to destroying pname:surface 182 * [[VUID-vkDestroySurfaceKHR-surface-01267]] 183 If sname:VkAllocationCallbacks were provided when pname:surface was 184 created, a compatible set of callbacks must: be provided here 185 * [[VUID-vkDestroySurfaceKHR-surface-01268]] 186 If no sname:VkAllocationCallbacks were provided when pname:surface was 187 created, pname:pAllocator must: be `NULL` 188**** 189 190include::{generated}/validity/protos/vkDestroySurfaceKHR.adoc[] 191-- 192 193ifdef::VK_KHR_display[] 194include::{chapters}/VK_KHR_display/display.adoc[] 195endif::VK_KHR_display[] 196 197ifdef::VK_EXT_headless_surface[] 198include::{chapters}/VK_EXT_headless_surface/headless.adoc[] 199endif::VK_EXT_headless_surface[] 200 201 202== Querying for WSI Support 203 204Not all physical devices will include WSI support. 205Within a physical device, not all queue families will support presentation. 206WSI support and compatibility can: be determined in a platform-neutral 207manner (which determines support for presentation to a particular surface 208object) and additionally may: be determined in platform-specific manners 209(which determine support for presentation on the specified physical device 210but do not guarantee support for presentation to a particular surface 211object). 212 213[open,refpage='vkGetPhysicalDeviceSurfaceSupportKHR',desc='Query if presentation is supported',type='protos'] 214-- 215To determine whether a queue family of a physical device supports 216presentation to a given surface, call: 217 218include::{generated}/api/protos/vkGetPhysicalDeviceSurfaceSupportKHR.adoc[] 219 220 * pname:physicalDevice is the physical device. 221 * pname:queueFamilyIndex is the queue family. 222 * pname:surface is the surface. 223 * pname:pSupported is a pointer to a basetype:VkBool32, which is set to 224 ename:VK_TRUE to indicate support, and ename:VK_FALSE otherwise. 225 226.Valid Usage 227**** 228 * [[VUID-vkGetPhysicalDeviceSurfaceSupportKHR-queueFamilyIndex-01269]] 229 pname:queueFamilyIndex must: be less than 230 pname:pQueueFamilyPropertyCount returned by 231 fname:vkGetPhysicalDeviceQueueFamilyProperties for the given 232 pname:physicalDevice 233**** 234 235include::{generated}/validity/protos/vkGetPhysicalDeviceSurfaceSupportKHR.adoc[] 236-- 237 238ifdef::VK_KHR_android_surface[] 239include::{chapters}/VK_KHR_android_surface/platformQuerySupport_android.adoc[] 240endif::VK_KHR_android_surface[] 241 242ifdef::VK_KHR_wayland_surface[] 243include::{chapters}/VK_KHR_wayland_surface/platformQuerySupport_wayland.adoc[] 244endif::VK_KHR_wayland_surface[] 245 246ifdef::VK_KHR_win32_surface[] 247include::{chapters}/VK_KHR_win32_surface/platformQuerySupport_win32.adoc[] 248endif::VK_KHR_win32_surface[] 249 250ifdef::VK_KHR_xcb_surface[] 251include::{chapters}/VK_KHR_xcb_surface/platformQuerySupport_xcb.adoc[] 252endif::VK_KHR_xcb_surface[] 253 254ifdef::VK_KHR_xlib_surface[] 255include::{chapters}/VK_KHR_xlib_surface/platformQuerySupport_xlib.adoc[] 256endif::VK_KHR_xlib_surface[] 257 258ifdef::VK_EXT_directfb_surface[] 259include::{chapters}/VK_EXT_directfb_surface/platformQuerySupport_directfb.adoc[] 260endif::VK_EXT_directfb_surface[] 261 262ifdef::VK_FUCHSIA_imagepipe_surface[] 263include::{chapters}/VK_FUCHSIA_imagepipe_surface/platformQuerySupport_imagepipe.adoc[] 264endif::VK_FUCHSIA_imagepipe_surface[] 265 266ifdef::VK_GGP_stream_descriptor_surface[] 267include::{chapters}/VK_GGP_stream_descriptor_surface/platformQuerySupport_streamdescriptor.adoc[] 268endif::VK_GGP_stream_descriptor_surface[] 269 270ifdef::VK_MVK_ios_surface[] 271include::{chapters}/VK_MVK_ios_surface/platformQuerySupport_ios.adoc[] 272endif::VK_MVK_ios_surface[] 273 274ifdef::VK_MVK_macos_surface[] 275include::{chapters}/VK_MVK_macos_surface/platformQuerySupport_macos.adoc[] 276endif::VK_MVK_macos_surface[] 277 278ifdef::VK_NN_vi_surface[] 279include::{chapters}/VK_NN_vi_surface/platformQuerySupport_vi.adoc[] 280endif::VK_NN_vi_surface[] 281 282ifdef::VK_QNX_screen_surface[] 283include::{chapters}/VK_QNX_screen_surface/platformQuerySupport_screen.adoc[] 284endif::VK_QNX_screen_surface[] 285 286 287== Surface Queries 288 289The capabilities of a swapchain targeting a surface are the intersection of 290the capabilities of the WSI platform, the native window or display, and the 291physical device. 292The resulting capabilities can: be obtained with the queries listed below in 293this section. 294 295[NOTE] 296.Note 297==== 298In addition to the surface capabilities as obtained by surface queries 299below, swapchain images are also subject to ordinary image creation limits 300as reported by flink:vkGetPhysicalDeviceImageFormatProperties. 301As an application is instructed by the appropriate Valid Usage sections, 302both the surface capabilities and the image creation limits have to be 303satisfied whenever swapchain images are created. 304==== 305 306 307=== Surface Capabilities 308 309[open,refpage='vkGetPhysicalDeviceSurfaceCapabilitiesKHR',desc='Query surface capabilities',type='protos'] 310-- 311:refpage: vkGetPhysicalDeviceSurfaceCapabilitiesKHR 312 313To query the basic capabilities of a surface, needed in order to create a 314swapchain, call: 315 316include::{generated}/api/protos/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.adoc[] 317 318 * pname:physicalDevice is the physical device that will be associated with 319 the swapchain to be created, as described for 320 flink:vkCreateSwapchainKHR. 321 * pname:surface is the surface that will be associated with the swapchain. 322 * pname:pSurfaceCapabilities is a pointer to a 323 slink:VkSurfaceCapabilitiesKHR structure in which the capabilities are 324 returned. 325 326.Valid Usage 327**** 328include::{chapters}/commonvalidity/surface_physical_device_common.adoc[] 329**** 330 331include::{generated}/validity/protos/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.adoc[] 332-- 333 334[open,refpage='VkSurfaceCapabilitiesKHR',desc='Structure describing capabilities of a surface',type='structs'] 335-- 336The sname:VkSurfaceCapabilitiesKHR structure is defined as: 337 338include::{generated}/api/structs/VkSurfaceCapabilitiesKHR.adoc[] 339 340// These members are defined identically in VkSurfaceCapabilities2EXT, an 341// extendable structure version of this query, so they are just reused from 342// here. 343 344// tag::surface_capabilities_members[] 345 * pname:minImageCount is the minimum number of images the specified device 346 supports for a swapchain created for the surface, and will be at least 347 one. 348 * pname:maxImageCount is the maximum number of images the specified device 349 supports for a swapchain created for the surface, and will be either 0, 350 or greater than or equal to pname:minImageCount. 351 A value of 0 means that there is no limit on the number of images, 352 though there may: be limits related to the total amount of memory used 353 by presentable images. 354 * pname:currentExtent is the current width and height of the surface, or 355 the special value [eq]#(0xFFFFFFFF, 0xFFFFFFFF)# indicating that the 356 surface size will be determined by the extent of a swapchain targeting 357 the surface. 358 * pname:minImageExtent contains the smallest valid swapchain extent for 359 the surface on the specified device. 360 The pname:width and pname:height of the extent will each be less than or 361 equal to the corresponding pname:width and pname:height of 362 pname:currentExtent, unless pname:currentExtent has the special value 363 described above. 364 * pname:maxImageExtent contains the largest valid swapchain extent for the 365 surface on the specified device. 366 The pname:width and pname:height of the extent will each be greater than 367 or equal to the corresponding pname:width and pname:height of 368 pname:minImageExtent. 369 The pname:width and pname:height of the extent will each be greater than 370 or equal to the corresponding pname:width and pname:height of 371 pname:currentExtent, unless pname:currentExtent has the special value 372 described above. 373 * pname:maxImageArrayLayers is the maximum number of layers presentable 374 images can: have for a swapchain created for this device and surface, 375 and will be at least one. 376 * pname:supportedTransforms is a bitmask of 377 elink:VkSurfaceTransformFlagBitsKHR indicating the presentation 378 transforms supported for the surface on the specified device. 379 At least one bit will be set. 380 * pname:currentTransform is elink:VkSurfaceTransformFlagBitsKHR value 381 indicating the surface's current transform relative to the presentation 382 engine's natural orientation. 383 * pname:supportedCompositeAlpha is a bitmask of 384 elink:VkCompositeAlphaFlagBitsKHR, representing the alpha compositing 385 modes supported by the presentation engine for the surface on the 386 specified device, and at least one bit will be set. 387 Opaque composition can: be achieved in any alpha compositing mode by 388 either using an image format that has no alpha component, or by ensuring 389 that all pixels in the presentable images have an alpha value of 1.0. 390 * pname:supportedUsageFlags is a bitmask of elink:VkImageUsageFlagBits 391 representing the ways the application can: use the presentable images of 392 a swapchain created 393ifdef::VK_KHR_shared_presentable_image[] 394 with elink:VkPresentModeKHR set to ename:VK_PRESENT_MODE_IMMEDIATE_KHR, 395 ename:VK_PRESENT_MODE_MAILBOX_KHR, ename:VK_PRESENT_MODE_FIFO_KHR or 396 ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR 397endif::VK_KHR_shared_presentable_image[] 398 for the surface on the specified device. 399 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT must: be included in the set. 400 Implementations may: support additional usages. 401// end::surface_capabilities_members[] 402 403ifdef::VK_KHR_shared_presentable_image[] 404[NOTE] 405.Note 406==== 407Supported usage flags of a presentable image when using 408ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or 409ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR presentation mode are 410provided by 411slink:VkSharedPresentSurfaceCapabilitiesKHR::pname:sharedPresentSupportedUsageFlags. 412==== 413endif::VK_KHR_shared_presentable_image[] 414 415[NOTE] 416.Note 417==== 418Formulas such as [eq]#min(N, pname:maxImageCount)# are not correct, since 419pname:maxImageCount may: be zero. 420==== 421 422include::{generated}/validity/structs/VkSurfaceCapabilitiesKHR.adoc[] 423-- 424 425ifdef::VK_KHR_get_surface_capabilities2[] 426[open,refpage='vkGetPhysicalDeviceSurfaceCapabilities2KHR',desc='Reports capabilities of a surface on a physical device',type='protos'] 427-- 428:refpage: vkGetPhysicalDeviceSurfaceCapabilities2KHR 429 430To query the basic capabilities of a surface defined by the core or 431extensions, call: 432 433include::{generated}/api/protos/vkGetPhysicalDeviceSurfaceCapabilities2KHR.adoc[] 434 435 * pname:physicalDevice is the physical device that will be associated with 436 the swapchain to be created, as described for 437 flink:vkCreateSwapchainKHR. 438 * pname:pSurfaceInfo is a pointer to a 439 slink:VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface 440 and other fixed parameters that would be consumed by 441 flink:vkCreateSwapchainKHR. 442 * pname:pSurfaceCapabilities is a pointer to a 443 slink:VkSurfaceCapabilities2KHR structure in which the capabilities are 444 returned. 445 446fname:vkGetPhysicalDeviceSurfaceCapabilities2KHR behaves similarly to 447flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with the ability to specify 448extended inputs via chained input structures, and to return extended 449information via chained output structures. 450 451.Valid Usage 452**** 453include::{chapters}/commonvalidity/surface_info_physical_device_surfaceless_common.adoc[] 454ifdef::VK_EXT_full_screen_exclusive+VK_KHR_win32_surface[] 455 * [[VUID-vkGetPhysicalDeviceSurfaceCapabilities2KHR-pNext-02671]] 456 If a slink:VkSurfaceCapabilitiesFullScreenExclusiveEXT structure is 457 included in the pname:pNext chain of pname:pSurfaceCapabilities, a 458 slink:VkSurfaceFullScreenExclusiveWin32InfoEXT structure must: be 459 included in the pname:pNext chain of pname:pSurfaceInfo 460endif::VK_EXT_full_screen_exclusive+VK_KHR_win32_surface[] 461ifdef::VK_EXT_surface_maintenance1[] 462 * [[VUID-vkGetPhysicalDeviceSurfaceCapabilities2KHR-pNext-07776]] 463 If a slink:VkSurfacePresentModeCompatibilityEXT structure is included in 464 the pname:pNext chain of pname:pSurfaceCapabilities, a 465 slink:VkSurfacePresentModeEXT structure must: be included in the 466 pname:pNext chain of pname:pSurfaceInfo 467 * [[VUID-vkGetPhysicalDeviceSurfaceCapabilities2KHR-pNext-07777]] 468 If a slink:VkSurfacePresentScalingCapabilitiesEXT structure is included 469 in the pname:pNext chain of pname:pSurfaceCapabilities, a 470 slink:VkSurfacePresentModeEXT structure must: be included in the 471 pname:pNext chain of pname:pSurfaceInfo 472ifdef::VK_GOOGLE_surfaceless_query[] 473 * [[VUID-vkGetPhysicalDeviceSurfaceCapabilities2KHR-pNext-07778]] 474 If a slink:VkSurfacePresentModeCompatibilityEXT structure is included in 475 the pname:pNext chain of pname:pSurfaceCapabilities, 476 pname:pSurfaceInfo->surface must: be a valid slink:VkSurfaceKHR handle 477 * [[VUID-vkGetPhysicalDeviceSurfaceCapabilities2KHR-pNext-07779]] 478 If a slink:VkSurfacePresentScalingCapabilitiesEXT structure is included 479 in the pname:pNext chain of pname:pSurfaceCapabilities, 480 pname:pSurfaceInfo->surface must: be a valid slink:VkSurfaceKHR handle 481endif::VK_GOOGLE_surfaceless_query[] 482endif::VK_EXT_surface_maintenance1[] 483**** 484 485include::{generated}/validity/protos/vkGetPhysicalDeviceSurfaceCapabilities2KHR.adoc[] 486-- 487 488[open,refpage='VkPhysicalDeviceSurfaceInfo2KHR',desc='Structure specifying a surface and related swapchain creation parameters',type='structs'] 489-- 490The sname:VkPhysicalDeviceSurfaceInfo2KHR structure is defined as: 491 492include::{generated}/api/structs/VkPhysicalDeviceSurfaceInfo2KHR.adoc[] 493 494 * pname:sType is the type of this structure. 495 * pname:pNext is `NULL` or a pointer to a structure extending this 496 structure. 497 * pname:surface is the surface that will be associated with the swapchain. 498 499The members of sname:VkPhysicalDeviceSurfaceInfo2KHR correspond to the 500arguments to flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with 501pname:sType and pname:pNext added for extensibility. 502 503ifdef::VK_EXT_full_screen_exclusive[] 504Additional capabilities of a surface may: be available to swapchains created 505with different full-screen exclusive settings - particularly if exclusive 506full-screen access is application controlled. 507These additional capabilities can: be queried by adding a 508slink:VkSurfaceFullScreenExclusiveInfoEXT structure to the pname:pNext chain 509of this structure when used to query surface properties. 510ifdef::VK_KHR_win32_surface[] 511Additionally, for Win32 surfaces with application controlled exclusive 512full-screen access, chaining a 513slink:VkSurfaceFullScreenExclusiveWin32InfoEXT structure may: also report 514additional surface capabilities. 515endif::VK_KHR_win32_surface[] 516These additional capabilities only apply to swapchains created with the same 517parameters included in the pname:pNext chain of 518slink:VkSwapchainCreateInfoKHR. 519endif::VK_EXT_full_screen_exclusive[] 520 521.Valid Usage 522**** 523ifdef::VK_KHR_win32_surface+VK_EXT_full_screen_exclusive[] 524 * [[VUID-VkPhysicalDeviceSurfaceInfo2KHR-pNext-02672]] 525 If the pname:pNext chain includes a 526 slink:VkSurfaceFullScreenExclusiveInfoEXT structure with its 527 pname:fullScreenExclusive member set to 528 ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT, and 529 pname:surface was created using flink:vkCreateWin32SurfaceKHR, a 530 slink:VkSurfaceFullScreenExclusiveWin32InfoEXT structure must: be 531 included in the pname:pNext chain 532endif::VK_KHR_win32_surface+VK_EXT_full_screen_exclusive[] 533ifdef::VK_GOOGLE_surfaceless_query[] 534 * [[VUID-VkPhysicalDeviceSurfaceInfo2KHR-pSurfaceInfo-06526]] 535 When passed as the pname:pSurfaceInfo parameter of 536 flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR, if the 537 `apiext:VK_GOOGLE_surfaceless_query` extension is enabled and the 538 pname:pNext chain of the pname:pSurfaceCapabilities parameter includes 539 sname:VkSurfaceProtectedCapabilitiesKHR, then pname:surface can: be 540 dlink:VK_NULL_HANDLE. 541 Otherwise, pname:surface must: be a valid slink:VkSurfaceKHR handle 542 * [[VUID-VkPhysicalDeviceSurfaceInfo2KHR-pSurfaceInfo-06527]] 543 When passed as the pname:pSurfaceInfo parameter of 544 flink:vkGetPhysicalDeviceSurfaceFormats2KHR, if the 545 `apiext:VK_GOOGLE_surfaceless_query` extension is enabled, then 546 pname:surface can: be dlink:VK_NULL_HANDLE. 547 Otherwise, pname:surface must: be a valid slink:VkSurfaceKHR handle 548 * [[VUID-VkPhysicalDeviceSurfaceInfo2KHR-pSurfaceInfo-06528]] 549 When passed as the pname:pSurfaceInfo parameter of 550 flink:vkGetPhysicalDeviceSurfacePresentModes2EXT, if the 551 `apiext:VK_GOOGLE_surfaceless_query` extension is enabled, then 552 pname:surface can: be dlink:VK_NULL_HANDLE. 553 Otherwise, pname:surface must: be a valid slink:VkSurfaceKHR handle 554endif::VK_GOOGLE_surfaceless_query[] 555ifndef::VK_GOOGLE_surfaceless_query[] 556 * [[VUID-VkPhysicalDeviceSurfaceInfo2KHR-surface-06529]] 557 pname:surface must: be a valid slink:VkSurfaceKHR handle 558endif::VK_GOOGLE_surfaceless_query[] 559**** 560 561include::{generated}/validity/structs/VkPhysicalDeviceSurfaceInfo2KHR.adoc[] 562-- 563 564ifdef::VK_EXT_full_screen_exclusive[] 565[open,refpage='VkSurfaceFullScreenExclusiveInfoEXT',desc='Structure specifying the preferred full-screen transition behavior',type='structs'] 566-- 567If the pname:pNext chain of slink:VkSwapchainCreateInfoKHR includes a 568sname:VkSurfaceFullScreenExclusiveInfoEXT structure, then that structure 569specifies the application's preferred full-screen transition behavior. 570 571The sname:VkSurfaceFullScreenExclusiveInfoEXT structure is defined as: 572 573include::{generated}/api/structs/VkSurfaceFullScreenExclusiveInfoEXT.adoc[] 574 575 * pname:sType is the type of this structure. 576 * pname:pNext is `NULL` or a pointer to a structure extending this 577 structure. 578 * pname:fullScreenExclusive is a elink:VkFullScreenExclusiveEXT value 579 specifying the preferred full-screen transition behavior. 580 581If this structure is not present, pname:fullScreenExclusive is considered to 582be ename:VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT. 583 584include::{generated}/validity/structs/VkSurfaceFullScreenExclusiveInfoEXT.adoc[] 585-- 586 587[open,refpage='VkFullScreenExclusiveEXT',desc='Hint values an application can specify affecting full-screen transition behavior',type='enums'] 588-- 589Possible values of 590sname:VkSurfaceFullScreenExclusiveInfoEXT::pname:fullScreenExclusive are: 591 592include::{generated}/api/enums/VkFullScreenExclusiveEXT.adoc[] 593 594 * ename:VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT indicates the implementation 595 should: determine the appropriate full-screen method by whatever means 596 it deems appropriate. 597 * ename:VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT indicates the implementation 598 may: use full-screen exclusive mechanisms when available. 599 Such mechanisms may: result in better performance and/or the 600 availability of different presentation capabilities, but may: require a 601 more disruptive transition during swapchain initialization, first 602 presentation and/or destruction. 603 * ename:VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT indicates the 604 implementation should: avoid using full-screen mechanisms which rely on 605 disruptive transitions. 606 * ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT indicates the 607 application will manage full-screen exclusive mode by using the 608 flink:vkAcquireFullScreenExclusiveModeEXT and 609 flink:vkReleaseFullScreenExclusiveModeEXT commands. 610-- 611 612ifdef::VK_KHR_win32_surface[] 613[open,refpage='VkSurfaceFullScreenExclusiveWin32InfoEXT',desc='Structure specifying additional creation parameters specific to Win32 fullscreen exclusive mode',type='structs'] 614-- 615The sname:VkSurfaceFullScreenExclusiveWin32InfoEXT structure is defined as: 616 617include::{generated}/api/structs/VkSurfaceFullScreenExclusiveWin32InfoEXT.adoc[] 618 619 * pname:sType is the type of this structure. 620 * pname:pNext is `NULL` or a pointer to a structure extending this 621 structure. 622 * pname:hmonitor is the Win32 code:HMONITOR handle identifying the display 623 to create the surface with. 624 625[NOTE] 626.Note 627==== 628If pname:hmonitor is invalidated (e.g. the monitor is unplugged) during the 629lifetime of a swapchain created with this structure, operations on that 630swapchain will return ename:VK_ERROR_OUT_OF_DATE_KHR. 631==== 632 633[NOTE] 634.Note 635==== 636It is the responsibility of the application to change the display settings 637of the targeted Win32 display using the appropriate platform APIs. 638Such changes may: alter the surface capabilities reported for the created 639surface. 640==== 641 642.Valid Usage 643**** 644 * [[VUID-VkSurfaceFullScreenExclusiveWin32InfoEXT-hmonitor-02673]] 645 pname:hmonitor must: be a valid code:HMONITOR 646**** 647 648include::{generated}/validity/structs/VkSurfaceFullScreenExclusiveWin32InfoEXT.adoc[] 649-- 650endif::VK_KHR_win32_surface[] 651endif::VK_EXT_full_screen_exclusive[] 652 653[open,refpage='VkSurfaceCapabilities2KHR',desc='Structure describing capabilities of a surface',type='structs'] 654-- 655The sname:VkSurfaceCapabilities2KHR structure is defined as: 656 657include::{generated}/api/structs/VkSurfaceCapabilities2KHR.adoc[] 658 659 * pname:sType is the type of this structure. 660 * pname:pNext is `NULL` or a pointer to a structure extending this 661 structure. 662 * pname:surfaceCapabilities is a slink:VkSurfaceCapabilitiesKHR structure 663 describing the capabilities of the specified surface. 664 665ifdef::VK_GOOGLE_surfaceless_query[] 666If the `apiext:VK_GOOGLE_surfaceless_query` extension is enabled and 667slink:VkPhysicalDeviceSurfaceInfo2KHR::pname:surface in the 668flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR call is 669dlink:VK_NULL_HANDLE, the values returned in pname:minImageCount, 670pname:maxImageCount, pname:currentExtent, and pname:currentTransform will 671not reflect that of any surface and will instead be as such: 672 673 * pname:minImageCount and pname:maxImageCount will be [eq]#0xFFFFFFFF# 674 * pname:currentExtent will be [eq]#(0xFFFFFFFF, 0xFFFFFFFF)# 675 * pname:currentTransform will be 676 ename:VK_SURFACE_TRANSFORM_INHERIT_BIT_KHR 677endif::VK_GOOGLE_surfaceless_query[] 678 679include::{generated}/validity/structs/VkSurfaceCapabilities2KHR.adoc[] 680-- 681 682ifdef::VK_KHR_surface_protected_capabilities[] 683[open,refpage='VkSurfaceProtectedCapabilitiesKHR',desc='Structure describing capability of a surface to be protected',type='structs'] 684-- 685An application queries if a protected slink:VkSurfaceKHR is displayable on a 686specific windowing system using sname:VkSurfaceProtectedCapabilitiesKHR, 687which can: be passed in pname:pNext parameter of 688sname:VkSurfaceCapabilities2KHR. 689 690The sname:VkSurfaceProtectedCapabilitiesKHR structure is defined as: 691 692include::{generated}/api/structs/VkSurfaceProtectedCapabilitiesKHR.adoc[] 693 694 * pname:sType is the type of this structure. 695 * pname:pNext is `NULL` or a pointer to a structure extending this 696 structure. 697 * pname:supportsProtected specifies whether a protected swapchain created 698 from slink:VkPhysicalDeviceSurfaceInfo2KHR::pname:surface for a 699 particular windowing system can: be displayed on screen or not. 700 If pname:supportsProtected is ename:VK_TRUE, then creation of swapchains 701 with the ename:VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR flag set must: be 702 supported for pname:surface. 703 704ifdef::VK_GOOGLE_surfaceless_query[] 705If the `apiext:VK_GOOGLE_surfaceless_query` extension is enabled, the value 706returned in pname:supportsProtected will be identical for every valid 707surface created on this physical device, and so in the 708flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR call, 709slink:VkPhysicalDeviceSurfaceInfo2KHR::pname:surface can: be 710dlink:VK_NULL_HANDLE. 711In that case, the contents of 712slink:VkSurfaceCapabilities2KHR::pname:surfaceCapabilities as well as any 713other struct chained to it will be undefined:. 714endif::VK_GOOGLE_surfaceless_query[] 715 716include::{generated}/validity/structs/VkSurfaceProtectedCapabilitiesKHR.adoc[] 717-- 718endif::VK_KHR_surface_protected_capabilities[] 719 720ifdef::VK_EXT_surface_maintenance1[] 721[open,refpage='VkSurfacePresentScalingCapabilitiesEXT',desc='Structure describing the presentation scaling capabilities of the surface',type='structs'] 722-- 723The sname:VkSurfacePresentScalingCapabilitiesEXT structure is defined as: 724 725include::{generated}/api/structs/VkSurfacePresentScalingCapabilitiesEXT.adoc[] 726 727 * pname:sType is the type of this structure. 728 * pname:pNext is `NULL` or a pointer to a structure extending this 729 structure. 730 * pname:supportedPresentScaling is a bitmask of 731 elink:VkPresentScalingFlagBitsEXT representing the scaling methods 732 supported by the surface, or `0` if application-defined scaling is not 733 supported. 734 * pname:supportedPresentGravityX is a bitmask of 735 elink:VkPresentGravityFlagBitsEXT representing the X-axis pixel gravity 736 supported by the surface, or `0` if Vulkan-defined pixel gravity is not 737 supported for the X axis. 738 * pname:supportedPresentGravityY is a bitmask of 739 elink:VkPresentGravityFlagBitsEXT representing the Y-axis pixel gravity 740 supported by the surface, or `0` if Vulkan-defined pixel gravity is not 741 supported for the Y axis. 742 * pname:minScaledImageExtent contains the smallest valid swapchain extent 743 for the surface on the specified device when one of the scaling methods 744 specified in pname:supportedPresentScaling is used, or the special value 745 [eq]#(0xFFFFFFFF, 0xFFFFFFFF)# indicating that the surface size will be 746 determined by the extent of a swapchain targeting the surface. 747 The pname:width and pname:height of the extent will each be smaller than 748 or equal to the corresponding pname:width and pname:height of 749 slink:VkSurfaceCapabilitiesKHR::pname:minImageExtent. 750 * pname:maxScaledImageExtent contains the largest valid swapchain extent 751 for the surface on the specified device when one of the scaling methods 752 specified in pname:supportedPresentScaling is used, or the special value 753 described above for pname:minScaledImageExtent. 754 The pname:width and pname:height of the extent will each be greater than 755 or equal to the corresponding pname:width and pname:height of 756 slink:VkSurfaceCapabilitiesKHR::pname:maxImageExtent. 757 758ifdef::VK_EXT_swapchain_maintenance1[] 759Before creating a swapchain whose scaling mode can: be specified through the 760use of slink:VkSwapchainPresentScalingCreateInfoEXT, obtain the set of 761supported scaling modes by including a slink:VkSurfacePresentModeEXT 762structure in the pname:pNext chain of slink:VkPhysicalDeviceSurfaceInfo2KHR 763when calling flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR. 764The implementation must: return the same values in 765sname:VkSurfacePresentScalingCapabilitiesEXT for any of the compatible 766present modes as obtained through 767slink:VkSurfacePresentModeCompatibilityEXT. 768endif::VK_EXT_swapchain_maintenance1[] 769 770include::{generated}/validity/structs/VkSurfacePresentScalingCapabilitiesEXT.adoc[] 771-- 772 773[open,refpage='VkPresentScalingFlagBitsEXT',desc='Bitmask specifying presentation scaling methods',type='enums'] 774-- 775Bits which may: be set in 776slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentScaling, 777specifying scaling modes supported by the surface, are: 778 779include::{generated}/api/enums/VkPresentScalingFlagBitsEXT.adoc[] 780 781 * ename:VK_PRESENT_SCALING_ONE_TO_ONE_BIT_EXT specifies that no scaling 782 occurs, and pixels in the swapchain image are mapped to one and only one 783 pixel in the surface. 784 The mapping between pixels is defined by the chosen presentation 785 gravity. 786 * ename:VK_PRESENT_SCALING_ASPECT_RATIO_STRETCH_BIT_EXT specifies that the 787 swapchain image will be minified or magnified such that at least one of 788 the resulting width or height is equal to the corresponding surface 789 dimension, and the other resulting dimension is less than or equal to 790 the corresponding surface dimension, with the aspect ratio of the 791 resulting image being identical to that of the original swapchain image. 792 * ename:VK_PRESENT_SCALING_STRETCH_BIT_EXT specifies that the swapchain 793 image will be minified or magnified such that the resulting image 794 dimensions are equal to those of the surface. 795-- 796 797[open,refpage='VkPresentScalingFlagsEXT',desc='Bitmask of VkPresentScalingFlagBitsEXT',type='flags'] 798-- 799include::{generated}/api/flags/VkPresentScalingFlagsEXT.adoc[] 800 801tname:VkPresentScalingFlagsEXT is a bitmask type for setting a mask of zero 802or more elink:VkPresentScalingFlagBitsEXT. 803-- 804 805[open,refpage='VkPresentGravityFlagBitsEXT',desc='Bitmask specifying presentation pixel gravity on either the x or y axis',type='enums'] 806-- 807Bits which may: be set in the 808slink:VkSurfacePresentScalingCapabilitiesEXT::pname:supportedPresentGravityX 809or pname:supportedPresentGravityY fields, specifying the gravity of 810presented pixels supported by the surface, are: 811 812include::{generated}/api/enums/VkPresentGravityFlagBitsEXT.adoc[] 813 814 * ename:VK_PRESENT_GRAVITY_MIN_BIT_EXT means that the pixels will 815 gravitate towards the top or left side of the surface. 816 * ename:VK_PRESENT_GRAVITY_MAX_BIT_EXT means that the pixels will 817 gravitate towards the bottom or right side of the surface. 818 * ename:VK_PRESENT_GRAVITY_CENTERED_BIT_EXT means that the pixels will be 819 centered in the surface. 820 821If the value in slink:VkSurfaceCapabilitiesKHR::pname:currentTransform is 822not ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, it is 823implementation-defined whether the gravity configuration applies to the 824presented image before or after transformation. 825-- 826 827[open,refpage='VkPresentGravityFlagsEXT',desc='Bitmask of VkPresentGravityFlagBitsEXT',type='flags'] 828-- 829include::{generated}/api/flags/VkPresentGravityFlagsEXT.adoc[] 830 831tname:VkPresentGravityFlagsEXT is a bitmask type for setting a mask of zero 832or more elink:VkPresentGravityFlagBitsEXT. 833-- 834 835[open,refpage='VkSurfacePresentModeEXT',desc='Structure describing present mode of a surface',type='structs'] 836-- 837The sname:VkSurfacePresentModeEXT structure is defined as: 838 839include::{generated}/api/structs/VkSurfacePresentModeEXT.adoc[] 840 841 * pname:sType is the type of this structure. 842 * pname:pNext is `NULL` or a pointer to a structure extending this 843 structure. 844 * pname:presentMode is the presentation mode the swapchain will use. 845 846If the sname:VkSurfacePresentModeEXT structure is included in the 847pname:pNext chain of slink:VkPhysicalDeviceSurfaceInfo2KHR, the values 848returned in slink:VkSurfaceCapabilitiesKHR::pname:minImageCount, 849slink:VkSurfaceCapabilitiesKHR::pname:maxImageCount, 850slink:VkSurfacePresentScalingCapabilitiesEXT::pname:minScaledImageExtent, 851and slink:VkSurfacePresentScalingCapabilitiesEXT::pname:maxScaledImageExtent 852are valid only for the specified pname:presentMode. 853ifdef::VK_KHR_shared_presentable_image[] 854If pname:presentMode is ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or 855ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, the per-present mode 856image counts must: both be one. 857endif::VK_KHR_shared_presentable_image[] 858The per-present mode image counts may: be less-than or greater-than the 859image counts returned when sname:VkSurfacePresentModeEXT is not provided. 860 861[NOTE] 862.Note 863==== 864If slink:VkSwapchainPresentModesCreateInfoEXT is provided to swapchain 865creation, the requirements for forward progress may be less strict. 866For example, a FIFO swapchain might only require 2 images to guarantee 867forward progress, but a MAILBOX one might require 4. 868Without the per-present image counts, such an implementation would have to 869return 4 in slink:VkSurfaceCapabilitiesKHR::pname:minImageCount, which 870pessimizes FIFO. 871Conversely, an implementation may return a low number for minImageCount, but 872internally bump the image count when application queries 873flink:vkGetSwapchainImagesKHR, which can surprise applications, and is not 874discoverable until swapchain creation. 875Using sname:VkSurfacePresentModeEXT and 876slink:VkSwapchainPresentModesCreateInfoEXT together effectively removes this 877problem. 878 879slink:VkSwapchainPresentModesCreateInfoEXT is required for the specification 880to be backwards compatible with applications that do not know about, or make 881use of this feature. 882==== 883 884.Valid Usage 885**** 886 * [[VUID-VkSurfacePresentModeEXT-presentMode-07780]] 887 pname:presentMode must: be a value reported by 888 flink:vkGetPhysicalDeviceSurfacePresentModesKHR for the specified 889 surface. 890**** 891 892include::{generated}/validity/structs/VkSurfacePresentModeEXT.adoc[] 893-- 894 895[open,refpage='VkSurfacePresentModeCompatibilityEXT',desc='Structure describing the subset of compatible presentation modes for the purposes of switching without swapchain recreation',type='structs'] 896-- 897The sname:VkSurfacePresentModeCompatibilityEXT structure is defined as: 898 899include::{generated}/api/structs/VkSurfacePresentModeCompatibilityEXT.adoc[] 900 901 * pname:sType is the type of this structure. 902 * pname:pNext is `NULL` or a pointer to a structure extending this 903 structure. 904 * pname:presentModeCount is an integer related to the number of present 905 modes available or queried, as described below. 906 * pname:pPresentModes is a pointer to an array of elink:VkPresentModeKHR 907 in which present modes compatible with a given present mode are 908 returned. 909 910If pname:pPresentModes is `NULL`, then the number of present modes that are 911compatible with the one specified in slink:VkSurfacePresentModeEXT is 912returned in pname:presentModeCount. 913Otherwise, pname:presentModeCount must be set by the user to the number of 914elements in the pname:pPresentModes array, and on return the variable is 915overwritten with the number of values actually written to 916pname:pPresentModes. 917If the value of pname:presentModeCount is less than the number of compatible 918present modes that are supported, at most pname:presentModeCount values will 919be written to pname:pPresentModes. 920The implementation must: include the present mode passed to 921slink:VkSurfacePresentModeEXT in pname:pPresentModes, unless 922pname:presentModeCount is zero. 923 924ifdef::VK_EXT_swapchain_maintenance1[] 925Before creating a swapchain whose present modes can: be modified through the 926use of slink:VkSwapchainPresentModesCreateInfoEXT, obtain the set of present 927modes compatible with a given initial present mode by including a 928slink:VkSurfacePresentModeEXT structure in the pname:pNext chain of 929slink:VkPhysicalDeviceSurfaceInfo2KHR when calling 930flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR. 931endif::VK_EXT_swapchain_maintenance1[] 932 933include::{generated}/validity/structs/VkSurfacePresentModeCompatibilityEXT.adoc[] 934-- 935endif::VK_EXT_surface_maintenance1[] 936 937ifdef::VK_KHR_shared_presentable_image[] 938[open,refpage='VkSharedPresentSurfaceCapabilitiesKHR',desc='Structure describing capabilities of a surface for shared presentation',type='structs'] 939-- 940The sname:VkSharedPresentSurfaceCapabilitiesKHR structure is defined as: 941 942include::{generated}/api/structs/VkSharedPresentSurfaceCapabilitiesKHR.adoc[] 943 944 * pname:sType is the type of this structure. 945 * pname:pNext is `NULL` or a pointer to a structure extending this 946 structure. 947 * pname:sharedPresentSupportedUsageFlags is a bitmask of 948 elink:VkImageUsageFlagBits representing the ways the application can: 949 use the shared presentable image from a swapchain created with 950 elink:VkPresentModeKHR set to 951 ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or 952 ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR for the surface on 953 the specified device. 954 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT must: be included in the set 955 but implementations may: support additional usages. 956 957include::{generated}/validity/structs/VkSharedPresentSurfaceCapabilitiesKHR.adoc[] 958-- 959endif::VK_KHR_shared_presentable_image[] 960 961ifdef::VK_AMD_display_native_hdr[] 962[open,refpage='VkDisplayNativeHdrSurfaceCapabilitiesAMD',desc='Structure describing display native HDR specific capabilities of a surface',type='structs'] 963-- 964The sname:VkDisplayNativeHdrSurfaceCapabilitiesAMD structure is defined as: 965 966include::{generated}/api/structs/VkDisplayNativeHdrSurfaceCapabilitiesAMD.adoc[] 967 968 * pname:sType is the type of this structure. 969 * pname:pNext is `NULL` or a pointer to a structure extending this 970 structure. 971 * pname:localDimmingSupport specifies whether the surface supports local 972 dimming. 973 If this is ename:VK_TRUE, slink:VkSwapchainDisplayNativeHdrCreateInfoAMD 974 can: be used to explicitly enable or disable local dimming for the 975 surface. 976 Local dimming may also be overridden by flink:vkSetLocalDimmingAMD 977 during the lifetime of the swapchain. 978 979include::{generated}/validity/structs/VkDisplayNativeHdrSurfaceCapabilitiesAMD.adoc[] 980-- 981endif::VK_AMD_display_native_hdr[] 982 983ifdef::VK_EXT_full_screen_exclusive[] 984[open,refpage='VkSurfaceCapabilitiesFullScreenExclusiveEXT',desc='Structure describing full screen exclusive capabilities of a surface',type='structs'] 985-- 986The sname:VkSurfaceCapabilitiesFullScreenExclusiveEXT structure is defined 987as: 988 989include::{generated}/api/structs/VkSurfaceCapabilitiesFullScreenExclusiveEXT.adoc[] 990 991 * pname:sType is the type of this structure. 992 * pname:pNext is `NULL` or a pointer to a structure extending this 993 structure. 994 * pname:fullScreenExclusiveControlSupported is a boolean describing 995 whether the surface is able to make use of exclusive full-screen access. 996 997This structure can: be included in the pname:pNext chain of 998slink:VkSurfaceCapabilities2KHR to determine support for exclusive 999full-screen access. 1000If pname:fullScreenExclusiveSupported is ename:VK_FALSE, it indicates that 1001exclusive full-screen access is not obtainable for this surface. 1002 1003Applications must: not attempt to create swapchains with 1004ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT set if 1005pname:fullScreenExclusiveSupported is ename:VK_FALSE. 1006 1007include::{generated}/validity/structs/VkSurfaceCapabilitiesFullScreenExclusiveEXT.adoc[] 1008-- 1009endif::VK_EXT_full_screen_exclusive[] 1010 1011ifdef::VK_NV_present_barrier[] 1012[open,refpage='VkSurfaceCapabilitiesPresentBarrierNV',desc='Structure describing present barrier capabilities of a surface',type='structs'] 1013-- 1014The sname:VkSurfaceCapabilitiesPresentBarrierNV structure is defined as: 1015 1016include::{generated}/api/structs/VkSurfaceCapabilitiesPresentBarrierNV.adoc[] 1017 1018 * pname:sType is the type of this structure. 1019 * pname:pNext is `NULL` or a pointer to a structure extending this 1020 structure. 1021 * pname:presentBarrierSupported is a boolean describing whether the 1022 surface is able to make use of the present barrier feature. 1023 1024This structure can: be included in the pname:pNext chain of 1025slink:VkSurfaceCapabilities2KHR to determine support for present barrier 1026access. 1027If pname:presentBarrierSupported is ename:VK_FALSE, it indicates that the 1028present barrier feature is not obtainable for this surface. 1029 1030include::{generated}/validity/structs/VkSurfaceCapabilitiesPresentBarrierNV.adoc[] 1031-- 1032endif::VK_NV_present_barrier[] 1033endif::VK_KHR_get_surface_capabilities2[] 1034 1035ifdef::VK_EXT_display_surface_counter[] 1036include::{chapters}/VK_EXT_display_surface_counter/surface_capabilities.adoc[] 1037endif::VK_EXT_display_surface_counter[] 1038 1039[open,refpage='VkSurfaceTransformFlagBitsKHR',desc='Presentation transforms supported on a device',type='enums'] 1040-- 1041Bits which may: be set in 1042slink:VkSurfaceCapabilitiesKHR::pname:supportedTransforms indicating the 1043presentation transforms supported for the surface on the specified device, 1044and possible values of 1045slink:VkSurfaceCapabilitiesKHR::pname:currentTransform indicating the 1046surface's current transform relative to the presentation engine's natural 1047orientation, are: 1048 1049include::{generated}/api/enums/VkSurfaceTransformFlagBitsKHR.adoc[] 1050 1051 * ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR specifies that image content 1052 is presented without being transformed. 1053 * ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR specifies that image 1054 content is rotated 90 degrees clockwise. 1055 * ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR specifies that image 1056 content is rotated 180 degrees clockwise. 1057 * ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR specifies that image 1058 content is rotated 270 degrees clockwise. 1059 * ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR specifies that 1060 image content is mirrored horizontally. 1061 * ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR specifies 1062 that image content is mirrored horizontally, then rotated 90 degrees 1063 clockwise. 1064 * ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR 1065 specifies that image content is mirrored horizontally, then rotated 180 1066 degrees clockwise. 1067 * ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR 1068 specifies that image content is mirrored horizontally, then rotated 270 1069 degrees clockwise. 1070 * ename:VK_SURFACE_TRANSFORM_INHERIT_BIT_KHR specifies that the 1071 presentation transform is not specified, and is instead determined by 1072 platform-specific considerations and mechanisms outside Vulkan. 1073-- 1074 1075[open,refpage='VkSurfaceTransformFlagsKHR',desc='Bitmask of VkSurfaceTransformFlagBitsKHR',type='flags'] 1076-- 1077include::{generated}/api/flags/VkSurfaceTransformFlagsKHR.adoc[] 1078 1079tname:VkSurfaceTransformFlagsKHR is a bitmask type for setting a mask of 1080zero or more elink:VkSurfaceTransformFlagBitsKHR. 1081-- 1082 1083[open,refpage='VkCompositeAlphaFlagBitsKHR',desc='Alpha compositing modes supported on a device',type='enums'] 1084-- 1085The pname:supportedCompositeAlpha member is of type 1086elink:VkCompositeAlphaFlagBitsKHR, containing the following values: 1087 1088include::{generated}/api/enums/VkCompositeAlphaFlagBitsKHR.adoc[] 1089 1090These values are described as follows: 1091 1092 * ename:VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha component, if it 1093 exists, of the images is ignored in the compositing process. 1094 Instead, the image is treated as if it has a constant alpha of 1.0. 1095 * ename:VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha component, if 1096 it exists, of the images is respected in the compositing process. 1097 The non-alpha components of the image are expected to already be 1098 multiplied by the alpha component by the application. 1099 * ename:VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha component, 1100 if it exists, of the images is respected in the compositing process. 1101 The non-alpha components of the image are not expected to already be 1102 multiplied by the alpha component by the application; instead, the 1103 compositor will multiply the non-alpha components of the image by the 1104 alpha component during compositing. 1105 * ename:VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the 1106 presentation engine treats the alpha component in the images is unknown 1107 to the Vulkan API. 1108 Instead, the application is responsible for setting the composite alpha 1109 blending mode using native window system commands. 1110 If the application does not set the blending mode using native window 1111 system commands, then a platform-specific default will be used. 1112-- 1113 1114[open,refpage='VkCompositeAlphaFlagsKHR',desc='Bitmask of VkCompositeAlphaFlagBitsKHR',type='flags'] 1115-- 1116include::{generated}/api/flags/VkCompositeAlphaFlagsKHR.adoc[] 1117 1118tname:VkCompositeAlphaFlagsKHR is a bitmask type for setting a mask of zero 1119or more elink:VkCompositeAlphaFlagBitsKHR. 1120-- 1121 1122 1123=== Surface Format Support 1124 1125[open,refpage='vkGetPhysicalDeviceSurfaceFormatsKHR',desc='Query color formats supported by surface',type='protos'] 1126-- 1127:refpage: vkGetPhysicalDeviceSurfaceFormatsKHR 1128 1129To query the supported swapchain format-color space pairs for a surface, 1130call: 1131 1132include::{generated}/api/protos/vkGetPhysicalDeviceSurfaceFormatsKHR.adoc[] 1133 1134 * pname:physicalDevice is the physical device that will be associated with 1135 the swapchain to be created, as described for 1136 flink:vkCreateSwapchainKHR. 1137 * pname:surface is the surface that will be associated with the swapchain. 1138 * pname:pSurfaceFormatCount is a pointer to an integer related to the 1139 number of format pairs available or queried, as described below. 1140 * pname:pSurfaceFormats is either `NULL` or a pointer to an array of 1141 sname:VkSurfaceFormatKHR structures. 1142 1143If pname:pSurfaceFormats is `NULL`, then the number of format pairs 1144supported for the given pname:surface is returned in 1145pname:pSurfaceFormatCount. 1146Otherwise, pname:pSurfaceFormatCount must: point to a variable set by the 1147user to the number of elements in the pname:pSurfaceFormats array, and on 1148return the variable is overwritten with the number of structures actually 1149written to pname:pSurfaceFormats. 1150If the value of pname:pSurfaceFormatCount is less than the number of format 1151pairs supported, at most pname:pSurfaceFormatCount structures will be 1152written, and ename:VK_INCOMPLETE will be returned instead of 1153ename:VK_SUCCESS, to indicate that not all the available format pairs were 1154returned. 1155 1156The number of format pairs supported must: be greater than or equal to 1. 1157pname:pSurfaceFormats must: not contain an entry whose value for 1158pname:format is ename:VK_FORMAT_UNDEFINED. 1159 1160If pname:pSurfaceFormats includes an entry whose value for pname:colorSpace 1161is ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR and whose value for pname:format 1162is a UNORM (or SRGB) format and the corresponding SRGB (or UNORM) format is 1163a color renderable format for ename:VK_IMAGE_TILING_OPTIMAL, then 1164pname:pSurfaceFormats must: also contain an entry with the same value for 1165pname:colorSpace and pname:format equal to the corresponding SRGB (or UNORM) 1166format. 1167 1168ifdef::VK_GOOGLE_surfaceless_query[] 1169If the `apiext:VK_GOOGLE_surfaceless_query` extension is enabled, the values 1170returned in pname:pSurfaceFormats will be identical for every valid surface 1171created on this physical device, and so pname:surface can: be 1172dlink:VK_NULL_HANDLE. 1173endif::VK_GOOGLE_surfaceless_query[] 1174 1175.Valid Usage 1176**** 1177include::{chapters}/commonvalidity/surface_physical_device_surfaceless_common.adoc[] 1178**** 1179 1180include::{generated}/validity/protos/vkGetPhysicalDeviceSurfaceFormatsKHR.adoc[] 1181-- 1182 1183[open,refpage='VkSurfaceFormatKHR',desc='Structure describing a supported swapchain format-color space pair',type='structs'] 1184-- 1185The sname:VkSurfaceFormatKHR structure is defined as: 1186 1187include::{generated}/api/structs/VkSurfaceFormatKHR.adoc[] 1188 1189 * pname:format is a elink:VkFormat that is compatible with the specified 1190 surface. 1191 * pname:colorSpace is a presentation elink:VkColorSpaceKHR that is 1192 compatible with the surface. 1193 1194include::{generated}/validity/structs/VkSurfaceFormatKHR.adoc[] 1195-- 1196 1197ifdef::VK_KHR_get_surface_capabilities2[] 1198[open,refpage='vkGetPhysicalDeviceSurfaceFormats2KHR',desc='Query color formats supported by surface',type='protos'] 1199-- 1200:refpage: vkGetPhysicalDeviceSurfaceFormats2KHR 1201 1202To query the supported swapchain format tuples for a surface, call: 1203 1204include::{generated}/api/protos/vkGetPhysicalDeviceSurfaceFormats2KHR.adoc[] 1205 1206 * pname:physicalDevice is the physical device that will be associated with 1207 the swapchain to be created, as described for 1208 flink:vkCreateSwapchainKHR. 1209 * pname:pSurfaceInfo is a pointer to a 1210 slink:VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface 1211 and other fixed parameters that would be consumed by 1212 flink:vkCreateSwapchainKHR. 1213 * pname:pSurfaceFormatCount is a pointer to an integer related to the 1214 number of format tuples available or queried, as described below. 1215 * pname:pSurfaceFormats is either `NULL` or a pointer to an array of 1216 slink:VkSurfaceFormat2KHR structures. 1217 1218flink:vkGetPhysicalDeviceSurfaceFormats2KHR behaves similarly to 1219flink:vkGetPhysicalDeviceSurfaceFormatsKHR, with the ability to be extended 1220via pname:pNext chains. 1221 1222If pname:pSurfaceFormats is `NULL`, then the number of format tuples 1223supported for the given pname:surface is returned in 1224pname:pSurfaceFormatCount. 1225Otherwise, pname:pSurfaceFormatCount must: point to a variable set by the 1226user to the number of elements in the pname:pSurfaceFormats array, and on 1227return the variable is overwritten with the number of structures actually 1228written to pname:pSurfaceFormats. 1229If the value of pname:pSurfaceFormatCount is less than the number of format 1230tuples supported, at most pname:pSurfaceFormatCount structures will be 1231written, and ename:VK_INCOMPLETE will be returned instead of 1232ename:VK_SUCCESS, to indicate that not all the available values were 1233returned. 1234 1235.Valid Usage 1236**** 1237include::{chapters}/commonvalidity/surface_info_physical_device_surfaceless_common.adoc[] 1238**** 1239 1240include::{generated}/validity/protos/vkGetPhysicalDeviceSurfaceFormats2KHR.adoc[] 1241-- 1242 1243[open,refpage='VkSurfaceFormat2KHR',desc='Structure describing a supported swapchain format tuple',type='structs'] 1244-- 1245The sname:VkSurfaceFormat2KHR structure is defined as: 1246 1247include::{generated}/api/structs/VkSurfaceFormat2KHR.adoc[] 1248 1249 * pname:sType is the type of this structure. 1250 * pname:pNext is `NULL` or a pointer to a structure extending this 1251 structure. 1252 * pname:surfaceFormat is a slink:VkSurfaceFormatKHR structure describing a 1253 format-color space pair that is compatible with the specified surface. 1254 1255ifdef::VK_EXT_image_compression_control[] 1256.Valid Usage 1257**** 1258ifndef::VK_EXT_image_compression_control_swapchain[] 1259 * [[VUID-VkSurfaceFormat2KHR-pNext-06749]] 1260 The pname:pNext chain must: not include an 1261 slink:VkImageCompressionPropertiesEXT structure 1262endif::VK_EXT_image_compression_control_swapchain[] 1263ifdef::VK_EXT_image_compression_control_swapchain[] 1264 * [[VUID-VkSurfaceFormat2KHR-pNext-06750]] 1265 If the <<features-imageCompressionControlSwapchain, 1266 pname:imageCompressionControlSwapchain>> feature is not enabled, the 1267 pname:pNext chain must: not include an 1268 slink:VkImageCompressionPropertiesEXT structure 1269endif::VK_EXT_image_compression_control_swapchain[] 1270**** 1271endif::VK_EXT_image_compression_control[] 1272 1273include::{generated}/validity/structs/VkSurfaceFormat2KHR.adoc[] 1274-- 1275 1276ifdef::VK_EXT_image_compression_control[] 1277ifdef::VK_EXT_image_compression_control_swapchain[] 1278If the <<features-imageCompressionControlSwapchain, 1279pname:imageCompressionControlSwapchain>> feature is supported and a 1280slink:VkImageCompressionPropertiesEXT structure is included in the 1281pname:pNext chain of this structure, then it will be filled with the 1282compression properties that are supported for the pname:surfaceFormat. 1283endif::VK_EXT_image_compression_control_swapchain[] 1284endif::VK_EXT_image_compression_control[] 1285 1286endif::VK_KHR_get_surface_capabilities2[] 1287 1288While the pname:format of a presentable image refers to the encoding of each 1289pixel, the pname:colorSpace determines how the presentation engine 1290interprets the pixel values. 1291A color space in this document refers to a specific color space (defined by 1292the chromaticities of its primaries and a white point in CIE Lab), and a 1293transfer function that is applied before storing or transmitting color data 1294in the given color space. 1295 1296[open,refpage='VkColorSpaceKHR',desc='Supported color space of the presentation engine',type='enums'] 1297-- 1298Possible values of slink:VkSurfaceFormatKHR::pname:colorSpace, specifying 1299supported color spaces of a presentation engine, are: 1300 1301include::{generated}/api/enums/VkColorSpaceKHR.adoc[] 1302 1303 * ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR specifies support for the sRGB 1304 color space. 1305ifdef::VK_EXT_swapchain_colorspace[] 1306 * ename:VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT specifies support for the 1307 Display-P3 color space to be displayed using an sRGB-like EOTF (defined 1308 below). 1309 * ename:VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT specifies support for the 1310 extended sRGB color space to be displayed using a linear EOTF. 1311 * ename:VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT specifies support for 1312 the extended sRGB color space to be displayed using an sRGB EOTF. 1313 * ename:VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT specifies support for the 1314 Display-P3 color space to be displayed using a linear EOTF. 1315 * ename:VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT specifies support for the 1316 DCI-P3 color space to be displayed using the DCI-P3 EOTF. 1317 Note that values in such an image are interpreted as XYZ encoded color 1318 data by the presentation engine. 1319 * ename:VK_COLOR_SPACE_BT709_LINEAR_EXT specifies support for the BT709 1320 color space to be displayed using a linear EOTF. 1321 * ename:VK_COLOR_SPACE_BT709_NONLINEAR_EXT specifies support for the BT709 1322 color space to be displayed using the SMPTE 170M EOTF. 1323 * ename:VK_COLOR_SPACE_BT2020_LINEAR_EXT specifies support for the BT2020 1324 color space to be displayed using a linear EOTF. 1325 * ename:VK_COLOR_SPACE_HDR10_ST2084_EXT specifies support for the HDR10 1326 (BT2020 color) space to be displayed using the SMPTE ST2084 Perceptual 1327 Quantizer (PQ) EOTF. 1328 * ename:VK_COLOR_SPACE_DOLBYVISION_EXT specifies support for the Dolby 1329 Vision (BT2020 color space), proprietary encoding, to be displayed using 1330 the SMPTE ST2084 EOTF. 1331 * ename:VK_COLOR_SPACE_HDR10_HLG_EXT specifies support for the HDR10 1332 (BT2020 color space) to be displayed using the Hybrid Log Gamma (HLG) 1333 EOTF. 1334 * ename:VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT specifies support for the 1335 AdobeRGB color space to be displayed using a linear EOTF. 1336 * ename:VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT specifies support for the 1337 AdobeRGB color space to be displayed using the Gamma 2.2 EOTF. 1338 * ename:VK_COLOR_SPACE_PASS_THROUGH_EXT specifies that color components 1339 are used "`as is`". 1340 This is intended to allow applications to supply data for color spaces 1341 not described here. 1342ifdef::VK_AMD_display_native_hdr[] 1343 * ename:VK_COLOR_SPACE_DISPLAY_NATIVE_AMD specifies support for the 1344 display's native color space. 1345 This matches the color space expectations of AMD's FreeSync2 standard, 1346 for displays supporting it. 1347endif::VK_AMD_display_native_hdr[] 1348 1349[NOTE] 1350.Note 1351==== 1352In the initial release of the `apiext:VK_KHR_surface` and 1353`apiext:VK_KHR_swapchain` extensions, the token 1354ename:VK_COLORSPACE_SRGB_NONLINEAR_KHR was used. 1355Starting in the 2016-05-13 updates to the extension branches, matching 1356release 1.0.13 of the core API specification, 1357ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR is used instead for consistency with 1358Vulkan naming rules. 1359The older enum is still available for backwards compatibility. 1360==== 1361 1362[NOTE] 1363.Note 1364==== 1365In older versions of this extension 1366ename:VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT was misnamed 1367ename:VK_COLOR_SPACE_DCI_P3_LINEAR_EXT. 1368This has been updated to indicate that it uses RGB color encoding, not XYZ. 1369The old name is deprecated but is maintained for backwards compatibility. 1370==== 1371 1372[NOTE] 1373.Note 1374==== 1375For a traditional "`Linear`" or non-gamma transfer function color space use 1376ename:VK_COLOR_SPACE_PASS_THROUGH_EXT. 1377==== 1378 1379The color components of non-linear color space swap chain images must: have 1380had the appropriate transfer function applied. 1381The color space selected for the swap chain image will not affect the 1382processing of data written into the image by the implementation. 1383Vulkan requires that all implementations support the sRGB transfer function 1384by use of an SRGB pixel format. 1385Other transfer functions, such as SMPTE 170M or SMPTE2084, can: be performed 1386by the application shader. 1387This extension defines enums for elink:VkColorSpaceKHR that correspond to 1388the following color spaces: 1389 1390[[VK_EXT_swapchain_colorspace-table]] 1391.Color Spaces and Attributes 1392[options="header"] 1393|==== 1394| Name | Red Primary | Green Primary | Blue Primary | White-point | Transfer function 1395| DCI-P3 | 1.000, 0.000 | 0.000, 1.000 | 0.000, 0.000 | 0.3333, 0.3333 | DCI P3 1396| Display-P3 | 0.680, 0.320 | 0.265, 0.690 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | Display-P3 1397| BT709 | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | ITU (SMPTE 170M) 1398| sRGB | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | sRGB 1399| extended sRGB | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | extended sRGB 1400| HDR10_ST2084 | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | ST2084 PQ 1401| DOLBYVISION | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | ST2084 PQ 1402| HDR10_HLG | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | HLG 1403| AdobeRGB | 0.640, 0.330 | 0.210, 0.710 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | AdobeRGB 1404|==== 1405 1406The transfer functions are described in the "`Transfer Functions`" chapter 1407of the <<data-format,Khronos Data Format Specification>>. 1408 1409Except Display-P3 OETF, which is: 1410 1411[latexmath] 1412+++++++++++++++++++ 1413\begin{aligned} 1414E & = 1415 \begin{cases} 1416 1.055 \times L^{1 \over 2.4} - 0.055 & \text{for}\ 0.0030186 \leq L \leq 1 \\ 1417 12.92 \times L & \text{for}\ 0 \leq L < 0.0030186 1418 \end{cases} 1419\end{aligned} 1420+++++++++++++++++++ 1421 1422where [eq]#L# is the linear value of a color component and [eq]#E# is the 1423encoded value (as stored in the image in memory). 1424 1425[NOTE] 1426.Note 1427==== 1428For most uses, the sRGB OETF is equivalent. 1429==== 1430endif::VK_EXT_swapchain_colorspace[] 1431-- 1432 1433 1434=== Surface Presentation Mode Support 1435 1436[open,refpage='vkGetPhysicalDeviceSurfacePresentModesKHR',desc='Query supported presentation modes',type='protos'] 1437-- 1438:refpage: vkGetPhysicalDeviceSurfacePresentModesKHR 1439 1440To query the supported presentation modes for a surface, call: 1441 1442include::{generated}/api/protos/vkGetPhysicalDeviceSurfacePresentModesKHR.adoc[] 1443 1444 * pname:physicalDevice is the physical device that will be associated with 1445 the swapchain to be created, as described for 1446 flink:vkCreateSwapchainKHR. 1447 * pname:surface is the surface that will be associated with the swapchain. 1448 * pname:pPresentModeCount is a pointer to an integer related to the number 1449 of presentation modes available or queried, as described below. 1450 * pname:pPresentModes is either `NULL` or a pointer to an array of 1451 elink:VkPresentModeKHR values, indicating the supported presentation 1452 modes. 1453 1454If pname:pPresentModes is `NULL`, then the number of presentation modes 1455supported for the given pname:surface is returned in 1456pname:pPresentModeCount. 1457Otherwise, pname:pPresentModeCount must: point to a variable set by the user 1458to the number of elements in the pname:pPresentModes array, and on return 1459the variable is overwritten with the number of values actually written to 1460pname:pPresentModes. 1461If the value of pname:pPresentModeCount is less than the number of 1462presentation modes supported, at most pname:pPresentModeCount values will be 1463written, and ename:VK_INCOMPLETE will be returned instead of 1464ename:VK_SUCCESS, to indicate that not all the available modes were 1465returned. 1466 1467ifdef::VK_GOOGLE_surfaceless_query[] 1468If the `apiext:VK_GOOGLE_surfaceless_query` extension is enabled and 1469pname:surface is dlink:VK_NULL_HANDLE, the values returned in 1470pname:pPresentModes will only indicate support for 1471ifndef::VK_KHR_shared_presentable_image[] 1472ename:VK_PRESENT_MODE_FIFO_KHR. 1473endif::VK_KHR_shared_presentable_image[] 1474ifdef::VK_KHR_shared_presentable_image[] 1475ename:VK_PRESENT_MODE_FIFO_KHR, 1476ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR, and 1477ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR. 1478endif::VK_KHR_shared_presentable_image[] 1479To query support for any other present mode, a valid handle must: be 1480provided in pname:surface. 1481endif::VK_GOOGLE_surfaceless_query[] 1482 1483.Valid Usage 1484**** 1485include::{chapters}/commonvalidity/surface_physical_device_surfaceless_common.adoc[] 1486**** 1487 1488include::{generated}/validity/protos/vkGetPhysicalDeviceSurfacePresentModesKHR.adoc[] 1489-- 1490 1491ifdef::VK_EXT_full_screen_exclusive[] 1492[open,refpage='vkGetPhysicalDeviceSurfacePresentModes2EXT',desc='Query supported presentation modes',type='protos'] 1493-- 1494:refpage: vkGetPhysicalDeviceSurfacePresentModes2EXT 1495 1496Alternatively, to query the supported presentation modes for a surface 1497combined with select other fixed swapchain creation parameters, call: 1498 1499include::{generated}/api/protos/vkGetPhysicalDeviceSurfacePresentModes2EXT.adoc[] 1500 1501 * pname:physicalDevice is the physical device that will be associated with 1502 the swapchain to be created, as described for 1503 flink:vkCreateSwapchainKHR. 1504 * pname:pSurfaceInfo is a pointer to a 1505 slink:VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface 1506 and other fixed parameters that would be consumed by 1507 flink:vkCreateSwapchainKHR. 1508 * pname:pPresentModeCount is a pointer to an integer related to the number 1509 of presentation modes available or queried, as described below. 1510 * pname:pPresentModes is either `NULL` or a pointer to an array of 1511 elink:VkPresentModeKHR values, indicating the supported presentation 1512 modes. 1513 1514fname:vkGetPhysicalDeviceSurfacePresentModes2EXT behaves similarly to 1515flink:vkGetPhysicalDeviceSurfacePresentModesKHR, with the ability to specify 1516extended inputs via chained input structures. 1517 1518.Valid Usage 1519**** 1520include::{chapters}/commonvalidity/surface_info_physical_device_surfaceless_common.adoc[] 1521**** 1522 1523include::{generated}/validity/protos/vkGetPhysicalDeviceSurfacePresentModes2EXT.adoc[] 1524-- 1525endif::VK_EXT_full_screen_exclusive[] 1526 1527[open,refpage='VkPresentModeKHR',desc='Presentation mode supported for a surface',type='enums'] 1528-- 1529Possible values of elements of the 1530flink:vkGetPhysicalDeviceSurfacePresentModesKHR::pname:pPresentModes array, 1531indicating the supported presentation modes for a surface, are: 1532 1533include::{generated}/api/enums/VkPresentModeKHR.adoc[] 1534 1535 * ename:VK_PRESENT_MODE_IMMEDIATE_KHR specifies that the presentation 1536 engine does not wait for a vertical blanking period to update the 1537 current image, meaning this mode may: result in visible tearing. 1538 No internal queuing of presentation requests is needed, as the requests 1539 are applied immediately. 1540 * ename:VK_PRESENT_MODE_MAILBOX_KHR specifies that the presentation engine 1541 waits for the next vertical blanking period to update the current image. 1542 Tearing cannot: be observed. 1543 An internal single-entry queue is used to hold pending presentation 1544 requests. 1545 If the queue is full when a new presentation request is received, the 1546 new request replaces the existing entry, and any images associated with 1547 the prior entry become available for re-use by the application. 1548 One request is removed from the queue and processed during each vertical 1549 blanking period in which the queue is non-empty. 1550 * ename:VK_PRESENT_MODE_FIFO_KHR specifies that the presentation engine 1551 waits for the next vertical blanking period to update the current image. 1552 Tearing cannot: be observed. 1553 An internal queue is used to hold pending presentation requests. 1554 New requests are appended to the end of the queue, and one request is 1555 removed from the beginning of the queue and processed during each 1556 vertical blanking period in which the queue is non-empty. 1557 This is the only value of pname:presentMode that is required: to be 1558 supported. 1559 * ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR specifies that the presentation 1560 engine generally waits for the next vertical blanking period to update 1561 the current image. 1562 If a vertical blanking period has already passed since the last update 1563 of the current image then the presentation engine does not wait for 1564 another vertical blanking period for the update, meaning this mode may: 1565 result in visible tearing in this case. 1566 This mode is useful for reducing visual stutter with an application that 1567 will mostly present a new image before the next vertical blanking 1568 period, but may occasionally be late, and present a new image just after 1569 the next vertical blanking period. 1570 An internal queue is used to hold pending presentation requests. 1571 New requests are appended to the end of the queue, and one request is 1572 removed from the beginning of the queue and processed during or after 1573 each vertical blanking period in which the queue is non-empty. 1574ifdef::VK_KHR_shared_presentable_image[] 1575 * ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR specifies that the 1576 presentation engine and application have concurrent access to a single 1577 image, which is referred to as a _shared presentable image_. 1578 The presentation engine is only required to update the current image 1579 after a new presentation request is received. 1580 Therefore the application must: make a presentation request whenever an 1581 update is required. 1582 However, the presentation engine may: update the current image at any 1583 point, meaning this mode may: result in visible tearing. 1584 * ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR specifies that the 1585 presentation engine and application have concurrent access to a single 1586 image, which is referred to as a _shared presentable image_. 1587 The presentation engine periodically updates the current image on its 1588 regular refresh cycle. 1589 The application is only required to make one initial presentation 1590 request, after which the presentation engine must: update the current 1591 image without any need for further presentation requests. 1592 The application can: indicate the image contents have been updated by 1593 making a presentation request, but this does not guarantee the timing of 1594 when it will be updated. 1595 This mode may: result in visible tearing if rendering to the image is 1596 not timed correctly. 1597 1598The supported elink:VkImageUsageFlagBits of the presentable images of a 1599swapchain created for a surface may: differ depending on the presentation 1600mode, and can be determined as per the table below: 1601 1602.Presentable image usage queries 1603[width="100%",cols="<50%,<50%",options="header"] 1604|==== 1605| Presentation mode | Image usage flags 1606| ename:VK_PRESENT_MODE_IMMEDIATE_KHR | slink:VkSurfaceCapabilitiesKHR::pname:supportedUsageFlags 1607| ename:VK_PRESENT_MODE_MAILBOX_KHR | slink:VkSurfaceCapabilitiesKHR::pname:supportedUsageFlags 1608| ename:VK_PRESENT_MODE_FIFO_KHR | slink:VkSurfaceCapabilitiesKHR::pname:supportedUsageFlags 1609| ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR | slink:VkSurfaceCapabilitiesKHR::pname:supportedUsageFlags 1610| ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR | slink:VkSharedPresentSurfaceCapabilitiesKHR::pname:sharedPresentSupportedUsageFlags 1611| ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR | slink:VkSharedPresentSurfaceCapabilitiesKHR::pname:sharedPresentSupportedUsageFlags 1612|==== 1613endif::VK_KHR_shared_presentable_image[] 1614 1615[NOTE] 1616.Note 1617==== 1618For reference, the mode indicated by ename:VK_PRESENT_MODE_FIFO_KHR is 1619equivalent to the behavior of {wgl|glX|egl}SwapBuffers with a swap interval 1620of 1, while the mode indicated by ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR is 1621equivalent to the behavior of {wgl|glX}SwapBuffers with a swap interval of 1622-1 (from the {WGL|GLX}_EXT_swap_control_tear extensions). 1623==== 1624-- 1625 1626ifdef::VK_EXT_full_screen_exclusive[] 1627== Full Screen Exclusive Control 1628 1629Swapchains created with pname:fullScreenExclusive set to 1630ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT must: acquire and 1631release exclusive full-screen access explicitly, using the following 1632commands. 1633 1634[open,refpage='vkAcquireFullScreenExclusiveModeEXT',desc='Acquire full-screen exclusive mode for a swapchain',type='protos'] 1635-- 1636To acquire exclusive full-screen access for a swapchain, call: 1637 1638include::{generated}/api/protos/vkAcquireFullScreenExclusiveModeEXT.adoc[] 1639 1640 * pname:device is the device associated with pname:swapchain. 1641 * pname:swapchain is the swapchain to acquire exclusive full-screen access 1642 for. 1643 1644.Valid Usage 1645**** 1646 * [[VUID-vkAcquireFullScreenExclusiveModeEXT-swapchain-02674]] 1647 pname:swapchain must: not be in the retired state 1648 * [[VUID-vkAcquireFullScreenExclusiveModeEXT-swapchain-02675]] 1649 pname:swapchain must: be a swapchain created with a 1650 slink:VkSurfaceFullScreenExclusiveInfoEXT structure, with 1651 pname:fullScreenExclusive set to 1652 ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT 1653 * [[VUID-vkAcquireFullScreenExclusiveModeEXT-swapchain-02676]] 1654 pname:swapchain must: not currently have exclusive full-screen access 1655**** 1656 1657A return value of ename:VK_SUCCESS indicates that the pname:swapchain 1658successfully acquired exclusive full-screen access. 1659The swapchain will retain this exclusivity until either the application 1660releases exclusive full-screen access with 1661flink:vkReleaseFullScreenExclusiveModeEXT, destroys the swapchain, or if any 1662of the swapchain commands return 1663ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT indicating that the mode 1664was lost because of platform-specific changes. 1665 1666If the swapchain was unable to acquire exclusive full-screen access to the 1667display then ename:VK_ERROR_INITIALIZATION_FAILED is returned. 1668An application can: attempt to acquire exclusive full-screen access again 1669for the same swapchain even if this command fails, or if 1670ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT has been returned by a 1671swapchain command. 1672 1673include::{generated}/validity/protos/vkAcquireFullScreenExclusiveModeEXT.adoc[] 1674-- 1675 1676[open,refpage='vkReleaseFullScreenExclusiveModeEXT',desc='Release full-screen exclusive mode from a swapchain',type='protos'] 1677-- 1678To release exclusive full-screen access from a swapchain, call: 1679 1680include::{generated}/api/protos/vkReleaseFullScreenExclusiveModeEXT.adoc[] 1681 1682 * pname:device is the device associated with pname:swapchain. 1683 * pname:swapchain is the swapchain to release exclusive full-screen access 1684 from. 1685 1686[NOTE] 1687.Note 1688==== 1689Applications will not be able to present to pname:swapchain after this call 1690until exclusive full-screen access is reacquired. 1691This is usually useful to handle when an application is minimised or 1692otherwise intends to stop presenting for a time. 1693==== 1694 1695.Valid Usage 1696**** 1697 * [[VUID-vkReleaseFullScreenExclusiveModeEXT-swapchain-02677]] 1698 pname:swapchain must: not be in the retired state 1699 * [[VUID-vkReleaseFullScreenExclusiveModeEXT-swapchain-02678]] 1700 pname:swapchain must: be a swapchain created with a 1701 slink:VkSurfaceFullScreenExclusiveInfoEXT structure, with 1702 pname:fullScreenExclusive set to 1703 ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT 1704**** 1705-- 1706endif::VK_EXT_full_screen_exclusive[] 1707 1708 1709ifdef::VK_KHR_swapchain[] 1710ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1711== Device Group Queries 1712 1713[open,refpage='vkGetDeviceGroupPresentCapabilitiesKHR',desc='Query present capabilities from other physical devices',type='protos'] 1714-- 1715A logical device that represents multiple physical devices may: support 1716presenting from images on more than one physical device, or combining images 1717from multiple physical devices. 1718 1719To query these capabilities, call: 1720 1721include::{generated}/api/protos/vkGetDeviceGroupPresentCapabilitiesKHR.adoc[] 1722 1723 * pname:device is the logical device. 1724 * pname:pDeviceGroupPresentCapabilities is a pointer to a 1725 slink:VkDeviceGroupPresentCapabilitiesKHR structure in which the 1726 device's capabilities are returned. 1727 1728include::{generated}/validity/protos/vkGetDeviceGroupPresentCapabilitiesKHR.adoc[] 1729-- 1730 1731[open,refpage='VkDeviceGroupPresentCapabilitiesKHR',desc='Present capabilities from other physical devices',type='structs'] 1732-- 1733The sname:VkDeviceGroupPresentCapabilitiesKHR structure is defined as: 1734 1735include::{generated}/api/structs/VkDeviceGroupPresentCapabilitiesKHR.adoc[] 1736 1737 * pname:sType is the type of this structure. 1738 * pname:pNext is `NULL` or a pointer to a structure extending this 1739 structure. 1740 * pname:presentMask is an array of ename:VK_MAX_DEVICE_GROUP_SIZE 1741 code:uint32_t masks, where the mask at element [eq]#i# is non-zero if 1742 physical device [eq]#i# has a presentation engine, and where bit [eq]#j# 1743 is set in element [eq]#i# if physical device [eq]#i# can: present 1744 swapchain images from physical device [eq]#j#. 1745 If element [eq]#i# is non-zero, then bit [eq]#i# must: be set. 1746 * pname:modes is a bitmask of elink:VkDeviceGroupPresentModeFlagBitsKHR 1747 indicating which device group presentation modes are supported. 1748 1749pname:modes always has ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR set. 1750 1751The present mode flags are also used when presenting an image, in 1752slink:VkDeviceGroupPresentInfoKHR::pname:mode. 1753 1754If a device group only includes a single physical device, then pname:modes 1755must: equal ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR. 1756 1757include::{generated}/validity/structs/VkDeviceGroupPresentCapabilitiesKHR.adoc[] 1758-- 1759 1760 1761[open,refpage='VkDeviceGroupPresentModeFlagBitsKHR',desc='Bitmask specifying supported device group present modes',type='enums'] 1762-- 1763Bits which may: be set in 1764slink:VkDeviceGroupPresentCapabilitiesKHR::pname:modes, indicating which 1765device group presentation modes are supported, are: 1766 1767include::{generated}/api/enums/VkDeviceGroupPresentModeFlagBitsKHR.adoc[] 1768 1769 * ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR specifies that any 1770 physical device with a presentation engine can: present its own 1771 swapchain images. 1772 * ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR specifies that any 1773 physical device with a presentation engine can: present swapchain images 1774 from any physical device in its pname:presentMask. 1775 * ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR specifies that any 1776 physical device with a presentation engine can: present the sum of 1777 swapchain images from any physical devices in its pname:presentMask. 1778 * ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR specifies 1779 that multiple physical devices with a presentation engine can: each 1780 present their own swapchain images. 1781-- 1782 1783[open,refpage='VkDeviceGroupPresentModeFlagsKHR',desc='Bitmask of VkDeviceGroupPresentModeFlagBitsKHR',type='flags'] 1784-- 1785include::{generated}/api/flags/VkDeviceGroupPresentModeFlagsKHR.adoc[] 1786 1787tname:VkDeviceGroupPresentModeFlagsKHR is a bitmask type for setting a mask 1788of zero or more elink:VkDeviceGroupPresentModeFlagBitsKHR. 1789-- 1790 1791[open,refpage='vkGetDeviceGroupSurfacePresentModesKHR',desc='Query present capabilities for a surface',type='protos'] 1792-- 1793Some surfaces may: not be capable of using all the device group present 1794modes. 1795 1796To query the supported device group present modes for a particular surface, 1797call: 1798 1799include::{generated}/api/protos/vkGetDeviceGroupSurfacePresentModesKHR.adoc[] 1800 1801 * pname:device is the logical device. 1802 * pname:surface is the surface. 1803 * pname:pModes is a pointer to a tlink:VkDeviceGroupPresentModeFlagsKHR in 1804 which the supported device group present modes for the surface are 1805 returned. 1806 1807The modes returned by this command are not invariant, and may: change in 1808response to the surface being moved, resized, or occluded. 1809These modes must: be a subset of the modes returned by 1810flink:vkGetDeviceGroupPresentCapabilitiesKHR. 1811 1812.Valid Usage 1813**** 1814 * [[VUID-vkGetDeviceGroupSurfacePresentModesKHR-surface-06212]] 1815 pname:surface must: be supported by all physical devices associated with 1816 pname:device, as reported by flink:vkGetPhysicalDeviceSurfaceSupportKHR 1817 or an equivalent platform-specific mechanism 1818**** 1819 1820include::{generated}/validity/protos/vkGetDeviceGroupSurfacePresentModesKHR.adoc[] 1821-- 1822 1823ifdef::VK_EXT_full_screen_exclusive[] 1824[open,refpage='vkGetDeviceGroupSurfacePresentModes2EXT',desc='Query device group present capabilities for a surface',type='protos'] 1825-- 1826Alternatively, to query the supported device group presentation modes for a 1827surface combined with select other fixed swapchain creation parameters, 1828call: 1829 1830include::{generated}/api/protos/vkGetDeviceGroupSurfacePresentModes2EXT.adoc[] 1831 1832 * pname:device is the logical device. 1833 * pname:pSurfaceInfo is a pointer to a 1834 slink:VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface 1835 and other fixed parameters that would be consumed by 1836 flink:vkCreateSwapchainKHR. 1837 * pname:pModes is a pointer to a tlink:VkDeviceGroupPresentModeFlagsKHR in 1838 which the supported device group present modes for the surface are 1839 returned. 1840 1841fname:vkGetDeviceGroupSurfacePresentModes2EXT behaves similarly to 1842flink:vkGetDeviceGroupSurfacePresentModesKHR, with the ability to specify 1843extended inputs via chained input structures. 1844 1845.Valid Usage 1846**** 1847 * [[VUID-vkGetDeviceGroupSurfacePresentModes2EXT-pSurfaceInfo-06213]] 1848 pname:pSurfaceInfo->surface must: be supported by all physical devices 1849 associated with pname:device, as reported by 1850 flink:vkGetPhysicalDeviceSurfaceSupportKHR or an equivalent 1851 platform-specific mechanism 1852**** 1853 1854include::{generated}/validity/protos/vkGetDeviceGroupSurfacePresentModes2EXT.adoc[] 1855-- 1856endif::VK_EXT_full_screen_exclusive[] 1857 1858[open,refpage='vkGetPhysicalDevicePresentRectanglesKHR',desc='Query present rectangles for a surface on a physical device',type='protos'] 1859-- 1860:refpage: vkGetPhysicalDevicePresentRectanglesKHR 1861 1862When using ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, 1863the application may: need to know which regions of the surface are used when 1864presenting locally on each physical device. 1865Presentation of swapchain images to this surface need only have valid 1866contents in the regions returned by this command. 1867 1868To query a set of rectangles used in presentation on the physical device, 1869call: 1870 1871include::{generated}/api/protos/vkGetPhysicalDevicePresentRectanglesKHR.adoc[] 1872 1873 * pname:physicalDevice is the physical device. 1874 * pname:surface is the surface. 1875 * pname:pRectCount is a pointer to an integer related to the number of 1876 rectangles available or queried, as described below. 1877 * pname:pRects is either `NULL` or a pointer to an array of slink:VkRect2D 1878 structures. 1879 1880If pname:pRects is `NULL`, then the number of rectangles used when 1881presenting the given pname:surface is returned in pname:pRectCount. 1882Otherwise, pname:pRectCount must: point to a variable set by the user to the 1883number of elements in the pname:pRects array, and on return the variable is 1884overwritten with the number of structures actually written to pname:pRects. 1885If the value of pname:pRectCount is less than the number of rectangles, at 1886most pname:pRectCount structures will be written, and ename:VK_INCOMPLETE 1887will be returned instead of ename:VK_SUCCESS, to indicate that not all the 1888available rectangles were returned. 1889 1890The values returned by this command are not invariant, and may: change in 1891response to the surface being moved, resized, or occluded. 1892 1893The rectangles returned by this command must: not overlap. 1894 1895.Valid Usage 1896**** 1897include::{chapters}/commonvalidity/surface_physical_device_common.adoc[] 1898**** 1899 1900include::{generated}/validity/protos/vkGetPhysicalDevicePresentRectanglesKHR.adoc[] 1901-- 1902endif::VK_VERSION_1_1,VK_KHR_device_group[] 1903 1904ifdef::VK_GOOGLE_display_timing[] 1905include::{chapters}/VK_GOOGLE_display_timing/queries.adoc[] 1906endif::VK_GOOGLE_display_timing[] 1907 1908ifdef::VK_KHR_present_wait[] 1909include::{chapters}/VK_KHR_present_wait/present_wait.adoc[] 1910endif::VK_KHR_present_wait[] 1911 1912include::{chapters}/VK_KHR_swapchain/wsi.adoc[] 1913endif::VK_KHR_swapchain[] 1914 1915ifdef::VK_NV_present_barrier[] 1916include::{chapters}/VK_NV_present_barrier/present_barrier.adoc[] 1917endif::VK_NV_present_barrier[] 1918