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