1// Copyright 2014-2021 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.txt[] 56 57The `VK_KHR_surface` extension declares the sname:VkSurfaceKHR object, and 58provides 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.txt[] 93endif::VK_KHR_android_surface[] 94 95ifdef::VK_KHR_wayland_surface[] 96include::{chapters}/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt[] 97endif::VK_KHR_wayland_surface[] 98 99ifdef::VK_KHR_win32_surface[] 100include::{chapters}/VK_KHR_win32_surface/platformCreateSurface_win32.txt[] 101endif::VK_KHR_win32_surface[] 102 103ifdef::VK_KHR_xcb_surface[] 104include::{chapters}/VK_KHR_xcb_surface/platformCreateSurface_xcb.txt[] 105endif::VK_KHR_xcb_surface[] 106 107ifdef::VK_KHR_xlib_surface[] 108include::{chapters}/VK_KHR_xlib_surface/platformCreateSurface_xlib.txt[] 109endif::VK_KHR_xlib_surface[] 110 111ifdef::VK_EXT_directfb_surface[] 112include::{chapters}/VK_EXT_directfb_surface/platformCreateSurface_directfb.txt[] 113endif::VK_EXT_directfb_surface[] 114 115ifdef::VK_FUCHSIA_imagepipe_surface[] 116include::{chapters}/VK_FUCHSIA_imagepipe_surface/platformCreateSurface_imagepipe.txt[] 117endif::VK_FUCHSIA_imagepipe_surface[] 118 119ifdef::VK_GGP_stream_descriptor_surface[] 120include::{chapters}/VK_GGP_stream_descriptor_surface/platformCreateSurface_streamdescriptor.txt[] 121endif::VK_GGP_stream_descriptor_surface[] 122 123ifdef::VK_MVK_ios_surface[] 124include::{chapters}/VK_MVK_ios_surface/platformCreateSurface_ios.txt[] 125endif::VK_MVK_ios_surface[] 126 127ifdef::VK_MVK_macos_surface[] 128include::{chapters}/VK_MVK_macos_surface/platformCreateSurface_macos.txt[] 129endif::VK_MVK_macos_surface[] 130 131ifdef::VK_NN_vi_surface[] 132include::{chapters}/VK_NN_vi_surface/platformCreateSurface_vi.txt[] 133endif::VK_NN_vi_surface[] 134 135ifdef::VK_EXT_metal_surface[] 136include::{chapters}/VK_EXT_metal_surface/platformCreateSurface_metal.txt[] 137endif::VK_EXT_metal_surface[] 138 139ifdef::VK_QNX_screen_surface[] 140include::{chapters}/VK_QNX_screen_surface/platformCreateSurface_screen.txt[] 141endif::VK_QNX_screen_surface[] 142 143=== Platform-Independent Information 144 145Once created, sname:VkSurfaceKHR objects can: be used in this and other 146extensions, in particular the `apiext:VK_KHR_swapchain` extension. 147 148Several WSI functions return ename:VK_ERROR_SURFACE_LOST_KHR if the surface 149becomes no longer available. 150After such an error, the surface (and any child swapchain, if one exists) 151should: be destroyed, as there is no way to restore them to a not-lost 152state. 153Applications may: attempt to create a new sname:VkSurfaceKHR using the same 154native platform window object, but whether such re-creation will succeed is 155platform-dependent and may: depend on the reason the surface became 156unavailable. 157A lost surface does not otherwise cause devices to be 158<<devsandqueues-lost-device,lost>>. 159 160[open,refpage='vkDestroySurfaceKHR',desc='Destroy a VkSurfaceKHR object',type='protos'] 161-- 162To destroy a sname:VkSurfaceKHR object, call: 163 164include::{generated}/api/protos/vkDestroySurfaceKHR.txt[] 165 166 * pname:instance is the instance used to create the surface. 167 * pname:surface is the surface to destroy. 168 * pname:pAllocator is the allocator used for host memory allocated for the 169 surface object when there is no more specific allocator available (see 170 <<memory-allocation,Memory Allocation>>). 171 172Destroying a sname:VkSurfaceKHR merely severs the connection between Vulkan 173and the native surface, and does not imply destroying the native surface, 174closing a window, or similar behavior. 175 176.Valid Usage 177**** 178 * [[VUID-vkDestroySurfaceKHR-surface-01266]] 179 All sname:VkSwapchainKHR objects created for pname:surface must: have 180 been destroyed prior to destroying pname:surface 181 * [[VUID-vkDestroySurfaceKHR-surface-01267]] 182 If sname:VkAllocationCallbacks were provided when pname:surface was 183 created, a compatible set of callbacks must: be provided here 184 * [[VUID-vkDestroySurfaceKHR-surface-01268]] 185 If no sname:VkAllocationCallbacks were provided when pname:surface was 186 created, pname:pAllocator must: be `NULL` 187**** 188 189include::{generated}/validity/protos/vkDestroySurfaceKHR.txt[] 190-- 191 192ifdef::VK_KHR_display[] 193include::{chapters}/VK_KHR_display/display.txt[] 194endif::VK_KHR_display[] 195 196ifdef::VK_EXT_headless_surface[] 197include::{chapters}/VK_EXT_headless_surface/headless.txt[] 198endif::VK_EXT_headless_surface[] 199 200 201== Querying for WSI Support 202 203Not all physical devices will include WSI support. 204Within a physical device, not all queue families will support presentation. 205WSI support and compatibility can: be determined in a platform-neutral 206manner (which determines support for presentation to a particular surface 207object) and additionally may: be determined in platform-specific manners 208(which determine support for presentation on the specified physical device 209but do not guarantee support for presentation to a particular surface 210object). 211 212[open,refpage='vkGetPhysicalDeviceSurfaceSupportKHR',desc='Query if presentation is supported',type='protos'] 213-- 214To determine whether a queue family of a physical device supports 215presentation to a given surface, call: 216 217include::{generated}/api/protos/vkGetPhysicalDeviceSurfaceSupportKHR.txt[] 218 219 * pname:physicalDevice is the physical device. 220 * pname:queueFamilyIndex is the queue family. 221 * pname:surface is the surface. 222 * pname:pSupported is a pointer to a basetype:VkBool32, which is set to 223 ename:VK_TRUE to indicate support, and ename:VK_FALSE otherwise. 224 225.Valid Usage 226**** 227 * [[VUID-vkGetPhysicalDeviceSurfaceSupportKHR-queueFamilyIndex-01269]] 228 pname:queueFamilyIndex must: be less than 229 pname:pQueueFamilyPropertyCount returned by 230 fname:vkGetPhysicalDeviceQueueFamilyProperties for the given 231 pname:physicalDevice 232**** 233 234include::{generated}/validity/protos/vkGetPhysicalDeviceSurfaceSupportKHR.txt[] 235-- 236 237ifdef::VK_KHR_android_surface[] 238include::{chapters}/VK_KHR_android_surface/platformQuerySupport_android.txt[] 239endif::VK_KHR_android_surface[] 240 241ifdef::VK_KHR_wayland_surface[] 242include::{chapters}/VK_KHR_wayland_surface/platformQuerySupport_wayland.txt[] 243endif::VK_KHR_wayland_surface[] 244 245ifdef::VK_KHR_win32_surface[] 246include::{chapters}/VK_KHR_win32_surface/platformQuerySupport_win32.txt[] 247endif::VK_KHR_win32_surface[] 248 249ifdef::VK_KHR_xcb_surface[] 250include::{chapters}/VK_KHR_xcb_surface/platformQuerySupport_xcb.txt[] 251endif::VK_KHR_xcb_surface[] 252 253ifdef::VK_KHR_xlib_surface[] 254include::{chapters}/VK_KHR_xlib_surface/platformQuerySupport_xlib.txt[] 255endif::VK_KHR_xlib_surface[] 256 257ifdef::VK_EXT_directfb_surface[] 258include::{chapters}/VK_EXT_directfb_surface/platformQuerySupport_directfb.txt[] 259endif::VK_EXT_directfb_surface[] 260 261ifdef::VK_FUCHSIA_imagepipe_surface[] 262include::{chapters}/VK_FUCHSIA_imagepipe_surface/platformQuerySupport_imagepipe.txt[] 263endif::VK_FUCHSIA_imagepipe_surface[] 264 265ifdef::VK_GGP_stream_descriptor_surface[] 266include::{chapters}/VK_GGP_stream_descriptor_surface/platformQuerySupport_streamdescriptor.txt[] 267endif::VK_GGP_stream_descriptor_surface[] 268 269ifdef::VK_MVK_ios_surface[] 270include::{chapters}/VK_MVK_ios_surface/platformQuerySupport_ios.txt[] 271endif::VK_MVK_ios_surface[] 272 273ifdef::VK_MVK_macos_surface[] 274include::{chapters}/VK_MVK_macos_surface/platformQuerySupport_macos.txt[] 275endif::VK_MVK_macos_surface[] 276 277ifdef::VK_NN_vi_surface[] 278include::{chapters}/VK_NN_vi_surface/platformQuerySupport_vi.txt[] 279endif::VK_NN_vi_surface[] 280 281ifdef::VK_QNX_screen_surface[] 282include::{chapters}/VK_QNX_screen_surface/platformQuerySupport_screen.txt[] 283endif::VK_QNX_screen_surface[] 284 285== Surface Queries 286 287The capabilities of a swapchain targeting a surface are the intersection of 288the capabilities of the WSI platform, the native window or display, and the 289physical device. 290The resulting capabilities can: be obtained with the queries listed below in 291this section. 292 293[NOTE] 294.Note 295==== 296In addition to the surface capabilities as obtained by surface queries 297below, swapchain images are also subject to ordinary image creation limits 298as reported by flink:vkGetPhysicalDeviceImageFormatProperties. 299As an application is instructed by the appropriate Valid Usage sections, 300both the surface capabilities and the image creation limits have to be 301satisfied whenever swapchain images are created. 302==== 303 304 305=== Surface Capabilities 306 307[open,refpage='vkGetPhysicalDeviceSurfaceCapabilitiesKHR',desc='Query surface capabilities',type='protos'] 308-- 309:refpage: vkGetPhysicalDeviceSurfaceCapabilitiesKHR 310 311To query the basic capabilities of a surface, needed in order to create a 312swapchain, call: 313 314include::{generated}/api/protos/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.txt[] 315 316 * pname:physicalDevice is the physical device that will be associated with 317 the swapchain to be created, as described for 318 flink:vkCreateSwapchainKHR. 319 * pname:surface is the surface that will be associated with the swapchain. 320 * pname:pSurfaceCapabilities is a pointer to a 321 slink:VkSurfaceCapabilitiesKHR structure in which the capabilities are 322 returned. 323 324.Valid Usage 325**** 326include::{chapters}/commonvalidity/surface_physical_device_common.txt[] 327**** 328 329include::{generated}/validity/protos/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.txt[] 330-- 331 332[open,refpage='VkSurfaceCapabilitiesKHR',desc='Structure describing capabilities of a surface',type='structs'] 333-- 334The sname:VkSurfaceCapabilitiesKHR structure is defined as: 335 336include::{generated}/api/structs/VkSurfaceCapabilitiesKHR.txt[] 337 338// These members are defined identically in VkSurfaceCapabilities2EXT, an 339// extendable structure version of this query, so they are just reused from 340// here. 341 342// tag::surface_capabilities_members[] 343 * pname:minImageCount is the minimum number of images the specified device 344 supports for a swapchain created for the surface, and will be at least 345 one. 346 * pname:maxImageCount is the maximum number of images the specified device 347 supports for a swapchain created for the surface, and will be either 0, 348 or greater than or equal to pname:minImageCount. 349 A value of 0 means that there is no limit on the number of images, 350 though there may: be limits related to the total amount of memory used 351 by presentable images. 352 * pname:currentExtent is the current width and height of the surface, or 353 the special value [eq]#(0xFFFFFFFF, 0xFFFFFFFF)# indicating that the 354 surface size will be determined by the extent of a swapchain targeting 355 the surface. 356 * pname:minImageExtent contains the smallest valid swapchain extent for 357 the surface on the specified device. 358 The pname:width and pname:height of the extent will each be less than or 359 equal to the corresponding pname:width and pname:height of 360 pname:currentExtent, unless pname:currentExtent has the special value 361 described above. 362 * pname:maxImageExtent contains the largest valid swapchain extent for the 363 surface on the specified device. 364 The pname:width and pname:height of the extent will each be greater than 365 or equal to the corresponding pname:width and pname:height of 366 pname:minImageExtent. 367 The pname:width and pname:height of the extent will each be greater than 368 or equal to the corresponding pname:width and pname:height of 369 pname:currentExtent, unless pname:currentExtent has the special value 370 described above. 371 * pname:maxImageArrayLayers is the maximum number of layers presentable 372 images can: have for a swapchain created for this device and surface, 373 and will be at least one. 374 * pname:supportedTransforms is a bitmask of 375 elink:VkSurfaceTransformFlagBitsKHR indicating the presentation 376 transforms supported for the surface on the specified device. 377 At least one bit will be set. 378 * pname:currentTransform is elink:VkSurfaceTransformFlagBitsKHR value 379 indicating the surface's current transform relative to the presentation 380 engine's natural orientation. 381 * pname:supportedCompositeAlpha is a bitmask of 382 elink:VkCompositeAlphaFlagBitsKHR, representing the alpha compositing 383 modes supported by the presentation engine for the surface on the 384 specified device, and at least one bit will be set. 385 Opaque composition can: be achieved in any alpha compositing mode by 386 either using an image format that has no alpha component, or by ensuring 387 that all pixels in the presentable images have an alpha value of 1.0. 388 * pname:supportedUsageFlags is a bitmask of elink:VkImageUsageFlagBits 389 representing the ways the application can: use the presentable images of 390 a swapchain created 391ifdef::VK_KHR_shared_presentable_image[] 392 with elink:VkPresentModeKHR set to ename:VK_PRESENT_MODE_IMMEDIATE_KHR, 393 ename:VK_PRESENT_MODE_MAILBOX_KHR, ename:VK_PRESENT_MODE_FIFO_KHR or 394 ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR 395endif::VK_KHR_shared_presentable_image[] 396 for the surface on the specified device. 397 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT must: be included in the set. 398 Implementations may: support additional usages. 399// end::surface_capabilities_members[] 400 401ifdef::VK_KHR_shared_presentable_image[] 402[NOTE] 403.Note 404==== 405Supported usage flags of a presentable image when using 406ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or 407ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR presentation mode are 408provided by 409slink:VkSharedPresentSurfaceCapabilitiesKHR::pname:sharedPresentSupportedUsageFlags. 410==== 411endif::VK_KHR_shared_presentable_image[] 412 413[NOTE] 414.Note 415==== 416Formulas such as [eq]#min(N, pname:maxImageCount)# are not correct, since 417pname:maxImageCount may: be zero. 418==== 419 420include::{generated}/validity/structs/VkSurfaceCapabilitiesKHR.txt[] 421-- 422 423ifdef::VK_KHR_get_surface_capabilities2[] 424[open,refpage='vkGetPhysicalDeviceSurfaceCapabilities2KHR',desc='Reports capabilities of a surface on a physical device',type='protos'] 425-- 426:refpage: vkGetPhysicalDeviceSurfaceCapabilities2KHR 427 428To query the basic capabilities of a surface defined by the core or 429extensions, call: 430 431include::{generated}/api/protos/vkGetPhysicalDeviceSurfaceCapabilities2KHR.txt[] 432 433 * pname:physicalDevice is the physical device that will be associated with 434 the swapchain to be created, as described for 435 flink:vkCreateSwapchainKHR. 436 * pname:pSurfaceInfo is a pointer to a 437 slink:VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface 438 and other fixed parameters that would be consumed by 439 flink:vkCreateSwapchainKHR. 440 * pname:pSurfaceCapabilities is a pointer to a 441 slink:VkSurfaceCapabilities2KHR structure in which the capabilities are 442 returned. 443 444fname:vkGetPhysicalDeviceSurfaceCapabilities2KHR behaves similarly to 445flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with the ability to specify 446extended inputs via chained input structures, and to return extended 447information via chained output structures. 448 449ifdef::VK_EXT_full_screen_exclusive+VK_KHR_win32_surface[] 450.Valid Usage 451**** 452include::{chapters}/commonvalidity/surface_info_physical_device_common.txt[] 453 * [[VUID-vkGetPhysicalDeviceSurfaceCapabilities2KHR-pNext-02671]] 454 If a slink:VkSurfaceCapabilitiesFullScreenExclusiveEXT structure is 455 included in the pname:pNext chain of pname:pSurfaceCapabilities, a 456 slink:VkSurfaceFullScreenExclusiveWin32InfoEXT structure must: be 457 included in the pname:pNext chain of pname:pSurfaceInfo 458**** 459endif::VK_EXT_full_screen_exclusive+VK_KHR_win32_surface[] 460 461include::{generated}/validity/protos/vkGetPhysicalDeviceSurfaceCapabilities2KHR.txt[] 462-- 463 464[open,refpage='VkPhysicalDeviceSurfaceInfo2KHR',desc='Structure specifying a surface and related swapchain creation parameters',type='structs'] 465-- 466The sname:VkPhysicalDeviceSurfaceInfo2KHR structure is defined as: 467 468include::{generated}/api/structs/VkPhysicalDeviceSurfaceInfo2KHR.txt[] 469 470 * pname:sType is the type of this structure. 471 * pname:pNext is `NULL` or a pointer to a structure extending this 472 structure. 473 * pname:surface is the surface that will be associated with the swapchain. 474 475The members of sname:VkPhysicalDeviceSurfaceInfo2KHR correspond to the 476arguments to flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with 477pname:sType and pname:pNext added for extensibility. 478 479ifdef::VK_EXT_full_screen_exclusive[] 480Additional capabilities of a surface may: be available to swapchains created 481with different full-screen exclusive settings - particularly if exclusive 482full-screen access is application controlled. 483These additional capabilities can: be queried by adding a 484slink:VkSurfaceFullScreenExclusiveInfoEXT structure to the pname:pNext chain 485of this structure when used to query surface properties. 486ifdef::VK_KHR_win32_surface[] 487Additionally, for Win32 surfaces with application controlled exclusive 488full-screen access, chaining a 489slink:VkSurfaceFullScreenExclusiveWin32InfoEXT structure may: also report 490additional surface capabilities. 491endif::VK_KHR_win32_surface[] 492These additional capabilities only apply to swapchains created with the same 493parameters included in the pname:pNext chain of 494slink:VkSwapchainCreateInfoKHR. 495endif::VK_EXT_full_screen_exclusive[] 496 497ifdef::VK_KHR_win32_surface+VK_EXT_full_screen_exclusive[] 498.Valid Usage 499**** 500 * [[VUID-VkPhysicalDeviceSurfaceInfo2KHR-pNext-02672]] 501 If the pname:pNext chain includes a 502 slink:VkSurfaceFullScreenExclusiveInfoEXT structure with its 503 pname:fullScreenExclusive member set to 504 ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT, and 505 pname:surface was created using flink:vkCreateWin32SurfaceKHR, a 506 slink:VkSurfaceFullScreenExclusiveWin32InfoEXT structure must: be 507 included in the pname:pNext chain 508**** 509endif::VK_KHR_win32_surface+VK_EXT_full_screen_exclusive[] 510 511include::{generated}/validity/structs/VkPhysicalDeviceSurfaceInfo2KHR.txt[] 512-- 513 514ifdef::VK_EXT_full_screen_exclusive[] 515[open,refpage='VkSurfaceFullScreenExclusiveInfoEXT',desc='Structure specifying the preferred full-screen transition behavior',type='structs'] 516-- 517If the pname:pNext chain of slink:VkSwapchainCreateInfoKHR includes a 518sname:VkSurfaceFullScreenExclusiveInfoEXT structure, then that structure 519specifies the application's preferred full-screen transition behavior. 520 521The sname:VkSurfaceFullScreenExclusiveInfoEXT structure is defined as: 522 523include::{generated}/api/structs/VkSurfaceFullScreenExclusiveInfoEXT.txt[] 524 525 * pname:sType is the type of this structure. 526 * pname:pNext is `NULL` or a pointer to a structure extending this 527 structure. 528 * pname:fullScreenExclusive is a elink:VkFullScreenExclusiveEXT value 529 specifying the preferred full-screen transition behavior. 530 531If this structure is not present, pname:fullScreenExclusive is considered to 532be ename:VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT. 533 534include::{generated}/validity/structs/VkSurfaceFullScreenExclusiveInfoEXT.txt[] 535-- 536 537[open,refpage='VkFullScreenExclusiveEXT',desc='Hint values an application can specify affecting full-screen transition behavior',type='enums'] 538-- 539Possible values of 540sname:VkSurfaceFullScreenExclusiveInfoEXT::pname:fullScreenExclusive are: 541 542include::{generated}/api/enums/VkFullScreenExclusiveEXT.txt[] 543 544 * ename:VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT indicates the implementation 545 should: determine the appropriate full-screen method by whatever means 546 it deems appropriate. 547 * ename:VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT indicates the implementation 548 may: use full-screen exclusive mechanisms when available. 549 Such mechanisms may: result in better performance and/or the 550 availability of different presentation capabilities, but may: require a 551 more disruptive transition during swapchain initialization, first 552 presentation and/or destruction. 553 * ename:VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT indicates the 554 implementation should: avoid using full-screen mechanisms which rely on 555 disruptive transitions. 556 * ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT indicates the 557 application will manage full-screen exclusive mode by using the 558 flink:vkAcquireFullScreenExclusiveModeEXT and 559 flink:vkReleaseFullScreenExclusiveModeEXT commands. 560-- 561 562ifdef::VK_KHR_win32_surface[] 563[open,refpage='VkSurfaceFullScreenExclusiveWin32InfoEXT',desc='Structure specifying additional creation parameters specific to Win32 fullscreen exclusive mode',type='structs'] 564-- 565The sname:VkSurfaceFullScreenExclusiveWin32InfoEXT structure is defined as: 566 567include::{generated}/api/structs/VkSurfaceFullScreenExclusiveWin32InfoEXT.txt[] 568 569 * pname:sType is the type of this structure. 570 * pname:pNext is `NULL` or a pointer to a structure extending this 571 structure. 572 * pname:hmonitor is the Win32 code:HMONITOR handle identifying the display 573 to create the surface with. 574 575[NOTE] 576.Note 577==== 578If pname:hmonitor is invalidated (e.g. the monitor is unplugged) during the 579lifetime of a swapchain created with this structure, operations on that 580swapchain will return ename:VK_ERROR_OUT_OF_DATE_KHR. 581==== 582 583[NOTE] 584.Note 585==== 586It is the responsibility of the application to change the display settings 587of the targeted Win32 display using the appropriate platform APIs. 588Such changes may: alter the surface capabilities reported for the created 589surface. 590==== 591 592.Valid Usage 593**** 594 * [[VUID-VkSurfaceFullScreenExclusiveWin32InfoEXT-hmonitor-02673]] 595 pname:hmonitor must: be a valid code:HMONITOR 596**** 597 598include::{generated}/validity/structs/VkSurfaceFullScreenExclusiveWin32InfoEXT.txt[] 599-- 600endif::VK_KHR_win32_surface[] 601endif::VK_EXT_full_screen_exclusive[] 602 603[open,refpage='VkSurfaceCapabilities2KHR',desc='Structure describing capabilities of a surface',type='structs'] 604-- 605The sname:VkSurfaceCapabilities2KHR structure is defined as: 606 607include::{generated}/api/structs/VkSurfaceCapabilities2KHR.txt[] 608 609 * pname:sType is the type of this structure. 610 * pname:pNext is `NULL` or a pointer to a structure extending this 611 structure. 612 * pname:surfaceCapabilities is a slink:VkSurfaceCapabilitiesKHR structure 613 describing the capabilities of the specified surface. 614 615include::{generated}/validity/structs/VkSurfaceCapabilities2KHR.txt[] 616-- 617 618ifdef::VK_KHR_surface_protected_capabilities[] 619[open,refpage='VkSurfaceProtectedCapabilitiesKHR',desc='Structure describing capability of a surface to be protected',type='structs'] 620-- 621An application queries if a protected slink:VkSurfaceKHR is displayable on a 622specific windowing system using sname:VkSurfaceProtectedCapabilitiesKHR, 623which can: be passed in pname:pNext parameter of 624sname:VkSurfaceCapabilities2KHR. 625 626The sname:VkSurfaceProtectedCapabilitiesKHR structure is defined as: 627 628include::{generated}/api/structs/VkSurfaceProtectedCapabilitiesKHR.txt[] 629 630 * pname:sType is the type of this structure. 631 * pname:pNext is `NULL` or a pointer to a structure extending this 632 structure. 633 * pname:supportsProtected specifies whether a protected swapchain created 634 from slink:VkPhysicalDeviceSurfaceInfo2KHR::pname:surface for a 635 particular windowing system can: be displayed on screen or not. 636 If pname:supportsProtected is ename:VK_TRUE, then creation of swapchains 637 with the ename:VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR flag set must: be 638 supported for pname:surface. 639 640 641include::{generated}/validity/structs/VkSurfaceProtectedCapabilitiesKHR.txt[] 642-- 643endif::VK_KHR_surface_protected_capabilities[] 644 645ifdef::VK_KHR_shared_presentable_image[] 646[open,refpage='VkSharedPresentSurfaceCapabilitiesKHR',desc='Structure describing capabilities of a surface for shared presentation',type='structs'] 647-- 648The sname:VkSharedPresentSurfaceCapabilitiesKHR structure is defined as: 649 650include::{generated}/api/structs/VkSharedPresentSurfaceCapabilitiesKHR.txt[] 651 652 * pname:sType is the type of this structure. 653 * pname:pNext is `NULL` or a pointer to a structure extending this 654 structure. 655 * pname:sharedPresentSupportedUsageFlags is a bitmask of 656 elink:VkImageUsageFlagBits representing the ways the application can: 657 use the shared presentable image from a swapchain created with 658 elink:VkPresentModeKHR set to 659 ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or 660 ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR for the surface on 661 the specified device. 662 ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT must: be included in the set 663 but implementations may: support additional usages. 664 665include::{generated}/validity/structs/VkSharedPresentSurfaceCapabilitiesKHR.txt[] 666-- 667endif::VK_KHR_shared_presentable_image[] 668 669ifdef::VK_AMD_display_native_hdr[] 670[open,refpage='VkDisplayNativeHdrSurfaceCapabilitiesAMD',desc='Structure describing display native HDR specific capabilities of a surface',type='structs'] 671-- 672The sname:VkDisplayNativeHdrSurfaceCapabilitiesAMD structure is defined as: 673 674include::{generated}/api/structs/VkDisplayNativeHdrSurfaceCapabilitiesAMD.txt[] 675 676 * pname:sType is the type of this structure. 677 * pname:pNext is `NULL` or a pointer to a structure extending this 678 structure. 679 * pname:localDimmingSupport specifies whether the surface supports local 680 dimming. 681 If this is ename:VK_TRUE, slink:VkSwapchainDisplayNativeHdrCreateInfoAMD 682 can: be used to explicitly enable or disable local dimming for the 683 surface. 684 Local dimming may also be overriden by flink:vkSetLocalDimmingAMD during 685 the lifetime of the swapchain. 686 687include::{generated}/validity/structs/VkDisplayNativeHdrSurfaceCapabilitiesAMD.txt[] 688-- 689endif::VK_AMD_display_native_hdr[] 690 691ifdef::VK_EXT_full_screen_exclusive[] 692[open,refpage='VkSurfaceCapabilitiesFullScreenExclusiveEXT',desc='Structure describing full screen exclusive capabilities of a surface',type='structs'] 693-- 694The sname:VkSurfaceCapabilitiesFullScreenExclusiveEXT structure is defined 695as: 696 697include::{generated}/api/structs/VkSurfaceCapabilitiesFullScreenExclusiveEXT.txt[] 698 699 * pname:sType is the type of this structure. 700 * pname:pNext is `NULL` or a pointer to a structure extending this 701 structure. 702 * pname:fullScreenExclusiveControlSupported is a boolean describing 703 whether the surface is able to make use of exclusive full-screen access. 704 705This structure can: be included in the pname:pNext chain of 706slink:VkSurfaceCapabilities2KHR to determine support for exclusive 707full-screen access. 708If pname:fullScreenExclusiveSupported is ename:VK_FALSE, it indicates that 709exclusive full-screen access is not obtainable for this surface. 710 711Applications must: not attempt to create swapchains with 712ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT set if 713pname:fullScreenExclusiveSupported is ename:VK_FALSE. 714 715include::{generated}/validity/structs/VkSurfaceCapabilitiesFullScreenExclusiveEXT.txt[] 716-- 717endif::VK_EXT_full_screen_exclusive[] 718endif::VK_KHR_get_surface_capabilities2[] 719 720ifdef::VK_EXT_display_surface_counter[] 721include::{chapters}/VK_EXT_display_surface_counter/surface_capabilities.txt[] 722endif::VK_EXT_display_surface_counter[] 723 724[open,refpage='VkSurfaceTransformFlagBitsKHR',desc='Presentation transforms supported on a device',type='enums'] 725-- 726Bits which may: be set in 727slink:VkSurfaceCapabilitiesKHR::pname:supportedTransforms indicating the 728presentation transforms supported for the surface on the specified device, 729and possible values of 730slink:VkSurfaceCapabilitiesKHR::pname:currentTransform indicating the 731surface's current transform relative to the presentation engine's natural 732orientation, are: 733 734include::{generated}/api/enums/VkSurfaceTransformFlagBitsKHR.txt[] 735 736 * ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR specifies that image content 737 is presented without being transformed. 738 * ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR specifies that image 739 content is rotated 90 degrees clockwise. 740 * ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR specifies that image 741 content is rotated 180 degrees clockwise. 742 * ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR specifies that image 743 content is rotated 270 degrees clockwise. 744 * ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR specifies that 745 image content is mirrored horizontally. 746 * ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR specifies 747 that image content is mirrored horizontally, then rotated 90 degrees 748 clockwise. 749 * ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR 750 specifies that image content is mirrored horizontally, then rotated 180 751 degrees clockwise. 752 * ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR 753 specifies that image content is mirrored horizontally, then rotated 270 754 degrees clockwise. 755 * ename:VK_SURFACE_TRANSFORM_INHERIT_BIT_KHR specifies that the 756 presentation transform is not specified, and is instead determined by 757 platform-specific considerations and mechanisms outside Vulkan. 758-- 759 760[open,refpage='VkSurfaceTransformFlagsKHR',desc='Bitmask of VkSurfaceTransformFlagBitsKHR',type='flags'] 761-- 762include::{generated}/api/flags/VkSurfaceTransformFlagsKHR.txt[] 763 764tname:VkSurfaceTransformFlagsKHR is a bitmask type for setting a mask of 765zero or more elink:VkSurfaceTransformFlagBitsKHR. 766-- 767 768[open,refpage='VkCompositeAlphaFlagBitsKHR',desc='Alpha compositing modes supported on a device',type='enums'] 769-- 770The pname:supportedCompositeAlpha member is of type 771elink:VkCompositeAlphaFlagBitsKHR, containing the following values: 772 773include::{generated}/api/enums/VkCompositeAlphaFlagBitsKHR.txt[] 774 775These values are described as follows: 776 777 * ename:VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha component, if it 778 exists, of the images is ignored in the compositing process. 779 Instead, the image is treated as if it has a constant alpha of 1.0. 780 * ename:VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha component, if 781 it exists, of the images is respected in the compositing process. 782 The non-alpha components of the image are expected to already be 783 multiplied by the alpha component by the application. 784 * ename:VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha component, 785 if it exists, of the images is respected in the compositing process. 786 The non-alpha components of the image are not expected to already be 787 multiplied by the alpha component by the application; instead, the 788 compositor will multiply the non-alpha components of the image by the 789 alpha component during compositing. 790 * ename:VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the 791 presentation engine treats the alpha component in the images is unknown 792 to the Vulkan API. 793 Instead, the application is responsible for setting the composite alpha 794 blending mode using native window system commands. 795 If the application does not set the blending mode using native window 796 system commands, then a platform-specific default will be used. 797-- 798 799[open,refpage='VkCompositeAlphaFlagsKHR',desc='Bitmask of VkCompositeAlphaFlagBitsKHR',type='flags'] 800-- 801include::{generated}/api/flags/VkCompositeAlphaFlagsKHR.txt[] 802 803tname:VkCompositeAlphaFlagsKHR is a bitmask type for setting a mask of zero 804or more elink:VkCompositeAlphaFlagBitsKHR. 805-- 806 807 808=== Surface Format Support 809 810[open,refpage='vkGetPhysicalDeviceSurfaceFormatsKHR',desc='Query color formats supported by surface',type='protos'] 811-- 812:refpage: vkGetPhysicalDeviceSurfaceFormatsKHR 813 814To query the supported swapchain format-color space pairs for a surface, 815call: 816 817include::{generated}/api/protos/vkGetPhysicalDeviceSurfaceFormatsKHR.txt[] 818 819 * pname:physicalDevice is the physical device that will be associated with 820 the swapchain to be created, as described for 821 flink:vkCreateSwapchainKHR. 822 * pname:surface is the surface that will be associated with the swapchain. 823 * pname:pSurfaceFormatCount is a pointer to an integer related to the 824 number of format pairs available or queried, as described below. 825 * pname:pSurfaceFormats is either `NULL` or a pointer to an array of 826 sname:VkSurfaceFormatKHR structures. 827 828If pname:pSurfaceFormats is `NULL`, then the number of format pairs 829supported for the given pname:surface is returned in 830pname:pSurfaceFormatCount. 831Otherwise, pname:pSurfaceFormatCount must: point to a variable set by the 832user to the number of elements in the pname:pSurfaceFormats array, and on 833return the variable is overwritten with the number of structures actually 834written to pname:pSurfaceFormats. 835If the value of pname:pSurfaceFormatCount is less than the number of format 836pairs supported, at most pname:pSurfaceFormatCount structures will be 837written, and ename:VK_INCOMPLETE will be returned instead of 838ename:VK_SUCCESS, to indicate that not all the available format pairs were 839returned. 840 841The number of format pairs supported must: be greater than or equal to 1. 842pname:pSurfaceFormats must: not contain an entry whose value for 843pname:format is ename:VK_FORMAT_UNDEFINED. 844 845If pname:pSurfaceFormats includes an entry whose value for pname:colorSpace 846is ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR and whose value for pname:format 847is a UNORM (or SRGB) format and the corresponding SRGB (or UNORM) format is 848a color renderable format for ename:VK_IMAGE_TILING_OPTIMAL, then 849pname:pSurfaceFormats must: also contain an entry with the same value for 850pname:colorSpace and pname:format equal to the corresponding SRGB (or UNORM) 851format. 852 853.Valid Usage 854**** 855include::{chapters}/commonvalidity/surface_physical_device_common.txt[] 856**** 857 858include::{generated}/validity/protos/vkGetPhysicalDeviceSurfaceFormatsKHR.txt[] 859-- 860 861[open,refpage='VkSurfaceFormatKHR',desc='Structure describing a supported swapchain format-color space pair',type='structs'] 862-- 863The sname:VkSurfaceFormatKHR structure is defined as: 864 865include::{generated}/api/structs/VkSurfaceFormatKHR.txt[] 866 867 * pname:format is a elink:VkFormat that is compatible with the specified 868 surface. 869 * pname:colorSpace is a presentation elink:VkColorSpaceKHR that is 870 compatible with the surface. 871 872include::{generated}/validity/structs/VkSurfaceFormatKHR.txt[] 873-- 874 875ifdef::VK_KHR_get_surface_capabilities2[] 876[open,refpage='vkGetPhysicalDeviceSurfaceFormats2KHR',desc='Query color formats supported by surface',type='protos'] 877-- 878:refpage: vkGetPhysicalDeviceSurfaceFormats2KHR 879 880To query the supported swapchain format tuples for a surface, call: 881 882include::{generated}/api/protos/vkGetPhysicalDeviceSurfaceFormats2KHR.txt[] 883 884 * pname:physicalDevice is the physical device that will be associated with 885 the swapchain to be created, as described for 886 flink:vkCreateSwapchainKHR. 887 * pname:pSurfaceInfo is a pointer to a 888 slink:VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface 889 and other fixed parameters that would be consumed by 890 flink:vkCreateSwapchainKHR. 891 * pname:pSurfaceFormatCount is a pointer to an integer related to the 892 number of format tuples available or queried, as described below. 893 * pname:pSurfaceFormats is either `NULL` or a pointer to an array of 894 slink:VkSurfaceFormat2KHR structures. 895 896flink:vkGetPhysicalDeviceSurfaceFormats2KHR behaves similarly to 897flink:vkGetPhysicalDeviceSurfaceFormatsKHR, with the ability to be extended 898via pname:pNext chains. 899 900If pname:pSurfaceFormats is `NULL`, then the number of format tuples 901supported for the given pname:surface is returned in 902pname:pSurfaceFormatCount. 903Otherwise, pname:pSurfaceFormatCount must: point to a variable set by the 904user to the number of elements in the pname:pSurfaceFormats array, and on 905return the variable is overwritten with the number of structures actually 906written to pname:pSurfaceFormats. 907If the value of pname:pSurfaceFormatCount is less than the number of format 908tuples supported, at most pname:pSurfaceFormatCount structures will be 909written, and ename:VK_INCOMPLETE will be returned instead of 910ename:VK_SUCCESS, to indicate that not all the available values were 911returned. 912 913.Valid Usage 914**** 915include::{chapters}/commonvalidity/surface_info_physical_device_common.txt[] 916**** 917 918include::{generated}/validity/protos/vkGetPhysicalDeviceSurfaceFormats2KHR.txt[] 919-- 920 921[open,refpage='VkSurfaceFormat2KHR',desc='Structure describing a supported swapchain format tuple',type='structs'] 922-- 923The sname:VkSurfaceFormat2KHR structure is defined as: 924 925include::{generated}/api/structs/VkSurfaceFormat2KHR.txt[] 926 927 * pname:sType is the type of this structure. 928 * pname:pNext is `NULL` or a pointer to a structure extending this 929 structure. 930 * pname:surfaceFormat is a slink:VkSurfaceFormatKHR structure describing a 931 format-color space pair that is compatible with the specified surface. 932 933include::{generated}/validity/structs/VkSurfaceFormat2KHR.txt[] 934-- 935endif::VK_KHR_get_surface_capabilities2[] 936 937While the pname:format of a presentable image refers to the encoding of each 938pixel, the pname:colorSpace determines how the presentation engine 939interprets the pixel values. 940A color space in this document refers to a specific color space (defined by 941the chromaticities of its primaries and a white point in CIE Lab), and a 942transfer function that is applied before storing or transmitting color data 943in the given color space. 944 945[open,refpage='VkColorSpaceKHR',desc='Supported color space of the presentation engine',type='enums'] 946-- 947Possible values of slink:VkSurfaceFormatKHR::pname:colorSpace, specifying 948supported color spaces of a presentation engine, are: 949 950include::{generated}/api/enums/VkColorSpaceKHR.txt[] 951 952 * ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR specifies support for the sRGB 953 color space. 954ifdef::VK_EXT_swapchain_colorspace[] 955 * ename:VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT specifies support for the 956 Display-P3 color space to be displayed using an sRGB-like EOTF (defined 957 below). 958 * ename:VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT specifies support for the 959 extended sRGB color space to be displayed using a linear EOTF. 960 * ename:VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT specifies support for 961 the extended sRGB color space to be displayed using an sRGB EOTF. 962 * ename:VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT specifies support for the 963 Display-P3 color space to be displayed using a linear EOTF. 964 * ename:VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT specifies support for the 965 DCI-P3 color space to be displayed using the DCI-P3 EOTF. 966 Note that values in such an image are interpreted as XYZ encoded color 967 data by the presentation engine. 968 * ename:VK_COLOR_SPACE_BT709_LINEAR_EXT specifies support for the BT709 969 color space to be displayed using a linear EOTF. 970 * ename:VK_COLOR_SPACE_BT709_NONLINEAR_EXT specifies support for the BT709 971 color space to be displayed using the SMPTE 170M EOTF. 972 * ename:VK_COLOR_SPACE_BT2020_LINEAR_EXT specifies support for the BT2020 973 color space to be displayed using a linear EOTF. 974 * ename:VK_COLOR_SPACE_HDR10_ST2084_EXT specifies support for the HDR10 975 (BT2020 color) space to be displayed using the SMPTE ST2084 Perceptual 976 Quantizer (PQ) EOTF. 977 * ename:VK_COLOR_SPACE_DOLBYVISION_EXT specifies support for the Dolby 978 Vision (BT2020 color space), proprietary encoding, to be displayed using 979 the SMPTE ST2084 EOTF. 980 * ename:VK_COLOR_SPACE_HDR10_HLG_EXT specifies support for the HDR10 981 (BT2020 color space) to be displayed using the Hybrid Log Gamma (HLG) 982 EOTF. 983 * ename:VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT specifies support for the 984 AdobeRGB color space to be displayed using a linear EOTF. 985 * ename:VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT specifies support for the 986 AdobeRGB color space to be displayed using the Gamma 2.2 EOTF. 987 * ename:VK_COLOR_SPACE_PASS_THROUGH_EXT specifies that color components 988 are used "`as is`". 989 This is intended to allow applications to supply data for color spaces 990 not described here. 991ifdef::VK_AMD_display_native_hdr[] 992 * ename:VK_COLOR_SPACE_DISPLAY_NATIVE_AMD specifies support for the 993 display's native color space. 994 This matches the color space expectations of AMD's FreeSync2 standard, 995 for displays supporting it. 996endif::VK_AMD_display_native_hdr[] 997 998[NOTE] 999.Note 1000==== 1001In the initial release of the `VK_KHR_surface` and `apiext:VK_KHR_swapchain` 1002extensions, the token ename:VK_COLORSPACE_SRGB_NONLINEAR_KHR was used. 1003Starting in the 2016-05-13 updates to the extension branches, matching 1004release 1.0.13 of the core API specification, 1005ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR is used instead for consistency with 1006Vulkan naming rules. 1007The older enum is still available for backwards compatibility. 1008==== 1009 1010[NOTE] 1011.Note 1012==== 1013In older versions of this extension 1014ename:VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT was misnamed 1015ename:VK_COLOR_SPACE_DCI_P3_LINEAR_EXT. 1016This has been updated to indicate that it uses RGB color encoding, not XYZ. 1017The old name is deprecated but is maintained for backwards compatibility. 1018==== 1019 1020The color components of non-linear color space swap chain images must: have 1021had the appropriate transfer function applied. 1022The color space selected for the swap chain image will not affect the 1023processing of data written into the image by the implementation. 1024Vulkan requires that all implementations support the sRGB transfer function 1025by use of an SRGB pixel format. 1026Other transfer functions, such as SMPTE 170M or SMPTE2084, can: be performed 1027by the application shader. 1028This extension defines enums for elink:VkColorSpaceKHR that correspond to 1029the following color spaces: 1030 1031[[VK_EXT_swapchain_colorspace-table]] 1032.Color Spaces and Attributes 1033[options="header"] 1034|==== 1035| Name | Red Primary | Green Primary | Blue Primary | White-point | Transfer function 1036| DCI-P3 | 1.000, 0.000 | 0.000, 1.000 | 0.000, 0.000 | 0.3333, 0.3333 | DCI P3 1037| Display-P3 | 0.680, 0.320 | 0.265, 0.690 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | Display-P3 1038| BT709 | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | ITU (SMPTE 170M) 1039| sRGB | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | sRGB 1040| extended sRGB | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | extended sRGB 1041| HDR10_ST2084 | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | ST2084 PQ 1042| DOLBYVISION | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | ST2084 PQ 1043| HDR10_HLG | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | HLG 1044| AdobeRGB | 0.640, 0.330 | 0.210, 0.710 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | AdobeRGB 1045|==== 1046 1047The transfer functions are described in the "`Transfer Functions`" chapter 1048of the <<data-format,Khronos Data Format Specification>>. 1049 1050Except Display-P3 OETF, which is: 1051 1052[latexmath] 1053+++++++++++++++++++ 1054\begin{aligned} 1055E & = 1056 \begin{cases} 1057 1.055 \times L^{1 \over 2.4} - 0.055 & \text{for}\ 0.0030186 \leq L \leq 1 \\ 1058 12.92 \times L & \text{for}\ 0 \leq L < 0.0030186 1059 \end{cases} 1060\end{aligned} 1061+++++++++++++++++++ 1062 1063where [eq]#L# is the linear value of a color component and [eq]#E# is the 1064encoded value (as stored in the image in memory). 1065 1066[NOTE] 1067.Note 1068==== 1069For most uses, the sRGB OETF is equivalent. 1070==== 1071endif::VK_EXT_swapchain_colorspace[] 1072-- 1073 1074 1075=== Surface Presentation Mode Support 1076 1077[open,refpage='vkGetPhysicalDeviceSurfacePresentModesKHR',desc='Query supported presentation modes',type='protos'] 1078-- 1079:refpage: vkGetPhysicalDeviceSurfacePresentModesKHR 1080 1081To query the supported presentation modes for a surface, call: 1082 1083include::{generated}/api/protos/vkGetPhysicalDeviceSurfacePresentModesKHR.txt[] 1084 1085 * pname:physicalDevice is the physical device that will be associated with 1086 the swapchain to be created, as described for 1087 flink:vkCreateSwapchainKHR. 1088 * pname:surface is the surface that will be associated with the swapchain. 1089 * pname:pPresentModeCount is a pointer to an integer related to the number 1090 of presentation modes available or queried, as described below. 1091 * pname:pPresentModes is either `NULL` or a pointer to an array of 1092 elink:VkPresentModeKHR values, indicating the supported presentation 1093 modes. 1094 1095If pname:pPresentModes is `NULL`, then the number of presentation modes 1096supported for the given pname:surface is returned in 1097pname:pPresentModeCount. 1098Otherwise, pname:pPresentModeCount must: point to a variable set by the user 1099to the number of elements in the pname:pPresentModes array, and on return 1100the variable is overwritten with the number of values actually written to 1101pname:pPresentModes. 1102If the value of pname:pPresentModeCount is less than the number of 1103presentation modes supported, at most pname:pPresentModeCount values will be 1104written, and ename:VK_INCOMPLETE will be returned instead of 1105ename:VK_SUCCESS, to indicate that not all the available modes were 1106returned. 1107 1108.Valid Usage 1109**** 1110include::{chapters}/commonvalidity/surface_physical_device_common.txt[] 1111**** 1112 1113include::{generated}/validity/protos/vkGetPhysicalDeviceSurfacePresentModesKHR.txt[] 1114-- 1115 1116ifdef::VK_EXT_full_screen_exclusive[] 1117[open,refpage='vkGetPhysicalDeviceSurfacePresentModes2EXT',desc='Query supported presentation modes',type='protos'] 1118-- 1119:refpage: vkGetPhysicalDeviceSurfacePresentModes2EXT 1120 1121Alternatively, to query the supported presentation modes for a surface 1122combined with select other fixed swapchain creation parameters, call: 1123 1124include::{generated}/api/protos/vkGetPhysicalDeviceSurfacePresentModes2EXT.txt[] 1125 1126 * pname:physicalDevice is the physical device that will be associated with 1127 the swapchain to be created, as described for 1128 flink:vkCreateSwapchainKHR. 1129 * pname:pSurfaceInfo is a pointer to a 1130 slink:VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface 1131 and other fixed parameters that would be consumed by 1132 flink:vkCreateSwapchainKHR. 1133 * pname:pPresentModeCount is a pointer to an integer related to the number 1134 of presentation modes available or queried, as described below. 1135 * pname:pPresentModes is either `NULL` or a pointer to an array of 1136 elink:VkPresentModeKHR values, indicating the supported presentation 1137 modes. 1138 1139fname:vkGetPhysicalDeviceSurfacePresentModes2EXT behaves similarly to 1140flink:vkGetPhysicalDeviceSurfacePresentModesKHR, with the ability to specify 1141extended inputs via chained input structures. 1142 1143.Valid Usage 1144**** 1145include::{chapters}/commonvalidity/surface_info_physical_device_common.txt[] 1146**** 1147 1148include::{generated}/validity/protos/vkGetPhysicalDeviceSurfacePresentModes2EXT.txt[] 1149-- 1150endif::VK_EXT_full_screen_exclusive[] 1151 1152[open,refpage='VkPresentModeKHR',desc='Presentation mode supported for a surface',type='enums'] 1153-- 1154Possible values of elements of the 1155flink:vkGetPhysicalDeviceSurfacePresentModesKHR::pname:pPresentModes array, 1156indicating the supported presentation modes for a surface, are: 1157 1158include::{generated}/api/enums/VkPresentModeKHR.txt[] 1159 1160 * ename:VK_PRESENT_MODE_IMMEDIATE_KHR specifies that the presentation 1161 engine does not wait for a vertical blanking period to update the 1162 current image, meaning this mode may: result in visible tearing. 1163 No internal queuing of presentation requests is needed, as the requests 1164 are applied immediately. 1165 * ename:VK_PRESENT_MODE_MAILBOX_KHR specifies that the presentation engine 1166 waits for the next vertical blanking period to update the current image. 1167 Tearing cannot: be observed. 1168 An internal single-entry queue is used to hold pending presentation 1169 requests. 1170 If the queue is full when a new presentation request is received, the 1171 new request replaces the existing entry, and any images associated with 1172 the prior entry become available for re-use by the application. 1173 One request is removed from the queue and processed during each vertical 1174 blanking period in which the queue is non-empty. 1175 * ename:VK_PRESENT_MODE_FIFO_KHR specifies that the presentation engine 1176 waits for the next vertical blanking period to update the current image. 1177 Tearing cannot: be observed. 1178 An internal queue is used to hold pending presentation requests. 1179 New requests are appended to the end of the queue, and one request is 1180 removed from the beginning of the queue and processed during each 1181 vertical blanking period in which the queue is non-empty. 1182 This is the only value of pname:presentMode that is required: to be 1183 supported. 1184 * ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR specifies that the presentation 1185 engine generally waits for the next vertical blanking period to update 1186 the current image. 1187 If a vertical blanking period has already passed since the last update 1188 of the current image then the presentation engine does not wait for 1189 another vertical blanking period for the update, meaning this mode may: 1190 result in visible tearing in this case. 1191 This mode is useful for reducing visual stutter with an application that 1192 will mostly present a new image before the next vertical blanking 1193 period, but may occasionally be late, and present a new image just after 1194 the next vertical blanking period. 1195 An internal queue is used to hold pending presentation requests. 1196 New requests are appended to the end of the queue, and one request is 1197 removed from the beginning of the queue and processed during or after 1198 each vertical blanking period in which the queue is non-empty. 1199ifdef::VK_KHR_shared_presentable_image[] 1200 * ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR specifies that the 1201 presentation engine and application have concurrent access to a single 1202 image, which is referred to as a _shared presentable image_. 1203 The presentation engine is only required to update the current image 1204 after a new presentation request is received. 1205 Therefore the application must: make a presentation request whenever an 1206 update is required. 1207 However, the presentation engine may: update the current image at any 1208 point, meaning this mode may: result in visible tearing. 1209 * ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR specifies that the 1210 presentation engine and application have concurrent access to a single 1211 image, which is referred to as a _shared presentable image_. 1212 The presentation engine periodically updates the current image on its 1213 regular refresh cycle. 1214 The application is only required to make one initial presentation 1215 request, after which the presentation engine must: update the current 1216 image without any need for further presentation requests. 1217 The application can: indicate the image contents have been updated by 1218 making a presentation request, but this does not guarantee the timing of 1219 when it will be updated. 1220 This mode may: result in visible tearing if rendering to the image is 1221 not timed correctly. 1222 1223The supported elink:VkImageUsageFlagBits of the presentable images of a 1224swapchain created for a surface may: differ depending on the presentation 1225mode, and can be determined as per the table below: 1226 1227.Presentable image usage queries 1228[width="100%",cols="<50%,<50%",options="header"] 1229|==== 1230| Presentation mode | Image usage flags 1231| ename:VK_PRESENT_MODE_IMMEDIATE_KHR | slink:VkSurfaceCapabilitiesKHR::pname:supportedUsageFlags 1232| ename:VK_PRESENT_MODE_MAILBOX_KHR | slink:VkSurfaceCapabilitiesKHR::pname:supportedUsageFlags 1233| ename:VK_PRESENT_MODE_FIFO_KHR | slink:VkSurfaceCapabilitiesKHR::pname:supportedUsageFlags 1234| ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR | slink:VkSurfaceCapabilitiesKHR::pname:supportedUsageFlags 1235| ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR | slink:VkSharedPresentSurfaceCapabilitiesKHR::pname:sharedPresentSupportedUsageFlags 1236| ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR | slink:VkSharedPresentSurfaceCapabilitiesKHR::pname:sharedPresentSupportedUsageFlags 1237|==== 1238endif::VK_KHR_shared_presentable_image[] 1239 1240[NOTE] 1241.Note 1242==== 1243For reference, the mode indicated by ename:VK_PRESENT_MODE_FIFO_KHR is 1244equivalent to the behavior of {wgl|glX|egl}SwapBuffers with a swap interval 1245of 1, while the mode indicated by ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR is 1246equivalent to the behavior of {wgl|glX}SwapBuffers with a swap interval of 1247-1 (from the {WGL|GLX}_EXT_swap_control_tear extensions). 1248==== 1249-- 1250 1251ifdef::VK_EXT_full_screen_exclusive[] 1252== Full Screen Exclusive Control 1253 1254Swapchains created with pname:fullScreenExclusive set to 1255ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT must: acquire and 1256release exclusive full-screen access explicitly, using the following 1257commands. 1258 1259[open,refpage='vkAcquireFullScreenExclusiveModeEXT',desc='Acquire full-screen exclusive mode for a swapchain',type='protos'] 1260-- 1261To acquire exclusive full-screen access for a swapchain, call: 1262 1263include::{generated}/api/protos/vkAcquireFullScreenExclusiveModeEXT.txt[] 1264 1265 * pname:device is the device associated with pname:swapchain. 1266 * pname:swapchain is the swapchain to acquire exclusive full-screen access 1267 for. 1268 1269.Valid Usage 1270**** 1271 * [[VUID-vkAcquireFullScreenExclusiveModeEXT-swapchain-02674]] 1272 pname:swapchain must: not be in the retired state 1273 * [[VUID-vkAcquireFullScreenExclusiveModeEXT-swapchain-02675]] 1274 pname:swapchain must: be a swapchain created with a 1275 slink:VkSurfaceFullScreenExclusiveInfoEXT structure, with 1276 pname:fullScreenExclusive set to 1277 ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT 1278 * [[VUID-vkAcquireFullScreenExclusiveModeEXT-swapchain-02676]] 1279 pname:swapchain must: not currently have exclusive full-screen access 1280**** 1281 1282A return value of ename:VK_SUCCESS indicates that the pname:swapchain 1283successfully acquired exclusive full-screen access. 1284The swapchain will retain this exclusivity until either the application 1285releases exclusive full-screen access with 1286flink:vkReleaseFullScreenExclusiveModeEXT, destroys the swapchain, or if any 1287of the swapchain commands return 1288ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT indicating that the mode 1289was lost because of platform-specific changes. 1290 1291If the swapchain was unable to acquire exclusive full-screen access to the 1292display then ename:VK_ERROR_INITIALIZATION_FAILED is returned. 1293An application can: attempt to acquire exclusive full-screen access again 1294for the same swapchain even if this command fails, or if 1295ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT has been returned by a 1296swapchain command. 1297 1298include::{generated}/validity/protos/vkAcquireFullScreenExclusiveModeEXT.txt[] 1299-- 1300 1301[open,refpage='vkReleaseFullScreenExclusiveModeEXT',desc='Release full-screen exclusive mode from a swapchain',type='protos'] 1302-- 1303To release exclusive full-screen access from a swapchain, call: 1304 1305include::{generated}/api/protos/vkReleaseFullScreenExclusiveModeEXT.txt[] 1306 1307 * pname:device is the device associated with pname:swapchain. 1308 * pname:swapchain is the swapchain to release exclusive full-screen access 1309 from. 1310 1311[NOTE] 1312.Note 1313==== 1314Applications will not be able to present to pname:swapchain after this call 1315until exclusive full-screen access is reacquired. 1316This is usually useful to handle when an application is minimised or 1317otherwise intends to stop presenting for a time. 1318==== 1319 1320.Valid Usage 1321**** 1322 * [[VUID-vkReleaseFullScreenExclusiveModeEXT-swapchain-02677]] 1323 pname:swapchain must: not be in the retired state 1324 * [[VUID-vkReleaseFullScreenExclusiveModeEXT-swapchain-02678]] 1325 pname:swapchain must: be a swapchain created with a 1326 slink:VkSurfaceFullScreenExclusiveInfoEXT structure, with 1327 pname:fullScreenExclusive set to 1328 ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT 1329**** 1330-- 1331endif::VK_EXT_full_screen_exclusive[] 1332 1333 1334ifdef::VK_KHR_swapchain[] 1335ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1336== Device Group Queries 1337 1338[open,refpage='vkGetDeviceGroupPresentCapabilitiesKHR',desc='Query present capabilities from other physical devices',type='protos'] 1339-- 1340A logical device that represents multiple physical devices may: support 1341presenting from images on more than one physical device, or combining images 1342from multiple physical devices. 1343 1344To query these capabilities, call: 1345 1346include::{generated}/api/protos/vkGetDeviceGroupPresentCapabilitiesKHR.txt[] 1347 1348 * pname:device is the logical device. 1349 * pname:pDeviceGroupPresentCapabilities is a pointer to a 1350 slink:VkDeviceGroupPresentCapabilitiesKHR structure in which the 1351 device's capabilities are returned. 1352 1353include::{generated}/validity/protos/vkGetDeviceGroupPresentCapabilitiesKHR.txt[] 1354-- 1355 1356[open,refpage='VkDeviceGroupPresentCapabilitiesKHR',desc='Present capabilities from other physical devices',type='structs'] 1357-- 1358The sname:VkDeviceGroupPresentCapabilitiesKHR structure is defined as: 1359 1360include::{generated}/api/structs/VkDeviceGroupPresentCapabilitiesKHR.txt[] 1361 1362 * pname:sType is the type of this structure. 1363 * pname:pNext is `NULL` or a pointer to a structure extending this 1364 structure. 1365 * pname:presentMask is an array of ename:VK_MAX_DEVICE_GROUP_SIZE 1366 code:uint32_t masks, where the mask at element [eq]#i# is non-zero if 1367 physical device [eq]#i# has a presentation engine, and where bit [eq]#j# 1368 is set in element [eq]#i# if physical device [eq]#i# can: present 1369 swapchain images from physical device [eq]#j#. 1370 If element [eq]#i# is non-zero, then bit [eq]#i# must: be set. 1371 * pname:modes is a bitmask of elink:VkDeviceGroupPresentModeFlagBitsKHR 1372 indicating which device group presentation modes are supported. 1373 1374pname:modes always has ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR set. 1375 1376The present mode flags are also used when presenting an image, in 1377slink:VkDeviceGroupPresentInfoKHR::pname:mode. 1378 1379If a device group only includes a single physical device, then pname:modes 1380must: equal ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR. 1381 1382include::{generated}/validity/structs/VkDeviceGroupPresentCapabilitiesKHR.txt[] 1383-- 1384 1385 1386[open,refpage='VkDeviceGroupPresentModeFlagBitsKHR',desc='Bitmask specifying supported device group present modes',type='enums'] 1387-- 1388Bits which may: be set in 1389slink:VkDeviceGroupPresentCapabilitiesKHR::pname:modes to indicate which 1390device group presentation modes are supported are: 1391 1392include::{generated}/api/enums/VkDeviceGroupPresentModeFlagBitsKHR.txt[] 1393 1394 * ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR specifies that any 1395 physical device with a presentation engine can: present its own 1396 swapchain images. 1397 * ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR specifies that any 1398 physical device with a presentation engine can: present swapchain images 1399 from any physical device in its pname:presentMask. 1400 * ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR specifies that any 1401 physical device with a presentation engine can: present the sum of 1402 swapchain images from any physical devices in its pname:presentMask. 1403 * ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR specifies 1404 that multiple physical devices with a presentation engine can: each 1405 present their own swapchain images. 1406-- 1407 1408[open,refpage='VkDeviceGroupPresentModeFlagsKHR',desc='Bitmask of VkDeviceGroupPresentModeFlagBitsKHR',type='flags'] 1409-- 1410include::{generated}/api/flags/VkDeviceGroupPresentModeFlagsKHR.txt[] 1411 1412tname:VkDeviceGroupPresentModeFlagsKHR is a bitmask type for setting a mask 1413of zero or more elink:VkDeviceGroupPresentModeFlagBitsKHR. 1414-- 1415 1416[open,refpage='vkGetDeviceGroupSurfacePresentModesKHR',desc='Query present capabilities for a surface',type='protos'] 1417-- 1418Some surfaces may: not be capable of using all the device group present 1419modes. 1420 1421To query the supported device group present modes for a particular surface, 1422call: 1423 1424include::{generated}/api/protos/vkGetDeviceGroupSurfacePresentModesKHR.txt[] 1425 1426 * pname:device is the logical device. 1427 * pname:surface is the surface. 1428 * pname:pModes is a pointer to a tlink:VkDeviceGroupPresentModeFlagsKHR in 1429 which the supported device group present modes for the surface are 1430 returned. 1431 1432The modes returned by this command are not invariant, and may: change in 1433response to the surface being moved, resized, or occluded. 1434These modes must: be a subset of the modes returned by 1435flink:vkGetDeviceGroupPresentCapabilitiesKHR. 1436 1437.Valid Usage 1438**** 1439 * [[VUID-vkGetDeviceGroupSurfacePresentModesKHR-surface-06212]] 1440 pname:surface must: be supported by all physical devices associated with 1441 pname:device, as reported by flink:vkGetPhysicalDeviceSurfaceSupportKHR 1442 or an equivalent platform-specific mechanism 1443**** 1444 1445include::{generated}/validity/protos/vkGetDeviceGroupSurfacePresentModesKHR.txt[] 1446-- 1447 1448ifdef::VK_EXT_full_screen_exclusive[] 1449[open,refpage='vkGetDeviceGroupSurfacePresentModes2EXT',desc='Query device group present capabilities for a surface',type='protos'] 1450-- 1451Alternatively, to query the supported device group presentation modes for a 1452surface combined with select other fixed swapchain creation parameters, 1453call: 1454 1455include::{generated}/api/protos/vkGetDeviceGroupSurfacePresentModes2EXT.txt[] 1456 1457 * pname:device is the logical device. 1458 * pname:pSurfaceInfo is a pointer to a 1459 slink:VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface 1460 and other fixed parameters that would be consumed by 1461 flink:vkCreateSwapchainKHR. 1462 * pname:pModes is a pointer to a tlink:VkDeviceGroupPresentModeFlagsKHR in 1463 which the supported device group present modes for the surface are 1464 returned. 1465 1466fname:vkGetDeviceGroupSurfacePresentModes2EXT behaves similarly to 1467flink:vkGetDeviceGroupSurfacePresentModesKHR, with the ability to specify 1468extended inputs via chained input structures. 1469 1470.Valid Usage 1471**** 1472 * [[VUID-vkGetDeviceGroupSurfacePresentModes2EXT-pSurfaceInfo-06213]] 1473 pname:pSurfaceInfo->surface must: be supported by all physical devices 1474 associated with pname:device, as reported by 1475 flink:vkGetPhysicalDeviceSurfaceSupportKHR or an equivalent 1476 platform-specific mechanism 1477**** 1478 1479include::{generated}/validity/protos/vkGetDeviceGroupSurfacePresentModes2EXT.txt[] 1480-- 1481endif::VK_EXT_full_screen_exclusive[] 1482 1483[open,refpage='vkGetPhysicalDevicePresentRectanglesKHR',desc='Query present rectangles for a surface on a physical device',type='protos'] 1484-- 1485:refpage: vkGetPhysicalDevicePresentRectanglesKHR 1486 1487When using ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, 1488the application may: need to know which regions of the surface are used when 1489presenting locally on each physical device. 1490Presentation of swapchain images to this surface need only have valid 1491contents in the regions returned by this command. 1492 1493To query a set of rectangles used in presentation on the physical device, 1494call: 1495 1496include::{generated}/api/protos/vkGetPhysicalDevicePresentRectanglesKHR.txt[] 1497 1498 * pname:physicalDevice is the physical device. 1499 * pname:surface is the surface. 1500 * pname:pRectCount is a pointer to an integer related to the number of 1501 rectangles available or queried, as described below. 1502 * pname:pRects is either `NULL` or a pointer to an array of slink:VkRect2D 1503 structures. 1504 1505If pname:pRects is `NULL`, then the number of rectangles used when 1506presenting the given pname:surface is returned in pname:pRectCount. 1507Otherwise, pname:pRectCount must: point to a variable set by the user to the 1508number of elements in the pname:pRects array, and on return the variable is 1509overwritten with the number of structures actually written to pname:pRects. 1510If the value of pname:pRectCount is less than the number of rectangles, at 1511most pname:pRectCount structures will be written, and ename:VK_INCOMPLETE 1512will be returned instead of ename:VK_SUCCESS, to indicate that not all the 1513available rectangles were returned. 1514 1515The values returned by this command are not invariant, and may: change in 1516response to the surface being moved, resized, or occluded. 1517 1518The rectangles returned by this command must: not overlap. 1519 1520.Valid Usage 1521**** 1522include::{chapters}/commonvalidity/surface_physical_device_common.txt[] 1523**** 1524 1525include::{generated}/validity/protos/vkGetPhysicalDevicePresentRectanglesKHR.txt[] 1526-- 1527endif::VK_VERSION_1_1,VK_KHR_device_group[] 1528 1529ifdef::VK_GOOGLE_display_timing[] 1530include::{chapters}/VK_GOOGLE_display_timing/queries.txt[] 1531endif::VK_GOOGLE_display_timing[] 1532 1533ifdef::VK_KHR_present_wait[] 1534include::{chapters}/VK_KHR_present_wait/present_wait.txt[] 1535endif::VK_KHR_present_wait[] 1536 1537include::{chapters}/VK_KHR_swapchain/wsi.txt[] 1538endif::VK_KHR_swapchain[] 1539