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