1// Copyright 2014-2024 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5== WSI Swapchain 6 7[open,refpage='VkSwapchainKHR',desc='Opaque handle to a swapchain object',type='handles',xrefs='vkQueuePresentKHR'] 8-- 9A swapchain object (a.k.a. 10swapchain) provides the ability to present rendering results to a surface. 11Swapchain objects are represented by sname:VkSwapchainKHR handles: 12 13include::{generated}/api/handles/VkSwapchainKHR.adoc[] 14 15A swapchain is an abstraction for an array of presentable images that are 16associated with a surface. 17The presentable images are represented by sname:VkImage objects created by 18the platform. 19One image (which can: be an array image for multiview/stereoscopic-3D 20surfaces) is displayed at a time, but multiple images can: be queued for 21presentation. 22An application renders to the image, and then queues the image for 23presentation to the surface. 24 25A native window cannot: be associated with more than one non-retired 26swapchain at a time. 27Further, swapchains cannot: be created for native windows that have a 28non-Vulkan graphics API surface associated with them. 29 30[NOTE] 31.Note 32==== 33The presentation engine is an abstraction for the platform's compositor or 34display engine. 35 36The presentation engine may: be synchronous or asynchronous with respect to 37the application and/or logical device. 38 39Some implementations may: use the device's graphics queue or dedicated 40presentation hardware to perform presentation. 41==== 42 43The presentable images of a swapchain are owned by the presentation engine. 44An application can: acquire use of a presentable image from the presentation 45engine. 46Use of a presentable image must: occur only after the image is returned by 47flink:vkAcquireNextImageKHR, and before it is released by 48flink:vkQueuePresentKHR. 49This includes transitioning the image layout and rendering commands. 50 51An application can: acquire use of a presentable image with 52flink:vkAcquireNextImageKHR. 53After acquiring a presentable image and before modifying it, the application 54must: use a synchronization primitive to ensure that the presentation engine 55has finished reading from the image. 56The application can: then transition the image's layout, queue rendering 57commands to it, etc. 58Finally, the application presents the image with flink:vkQueuePresentKHR, 59which releases the acquisition of the image. 60ifdef::VK_EXT_swapchain_maintenance1[] 61The application can: also release the acquisition of the image through 62flink:vkReleaseSwapchainImagesEXT, if the image is not in use by the device, 63and skip the present operation. 64endif::VK_EXT_swapchain_maintenance1[] 65 66The presentation engine controls the order in which presentable images are 67acquired for use by the application. 68 69[NOTE] 70.Note 71==== 72This allows the platform to handle situations which require out-of-order 73return of images after presentation. 74At the same time, it allows the application to generate command buffers 75referencing all of the images in the swapchain at initialization time, 76rather than in its main loop. 77==== 78-- 79 80How this all works is described below. 81 82ifdef::VK_KHR_shared_presentable_image[] 83include::{chapters}/VK_KHR_shared_presentable_image/wsi.adoc[] 84endif::VK_KHR_shared_presentable_image[] 85 86[open,refpage='vkCreateSwapchainKHR',desc='Create a swapchain',type='protos'] 87-- 88:refpage: vkCreateSwapchainKHR 89:objectnameplural: swapchains 90:objectnamecamelcase: swapchain 91:objectcount: 1 92 93To create a swapchain, call: 94 95include::{generated}/api/protos/vkCreateSwapchainKHR.adoc[] 96 97 * pname:device is the device to create the swapchain for. 98 * pname:pCreateInfo is a pointer to a slink:VkSwapchainCreateInfoKHR 99 structure specifying the parameters of the created swapchain. 100 * pname:pAllocator is the allocator used for host memory allocated for the 101 swapchain object when there is no more specific allocator available (see 102 <<memory-allocation,Memory Allocation>>). 103 * pname:pSwapchain is a pointer to a slink:VkSwapchainKHR handle in which 104 the created swapchain object will be returned. 105 106As mentioned above, if fname:vkCreateSwapchainKHR succeeds, it will return a 107handle to a swapchain containing an array of at least 108pname:pCreateInfo->minImageCount presentable images. 109 110While acquired by the application, presentable images can: be used in any 111way that equivalent non-presentable images can: be used. 112A presentable image is equivalent to a non-presentable image created with 113the following slink:VkImageCreateInfo parameters: 114 115[[swapchain-wsi-image-create-info]] 116[options="header"] 117|==== 118| sname:VkImageCreateInfo Field | Value 119ifndef::VK_VERSION_1_1,VK_KHR_device_group,VK_KHR_swapchain_mutable_format[] 120| pname:flags | 0 121endif::VK_VERSION_1_1,VK_KHR_device_group,VK_KHR_swapchain_mutable_format[] 122ifdef::VK_VERSION_1_1,VK_KHR_device_group,VK_KHR_swapchain_mutable_format[] 123| pname:flags | 124ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 125ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT is set if 126ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR is set 127 128endif::VK_VERSION_1_1,VK_KHR_device_group[] 129ifdef::VK_VERSION_1_1[] 130ename:VK_IMAGE_CREATE_PROTECTED_BIT is set if 131ename:VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR is set 132 133endif::VK_VERSION_1_1[] 134ifdef::VK_KHR_swapchain_mutable_format[] 135ename:VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT and 136ename:VK_IMAGE_CREATE_EXTENDED_USAGE_BIT_KHR are both set if 137ename:VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR is set 138 139endif::VK_KHR_swapchain_mutable_format[] 140all other bits are unset 141endif::VK_VERSION_1_1,VK_KHR_device_group,VK_KHR_swapchain_mutable_format[] 142| pname:imageType | ename:VK_IMAGE_TYPE_2D 143| pname:format | pname:pCreateInfo->imageFormat 144| pname:extent | {pname:pCreateInfo->imageExtent.width, pname:pCreateInfo->imageExtent.height, `1`} 145| pname:mipLevels | 1 146| pname:arrayLayers | pname:pCreateInfo->imageArrayLayers 147| pname:samples | ename:VK_SAMPLE_COUNT_1_BIT 148| pname:tiling | ename:VK_IMAGE_TILING_OPTIMAL 149| pname:usage | pname:pCreateInfo->imageUsage 150| pname:sharingMode | pname:pCreateInfo->imageSharingMode 151| pname:queueFamilyIndexCount | pname:pCreateInfo->queueFamilyIndexCount 152| pname:pQueueFamilyIndices | pname:pCreateInfo->pQueueFamilyIndices 153| pname:initialLayout | ename:VK_IMAGE_LAYOUT_UNDEFINED 154|==== 155 156The pname:pCreateInfo->surface must: not be destroyed until after the 157swapchain is destroyed. 158 159ifdef::VKSC_VERSION_1_0[If] 160ifndef::VKSC_VERSION_1_0[If pname:oldSwapchain is dlink:VK_NULL_HANDLE, and] 161the native window referred to by pname:pCreateInfo->surface is already 162associated with a Vulkan swapchain, ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR 163must: be returned. 164 165If the native window referred to by pname:pCreateInfo->surface is already 166associated with a non-Vulkan graphics API surface, 167ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR must: be returned. 168 169The native window referred to by pname:pCreateInfo->surface must: not become 170associated with a non-Vulkan graphics API surface before all associated 171Vulkan swapchains have been destroyed. 172 173fname:vkCreateSwapchainKHR will return ename:VK_ERROR_DEVICE_LOST if the 174logical device was lost. 175ifndef::VKSC_VERSION_1_0[] 176The sname:VkSwapchainKHR is a child of the pname:device, and must: be 177destroyed before the pname:device. 178endif::VKSC_VERSION_1_0[] 179However, sname:VkSurfaceKHR is not a child of any sname:VkDevice and is not 180affected by the lost device. 181After successfully recreating a sname:VkDevice, the same sname:VkSurfaceKHR 182can: be used to create a new sname:VkSwapchainKHR, provided the previous one 183was destroyed. 184 185ifdef::VK_EXT_full_screen_exclusive[] 186If the pname:oldSwapchain parameter of pname:pCreateInfo is a valid 187swapchain, which has exclusive full-screen access, that access is released 188from pname:pCreateInfo->oldSwapchain. 189If the command succeeds in this case, the newly created swapchain will 190automatically acquire exclusive full-screen access from 191pname:pCreateInfo->oldSwapchain. 192 193[NOTE] 194.Note 195==== 196This implicit transfer is intended to avoid exiting and entering full-screen 197exclusive mode, which may otherwise cause unwanted visual updates to the 198display. 199==== 200 201In some cases, swapchain creation may: fail if exclusive full-screen mode is 202requested for application control, but for some implementation-specific 203reason exclusive full-screen access is unavailable for the particular 204combination of parameters provided. 205If this occurs, ename:VK_ERROR_INITIALIZATION_FAILED will be returned. 206 207[NOTE] 208.Note 209==== 210In particular, it will fail if the pname:imageExtent member of 211pname:pCreateInfo does not match the extents of the monitor. 212ifdef::VK_KHR_win32_surface[] 213Other reasons for failure may include the app not being set as high-dpi 214aware, or if the physical device and monitor are not compatible in this 215mode. 216endif::VK_KHR_win32_surface[] 217==== 218 219endif::VK_EXT_full_screen_exclusive[] 220 221ifdef::VK_NV_present_barrier[] 222If the pname:pNext chain of slink:VkSwapchainCreateInfoKHR includes a 223slink:VkSwapchainPresentBarrierCreateInfoNV structure, then that structure 224includes additional swapchain creation parameters specific to the present 225barrier. 226Swapchain creation may: fail if the state of the current system restricts 227the usage of the present barrier feature 228slink:VkSurfaceCapabilitiesPresentBarrierNV, or a swapchain itself does not 229satisfy all the required conditions. 230In this scenario ename:VK_ERROR_INITIALIZATION_FAILED is returned. 231endif::VK_NV_present_barrier[] 232 233ifdef::VK_NV_acquire_winrt_display[] 234When the slink:VkSurfaceKHR in slink:VkSwapchainCreateInfoKHR is a display 235surface, then the slink:VkDisplayModeKHR in display surface's 236slink:VkDisplaySurfaceCreateInfoKHR is associated with a particular 237slink:VkDisplayKHR. 238Swapchain creation may: fail if that slink:VkDisplayKHR is not acquired by 239the application. 240In this scenario ename:VK_ERROR_INITIALIZATION_FAILED is returned. 241endif::VK_NV_acquire_winrt_display[] 242 243include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 244 245ifdef::VKSC_VERSION_1_0[] 246.Valid Usage 247**** 248include::{chapters}/commonvalidity/memory_reservation_request_count_common.adoc[] 249**** 250endif::VKSC_VERSION_1_0[] 251 252include::{generated}/validity/protos/vkCreateSwapchainKHR.adoc[] 253-- 254 255[open,refpage='VkSwapchainCreateInfoKHR',desc='Structure specifying parameters of a newly created swapchain object',type='structs'] 256-- 257The sname:VkSwapchainCreateInfoKHR structure is defined as: 258 259include::{generated}/api/structs/VkSwapchainCreateInfoKHR.adoc[] 260 261 * pname:sType is a elink:VkStructureType value identifying this structure. 262 * pname:pNext is `NULL` or a pointer to a structure extending this 263 structure. 264 * pname:flags is a bitmask of elink:VkSwapchainCreateFlagBitsKHR 265 indicating parameters of the swapchain creation. 266 * pname:surface is the surface onto which the swapchain will present 267 images. 268 If the creation succeeds, the swapchain becomes associated with 269 pname:surface. 270 * pname:minImageCount is the minimum number of presentable images that the 271 application needs. 272 The implementation will either create the swapchain with at least that 273 many images, or it will fail to create the swapchain. 274 * pname:imageFormat is a elink:VkFormat value specifying the format the 275 swapchain image(s) will be created with. 276 * pname:imageColorSpace is a elink:VkColorSpaceKHR value specifying the 277 way the swapchain interprets image data. 278 * pname:imageExtent is the size (in pixels) of the swapchain image(s). 279 The behavior is platform-dependent if the image extent does not match 280 the surface's pname:currentExtent as returned by 281 fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR. 282+ 283[NOTE] 284.Note 285==== 286On some platforms, it is normal that pname:maxImageExtent may: become `(0, 2870)`, for example when the window is minimized. 288In such a case, it is not possible to create a swapchain due to the Valid 289Usage requirements 290ifdef::VK_EXT_swapchain_maintenance1[] 291, unless scaling is selected through 292slink:VkSwapchainPresentScalingCreateInfoEXT, if supported 293endif::VK_EXT_swapchain_maintenance1[] 294. 295==== 296 * pname:imageArrayLayers is the number of views in a multiview/stereo 297 surface. 298 For non-stereoscopic-3D applications, this value is 1. 299 * pname:imageUsage is a bitmask of elink:VkImageUsageFlagBits describing 300 the intended usage of the (acquired) swapchain images. 301 * pname:imageSharingMode is the sharing mode used for the image(s) of the 302 swapchain. 303 * pname:queueFamilyIndexCount is the number of queue families having 304 access to the image(s) of the swapchain when pname:imageSharingMode is 305 ename:VK_SHARING_MODE_CONCURRENT. 306 * pname:pQueueFamilyIndices is a pointer to an array of queue family 307 indices having access to the images(s) of the swapchain when 308 pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT. 309 * pname:preTransform is a elink:VkSurfaceTransformFlagBitsKHR value 310 describing the transform, relative to the presentation engine's natural 311 orientation, applied to the image content prior to presentation. 312 If it does not match the pname:currentTransform value returned by 313 fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, the presentation engine 314 will transform the image content as part of the presentation operation. 315 * pname:compositeAlpha is a elink:VkCompositeAlphaFlagBitsKHR value 316 indicating the alpha compositing mode to use when this surface is 317 composited together with other surfaces on certain window systems. 318 * pname:presentMode is the presentation mode the swapchain will use. 319 A swapchain's present mode determines how incoming present requests will 320 be processed and queued internally. 321 * pname:clipped specifies whether the Vulkan implementation is allowed to 322 discard rendering operations that affect regions of the surface that are 323 not visible. 324 ** If set to ename:VK_TRUE, the presentable images associated with the 325 swapchain may: not own all of their pixels. 326 Pixels in the presentable images that correspond to regions of the 327 target surface obscured by another window on the desktop, or subject to 328 some other clipping mechanism will have undefined: content when read 329 back. 330 Fragment shaders may: not execute for these pixels, and thus any side 331 effects they would have had will not occur. 332 Setting ename:VK_TRUE does not guarantee any clipping will occur, but 333 allows more efficient presentation methods to be used on some 334 platforms. 335 ** If set to ename:VK_FALSE, presentable images associated with the 336 swapchain will own all of the pixels they contain. 337+ 338[NOTE] 339.Note 340==== 341Applications should: set this value to ename:VK_TRUE if they do not expect 342to read back the content of presentable images before presenting them or 343after reacquiring them, and if their fragment shaders do not have any side 344effects that require them to run for all pixels in the presentable image. 345==== 346ifdef::VKSC_VERSION_1_0[] 347 * pname:oldSwapchain must: be dlink:VK_NULL_HANDLE in Vulkan SC 348 <<SCID-4>>. 349endif::VKSC_VERSION_1_0[] 350ifndef::VKSC_VERSION_1_0[] 351 * pname:oldSwapchain is dlink:VK_NULL_HANDLE, or the existing non-retired 352 swapchain currently associated with pname:surface. 353 Providing a valid pname:oldSwapchain may: aid in the resource reuse, and 354 also allows the application to still present any images that are already 355 acquired from it. 356endif::VKSC_VERSION_1_0[] 357 358ifndef::VKSC_VERSION_1_0[] 359Upon calling fname:vkCreateSwapchainKHR with an pname:oldSwapchain that is 360not dlink:VK_NULL_HANDLE, pname:oldSwapchain is retired -- even if creation 361of the new swapchain fails. 362The new swapchain is created in the non-retired state whether or not 363pname:oldSwapchain is dlink:VK_NULL_HANDLE. 364 365Upon calling fname:vkCreateSwapchainKHR with an pname:oldSwapchain that is 366not dlink:VK_NULL_HANDLE, any images from pname:oldSwapchain that are not 367acquired by the application may: be freed by the implementation, which may: 368occur even if creation of the new swapchain fails. 369The application can: destroy pname:oldSwapchain to free all memory 370associated with pname:oldSwapchain. 371 372[NOTE] 373.Note 374==== 375Multiple retired swapchains can: be associated with the same 376sname:VkSurfaceKHR through multiple uses of pname:oldSwapchain that 377outnumber calls to flink:vkDestroySwapchainKHR. 378 379After pname:oldSwapchain is retired, the application can: pass to 380flink:vkQueuePresentKHR any images it had already acquired from 381pname:oldSwapchain. 382E.g., an application may present an image from the old swapchain before an 383image from the new swapchain is ready to be presented. 384As usual, flink:vkQueuePresentKHR may: fail if pname:oldSwapchain has 385entered a state that causes ename:VK_ERROR_OUT_OF_DATE_KHR to be returned. 386 387ifdef::VK_KHR_shared_presentable_image[] 388The application can: continue to use a shared presentable image obtained 389from pname:oldSwapchain until a presentable image is acquired from the new 390swapchain, as long as it has not entered a state that causes it to return 391ename:VK_ERROR_OUT_OF_DATE_KHR. 392endif::VK_KHR_shared_presentable_image[] 393==== 394endif::VKSC_VERSION_1_0[] 395 396.Valid Usage 397**** 398 * [[VUID-VkSwapchainCreateInfoKHR-surface-01270]] 399 pname:surface must: be a surface that is supported by the device as 400 determined using flink:vkGetPhysicalDeviceSurfaceSupportKHR 401 * [[VUID-VkSwapchainCreateInfoKHR-minImageCount-01272]] 402 pname:minImageCount must: be less than or equal to the value returned in 403 the pname:maxImageCount member of the sname:VkSurfaceCapabilitiesKHR 404 structure returned by fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR 405 for the surface if the returned pname:maxImageCount is not zero 406 * [[VUID-VkSwapchainCreateInfoKHR-presentMode-02839]] 407ifdef::VK_KHR_shared_presentable_image[] 408 If pname:presentMode is not 409 ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR nor 410 ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, then 411endif::VK_KHR_shared_presentable_image[] 412 pname:minImageCount must: be greater than or equal to the value returned 413 in the pname:minImageCount member of the sname:VkSurfaceCapabilitiesKHR 414 structure returned by flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR 415 for the surface 416ifdef::VK_KHR_shared_presentable_image[] 417 * [[VUID-VkSwapchainCreateInfoKHR-minImageCount-01383]] 418 pname:minImageCount must: be `1` if pname:presentMode is either 419 ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or 420 ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR 421endif::VK_KHR_shared_presentable_image[] 422 * [[VUID-VkSwapchainCreateInfoKHR-imageFormat-01273]] 423 pname:imageFormat and pname:imageColorSpace must: match the pname:format 424 and pname:colorSpace members, respectively, of one of the 425 sname:VkSurfaceFormatKHR structures returned by 426 fname:vkGetPhysicalDeviceSurfaceFormatsKHR for the surface 427 * [[VUID-VkSwapchainCreateInfoKHR-pNext-07781]] 428ifdef::VK_EXT_swapchain_maintenance1[] 429 If a slink:VkSwapchainPresentScalingCreateInfoEXT structure was not 430 included in the pname:pNext chain, or it is included and 431 slink:VkSwapchainPresentScalingCreateInfoEXT::pname:scalingBehavior is 432 zero then 433endif::VK_EXT_swapchain_maintenance1[] 434 pname:imageExtent must: be between pname:minImageExtent and 435 pname:maxImageExtent, inclusive, where pname:minImageExtent and 436 pname:maxImageExtent are members of the sname:VkSurfaceCapabilitiesKHR 437 structure returned by fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR 438 for the surface 439ifdef::VK_EXT_swapchain_maintenance1[] 440 * [[VUID-VkSwapchainCreateInfoKHR-pNext-07782]] 441 If a slink:VkSwapchainPresentScalingCreateInfoEXT structure was included 442 in the pname:pNext chain and 443 slink:VkSwapchainPresentScalingCreateInfoEXT::pname:scalingBehavior is 444 not zero then pname:imageExtent must: be between 445 pname:minScaledImageExtent and pname:maxScaledImageExtent, inclusive, 446 where pname:minScaledImageExtent and pname:maxScaledImageExtent are 447 members of the sname:VkSurfacePresentScalingCapabilitiesEXT structure 448 returned by fname:vkGetPhysicalDeviceSurfaceCapabilities2KHR for the 449 surface and pname:presentMode 450endif::VK_EXT_swapchain_maintenance1[] 451 * [[VUID-VkSwapchainCreateInfoKHR-imageExtent-01689]] 452 pname:imageExtent members pname:width and pname:height must: both be 453 non-zero 454 * [[VUID-VkSwapchainCreateInfoKHR-imageArrayLayers-01275]] 455 pname:imageArrayLayers must: be greater than `0` and less than or equal 456 to the pname:maxImageArrayLayers member of the 457 sname:VkSurfaceCapabilitiesKHR structure returned by 458 fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface 459 * [[VUID-VkSwapchainCreateInfoKHR-presentMode-01427]] 460 If pname:presentMode is ename:VK_PRESENT_MODE_IMMEDIATE_KHR, 461 ename:VK_PRESENT_MODE_MAILBOX_KHR, ename:VK_PRESENT_MODE_FIFO_KHR or 462 ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR, pname:imageUsage must: be a 463 subset of the supported usage flags present in the 464 pname:supportedUsageFlags member of the slink:VkSurfaceCapabilitiesKHR 465 structure returned by flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR 466 for pname:surface 467ifdef::VK_KHR_shared_presentable_image[] 468 * [[VUID-VkSwapchainCreateInfoKHR-imageUsage-01384]] 469 If pname:presentMode is ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR 470 or ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, pname:imageUsage 471 must: be a subset of the supported usage flags present in the 472 pname:sharedPresentSupportedUsageFlags member of the 473 slink:VkSharedPresentSurfaceCapabilitiesKHR structure returned by 474 flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR for pname:surface 475endif::VK_KHR_shared_presentable_image[] 476 * [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01277]] 477 If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT, 478 pname:pQueueFamilyIndices must: be a valid pointer to an array of 479 pname:queueFamilyIndexCount code:uint32_t values 480 * [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01278]] 481 If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT, 482 pname:queueFamilyIndexCount must: be greater than `1` 483 * [[VUID-VkSwapchainCreateInfoKHR-imageSharingMode-01428]] 484 If pname:imageSharingMode is ename:VK_SHARING_MODE_CONCURRENT, each 485 element of pname:pQueueFamilyIndices must: be unique and must: be less 486 than pname:pQueueFamilyPropertyCount returned by either 487 flink:vkGetPhysicalDeviceQueueFamilyProperties 488ifdef::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 489 or flink:vkGetPhysicalDeviceQueueFamilyProperties2 490endif::VK_VERSION_1_1,VK_KHR_get_physical_device_properties2[] 491 for the pname:physicalDevice that was used to create pname:device 492 * [[VUID-VkSwapchainCreateInfoKHR-preTransform-01279]] 493 pname:preTransform must: be one of the bits present in the 494 pname:supportedTransforms member of the sname:VkSurfaceCapabilitiesKHR 495 structure returned by fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR 496 for the surface 497 * [[VUID-VkSwapchainCreateInfoKHR-compositeAlpha-01280]] 498 pname:compositeAlpha must: be one of the bits present in the 499 pname:supportedCompositeAlpha member of the 500 sname:VkSurfaceCapabilitiesKHR structure returned by 501 fname:vkGetPhysicalDeviceSurfaceCapabilitiesKHR for the surface 502 * [[VUID-VkSwapchainCreateInfoKHR-presentMode-01281]] 503 pname:presentMode must: be one of the elink:VkPresentModeKHR values 504 returned by fname:vkGetPhysicalDeviceSurfacePresentModesKHR for the 505 surface 506ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 507 * [[VUID-VkSwapchainCreateInfoKHR-physicalDeviceCount-01429]] 508ifndef::VKSC_VERSION_1_0[] 509 If the logical device was created with 510 slink:VkDeviceGroupDeviceCreateInfo::pname:physicalDeviceCount equal to 511 1, 512endif::VKSC_VERSION_1_0[] 513 pname:flags must: not contain 514 ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR 515endif::VK_VERSION_1_1,VK_KHR_device_group[] 516ifndef::VKSC_VERSION_1_0[] 517 * [[VUID-VkSwapchainCreateInfoKHR-oldSwapchain-01933]] 518 If pname:oldSwapchain is not dlink:VK_NULL_HANDLE, pname:oldSwapchain 519 must: be a non-retired swapchain associated with native window referred 520 to by pname:surface 521endif::VKSC_VERSION_1_0[] 522ifdef::VKSC_VERSION_1_0[] 523 * [[VUID-VkSwapchainCreateInfoKHR-oldSwapchain-05073]] 524 pname:oldSwapchain must: be dlink:VK_NULL_HANDLE 525endif::VKSC_VERSION_1_0[] 526 * [[VUID-VkSwapchainCreateInfoKHR-imageFormat-01778]] 527 The <<swapchain-wsi-image-create-info, implied image creation 528 parameters>> of the swapchain must: be supported as reported by 529 flink:vkGetPhysicalDeviceImageFormatProperties 530ifdef::VK_KHR_swapchain_mutable_format[] 531 * [[VUID-VkSwapchainCreateInfoKHR-flags-03168]] 532 If pname:flags contains ename:VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR 533 then the pname:pNext chain must: include a 534 slink:VkImageFormatListCreateInfo structure with a pname:viewFormatCount 535 greater than zero and pname:pViewFormats must: have an element equal to 536 pname:imageFormat 537 * [[VUID-VkSwapchainCreateInfoKHR-pNext-04099]] 538 If a slink:VkImageFormatListCreateInfo structure was included in the 539 pname:pNext chain and 540 slink:VkImageFormatListCreateInfo::pname:viewFormatCount is not zero 541 then all of the formats in 542 slink:VkImageFormatListCreateInfo::pname:pViewFormats must: be 543 compatible with the pname:format as described in the 544 <<formats-compatibility,compatibility table>> 545 * [[VUID-VkSwapchainCreateInfoKHR-flags-04100]] 546 If pname:flags does not contain 547 ename:VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR and the pname:pNext 548 chain include a slink:VkImageFormatListCreateInfo structure then 549 slink:VkImageFormatListCreateInfo::pname:viewFormatCount must: be `0` or 550 `1` 551endif::VK_KHR_swapchain_mutable_format[] 552ifdef::VK_KHR_surface_protected_capabilities[] 553 * [[VUID-VkSwapchainCreateInfoKHR-flags-03187]] 554 If pname:flags contains ename:VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR, 555 then sname:VkSurfaceProtectedCapabilitiesKHR::pname:supportsProtected 556 must: be ename:VK_TRUE in the slink:VkSurfaceProtectedCapabilitiesKHR 557 structure returned by flink:vkGetPhysicalDeviceSurfaceCapabilities2KHR 558 for pname:surface 559endif::VK_KHR_surface_protected_capabilities[] 560ifdef::VK_EXT_full_screen_exclusive+VK_KHR_win32_surface[] 561 * [[VUID-VkSwapchainCreateInfoKHR-pNext-02679]] 562 If the pname:pNext chain includes a 563 slink:VkSurfaceFullScreenExclusiveInfoEXT structure with its 564 pname:fullScreenExclusive member set to 565 ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT, and 566 pname:surface was created using flink:vkCreateWin32SurfaceKHR, a 567 slink:VkSurfaceFullScreenExclusiveWin32InfoEXT structure must: be 568 included in the pname:pNext chain 569endif::VK_EXT_full_screen_exclusive+VK_KHR_win32_surface[] 570ifdef::VK_EXT_image_compression_control[] 571 * [[VUID-VkSwapchainCreateInfoKHR-pNext-06752]] 572ifdef::VK_EXT_image_compression_control_swapchain[] 573 If the <<features-imageCompressionControlSwapchain, 574 pname:imageCompressionControlSwapchain>> feature is not enabled, the 575endif::VK_EXT_image_compression_control_swapchain[] 576ifndef::VK_EXT_image_compression_control_swapchain[The] 577 pname:pNext chain must: not include an 578 slink:VkImageCompressionControlEXT structure 579endif::VK_EXT_image_compression_control[] 580**** 581ifdef::VKSC_VERSION_1_0[] 582ifdef::hidden[] 583// tag::scdeviation[] 584 * slink:VkSwapchainCreateInfoKHR::pname:flags must: not contain 585 ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR 586 <<SCID-8>>. 587 * slink:VkSwapchainCreateInfoKHR::pname:oldSwapchain must: be 588 dlink:VK_NULL_HANDLE <<SCID-4>>. 589// end::scdeviation[] 590endif::hidden[] 591endif::VKSC_VERSION_1_0[] 592 593include::{generated}/validity/structs/VkSwapchainCreateInfoKHR.adoc[] 594-- 595 596[open,refpage='VkSwapchainCreateFlagBitsKHR',desc='Bitmask controlling swapchain creation',type='enums'] 597-- 598Bits which can: be set in slink:VkSwapchainCreateInfoKHR::pname:flags, 599specifying parameters of swapchain creation, are: 600 601include::{generated}/api/enums/VkSwapchainCreateFlagBitsKHR.adoc[] 602 603ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 604 * ename:VK_SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR specifies 605 that images created from the swapchain (i.e. with the pname:swapchain 606 member of slink:VkImageSwapchainCreateInfoKHR set to this swapchain's 607 handle) must: use ename:VK_IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT. 608ifdef::VKSC_VERSION_1_0[] 609 This flag is not supported in Vulkan SC <<SCID-8>>. 610endif::VKSC_VERSION_1_0[] 611endif::VK_VERSION_1_1,VK_KHR_device_group[] 612ifdef::VK_VERSION_1_1[] 613 * ename:VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR specifies that images 614 created from the swapchain are protected images. 615endif::VK_VERSION_1_1[] 616ifdef::VK_KHR_swapchain_mutable_format[] 617 * ename:VK_SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR specifies that the 618 images of the swapchain can: be used to create a sname:VkImageView with 619 a different format than what the swapchain was created with. 620 The list of allowed image view formats is specified by adding a 621 slink:VkImageFormatListCreateInfo structure to the pname:pNext chain of 622 slink:VkSwapchainCreateInfoKHR. 623 In addition, this flag also specifies that the swapchain can: be created 624 with usage flags that are not supported for the format the swapchain is 625 created with but are supported for at least one of the allowed image 626 view formats. 627endif::VK_KHR_swapchain_mutable_format[] 628ifdef::VK_EXT_swapchain_maintenance1[] 629 * ename:VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT specifies 630 that the implementation may: defer allocation of memory associated with 631 each swapchain image until its index is to be returned from 632 flink:vkAcquireNextImageKHR 633ifdef::VK_VERSION_1_1,VK_KHR_device_group[or flink:vkAcquireNextImage2KHR] 634 for the first time. 635endif::VK_EXT_swapchain_maintenance1[] 636-- 637 638[open,refpage='VkSwapchainCreateFlagsKHR',desc='Bitmask of VkSwapchainCreateFlagBitsKHR',type='flags'] 639-- 640include::{generated}/api/flags/VkSwapchainCreateFlagsKHR.adoc[] 641 642tname:VkSwapchainCreateFlagsKHR is a bitmask type for setting a mask of zero 643or more elink:VkSwapchainCreateFlagBitsKHR. 644-- 645 646ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 647[open,refpage='VkDeviceGroupSwapchainCreateInfoKHR',desc='Structure specifying parameters of a newly created swapchain object',type='structs'] 648-- 649If the pname:pNext chain of slink:VkSwapchainCreateInfoKHR includes a 650sname:VkDeviceGroupSwapchainCreateInfoKHR structure, then that structure 651includes a set of device group present modes that the swapchain can: be used 652with. 653 654The sname:VkDeviceGroupSwapchainCreateInfoKHR structure is defined as: 655 656include::{generated}/api/structs/VkDeviceGroupSwapchainCreateInfoKHR.adoc[] 657 658 * pname:sType is a elink:VkStructureType value identifying this structure. 659 * pname:pNext is `NULL` or a pointer to a structure extending this 660 structure. 661 * pname:modes is a bitfield of modes that the swapchain can: be used with. 662 663If this structure is not present, pname:modes is considered to be 664ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR. 665 666include::{generated}/validity/structs/VkDeviceGroupSwapchainCreateInfoKHR.adoc[] 667-- 668endif::VK_VERSION_1_1,VK_KHR_device_group[] 669 670ifdef::VK_AMD_display_native_hdr[] 671[open,refpage='VkSwapchainDisplayNativeHdrCreateInfoAMD',desc='Structure specifying display native HDR parameters of a newly created swapchain object',type='structs'] 672-- 673If the pname:pNext chain of slink:VkSwapchainCreateInfoKHR includes a 674sname:VkSwapchainDisplayNativeHdrCreateInfoAMD structure, then that 675structure includes additional swapchain creation parameters specific to 676display native HDR support. 677 678The sname:VkSwapchainDisplayNativeHdrCreateInfoAMD structure is defined as: 679 680include::{generated}/api/structs/VkSwapchainDisplayNativeHdrCreateInfoAMD.adoc[] 681 682 * pname:sType is a elink:VkStructureType value identifying this structure. 683 * pname:pNext is `NULL` or a pointer to a structure extending this 684 structure. 685 * pname:localDimmingEnable specifies whether local dimming is enabled for 686 the swapchain. 687 688If the pname:pNext chain of slink:VkSwapchainCreateInfoKHR does not include 689this structure, the default value for pname:localDimmingEnable is 690ename:VK_TRUE, meaning local dimming is initially enabled for the swapchain. 691 692include::{generated}/validity/structs/VkSwapchainDisplayNativeHdrCreateInfoAMD.adoc[] 693 694.Valid Usage 695**** 696 * [[VUID-VkSwapchainDisplayNativeHdrCreateInfoAMD-localDimmingEnable-04449]] 697 It is only valid to set pname:localDimmingEnable to ename:VK_TRUE if 698 slink:VkDisplayNativeHdrSurfaceCapabilitiesAMD::pname:localDimmingSupport 699 is supported 700**** 701-- 702 703[open,refpage='vkSetLocalDimmingAMD',desc='Set Local Dimming',type='protos'] 704-- 705The local dimming HDR setting may also be changed over the life of a 706swapchain by calling: 707 708include::{generated}/api/protos/vkSetLocalDimmingAMD.adoc[] 709 710 * pname:device is the device associated with pname:swapChain. 711 * pname:swapChain handle to enable local dimming. 712 * pname:localDimmingEnable specifies whether local dimming is enabled for 713 the swapchain. 714 715include::{generated}/validity/protos/vkSetLocalDimmingAMD.adoc[] 716 717.Valid Usage 718**** 719 * [[VUID-vkSetLocalDimmingAMD-localDimmingSupport-04618]] 720 slink:VkDisplayNativeHdrSurfaceCapabilitiesAMD::pname:localDimmingSupport 721 must: be supported 722**** 723-- 724endif::VK_AMD_display_native_hdr[] 725 726ifdef::VK_EXT_full_screen_exclusive[] 727If the pname:pNext chain of slink:VkSwapchainCreateInfoKHR includes a 728slink:VkSurfaceFullScreenExclusiveInfoEXT structure, then that structure 729specifies the application's preferred full-screen presentation behavior. 730If this structure is not present, pname:fullScreenExclusive is considered to 731be ename:VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT. 732endif::VK_EXT_full_screen_exclusive[] 733 734ifdef::VK_EXT_display_control[] 735include::{chapters}/VK_EXT_display_control/swapchain_counters.adoc[] 736endif::VK_EXT_display_control[] 737 738ifdef::VK_EXT_image_compression_control[] 739ifdef::VK_EXT_image_compression_control_swapchain[] 740To specify compression properties for the swapchain images in this 741swapchain, add a slink:VkImageCompressionControlEXT structure to the 742pname:pNext chain of the slink:VkSwapchainCreateInfoKHR structure. 743endif::VK_EXT_image_compression_control_swapchain[] 744endif::VK_EXT_image_compression_control[] 745 746ifdef::VK_EXT_swapchain_maintenance1[] 747include::{chapters}/VK_EXT_swapchain_maintenance1/SwapchainPresentModesCreateInfo.adoc[] 748include::{chapters}/VK_EXT_swapchain_maintenance1/SwapchainPresentScalingCreateInfo.adoc[] 749endif::VK_EXT_swapchain_maintenance1[] 750 751ifdef::VKSC_VERSION_1_0[] 752ifdef::hidden[] 753// tag::scremoved[] 754 * fname:vkDestroySwapchainKHR <<SCID-4>> 755// end::scremoved[] 756endif::hidden[] 757 758Swapchains cannot: be destroyed <<SCID-4>>. 759If 760slink:VkPhysicalDeviceVulkanSC10Properties::<<limits-deviceDestroyFreesMemory,pname:deviceDestroyFreesMemory>> 761is ename:VK_TRUE, the memory for swapchain images is returned to the system 762when the device is destroyed. 763 764endif::VKSC_VERSION_1_0[] 765ifndef::VKSC_VERSION_1_0[] 766[open,refpage='vkDestroySwapchainKHR',desc='Destroy a swapchain object',type='protos'] 767-- 768To destroy a swapchain object call: 769 770include::{generated}/api/protos/vkDestroySwapchainKHR.adoc[] 771 772 * pname:device is the slink:VkDevice associated with pname:swapchain. 773 * pname:swapchain is the swapchain to destroy. 774 * pname:pAllocator is the allocator used for host memory allocated for the 775 swapchain object when there is no more specific allocator available (see 776 <<memory-allocation,Memory Allocation>>). 777 778The application must: not destroy a swapchain until after completion of all 779outstanding operations on images that were acquired from the swapchain. 780pname:swapchain and all associated sname:VkImage handles are destroyed, and 781must: not be acquired or used any more by the application. 782The memory of each sname:VkImage will only be freed after that image is no 783longer used by the presentation engine. 784For example, if one image of the swapchain is being displayed in a window, 785the memory for that image may: not be freed until the window is destroyed, 786or another swapchain is created for the window. 787Destroying the swapchain does not invalidate the parent sname:VkSurfaceKHR, 788and a new swapchain can: be created with it. 789 790ifdef::VK_KHR_display_swapchain[] 791include::{chapters}/VK_KHR_display_swapchain/destroy_swapchain_interactions.adoc[] 792endif::VK_KHR_display_swapchain[] 793 794ifdef::VK_EXT_full_screen_exclusive[] 795If pname:swapchain has exclusive full-screen access, it is released before 796the swapchain is destroyed. 797endif::VK_EXT_full_screen_exclusive[] 798 799.Valid Usage 800**** 801 * [[VUID-vkDestroySwapchainKHR-swapchain-01282]] 802 All uses of presentable images acquired from pname:swapchain must: have 803 completed execution 804ifndef::VKSC_VERSION_1_0[] 805 * [[VUID-vkDestroySwapchainKHR-swapchain-01283]] 806 If sname:VkAllocationCallbacks were provided when pname:swapchain was 807 created, a compatible set of callbacks must: be provided here 808 * [[VUID-vkDestroySwapchainKHR-swapchain-01284]] 809 If no sname:VkAllocationCallbacks were provided when pname:swapchain was 810 created, pname:pAllocator must: be `NULL` 811endif::VKSC_VERSION_1_0[] 812**** 813 814include::{generated}/validity/protos/vkDestroySwapchainKHR.adoc[] 815-- 816endif::VKSC_VERSION_1_0[] 817 818ifdef::VK_KHR_display_swapchain[] 819include::{chapters}/VK_KHR_display_swapchain/create_shared_swapchains.adoc[] 820endif::VK_KHR_display_swapchain[] 821 822[open,refpage='vkGetSwapchainImagesKHR',desc='Obtain the array of presentable images associated with a swapchain',type='protos'] 823-- 824:refpage: vkGetSwapchainImagesKHR 825 826To obtain the array of presentable images associated with a swapchain, call: 827 828include::{generated}/api/protos/vkGetSwapchainImagesKHR.adoc[] 829 830 * pname:device is the device associated with pname:swapchain. 831 * pname:swapchain is the swapchain to query. 832 * pname:pSwapchainImageCount is a pointer to an integer related to the 833 number of presentable images available or queried, as described below. 834 * pname:pSwapchainImages is either `NULL` or a pointer to an array of 835 sname:VkImage handles. 836 837If pname:pSwapchainImages is `NULL`, then the number of presentable images 838for pname:swapchain is returned in pname:pSwapchainImageCount. 839Otherwise, pname:pSwapchainImageCount must: point to a variable set by the 840user to the number of elements in the pname:pSwapchainImages array, and on 841return the variable is overwritten with the number of structures actually 842written to pname:pSwapchainImages. 843If the value of pname:pSwapchainImageCount is less than the number of 844presentable images for pname:swapchain, at most pname:pSwapchainImageCount 845structures will be written, and ename:VK_INCOMPLETE will be returned instead 846of ename:VK_SUCCESS, to indicate that not all the available presentable 847images were returned. 848 849include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 850 851include::{generated}/validity/protos/vkGetSwapchainImagesKHR.adoc[] 852-- 853 854[NOTE] 855.Note 856==== 857By knowing all presentable images used in the swapchain, the application can 858create command buffers that reference these images prior to entering its 859main rendering loop. 860ifdef::VK_EXT_swapchain_maintenance1[] 861However, command buffers are not allowed to reference presentable images 862created with ename:VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT 863until their indices have been returned from flink:vkAcquireNextImageKHR at 864least once. 865endif::VK_EXT_swapchain_maintenance1[] 866==== 867 868Images returned by flink:vkGetSwapchainImagesKHR are fully backed by memory 869before they are passed to the application, as if they are each bound 870completely and contiguously to a single sname:VkDeviceMemory object 871ifdef::VK_EXT_swapchain_maintenance1[] 872, unless the swapchain is created with the 873ename:VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT flag 874endif::VK_EXT_swapchain_maintenance1[] 875. 876All presentable images are initially in the ename:VK_IMAGE_LAYOUT_UNDEFINED 877layout, thus before using presentable images, the application must: 878transition them to a valid layout for the intended use. 879 880ifndef::VKSC_VERSION_1_0[] 881 882Further, the lifetime of presentable images is controlled by the 883implementation, so applications must: not destroy a presentable image. 884See flink:vkDestroySwapchainKHR for further details on the lifetime of 885presentable images. 886 887endif::VKSC_VERSION_1_0[] 888 889ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 890 891Images can: also be created by using flink:vkCreateImage with 892slink:VkImageSwapchainCreateInfoKHR and bound to swapchain memory using 893flink:vkBindImageMemory2 with slink:VkBindImageMemorySwapchainInfoKHR. 894These images can: be used anywhere swapchain images are used, and are useful 895in logical devices with multiple physical devices to create peer memory 896bindings of swapchain memory. 897These images and bindings have no effect on what memory is presented. 898Unlike images retrieved from fname:vkGetSwapchainImagesKHR, these images 899must: be destroyed with flink:vkDestroyImage. 900 901endif::VK_VERSION_1_1,VK_KHR_device_group[] 902 903[open,refpage='vkAcquireNextImageKHR',desc='Retrieve the index of the next available presentable image',type='protos'] 904-- 905:refpage: vkAcquireNextImageKHR 906 907To acquire an available presentable image to use, and retrieve the index of 908that image, call: 909 910include::{generated}/api/protos/vkAcquireNextImageKHR.adoc[] 911 912 * pname:device is the device associated with pname:swapchain. 913 * pname:swapchain is the non-retired swapchain from which an image is 914 being acquired. 915 * pname:timeout specifies how long the function waits, in nanoseconds, if 916 no image is available. 917 * pname:semaphore is dlink:VK_NULL_HANDLE or a semaphore to signal. 918 * pname:fence is dlink:VK_NULL_HANDLE or a fence to signal. 919 * pname:pImageIndex is a pointer to a code:uint32_t in which the index of 920 the next image to use (i.e. an index into the array of images returned 921 by fname:vkGetSwapchainImagesKHR) is returned. 922 923ifdef::VK_EXT_swapchain_maintenance1[] 924If the pname:swapchain has been created with the 925ename:VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT flag, the image 926whose index is returned in pname:pImageIndex will be fully backed by memory 927before this call returns to the application, as if it is bound completely 928and contiguously to a single sname:VkDeviceMemory object. 929endif::VK_EXT_swapchain_maintenance1[] 930 931include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 932 933.Valid Usage 934**** 935 * [[VUID-vkAcquireNextImageKHR-swapchain-01285]] 936 pname:swapchain must: not be in the retired state 937 * [[VUID-vkAcquireNextImageKHR-semaphore-01286]] 938 If pname:semaphore is not dlink:VK_NULL_HANDLE it must: be unsignaled 939 * [[VUID-vkAcquireNextImageKHR-semaphore-01779]] 940 If pname:semaphore is not dlink:VK_NULL_HANDLE it must: not have any 941 uncompleted signal or wait operations pending 942 * [[VUID-vkAcquireNextImageKHR-fence-01287]] 943 If pname:fence is not dlink:VK_NULL_HANDLE it must: be unsignaled and 944 must: not be associated with any other queue command that has not yet 945 completed execution on that queue 946 * [[VUID-vkAcquireNextImageKHR-semaphore-01780]] 947 pname:semaphore and pname:fence must: not both be equal to 948 dlink:VK_NULL_HANDLE 949 * [[VUID-vkAcquireNextImageKHR-surface-07783]] 950 If <<swapchain-acquire-forward-progress,forward progress>> cannot be 951 guaranteed for the pname:surface used to create the pname:swapchain 952 member of pname:pAcquireInfo, the pname:timeout member of 953 pname:pAcquireInfo must: not be code:UINT64_MAX 954ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 955 * [[VUID-vkAcquireNextImageKHR-semaphore-03265]] 956 pname:semaphore must: have a elink:VkSemaphoreType of 957 ename:VK_SEMAPHORE_TYPE_BINARY 958endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 959**** 960 961include::{generated}/validity/protos/vkAcquireNextImageKHR.adoc[] 962-- 963 964If an image is acquired successfully, fname:vkAcquireNextImageKHR must: 965either return ename:VK_SUCCESS or ename:VK_SUBOPTIMAL_KHR. 966The implementation may: return ename:VK_SUBOPTIMAL_KHR if the swapchain no 967longer matches the surface properties exactly, but can: still be used for 968presentation. 969 970When successful, fname:vkAcquireNextImageKHR acquires a presentable image 971from pname:swapchain that an application can: use, and sets 972pname:pImageIndex to the index of that image within the swapchain. 973The presentation engine may: not have finished reading from the image at the 974time it is acquired, so the application must: use pname:semaphore and/or 975pname:fence to ensure that the image layout and contents are not modified 976until the presentation engine reads have completed. 977Once fname:vkAcquireNextImageKHR successfully acquires an image, the 978semaphore signal operation referenced by pname:semaphore, if not 979dlink:VK_NULL_HANDLE, and the fence signal operation referenced by 980pname:fence, if not dlink:VK_NULL_HANDLE, are submitted for execution. 981If fname:vkAcquireNextImageKHR does not successfully acquire an image, 982pname:semaphore and pname:fence are unaffected. 983The order in which images are acquired is implementation-dependent, and may: 984be different than the order the images were presented. 985 986If pname:timeout is zero, then fname:vkAcquireNextImageKHR does not wait, 987and will either successfully acquire an image, or fail and return 988ename:VK_NOT_READY if no image is available. 989 990If the specified timeout period expires before an image is acquired, 991fname:vkAcquireNextImageKHR returns ename:VK_TIMEOUT. 992If pname:timeout is code:UINT64_MAX, the timeout period is treated as 993infinite, and fname:vkAcquireNextImageKHR will block until an image is 994acquired or an error occurs. 995 996[[swapchain-acquire-forward-progress]] 997Let [eq]#S# be the number of images in pname:swapchain. 998ifndef::VK_EXT_swapchain_maintenance1[] 999Let [eq]#M# be the value of 1000slink:VkSurfaceCapabilitiesKHR::pname:minImageCount. 1001endif::VK_EXT_swapchain_maintenance1[] 1002ifdef::VK_EXT_swapchain_maintenance1[] 1003If pname:swapchain is created with 1004slink:VkSwapchainPresentModesCreateInfoEXT, let [eq]#M# be the maximum of 1005the values in slink:VkSurfaceCapabilitiesKHR::pname:minImageCount when 1006queried with each present mode in 1007slink:VkSwapchainPresentModesCreateInfoEXT::pname:pPresentModes in 1008slink:VkSurfacePresentModeEXT. 1009Otherwise, let [eq]#M# be the value of 1010slink:VkSurfaceCapabilitiesKHR::pname:minImageCount without a 1011slink:VkSurfacePresentModeEXT as part of the query input. 1012endif::VK_EXT_swapchain_maintenance1[] 1013 1014fname:vkAcquireNextImageKHR should: not be called if the number of images 1015that the application has currently acquired is greater than [eq]#S-M#. 1016If fname:vkAcquireNextImageKHR is called when the number of images that the 1017application has currently acquired is less than or equal to [eq]#S-M#, 1018fname:vkAcquireNextImageKHR must: return in finite time with an allowed 1019ename:VkResult code. 1020 1021[NOTE] 1022.Note 1023==== 1024Returning a result in finite time guarantees that the implementation cannot 1025deadlock an application, or suspend its execution indefinitely with correct 1026API usage. 1027Acquiring too many images at once may block indefinitely, which is covered 1028by valid usage when attempting to use code:UINT64_MAX. 1029For example, a scenario here is when a compositor holds on to images which 1030are currently being presented, and there are not any vacant images left to 1031be acquired. 1032==== 1033 1034[NOTE] 1035.Note 1036==== 1037ename:VK_SUBOPTIMAL_KHR may: happen, for example, if the platform surface 1038has been resized but the platform is able to scale the presented images to 1039the new size to produce valid surface updates. 1040It is up to the application to decide whether it prefers to continue using 1041the current swapchain in this state, or to re-create the swapchain to better 1042match the platform surface properties. 1043==== 1044 1045If the swapchain images no longer match native surface properties, either 1046ename:VK_SUBOPTIMAL_KHR or ename:VK_ERROR_OUT_OF_DATE_KHR must: be returned. 1047If ename:VK_ERROR_OUT_OF_DATE_KHR is returned, no image is acquired and 1048attempts to present previously acquired images to the swapchain will also 1049fail with ename:VK_ERROR_OUT_OF_DATE_KHR. 1050Applications need to create a new swapchain for the surface to continue 1051presenting if ename:VK_ERROR_OUT_OF_DATE_KHR is returned. 1052 1053If device loss occurs (see <<devsandqueues-lost-device,Lost Device>>) before 1054the timeout has expired, fname:vkAcquireNextImageKHR must: return in finite 1055time with either one of the allowed success codes, or 1056ename:VK_ERROR_DEVICE_LOST. 1057 1058If pname:semaphore is not dlink:VK_NULL_HANDLE, the semaphore must: be 1059unsignaled, with no signal or wait operations pending. 1060It will become signaled when the application can: use the image. 1061 1062[NOTE] 1063.Note 1064==== 1065Use of pname:semaphore allows rendering operations to be recorded and 1066submitted before the presentation engine has completed its use of the image. 1067==== 1068 1069If pname:fence is not equal to dlink:VK_NULL_HANDLE, the fence must: be 1070unsignaled, with no signal operations pending. 1071It will become signaled when the application can: use the image. 1072 1073[NOTE] 1074.Note 1075==== 1076Applications should: not rely on fname:vkAcquireNextImageKHR blocking in 1077order to meter their rendering speed. 1078The implementation may: return from this function immediately regardless of 1079how many presentation requests are queued, and regardless of when queued 1080presentation requests will complete relative to the call. 1081Instead, applications can: use pname:fence to meter their frame generation 1082work to match the presentation rate. 1083==== 1084 1085An application must: wait until either the pname:semaphore or pname:fence is 1086signaled before accessing the image's data. 1087 1088[NOTE] 1089.Note 1090==== 1091When the presentable image will be accessed by some stage [eq]#S#, the 1092recommended idiom for ensuring correct synchronization is: 1093 1094 * The slink:VkSubmitInfo used to submit the image layout transition for 1095 execution includes fname:vkAcquireNextImageKHR::pname:semaphore in its 1096 pname:pWaitSemaphores member, with the corresponding element of 1097 pname:pWaitDstStageMask including [eq]#S#. 1098 * The <<synchronization, synchronization command>> that performs any 1099 necessary image layout transition includes [eq]#S# in both the 1100 pname:srcStageMask and pname:dstStageMask. 1101==== 1102 1103After a successful return, the image indicated by pname:pImageIndex and its 1104data will be unmodified compared to when it was presented. 1105 1106[NOTE] 1107.Note 1108==== 1109Exclusive ownership of presentable images corresponding to a swapchain 1110created with ename:VK_SHARING_MODE_EXCLUSIVE as defined in 1111<<resources-sharing,Resource Sharing>> is not altered by a call to 1112fname:vkAcquireNextImageKHR. 1113That means upon the first acquisition from such a swapchain presentable 1114images are not owned by any queue family, while at subsequent acquisitions 1115the presentable images remain owned by the queue family the image was 1116previously presented on. 1117==== 1118 1119The possible return values for fname:vkAcquireNextImageKHR depend on the 1120pname:timeout provided: 1121 1122 * ename:VK_SUCCESS is returned if an image became available. 1123 * ename:VK_ERROR_SURFACE_LOST_KHR is returned if the surface becomes no 1124 longer available. 1125 * ename:VK_NOT_READY is returned if pname:timeout is zero and no image was 1126 available. 1127 * ename:VK_TIMEOUT is returned if pname:timeout is greater than zero and 1128 less than code:UINT64_MAX, and no image became available within the time 1129 allowed. 1130 * ename:VK_SUBOPTIMAL_KHR is returned if an image became available, and 1131 the swapchain no longer matches the surface properties exactly, but can: 1132 still be used to present to the surface successfully. 1133 1134[NOTE] 1135.Note 1136==== 1137This may: happen, for example, if the platform surface has been resized but 1138the platform is able to scale the presented images to the new size to 1139produce valid surface updates. 1140It is up to the application to decide whether it prefers to continue using 1141the current swapchain indefinitely or temporarily in this state, or to 1142re-create the swapchain to better match the platform surface properties. 1143==== 1144 1145 * ename:VK_ERROR_OUT_OF_DATE_KHR is returned if the surface has changed in 1146 such a way that it is no longer compatible with the swapchain, and 1147 further presentation requests using the swapchain will fail. 1148 Applications must: query the new surface properties and recreate their 1149 swapchain if they wish to continue presenting to the surface. 1150 1151If the native surface and presented image sizes no longer match, 1152presentation may: fail 1153ifdef::VK_EXT_swapchain_maintenance1[] 1154unless the swapchain is created with a non-zero value in 1155slink:VkSwapchainPresentScalingCreateInfoEXT::pname:scalingBehavior 1156endif::VK_EXT_swapchain_maintenance1[] 1157. 1158If presentation does succeed, the mapping from the presented image to the 1159native surface is 1160ifdef::VK_EXT_swapchain_maintenance1[] 1161defined by the slink:VkSwapchainPresentScalingCreateInfoEXT structure if 1162provided. 1163Otherwise it is 1164endif::VK_EXT_swapchain_maintenance1[] 1165implementation-defined. 1166It is the application's responsibility to detect surface size changes and 1167react appropriately. 1168If presentation fails because of a mismatch in the surface and presented 1169image sizes, a ename:VK_ERROR_OUT_OF_DATE_KHR error will be returned. 1170 1171[NOTE] 1172.Note 1173==== 1174For example, consider a 4x3 window/surface that gets resized to be 3x4 1175(taller than wider). 1176On some window systems, the portion of the window/surface that was 1177previously and still is visible (the 3x3 part) will contain the same 1178contents as before, while the remaining parts of the window will have 1179undefined: contents. 1180Other window systems may: squash/stretch the image to fill the new window 1181size without any undefined: contents, or apply some other mapping. 1182==== 1183 1184ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1185[open,refpage='vkAcquireNextImage2KHR',desc='Retrieve the index of the next available presentable image',type='protos'] 1186-- 1187:refpage: vkAcquireNextImage2KHR 1188 1189To acquire an available presentable image to use, and retrieve the index of 1190that image, call: 1191 1192include::{generated}/api/protos/vkAcquireNextImage2KHR.adoc[] 1193 1194 * pname:device is the device associated with pname:swapchain. 1195 * pname:pAcquireInfo is a pointer to a slink:VkAcquireNextImageInfoKHR 1196 structure containing parameters of the acquire. 1197 * pname:pImageIndex is a pointer to a code:uint32_t that is set to the 1198 index of the next image to use. 1199 1200ifdef::VK_EXT_swapchain_maintenance1[] 1201If the pname:swapchain has been created with the 1202ename:VK_SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_EXT flag, the image 1203whose index is returned in pname:pImageIndex will be fully backed by memory 1204before this call returns to the application. 1205endif::VK_EXT_swapchain_maintenance1[] 1206 1207include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 1208 1209.Valid Usage 1210**** 1211 * [[VUID-vkAcquireNextImage2KHR-surface-07784]] 1212 If <<swapchain-acquire-forward-progress,forward progress>> cannot be 1213 guaranteed for the pname:surface used to create pname:swapchain, the 1214 pname:timeout member of pname:pAcquireInfo must: not be code:UINT64_MAX 1215**** 1216 1217include::{generated}/validity/protos/vkAcquireNextImage2KHR.adoc[] 1218-- 1219 1220[open,refpage='VkAcquireNextImageInfoKHR',desc='Structure specifying parameters of the acquire',type='structs'] 1221-- 1222The sname:VkAcquireNextImageInfoKHR structure is defined as: 1223 1224include::{generated}/api/structs/VkAcquireNextImageInfoKHR.adoc[] 1225 1226 * pname:sType is a elink:VkStructureType value identifying this structure. 1227 * pname:pNext is `NULL` or a pointer to a structure extending this 1228 structure. 1229 * pname:swapchain is a non-retired swapchain from which an image is 1230 acquired. 1231 * pname:timeout specifies how long the function waits, in nanoseconds, if 1232 no image is available. 1233 * pname:semaphore is dlink:VK_NULL_HANDLE or a semaphore to signal. 1234 * pname:fence is dlink:VK_NULL_HANDLE or a fence to signal. 1235 * pname:deviceMask is a mask of physical devices for which the swapchain 1236 image will be ready to use when the semaphore or fence is signaled. 1237 1238If flink:vkAcquireNextImageKHR is used, the device mask is considered to 1239include all physical devices in the logical device. 1240 1241[NOTE] 1242.Note 1243==== 1244flink:vkAcquireNextImage2KHR signals at most one semaphore, even if the 1245application requests waiting for multiple physical devices to be ready via 1246the pname:deviceMask. 1247However, only a single physical device can: wait on that semaphore, since 1248the semaphore becomes unsignaled when the wait succeeds. 1249For other physical devices to wait for the image to be ready, it is 1250necessary for the application to submit semaphore signal operation(s) to 1251that first physical device to signal additional semaphore(s) after the wait 1252succeeds, which the other physical device(s) can: wait upon. 1253==== 1254 1255.Valid Usage 1256**** 1257 * [[VUID-VkAcquireNextImageInfoKHR-swapchain-01675]] 1258 pname:swapchain must: not be in the retired state 1259 * [[VUID-VkAcquireNextImageInfoKHR-semaphore-01288]] 1260 If pname:semaphore is not dlink:VK_NULL_HANDLE it must: be unsignaled 1261 * [[VUID-VkAcquireNextImageInfoKHR-semaphore-01781]] 1262 If pname:semaphore is not dlink:VK_NULL_HANDLE it must: not have any 1263 uncompleted signal or wait operations pending 1264 * [[VUID-VkAcquireNextImageInfoKHR-fence-01289]] 1265 If pname:fence is not dlink:VK_NULL_HANDLE it must: be unsignaled and 1266 must: not be associated with any other queue command that has not yet 1267 completed execution on that queue 1268 * [[VUID-VkAcquireNextImageInfoKHR-semaphore-01782]] 1269 pname:semaphore and pname:fence must: not both be equal to 1270 dlink:VK_NULL_HANDLE 1271 * [[VUID-VkAcquireNextImageInfoKHR-deviceMask-01290]] 1272 pname:deviceMask must: be a valid device mask 1273 * [[VUID-VkAcquireNextImageInfoKHR-deviceMask-01291]] 1274 pname:deviceMask must: not be zero 1275ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1276 * [[VUID-VkAcquireNextImageInfoKHR-semaphore-03266]] 1277 pname:semaphore must: have a elink:VkSemaphoreType of 1278 ename:VK_SEMAPHORE_TYPE_BINARY 1279endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1280**** 1281 1282include::{generated}/validity/structs/VkAcquireNextImageInfoKHR.adoc[] 1283-- 1284endif::VK_VERSION_1_1,VK_KHR_device_group[] 1285 1286[open,refpage='vkQueuePresentKHR',desc='Queue an image for presentation',type='protos'] 1287-- 1288:refpage: vkQueuePresentKHR 1289 1290After queueing all rendering commands and transitioning the image to the 1291correct layout, to queue an image for presentation, call: 1292 1293include::{generated}/api/protos/vkQueuePresentKHR.adoc[] 1294 1295 * pname:queue is a queue that is capable of presentation to the target 1296 surface's platform on the same device as the image's swapchain. 1297 * pname:pPresentInfo is a pointer to a slink:VkPresentInfoKHR structure 1298 specifying parameters of the presentation. 1299 1300.Note 1301[NOTE] 1302==== 1303There is no requirement for an application to present images in the same 1304order that they were acquired - applications can arbitrarily present any 1305image that is currently acquired. 1306==== 1307 1308include::{chapters}/commonvalidity/no_dynamic_allocations_common.adoc[] 1309 1310.Valid Usage 1311**** 1312 * [[VUID-vkQueuePresentKHR-pSwapchains-01292]] 1313 Each element of pname:pSwapchains member of pname:pPresentInfo must: be 1314 a swapchain that is created for a surface for which presentation is 1315 supported from pname:queue as determined using a call to 1316 fname:vkGetPhysicalDeviceSurfaceSupportKHR 1317ifdef::VK_KHR_display_swapchain[] 1318 * [[VUID-vkQueuePresentKHR-pSwapchains-01293]] 1319 If more than one member of pname:pSwapchains was created from a display 1320 surface, all display surfaces referenced that refer to the same display 1321 must: use the same display mode 1322endif::VK_KHR_display_swapchain[] 1323 * [[VUID-vkQueuePresentKHR-pWaitSemaphores-01294]] 1324 When a semaphore wait operation referring to a binary semaphore defined 1325 by the elements of the pname:pWaitSemaphores member of 1326 pname:pPresentInfo executes on pname:queue, there must: be no other 1327 queues waiting on the same semaphore 1328ifdef::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1329 * [[VUID-vkQueuePresentKHR-pWaitSemaphores-03267]] 1330 All elements of the pname:pWaitSemaphores member of pname:pPresentInfo 1331 must: be created with a elink:VkSemaphoreType of 1332 ename:VK_SEMAPHORE_TYPE_BINARY 1333endif::VK_VERSION_1_2,VK_KHR_timeline_semaphore[] 1334 * [[VUID-vkQueuePresentKHR-pWaitSemaphores-03268]] 1335 All elements of the pname:pWaitSemaphores member of pname:pPresentInfo 1336 must: reference a semaphore signal operation that has been submitted for 1337 execution and any <<synchronization-semaphores-signaling, semaphore 1338 signal operations>> on which it depends must: have also been submitted 1339 for execution 1340**** 1341 1342Any writes to memory backing the images referenced by the 1343pname:pImageIndices and pname:pSwapchains members of pname:pPresentInfo, 1344that are available before flink:vkQueuePresentKHR is executed, are 1345automatically made visible to the read access performed by the presentation 1346engine. 1347This automatic visibility operation for an image happens-after the semaphore 1348signal operation, and happens-before the presentation engine accesses the 1349image. 1350 1351Queueing an image for presentation defines a set of _queue operations_, 1352including waiting on the semaphores and submitting a presentation request to 1353the presentation engine. 1354However, the scope of this set of queue operations does not include the 1355actual processing of the image by the presentation engine. 1356 1357.Note 1358[NOTE] 1359==== 1360The origin of the native orientation of the surface coordinate system is not 1361specified in the Vulkan specification; it depends on the platform. 1362For most platforms the origin is by default upper-left, meaning the pixel of 1363the presented slink:VkImage at coordinates [eq]#(0,0)# would appear at the 1364upper left pixel of the platform surface (assuming 1365ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR, and the display standing the 1366right way up). 1367==== 1368 1369If fname:vkQueuePresentKHR fails to enqueue the corresponding set of queue 1370operations, it may: return ename:VK_ERROR_OUT_OF_HOST_MEMORY or 1371ename:VK_ERROR_OUT_OF_DEVICE_MEMORY. 1372If it does, the implementation must: ensure that the state and contents of 1373any resources or synchronization primitives referenced is unaffected by the 1374call or its failure. 1375 1376If fname:vkQueuePresentKHR fails in such a way that the implementation is 1377unable to make that guarantee, the implementation must: return 1378ename:VK_ERROR_DEVICE_LOST. 1379 1380However, if the presentation request is rejected by the presentation engine 1381with an error ename:VK_ERROR_OUT_OF_DATE_KHR, 1382ifdef::VK_EXT_full_screen_exclusive[] 1383ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT, 1384endif::VK_EXT_full_screen_exclusive[] 1385or ename:VK_ERROR_SURFACE_LOST_KHR, the set of queue operations are still 1386considered to be enqueued and thus any semaphore wait operation specified in 1387slink:VkPresentInfoKHR will execute when the corresponding queue operation 1388is complete. 1389 1390Calls to fname:vkQueuePresentKHR may: block, but must: return in finite 1391time. 1392 1393ifdef::VK_EXT_full_screen_exclusive[] 1394If any pname:swapchain member of pname:pPresentInfo was created with 1395ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT, 1396ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT will be returned if that 1397swapchain does not have exclusive full-screen access, possibly for 1398implementation-specific reasons outside of the application's control. 1399endif::VK_EXT_full_screen_exclusive[] 1400 1401include::{generated}/validity/protos/vkQueuePresentKHR.adoc[] 1402-- 1403 1404[open,refpage='VkPresentInfoKHR',desc='Structure describing parameters of a queue presentation',type='structs'] 1405-- 1406The sname:VkPresentInfoKHR structure is defined as: 1407 1408include::{generated}/api/structs/VkPresentInfoKHR.adoc[] 1409 1410 * pname:sType is a elink:VkStructureType value identifying this structure. 1411 * pname:pNext is `NULL` or a pointer to a structure extending this 1412 structure. 1413 * pname:waitSemaphoreCount is the number of semaphores to wait for before 1414 issuing the present request. 1415 The number may: be zero. 1416 * pname:pWaitSemaphores is `NULL` or a pointer to an array of 1417 slink:VkSemaphore objects with pname:waitSemaphoreCount entries, and 1418 specifies the semaphores to wait for before issuing the present request. 1419 * pname:swapchainCount is the number of swapchains being presented to by 1420 this command. 1421 * pname:pSwapchains is a pointer to an array of slink:VkSwapchainKHR 1422 objects with pname:swapchainCount entries. 1423 * pname:pImageIndices is a pointer to an array of indices into the array 1424 of each swapchain's presentable images, with pname:swapchainCount 1425 entries. 1426 Each entry in this array identifies the image to present on the 1427 corresponding entry in the pname:pSwapchains array. 1428 * pname:pResults is a pointer to an array of elink:VkResult typed elements 1429 with pname:swapchainCount entries. 1430 Applications that do not need per-swapchain results can: use `NULL` for 1431 pname:pResults. 1432 If non-`NULL`, each entry in pname:pResults will be set to the 1433 elink:VkResult for presenting the swapchain corresponding to the same 1434 index in pname:pSwapchains. 1435 1436Before an application can: present an image, the image's layout must: be 1437transitioned to the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR 1438ifdef::VK_KHR_shared_presentable_image[] 1439layout, or for a shared presentable image the 1440ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR 1441endif::VK_KHR_shared_presentable_image[] 1442layout. 1443 1444.Note 1445[NOTE] 1446==== 1447When transitioning the image to 1448ifdef::VK_KHR_shared_presentable_image[] 1449ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR or 1450endif::VK_KHR_shared_presentable_image[] 1451ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR, there is no need to delay subsequent 1452processing, or perform any visibility operations (as flink:vkQueuePresentKHR 1453performs automatic visibility operations). 1454To achieve this, the pname:dstAccessMask member of the 1455slink:VkImageMemoryBarrier should: be set to `0`, and the pname:dstStageMask 1456parameter should: be set to ename:VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT. 1457==== 1458 1459.Valid Usage 1460**** 1461 * [[VUID-VkPresentInfoKHR-pSwapchain-09231]] 1462 Elements of pname:pSwapchain must: be unique 1463 * [[VUID-VkPresentInfoKHR-pImageIndices-01430]] 1464 Each element of pname:pImageIndices must: be the index of a presentable 1465 image acquired from the swapchain specified by the corresponding element 1466 of the pname:pSwapchains array, and the presented image subresource 1467 must: be in the ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR 1468ifdef::VK_KHR_shared_presentable_image[] 1469 or ename:VK_IMAGE_LAYOUT_SHARED_PRESENT_KHR 1470endif::VK_KHR_shared_presentable_image[] 1471 layout at the time the operation is executed on a sname:VkDevice 1472ifdef::VK_KHR_present_id[] 1473 * [[VUID-VkPresentInfoKHR-pNext-06235]] 1474 If a slink:VkPresentIdKHR structure is included in the pname:pNext 1475 chain, and the <<features-presentId, pname:presentId>> feature is not 1476 enabled, each pname:presentIds entry in that structure must: be NULL 1477endif::VK_KHR_present_id[] 1478ifdef::VK_EXT_swapchain_maintenance1[] 1479 * [[VUID-VkPresentInfoKHR-pSwapchains-09199]] 1480 If any element of the pname:pSwapchains array has been created with 1481 slink:VkSwapchainPresentModesCreateInfoEXT, all of the elements of this 1482 array must: be created with slink:VkSwapchainPresentModesCreateInfoEXT 1483endif::VK_EXT_swapchain_maintenance1[] 1484**** 1485 1486include::{generated}/validity/structs/VkPresentInfoKHR.adoc[] 1487-- 1488 1489ifdef::VK_KHR_incremental_present[] 1490include::{chapters}/VK_KHR_incremental_present/wsi.adoc[] 1491endif::VK_KHR_incremental_present[] 1492 1493ifdef::VK_KHR_display_swapchain[] 1494include::{chapters}/VK_KHR_display_swapchain/display_swapchain_present.adoc[] 1495endif::VK_KHR_display_swapchain[] 1496 1497ifdef::VK_VERSION_1_1,VK_KHR_device_group[] 1498[open,refpage='VkDeviceGroupPresentInfoKHR',desc='Mode and mask controlling which physical devices\' images are presented',type='structs'] 1499-- 1500If the pname:pNext chain of slink:VkPresentInfoKHR includes a 1501sname:VkDeviceGroupPresentInfoKHR structure, then that structure includes an 1502array of device masks and a device group present mode. 1503 1504The sname:VkDeviceGroupPresentInfoKHR structure is defined as: 1505 1506include::{generated}/api/structs/VkDeviceGroupPresentInfoKHR.adoc[] 1507 1508 * pname:sType is a elink:VkStructureType value identifying this structure. 1509 * pname:pNext is `NULL` or a pointer to a structure extending this 1510 structure. 1511 * pname:swapchainCount is zero or the number of elements in 1512 pname:pDeviceMasks. 1513 * pname:pDeviceMasks is a pointer to an array of device masks, one for 1514 each element of slink:VkPresentInfoKHR::pname:pSwapchains. 1515 * pname:mode is a elink:VkDeviceGroupPresentModeFlagBitsKHR value 1516 specifying the device group present mode that will be used for this 1517 present. 1518 1519If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR, then each 1520element of pname:pDeviceMasks selects which instance of the swapchain image 1521is presented. 1522Each element of pname:pDeviceMasks must: have exactly one bit set, and the 1523corresponding physical device must: have a presentation engine as reported 1524by slink:VkDeviceGroupPresentCapabilitiesKHR. 1525 1526If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR, then 1527each element of pname:pDeviceMasks selects which instance of the swapchain 1528image is presented. 1529Each element of pname:pDeviceMasks must: have exactly one bit set, and some 1530physical device in the logical device must: include that bit in its 1531slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask. 1532 1533If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, then each 1534element of pname:pDeviceMasks selects which instances of the swapchain image 1535are component-wise summed and the sum of those images is presented. 1536If the sum in any component is outside the representable range, the value of 1537that component is undefined:. 1538Each element of pname:pDeviceMasks must: have a value for which all set bits 1539are set in one of the elements of 1540slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask. 1541 1542If pname:mode is 1543ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, then each 1544element of pname:pDeviceMasks selects which instance(s) of the swapchain 1545images are presented. 1546For each bit set in each element of pname:pDeviceMasks, the corresponding 1547physical device must: have a presentation engine as reported by 1548slink:VkDeviceGroupPresentCapabilitiesKHR. 1549 1550If sname:VkDeviceGroupPresentInfoKHR is not provided or pname:swapchainCount 1551is zero then the masks are considered to be `1`. 1552If sname:VkDeviceGroupPresentInfoKHR is not provided, pname:mode is 1553considered to be ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR. 1554 1555.Valid Usage 1556**** 1557 * [[VUID-VkDeviceGroupPresentInfoKHR-swapchainCount-01297]] 1558 pname:swapchainCount must: equal `0` or 1559 slink:VkPresentInfoKHR::pname:swapchainCount 1560 * [[VUID-VkDeviceGroupPresentInfoKHR-mode-01298]] 1561 If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR, then 1562 each element of pname:pDeviceMasks must: have exactly one bit set, and 1563 the corresponding element of 1564 slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask must: be 1565 non-zero 1566 * [[VUID-VkDeviceGroupPresentInfoKHR-mode-01299]] 1567 If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR, then 1568 each element of pname:pDeviceMasks must: have exactly one bit set, and 1569 some physical device in the logical device must: include that bit in its 1570 slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask 1571 * [[VUID-VkDeviceGroupPresentInfoKHR-mode-01300]] 1572 If pname:mode is ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR, then 1573 each element of pname:pDeviceMasks must: have a value for which all set 1574 bits are set in one of the elements of 1575 slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask 1576 * [[VUID-VkDeviceGroupPresentInfoKHR-mode-01301]] 1577 If pname:mode is 1578 ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR, then for 1579 each bit set in each element of pname:pDeviceMasks, the corresponding 1580 element of slink:VkDeviceGroupPresentCapabilitiesKHR::pname:presentMask 1581 must: be non-zero 1582 * [[VUID-VkDeviceGroupPresentInfoKHR-pDeviceMasks-01302]] 1583 The value of each element of pname:pDeviceMasks must: be equal to the 1584 device mask passed in slink:VkAcquireNextImageInfoKHR::pname:deviceMask 1585 when the image index was last acquired 1586 * [[VUID-VkDeviceGroupPresentInfoKHR-mode-01303]] 1587 pname:mode must: have exactly one bit set, and that bit must: have been 1588 included in slink:VkDeviceGroupSwapchainCreateInfoKHR::pname:modes 1589**** 1590 1591include::{generated}/validity/structs/VkDeviceGroupPresentInfoKHR.adoc[] 1592-- 1593endif::VK_VERSION_1_1,VK_KHR_device_group[] 1594 1595ifdef::VK_GOOGLE_display_timing[] 1596include::{chapters}/VK_GOOGLE_display_timing/PresentTimeInfo.adoc[] 1597endif::VK_GOOGLE_display_timing[] 1598 1599ifdef::VK_KHR_present_id[] 1600include::{chapters}/VK_KHR_swapchain/PresentId.adoc[] 1601endif::VK_KHR_present_id[] 1602 1603ifdef::VK_GGP_frame_token[] 1604include::{chapters}/VK_GGP_frame_token.adoc[] 1605endif::VK_GGP_frame_token[] 1606 1607ifdef::VK_EXT_swapchain_maintenance1[] 1608include::{chapters}/VK_EXT_swapchain_maintenance1/SwapchainPresentModeInfo.adoc[] 1609include::{chapters}/VK_EXT_swapchain_maintenance1/SwapchainPresentFenceInfo.adoc[] 1610endif::VK_EXT_swapchain_maintenance1[] 1611 1612fname:vkQueuePresentKHR releases the acquisition of the images referenced by 1613pname:imageIndices. 1614The queue family corresponding to the queue fname:vkQueuePresentKHR is 1615executed on must: have ownership of the presented images as defined in 1616<<resources-sharing,Resource Sharing>>. 1617fname:vkQueuePresentKHR does not alter the queue family ownership, but the 1618presented images must: not be used again before they have been reacquired 1619using fname:vkAcquireNextImageKHR. 1620 1621The processing of the presentation happens in issue order with other queue 1622operations, but semaphores have to be used to ensure that prior rendering 1623and other commands in the specified queue complete before the presentation 1624begins. 1625The presentation command itself does not delay processing of subsequent 1626commands on the queue, however, presentation requests sent to a particular 1627queue are always performed in order. 1628Exact presentation timing is controlled by the semantics of the presentation 1629engine and native platform in use. 1630 1631ifdef::VK_KHR_display_swapchain[] 1632include::{chapters}/VK_KHR_display_swapchain/queue_present_interactions.adoc[] 1633endif::VK_KHR_display_swapchain[] 1634 1635The result codes ename:VK_ERROR_OUT_OF_DATE_KHR and ename:VK_SUBOPTIMAL_KHR 1636have the same meaning when returned by fname:vkQueuePresentKHR as they do 1637when returned by fname:vkAcquireNextImageKHR. 1638If multiple swapchains are presented, the result code is determined applying 1639the following rules in order: 1640 1641 * If the device is lost, ename:VK_ERROR_DEVICE_LOST is returned. 1642 * If any of the target surfaces are no longer available the error 1643 ename:VK_ERROR_SURFACE_LOST_KHR is returned. 1644 * If any of the presents would have a result of 1645 ename:VK_ERROR_OUT_OF_DATE_KHR if issued separately then 1646 ename:VK_ERROR_OUT_OF_DATE_KHR is returned. 1647ifdef::VK_EXT_full_screen_exclusive[] 1648 * If any of the presents would have a result of 1649 ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT if issued separately 1650 then ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT is returned. 1651endif::VK_EXT_full_screen_exclusive[] 1652 * If any of the presents would have a result of ename:VK_SUBOPTIMAL_KHR if 1653 issued separately then ename:VK_SUBOPTIMAL_KHR is returned. 1654 * Otherwise ename:VK_SUCCESS is returned. 1655 1656Presentation is a read-only operation that will not affect the content of 1657the presentable images. 1658Upon reacquiring the image and transitioning it away from the 1659ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR layout, the contents will be the same 1660as they were prior to transitioning the image to the present source layout 1661and presenting it. 1662However, if a mechanism other than Vulkan is used to modify the platform 1663window associated with the swapchain, the content of all presentable images 1664in the swapchain becomes undefined:. 1665 1666[NOTE] 1667.Note 1668==== 1669The application can: continue to present any acquired images from a retired 1670swapchain as long as the swapchain has not entered a state that causes 1671flink:vkQueuePresentKHR to return ename:VK_ERROR_OUT_OF_DATE_KHR. 1672==== 1673 1674ifdef::VK_EXT_swapchain_maintenance1[] 1675[open,refpage='vkReleaseSwapchainImagesEXT',desc='Release previously acquired but unused images',type='protos'] 1676-- 1677To release images previously acquired through 1678ifdef::VK_VERSION_1_1,VK_KHR_device_group[flink:vkAcquireNextImage2KHR or] 1679flink:vkAcquireNextImageKHR, call: 1680 1681include::{generated}/api/protos/vkReleaseSwapchainImagesEXT.adoc[] 1682 1683 * pname:device is the device associated with 1684 slink:VkReleaseSwapchainImagesInfoEXT::pname:swapchain. 1685 * pname:pReleaseInfo is a pointer to a 1686 slink:VkReleaseSwapchainImagesInfoEXT structure containing parameters of 1687 the release. 1688 1689Only images that are not in use by the device can: be released. 1690 1691Releasing images is a read-only operation that will not affect the content 1692of the released images. 1693Upon reacquiring the image, the image contents and its layout will be the 1694same as they were prior to releasing it. 1695However, if a mechanism other than Vulkan is used to modify the platform 1696window associated with the swapchain, the content of all presentable images 1697in the swapchain becomes undefined:. 1698 1699.Note 1700[NOTE] 1701==== 1702This functionality is useful during swapchain recreation, where acquired 1703images from the old swapchain can be released instead of presented. 1704==== 1705 1706include::{generated}/validity/protos/vkReleaseSwapchainImagesEXT.adoc[] 1707-- 1708 1709[open,refpage='VkReleaseSwapchainImagesInfoEXT',desc='Structure describing a list of swapchain image indices to be released',type='structs'] 1710-- 1711The sname:VkReleaseSwapchainImagesInfoEXT structure is defined as: 1712 1713include::{generated}/api/structs/VkReleaseSwapchainImagesInfoEXT.adoc[] 1714 1715 * pname:sType is a elink:VkStructureType value identifying this structure. 1716 * pname:pNext is `NULL` or a pointer to a structure extending this 1717 structure. 1718 * pname:swapchain is a swapchain to which images are being released. 1719 * pname:imageIndexCount is the number of image indices to be released. 1720 * pname:pImageIndices is a pointer to an array of indices into the array 1721 of pname:swapchain's presentable images, with pname:imageIndexCount 1722 entries. 1723 1724.Valid Usage 1725**** 1726 * [[VUID-VkReleaseSwapchainImagesInfoEXT-pImageIndices-07785]] 1727 Each element of pname:pImageIndices must: be the index of a presentable 1728 image acquired from the swapchain specified by pname:swapchain 1729 * [[VUID-VkReleaseSwapchainImagesInfoEXT-pImageIndices-07786]] 1730 All uses of presentable images identified by elements of 1731 pname:pImageIndices must: have completed execution 1732**** 1733 1734include::{generated}/validity/structs/VkReleaseSwapchainImagesInfoEXT.adoc[] 1735-- 1736endif::VK_EXT_swapchain_maintenance1[] 1737 1738ifdef::VK_EXT_hdr_metadata[] 1739include::{chapters}/VK_EXT_hdr_metadata.adoc[] 1740endif::VK_EXT_hdr_metadata[] 1741