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