/ appendices / VK_KHR_swapchain.txt
VK_KHR_swapchain.txt
1 // Copyright (c) 2014-2019 Khronos Group. This work is licensed under a 2 // Creative Commons Attribution 4.0 International License; see 3 // http://creativecommons.org/licenses/by/4.0/ 4 5 include::meta/VK_KHR_swapchain.txt[] 6 7 *Last Modified Date*:: 8 2017-10-06 9 *IP Status*:: 10 No known IP claims. 11 *Interactions and External Dependencies*:: 12 - Interacts with Vulkan 1.1 13 *Contributors*:: 14 - Patrick Doane, Blizzard 15 - Ian Elliott, LunarG 16 - Jesse Hall, Google 17 - Mathias Heyer, NVIDIA 18 - James Jones, NVIDIA 19 - David Mao, AMD 20 - Norbert Nopper, Freescale 21 - Alon Or-bach, Samsung 22 - Daniel Rakos, AMD 23 - Graham Sellers, AMD 24 - Jeff Vigil, Qualcomm 25 - Chia-I Wu, LunarG 26 - Jason Ekstrand, Intel 27 - Matthaeus G. Chajdas, AMD 28 - Ray Smith, ARM 29 30 The `VK_KHR_swapchain` extension is the device-level companion to the 31 `<<VK_KHR_surface>>` extension. 32 It introduces slink:VkSwapchainKHR objects, which provide the ability to 33 present rendering results to a surface. 34 35 === New Object Types 36 37 * slink:VkSwapchainKHR 38 39 === New Enum Constants 40 41 * Extending elink:VkStructureType: 42 ** ename:VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR 43 ** ename:VK_STRUCTURE_TYPE_PRESENT_INFO_KHR 44 ifdef::VK_VERSION_1_1[] 45 ** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR 46 ** ename:VK_STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR 47 ** ename:VK_STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR 48 ** ename:VK_STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR 49 ** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR 50 ** ename:VK_STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR 51 endif::VK_VERSION_1_1[] 52 * Extending elink:VkImageLayout: 53 ** ename:VK_IMAGE_LAYOUT_PRESENT_SRC_KHR 54 * Extending elink:VkResult: 55 ** ename:VK_SUBOPTIMAL_KHR 56 ** ename:VK_ERROR_OUT_OF_DATE_KHR 57 58 === New Enums 59 60 ifdef::VK_VERSION_1_1[] 61 * elink:VkDeviceGroupPresentModeFlagBitsKHR 62 * elink:VkSwapchainCreateFlagBitsKHR 63 endif::VK_VERSION_1_1[] 64 65 === New Structures 66 67 * slink:VkSwapchainCreateInfoKHR 68 * slink:VkPresentInfoKHR 69 ifdef::VK_VERSION_1_1[] 70 * slink:VkDeviceGroupPresentCapabilitiesKHR 71 * slink:VkImageSwapchainCreateInfoKHR 72 * slink:VkBindImageMemorySwapchainInfoKHR 73 * slink:VkAcquireNextImageInfoKHR 74 * slink:VkDeviceGroupPresentInfoKHR 75 * slink:VkDeviceGroupSwapchainCreateInfoKHR 76 endif::VK_VERSION_1_1[] 77 78 === New Functions 79 80 * flink:vkCreateSwapchainKHR 81 * flink:vkDestroySwapchainKHR 82 * flink:vkGetSwapchainImagesKHR 83 * flink:vkAcquireNextImageKHR 84 * flink:vkQueuePresentKHR 85 ifdef::VK_VERSION_1_1[] 86 * flink:vkGetDeviceGroupPresentCapabilitiesKHR 87 * flink:vkGetDeviceGroupSurfacePresentModesKHR 88 * flink:vkGetPhysicalDevicePresentRectanglesKHR 89 * flink:vkAcquireNextImage2KHR 90 endif::VK_VERSION_1_1[] 91 92 === Issues 93 94 1) Does this extension allow the application to specify the memory backing 95 of the presentable images? 96 97 *RESOLVED*: No. 98 Unlike standard images, the implementation will allocate the memory backing 99 of the presentable image. 100 101 2) What operations are allowed on presentable images? 102 103 *RESOLVED*: This is determined by the image usage flags specified when 104 creating the presentable image's swapchain. 105 106 3) Does this extension support MSAA presentable images? 107 108 *RESOLVED*: No. 109 Presentable images are always single-sampled. 110 Multi-sampled rendering must use regular images. 111 To present the rendering results the application must manually resolve the 112 multi- sampled image to a single-sampled presentable image prior to 113 presentation. 114 115 4) Does this extension support stereo/multi-view presentable images? 116 117 *RESOLVED*: Yes. 118 The number of views associated with a presentable image is determined by the 119 pname:imageArrayLayers specified when creating a swapchain. 120 All presentable images in a given swapchain use the same array size. 121 122 5) Are the layers of stereo presentable images half-sized? 123 124 *RESOLVED*: No. 125 The image extents always match those requested by the application. 126 127 6) Do the "`present`" and "`acquire next image`" commands operate on a 128 queue? If not, do they need to include explicit semaphore objects to 129 interlock them with queue operations? 130 131 *RESOLVED*: The present command operates on a queue. 132 The image ownership operation it represents happens in order with other 133 operations on the queue, so no explicit semaphore object is required to 134 synchronize its actions. 135 136 Applications may want to acquire the next image in separate threads from 137 those in which they manage their queue, or in multiple threads. 138 To make such usage easier, the acquire next image command takes a semaphore 139 to signal as a method of explicit synchronization. 140 The application must later queue a wait for this semaphore before queuing 141 execution of any commands using the image. 142 143 7) Does flink:vkAcquireNextImageKHR block if no images are available? 144 145 *RESOLVED*: The command takes a timeout parameter. 146 Special values for the timeout are 0, which makes the call a non-blocking 147 operation, and code:UINT64_MAX, which blocks indefinitely. 148 Values in between will block for up to the specified time. 149 The call will return when an image becomes available or an error occurs. 150 It may, but is not required to, return before the specified timeout expires 151 if the swapchain becomes out of date. 152 153 8) Can multiple presents be queued using one flink:vkQueuePresentKHR call? 154 155 *RESOLVED*: Yes. 156 slink:VkPresentInfoKHR contains a list of swapchains and corresponding image 157 indices that will be presented. 158 When supported, all presentations queued with a single 159 flink:vkQueuePresentKHR call will be applied atomically as one operation. 160 The same swapchain must not appear in the list more than once. 161 Later extensions may provide applications stronger guarantees of atomicity 162 for such present operations, and/or allow them to query whether atomic 163 presentation of a particular group of swapchains is possible. 164 165 9) How do the presentation and acquire next image functions notify the 166 application the targeted surface has changed? 167 168 *RESOLVED*: Two new result codes are introduced for this purpose: 169 170 * ename:VK_SUBOPTIMAL_KHR - Presentation will still succeed, subject to 171 the window resize behavior, but the swapchain is no longer configured 172 optimally for the surface it targets. 173 Applications should query updated surface information and recreate their 174 swapchain at the next convenient opportunity. 175 * ename:VK_ERROR_OUT_OF_DATE_KHR - Failure. 176 The swapchain is no longer compatible with the surface it targets. 177 The application must query updated surface information and recreate the 178 swapchain before presentation will succeed. 179 180 These can be returned by both flink:vkAcquireNextImageKHR and 181 flink:vkQueuePresentKHR. 182 183 10) Does the flink:vkAcquireNextImageKHR command return a semaphore to the 184 application via an output parameter, or accept a semaphore to signal from 185 the application as an object handle parameter? 186 187 *RESOLVED*: Accept a semaphore to signal as an object handle. 188 This avoids the need to specify whether the application must destroy the 189 semaphore or whether it is owned by the swapchain, and if the latter, what 190 its lifetime is and whether it can be re-used for other operations once it 191 is received from flink:vkAcquireNextImageKHR. 192 193 11) What types of swapchain queuing behavior should be exposed? Options 194 include swap interval specification, mailbox/most recent vs. 195 FIFO queue management, targeting specific vertical blank intervals or 196 absolute times for a given present operation, and probably others. 197 For some of these, whether they are specified at swapchain creation time or 198 as per-present parameters needs to be decided as well. 199 200 *RESOLVED*: The base swapchain extension will expose 3 possible behaviors 201 (of which, FIFO will always be supported): 202 203 - Immediate present: Does not wait for vertical blanking period to update 204 the current image, likely resulting in visible tearing. 205 No internal queue is used. 206 Present requests are applied immediately. 207 - Mailbox queue: Waits for the next vertical blanking period to update the 208 current image. 209 No tearing should be observed. 210 An internal single-entry queue is used to hold pending presentation 211 requests. 212 If the queue is full when a new presentation request is received, the 213 new request replaces the existing entry, and any images associated with 214 the prior entry become available for re-use by the application. 215 - FIFO queue: Waits for the next vertical blanking period to update the 216 current image. 217 No tearing should be observed. 218 An internal queue containing [eq]#ptext:numSwapchainImages - 1# entries 219 is used to hold pending presentation requests. 220 New requests are appended to the end of the queue, and one request is 221 removed from the beginning of the queue and processed during each 222 vertical blanking period in which the queue is non-empty 223 224 Not all surfaces will support all of these modes, so the modes supported 225 will be returned using a surface info query. 226 All surfaces must support the FIFO queue mode. 227 Applications must choose one of these modes up front when creating a 228 swapchain. 229 Switching modes can be accomplished by recreating the swapchain. 230 231 12) Can ename:VK_PRESENT_MODE_MAILBOX_KHR provide non-blocking guarantees 232 for flink:vkAcquireNextImageKHR? If so, what is the proper criteria? 233 234 *RESOLVED*: Yes. 235 The difficulty is not immediately obvious here. 236 Naively, if at least 3 images are requested, mailbox mode should always have 237 an image available for the application if the application does not own any 238 images when the call to flink:vkAcquireNextImageKHR was made. 239 However, some presentation engines may have more than one "`current`" image, 240 and would still need to block in some cases. 241 The right requirement appears to be that if the application allocates the 242 surface's minimum number of images + 1 then it is guaranteed non-blocking 243 behavior when it does not currently own any images. 244 245 13) Is there a way to create and initialize a new swapchain for a surface 246 that has generated a ename:VK_SUBOPTIMAL_KHR return code while still using 247 the old swapchain? 248 249 *RESOLVED*: Not as part of this specification. 250 This could be useful to allow the application to create an "`optimal`" 251 replacement swapchain and rebuild all its command buffers using it in a 252 background thread at a low priority while continuing to use the 253 "`suboptimal`" swapchain in the main thread. 254 It could probably use the same "`atomic replace`" semantics proposed for 255 recreating direct-to-device swapchains without incurring a mode switch. 256 However, after discussion, it was determined some platforms probably could 257 not support concurrent swapchains for the same surface though, so this will 258 be left out of the base KHR extensions. 259 A future extension could add this for platforms where it is supported. 260 261 14) Should there be a special value for 262 slink:VkSurfaceCapabilitiesKHR::pname:maxImageCount to indicate there are no 263 practical limits on the number of images in a swapchain? 264 265 *RESOLVED*: Yes. 266 There where often be cases where there is no practical limit to the number 267 of images in a swapchain other than the amount of available resources (I.e., 268 memory) in the system. 269 Trying to derive a hard limit from things like memory size is prone to 270 failure. 271 It is better in such cases to leave it to applications to figure such soft 272 limits out via trial/failure iterations. 273 274 15) Should there be a special value for 275 slink:VkSurfaceCapabilitiesKHR::pname:currentExtent to indicate the size of 276 the platform surface is undefined:? 277 278 *RESOLVED*: Yes. 279 On some platforms (Wayland, for example), the surface size is defined by the 280 images presented to it rather than the other way around. 281 282 16) Should there be a special value for 283 slink:VkSurfaceCapabilitiesKHR::pname:maxImageExtent to indicate there is no 284 practical limit on the surface size? 285 286 *RESOLVED*: No. 287 It seems unlikely such a system would exist. 288 0 could be used to indicate the platform places no limits on the extents 289 beyond those imposed by Vulkan for normal images, but this query could just 290 as easily return those same limits, so a special "`unlimited`" value does 291 not seem useful for this field. 292 293 17) How should surface rotation and mirroring be exposed to applications? 294 How do they specify rotation and mirroring transforms applied prior to 295 presentation? 296 297 *RESOLVED*: Applications can query both the supported and current transforms 298 of a surface. 299 Both are specified relative to the device's "`natural`" display rotation and 300 direction. 301 The supported transforms indicates which orientations the presentation 302 engine accepts images in. 303 For example, a presentation engine that does not support transforming 304 surfaces as part of presentation, and which is presenting to a surface that 305 is displayed with a 90-degree rotation, would return only one supported 306 transform bit: ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR. 307 Applications must transform their rendering by the transform they specify 308 when creating the swapchain in pname:preTransform field. 309 310 18) Can surfaces ever not support etext:VK_MIRROR_NONE? Can they support 311 vertical and horizontal mirroring simultaneously? Relatedly, should 312 etext:VK_MIRROR_NONE[_BIT] be zero, or bit one, and should applications be 313 allowed to specify multiple pre and current mirror transform bits, or 314 exactly one? 315 316 *RESOLVED*: Since some platforms may not support presenting with a transform 317 other than the native window's current transform, and prerotation/mirroring 318 are specified relative to the device's natural rotation and direction, 319 rather than relative to the surface's current rotation and direction, it is 320 necessary to express lack of support for no mirroring. 321 To allow this, the etext:MIRROR_NONE enum must occupy a bit in the flags. 322 Since etext:MIRROR_NONE must be a bit in the bitmask rather than a bitmask 323 with no values set, allowing more than one bit to be set in the bitmask 324 would make it possible to describe undefined: transforms such as 325 etext:VK_MIRROR_NONE_BIT | etext:VK_MIRROR_HORIZONTAL_BIT, or a transform 326 that includes both "`no mirroring`" and "`horizontal mirroring`" 327 simultaneously. 328 Therefore, it is desirable to allow specifying all supported mirroring 329 transforms using only one bit. 330 The question then becomes, should there be a 331 etext:VK_MIRROR_HORIZONTAL_AND_VERTICAL_BIT to represent a simultaneous 332 horizontal and vertical mirror transform? However, such a transform is 333 equivalent to a 180 degree rotation, so presentation engines and 334 applications that wish to support or use such a transform can express it 335 through rotation instead. 336 Therefore, 3 exclusive bits are sufficient to express all needed mirroring 337 transforms. 338 339 19) Should support for sRGB be required? 340 341 *RESOLVED*: In the advent of UHD and HDR display devices, proper color space 342 information is vital to the display pipeline represented by the swapchain. 343 The app can discover the supported format/color-space pairs and select a 344 pair most suited to its rendering needs. 345 Currently only the sRGB color space is supported, future extensions may 346 provide support for more color spaces. 347 See issues 23 and 24. 348 349 20) Is there a mechanism to modify or replace an existing swapchain with one 350 targeting the same surface? 351 352 *RESOLVED*: Yes. 353 This is described above in the text. 354 355 21) Should there be a way to set prerotation and mirroring using native APIs 356 when presenting using a Vulkan swapchain? 357 358 *RESOLVED*: Yes. 359 The transforms that can be expressed in this extension are a subset of those 360 possible on native platforms. 361 If a platform exposes a method to specify the transform of presented images 362 for a given surface using native methods and exposes more transforms or 363 other properties for surfaces than Vulkan supports, it might be impossible, 364 difficult, or inconvenient to set some of those properties using Vulkan KHR 365 extensions and some using the native interfaces. 366 To avoid overwriting properties set using native commands when presenting 367 using a Vulkan swapchain, the application can set the pretransform to 368 "`inherit`", in which case the current native properties will be used, or if 369 none are available, a platform-specific default will be used. 370 Platforms that do not specify a reasonable default or do not provide native 371 mechanisms to specify such transforms should not include the inherit bits in 372 the pname:supportedTransforms bitmask they return in 373 slink:VkSurfaceCapabilitiesKHR. 374 375 22) Should the content of presentable images be clipped by objects obscuring 376 their target surface? 377 378 *RESOLVED*: Applications can choose which behavior they prefer. 379 Allowing the content to be clipped could enable more optimal presentation 380 methods on some platforms, but some applications might rely on the content 381 of presentable images to perform techniques such as partial updates or 382 motion blurs. 383 384 23) What is the purpose of specifying a elink:VkColorSpaceKHR along with 385 elink:VkFormat when creating a swapchain? 386 387 *RESOLVED*: While Vulkan itself is color space agnostic (e.g. even the 388 meaning of R, G, B and A can be freely defined by the rendering 389 application), the swapchain eventually will have to present the images on a 390 display device with specific color reproduction characteristics. 391 If any color space transformations are necessary before an image can be 392 displayed, the color space of the presented image must be known to the 393 swapchain. 394 A swapchain will only support a restricted set of color format and -space 395 pairs. 396 This set can be discovered via flink:vkGetPhysicalDeviceSurfaceFormatsKHR. 397 As it can be expected that most display devices support the sRGB color 398 space, at least one format/color-space pair has to be exposed, where the 399 color space is ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR. 400 401 24) How are sRGB formats and the sRGB color space related? 402 403 *RESOLVED*: While Vulkan exposes a number of SRGB texture formats, using 404 such formats does not guarantee working in a specific color space. 405 It merely means that the hardware can directly support applying the 406 non-linear transfer functions defined by the sRGB standard color space when 407 reading from or writing to images of that these formats. 408 Still, it is unlikely that a swapchain will expose a etext:*_SRGB format 409 along with any color space other than 410 ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR. 411 412 On the other hand, non-etext:*_SRGB formats will be very likely exposed in 413 pair with a SRGB color space. 414 This means, the hardware will not apply any transfer function when reading 415 from or writing to such images, yet they will still be presented on a device 416 with sRGB display characteristics. 417 In this case the application is responsible for applying the transfer 418 function, for instance by using shader math. 419 420 25) How are the lifetime of surfaces and swapchains targeting them related? 421 422 *RESOLVED*: A surface must outlive any swapchains targeting it. 423 A slink:VkSurfaceKHR owns the binding of the native window to the Vulkan 424 driver. 425 426 26) How can the client control the way the alpha channel of swapchain images 427 is treated by the presentation engine during compositing? 428 429 *RESOLVED*: We should add new enum values to allow the client to negotiate 430 with the presentation engine on how to treat image alpha values during the 431 compositing process. 432 Since not all platforms can practically control this through the Vulkan 433 driver, a value of ename:VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR is provided like 434 for surface transforms. 435 436 27) Is flink:vkCreateSwapchainKHR the right function to return 437 ename:VK_ERROR_NATIVE_WINDOW_IN_USE_KHR, or should the various 438 platform-specific slink:VkSurfaceKHR factory functions catch this error 439 earlier? 440 441 *RESOLVED*: For most platforms, the slink:VkSurfaceKHR structure is a simple 442 container holding the data that identifies a native window or other object 443 representing a surface on a particular platform. 444 For the surface factory functions to return this error, they would likely 445 need to register a reference on the native objects with the native display 446 server somehow, and ensure no other such references exist. 447 Surfaces were not intended to be that heavyweight. 448 449 Swapchains are intended to be the objects that directly manipulate native 450 windows and communicate with the native presentation mechanisms. 451 Swapchains will already need to communicate with the native display server 452 to negotiate allocation and/or presentation of presentable images for a 453 native surface. 454 Therefore, it makes more sense for swapchain creation to be the point at 455 which native object exclusivity is enforced. 456 Platforms may choose to enforce further restrictions on the number of 457 slink:VkSurfaceKHR objects that may be created for the same native window if 458 such a requirement makes sense on a particular platform, but a global 459 requirement is only sensible at the swapchain level. 460 461 === Examples 462 463 [NOTE] 464 .Note 465 ==== 466 The example code for the `<<VK_KHR_surface>>` and `VK_KHR_swapchain` 467 extensions was removed from the appendix after revision 1.0.29. 468 This WSI example code was ported to the cube demo that is shipped with the 469 official Khronos SDK, and is being kept up-to-date in that location (see: 470 https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c). 471 ==== 472 473 === Version History 474 475 * Revision 1, 2015-05-20 (James Jones) 476 - Initial draft, based on LunarG KHR spec, other KHR specs, patches 477 attached to bugs. 478 479 * Revision 2, 2015-05-22 (Ian Elliott) 480 - Made many agreed-upon changes from 2015-05-21 KHR TSG meeting. 481 This includes using only a queue for presentation, and having an 482 explicit function to acquire the next image. 483 - Fixed typos and other minor mistakes. 484 485 * Revision 3, 2015-05-26 (Ian Elliott) 486 - Improved the Description section. 487 - Added or resolved issues that were found in improving the Description. 488 For example, pSurfaceDescription is used consistently, instead of 489 sometimes using pSurface. 490 491 * Revision 4, 2015-05-27 (James Jones) 492 - Fixed some grammatical errors and typos 493 - Filled in the description of imageUseFlags when creating a swapchain. 494 - Added a description of swapInterval. 495 - Replaced the paragraph describing the order of operations on a queue 496 for image ownership and presentation. 497 498 * Revision 5, 2015-05-27 (James Jones) 499 - Imported relevant issues from the (abandoned) 500 vk_wsi_persistent_swapchain_images extension. 501 - Added issues 6 and 7, regarding behavior of the acquire next image and 502 present commands with respect to queues. 503 - Updated spec language and examples to align with proposed resolutions 504 to issues 6 and 7. 505 506 * Revision 6, 2015-05-27 (James Jones) 507 - Added issue 8, regarding atomic presentation of multiple swapchains 508 - Updated spec language and examples to align with proposed resolution to 509 issue 8. 510 511 * Revision 7, 2015-05-27 (James Jones) 512 - Fixed compilation errors in example code, and made related spec fixes. 513 514 * Revision 8, 2015-05-27 (James Jones) 515 - Added issue 9, and the related VK_SUBOPTIMAL_KHR result code. 516 - Renamed VK_OUT_OF_DATE_KHR to VK_ERROR_OUT_OF_DATE_KHR. 517 518 * Revision 9, 2015-05-27 (James Jones) 519 - Added inline proposed resolutions (marked with [JRJ]) to some XXX 520 questions/issues. 521 These should be moved to the issues section in a subsequent update if 522 the proposals are adopted. 523 524 * Revision 10, 2015-05-28 (James Jones) 525 - Converted vkAcquireNextImageKHR back to a non-queue operation that uses 526 a VkSemaphore object for explicit synchronization. 527 - Added issue 10 to determine whether vkAcquireNextImageKHR generates or 528 returns semaphores, or whether it operates on a semaphore provided by 529 the application. 530 531 * Revision 11, 2015-05-28 (James Jones) 532 - Marked issues 6, 7, and 8 resolved. 533 - Renamed VkSurfaceCapabilityPropertiesKHR to VkSurfacePropertiesKHR to 534 better convey the mutable nature of the info it contains. 535 536 * Revision 12, 2015-05-28 (James Jones) 537 - Added issue 11 with a proposed resolution, and the related issue 12. 538 - Updated various sections of the spec to match the proposed resolution 539 to issue 11. 540 541 * Revision 13, 2015-06-01 (James Jones) 542 - Moved some structures to VK_EXT_KHR_swap_chain to resolve the spec's 543 issues 1 and 2. 544 545 * Revision 14, 2015-06-01 (James Jones) 546 - Added code for example 4 demonstrating how an application might make 547 use of the two different present and acquire next image KHR result 548 codes. 549 - Added issue 13. 550 551 * Revision 15, 2015-06-01 (James Jones) 552 - Added issues 14 - 16 and related spec language. 553 - Fixed some spelling errors. 554 - Added language describing the meaningful return values for 555 vkAcquireNextImageKHR and vkQueuePresentKHR. 556 557 * Revision 16, 2015-06-02 (James Jones) 558 - Added issues 17 and 18, as well as related spec language. 559 - Removed some erroneous text added by mistake in the last update. 560 561 * Revision 17, 2015-06-15 (Ian Elliott) 562 - Changed special value from "-1" to "0" so that the data types can be 563 unsigned. 564 565 * Revision 18, 2015-06-15 (Ian Elliott) 566 - Clarified the values of VkSurfacePropertiesKHR::minImageCount and the 567 timeout parameter of the vkAcquireNextImageKHR function. 568 569 * Revision 19, 2015-06-17 (James Jones) 570 - Misc. 571 cleanup. 572 Removed resolved inline issues and fixed typos. 573 - Fixed clarification of VkSurfacePropertiesKHR::minImageCount made in 574 version 18. 575 - Added a brief "Image Ownership" definition to the list of terms used in 576 the spec. 577 578 * Revision 20, 2015-06-17 (James Jones) 579 - Updated enum-extending values using new convention. 580 581 * Revision 21, 2015-06-17 (James Jones) 582 - Added language describing how to use 583 VK_IMAGE_LAYOUT_PRESENT_SOURCE_KHR. 584 - Cleaned up an XXX comment regarding the description of which queues 585 vkQueuePresentKHR can be used on. 586 587 * Revision 22, 2015-06-17 (James Jones) 588 - Rebased on Vulkan API version 126. 589 590 * Revision 23, 2015-06-18 (James Jones) 591 - Updated language for issue 12 to read as a proposed resolution. 592 - Marked issues 11, 12, 13, 16, and 17 resolved. 593 - Temporarily added links to the relevant bugs under the remaining 594 unresolved issues. 595 - Added issues 19 and 20 as well as proposed resolutions. 596 597 * Revision 24, 2015-06-19 (Ian Elliott) 598 - Changed special value for VkSurfacePropertiesKHR::currentExtent back to 599 "-1" from "0". 600 This value will never need to be unsigned, and "0" is actually a legal 601 value. 602 603 * Revision 25, 2015-06-23 (Ian Elliott) 604 - Examples now show use of function pointers for extension functions. 605 - Eliminated extraneous whitespace. 606 607 * Revision 26, 2015-06-25 (Ian Elliott) 608 - Resolved Issues 9 & 10 per KHR TSG meeting. 609 610 * Revision 27, 2015-06-25 (James Jones) 611 - Added oldSwapchain member to VkSwapchainCreateInfoKHR. 612 613 * Revision 28, 2015-06-25 (James Jones) 614 - Added the "inherit" bits to the rotation and mirroring flags and the 615 associated issue 21. 616 617 * Revision 29, 2015-06-25 (James Jones) 618 - Added the "clipped" flag to VkSwapchainCreateInfoKHR, and the 619 associated issue 22. 620 - Specified that presenting an image does not modify it. 621 622 * Revision 30, 2015-06-25 (James Jones) 623 - Added language to the spec that clarifies the behavior of 624 vkCreateSwapchainKHR() when the oldSwapchain field of 625 VkSwapchainCreateInfoKHR is not NULL. 626 627 * Revision 31, 2015-06-26 (Ian Elliott) 628 - Example of new VkSwapchainCreateInfoKHR members, "oldSwapchain" and 629 "clipped". 630 - Example of using VkSurfacePropertiesKHR::{min|max}ImageCount to set 631 VkSwapchainCreateInfoKHR::minImageCount. 632 - Rename vkGetSurfaceInfoKHR()'s 4th parameter to "pDataSize", for 633 consistency with other functions. 634 - Add macro with C-string name of extension (just to header file). 635 636 * Revision 32, 2015-06-26 (James Jones) 637 - Minor adjustments to the language describing the behavior of 638 "oldSwapchain" 639 - Fixed the version date on my previous two updates. 640 641 * Revision 33, 2015-06-26 (Jesse Hall) 642 - Add usage flags to VkSwapchainCreateInfoKHR 643 644 * Revision 34, 2015-06-26 (Ian Elliott) 645 - Rename vkQueuePresentKHR()'s 2nd parameter to "pPresentInfo", for 646 consistency with other functions. 647 648 * Revision 35, 2015-06-26 (Jason Ekstrand) 649 - Merged the VkRotationFlagBitsKHR and VkMirrorFlagBitsKHR enums into a 650 single VkSurfaceTransformFlagBitsKHR enum. 651 652 * Revision 36, 2015-06-26 (Jason Ekstrand) 653 - Added a VkSurfaceTransformKHR enum that is not a bitmask. 654 Each value in VkSurfaceTransformKHR corresponds directly to one of the 655 bits in VkSurfaceTransformFlagBitsKHR so transforming from one to the 656 other is easy. 657 Having a separate enum means that currentTransform and preTransform are 658 now unambiguous by definition. 659 660 * Revision 37, 2015-06-29 (Ian Elliott) 661 - Corrected one of the signatures of vkAcquireNextImageKHR, which had the 662 last two parameters switched from what it is elsewhere in the 663 specification and header files. 664 665 * Revision 38, 2015-06-30 (Ian Elliott) 666 - Corrected a typo in description of the vkGetSwapchainInfoKHR() 667 function. 668 - Corrected a typo in header file comment for VkPresentInfoKHR::sType. 669 670 * Revision 39, 2015-07-07 (Daniel Rakos) 671 - Added error section describing when each error is expected to be 672 reported. 673 - Replaced bool32_t with VkBool32. 674 675 * Revision 40, 2015-07-10 (Ian Elliott) 676 - Updated to work with version 138 of the "vulkan.h" header. 677 This includes declaring the VkSwapchainKHR type using the new 678 VK_DEFINE_NONDISP_HANDLE macro, and no longer extending VkObjectType 679 (which was eliminated). 680 681 * Revision 41 2015-07-09 (Mathias Heyer) 682 - Added color space language. 683 684 * Revision 42, 2015-07-10 (Daniel Rakos) 685 - Updated query mechanism to reflect the convention changes done in the 686 core spec. 687 - Removed "queue" from the name of 688 VK_STRUCTURE_TYPE_QUEUE_PRESENT_INFO_KHR to be consistent with the 689 established naming convention. 690 - Removed reference to the no longer existing VkObjectType enum. 691 692 * Revision 43, 2015-07-17 (Daniel Rakos) 693 - Added support for concurrent sharing of swapchain images across queue 694 families. 695 - Updated sample code based on recent changes 696 697 * Revision 44, 2015-07-27 (Ian Elliott) 698 - Noted that support for VK_PRESENT_MODE_FIFO_KHR is required. 699 That is ICDs may optionally support IMMEDIATE and MAILBOX, but must 700 support FIFO. 701 702 * Revision 45, 2015-08-07 (Ian Elliott) 703 - Corrected a typo in spec file (type and variable name had wrong case 704 for the imageColorSpace member of the VkSwapchainCreateInfoKHR struct). 705 - Corrected a typo in header file (last parameter in 706 PFN_vkGetSurfacePropertiesKHR was missing "KHR" at the end of type: 707 VkSurfacePropertiesKHR). 708 709 * Revision 46, 2015-08-20 (Ian Elliott) 710 - Renamed this extension and all of its enumerations, types, functions, 711 etc. 712 This makes it compliant with the proposed standard for Vulkan 713 extensions. 714 - Switched from "revision" to "version", including use of the 715 VK_MAKE_VERSION macro in the header file. 716 - Made improvements to several descriptions. 717 - Changed the status of several issues from PROPOSED to RESOLVED, leaving 718 no unresolved issues. 719 - Resolved several TODOs, did miscellaneous cleanup, etc. 720 721 * Revision 47, 2015-08-20 (Ian Elliott--porting a 2015-07-29 change from 722 James Jones) 723 - Moved the surface transform enums to VK_WSI_swapchain so they could be 724 re-used by VK_WSI_display. 725 726 * Revision 48, 2015-09-01 (James Jones) 727 - Various minor cleanups. 728 729 * Revision 49, 2015-09-01 (James Jones) 730 - Restore single-field revision number. 731 732 * Revision 50, 2015-09-01 (James Jones) 733 - Update Example #4 to include code that illustrates how to use the 734 oldSwapchain field. 735 736 * Revision 51, 2015-09-01 (James Jones) 737 - Fix example code compilation errors. 738 739 * Revision 52, 2015-09-08 (Matthaeus G. Chajdas) 740 - Corrected a typo. 741 742 * Revision 53, 2015-09-10 (Alon Or-bach) 743 - Removed underscore from SWAP_CHAIN left in 744 VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR. 745 746 * Revision 54, 2015-09-11 (Jesse Hall) 747 - Described the execution and memory coherence requirements for image 748 transitions to and from VK_IMAGE_LAYOUT_PRESENT_SOURCE_KHR. 749 750 * Revision 55, 2015-09-11 (Ray Smith) 751 - Added errors for destroying and binding memory to presentable images 752 753 * Revision 56, 2015-09-18 (James Jones) 754 - Added fence argument to vkAcquireNextImageKHR 755 - Added example of how to meter a host thread based on presentation rate. 756 757 * Revision 57, 2015-09-26 (Jesse Hall) 758 - Replace VkSurfaceDescriptionKHR with VkSurfaceKHR. 759 - Added issue 25 with agreed resolution. 760 761 * Revision 58, 2015-09-28 (Jesse Hall) 762 - Renamed from VK_EXT_KHR_device_swapchain to VK_EXT_KHR_swapchain. 763 764 * Revision 59, 2015-09-29 (Ian Elliott) 765 - Changed vkDestroySwapchainKHR() to return void. 766 767 * Revision 60, 2015-10-01 (Jeff Vigil) 768 - Added error result VK_ERROR_SURFACE_LOST_KHR. 769 770 * Revision 61, 2015-10-05 (Jason Ekstrand) 771 - Added the VkCompositeAlpha enum and corresponding structure fields. 772 773 * Revision 62, 2015-10-12 (Daniel Rakos) 774 - Added VK_PRESENT_MODE_FIFO_RELAXED_KHR. 775 776 * Revision 63, 2015-10-15 (Daniel Rakos) 777 - Moved surface capability queries to VK_EXT_KHR_surface. 778 779 * Revision 64, 2015-10-26 (Ian Elliott) 780 - Renamed from VK_EXT_KHR_swapchain to VK_KHR_swapchain. 781 782 * Revision 65, 2015-10-28 (Ian Elliott) 783 - Added optional pResult member to VkPresentInfoKHR, so that 784 per-swapchain results can be obtained from vkQueuePresentKHR(). 785 786 * Revision 66, 2015-11-03 (Daniel Rakos) 787 - Added allocation callbacks to create and destroy functions. 788 - Updated resource transition language. 789 - Updated sample code. 790 791 * Revision 67, 2015-11-10 (Jesse Hall) 792 - Add reserved flags bitmask to VkSwapchainCreateInfoKHR. 793 - Modify naming and member ordering to match API style conventions, and 794 so the VkSwapchainCreateInfoKHR image property members mirror 795 corresponding VkImageCreateInfo members but with an 'image' prefix. 796 - Make VkPresentInfoKHR::pResults non-const; it is an output array 797 parameter. 798 - Make pPresentInfo parameter to vkQueuePresentKHR const. 799 800 * Revision 68, 2016-04-05 (Ian Elliott) 801 - Moved the "validity" include for vkAcquireNextImage to be in its proper 802 place, after the prototype and list of parameters. 803 - Clarified language about presentable images, including how they are 804 acquired, when applications can and cannot use them, etc. 805 As part of this, removed language about "ownership" of presentable 806 images, and replaced it with more-consistent language about presentable 807 images being "acquired" by the application. 808 809 * 2016-08-23 (Ian Elliott) 810 - Update the example code, to use the final API command names, to not 811 have so many characters per line, and to split out a new example to 812 show how to obtain function pointers. 813 This code is more similar to the LunarG "cube" demo program. 814 815 * 2016-08-25 (Ian Elliott) 816 - A note was added at the beginning of the example code, stating that it 817 will be removed from future versions of the appendix. 818 819 * Revision 69, 2017-09-07 (Tobias Hector) 820 - Added interactions with Vulkan 1.1 821 822 * Revision 70, 2017-10-06 (Ian Elliott) 823 - Corrected interactions with Vulkan 1.1