{-# language CPP #-} -- | = Name -- -- VK_KHR_swapchain - device extension -- -- == VK_KHR_swapchain -- -- [__Name String__] -- @VK_KHR_swapchain@ -- -- [__Extension Type__] -- Device extension -- -- [__Registered Extension Number__] -- 2 -- -- [__Revision__] -- 70 -- -- [__Extension and Version Dependencies__] -- -- - Requires Vulkan 1.0 -- -- - Requires @VK_KHR_surface@ -- -- [__Contact__] -- -- - James Jones -- > > -- -- - Ian Elliott -- > > -- -- == Other Extension Metadata -- -- [__Last Modified Date__] -- 2017-10-06 -- -- [__IP Status__] -- No known IP claims. -- -- [__Interactions and External Dependencies__] -- -- - Interacts with Vulkan 1.1 -- -- [__Contributors__] -- -- - Patrick Doane, Blizzard -- -- - Ian Elliott, LunarG -- -- - Jesse Hall, Google -- -- - Mathias Heyer, NVIDIA -- -- - James Jones, NVIDIA -- -- - David Mao, AMD -- -- - Norbert Nopper, Freescale -- -- - Alon Or-bach, Samsung -- -- - Daniel Rakos, AMD -- -- - Graham Sellers, AMD -- -- - Jeff Vigil, Qualcomm -- -- - Chia-I Wu, LunarG -- -- - Jason Ekstrand, Intel -- -- - Matthaeus G. Chajdas, AMD -- -- - Ray Smith, ARM -- -- == Description -- -- The @VK_KHR_swapchain@ extension is the device-level companion to the -- @VK_KHR_surface@ extension. It introduces -- 'Vulkan.Extensions.Handles.SwapchainKHR' objects, which provide the -- ability to present rendering results to a surface. -- -- == New Object Types -- -- - 'Vulkan.Extensions.Handles.SwapchainKHR' -- -- == New Commands -- -- - 'acquireNextImageKHR' -- -- - 'createSwapchainKHR' -- -- - 'destroySwapchainKHR' -- -- - 'getSwapchainImagesKHR' -- -- - 'queuePresentKHR' -- -- If -- -- is supported: -- -- - 'acquireNextImage2KHR' -- -- - 'getDeviceGroupPresentCapabilitiesKHR' -- -- - 'getDeviceGroupSurfacePresentModesKHR' -- -- - 'getPhysicalDevicePresentRectanglesKHR' -- -- == New Structures -- -- - 'PresentInfoKHR' -- -- - 'SwapchainCreateInfoKHR' -- -- If -- -- is supported: -- -- - 'AcquireNextImageInfoKHR' -- -- - 'DeviceGroupPresentCapabilitiesKHR' -- -- - Extending -- 'Vulkan.Core11.Promoted_From_VK_KHR_bind_memory2.BindImageMemoryInfo': -- -- - 'BindImageMemorySwapchainInfoKHR' -- -- - Extending 'Vulkan.Core10.Image.ImageCreateInfo': -- -- - 'ImageSwapchainCreateInfoKHR' -- -- - Extending 'PresentInfoKHR': -- -- - 'DeviceGroupPresentInfoKHR' -- -- - Extending 'SwapchainCreateInfoKHR': -- -- - 'DeviceGroupSwapchainCreateInfoKHR' -- -- == New Enums -- -- - 'SwapchainCreateFlagBitsKHR' -- -- If -- -- is supported: -- -- - 'DeviceGroupPresentModeFlagBitsKHR' -- -- == New Bitmasks -- -- - 'SwapchainCreateFlagsKHR' -- -- If -- -- is supported: -- -- - 'DeviceGroupPresentModeFlagsKHR' -- -- == New Enum Constants -- -- - 'KHR_SWAPCHAIN_EXTENSION_NAME' -- -- - 'KHR_SWAPCHAIN_SPEC_VERSION' -- -- - Extending 'Vulkan.Core10.Enums.ImageLayout.ImageLayout': -- -- - 'Vulkan.Core10.Enums.ImageLayout.IMAGE_LAYOUT_PRESENT_SRC_KHR' -- -- - Extending 'Vulkan.Core10.Enums.ObjectType.ObjectType': -- -- - 'Vulkan.Core10.Enums.ObjectType.OBJECT_TYPE_SWAPCHAIN_KHR' -- -- - Extending 'Vulkan.Core10.Enums.Result.Result': -- -- - 'Vulkan.Core10.Enums.Result.ERROR_OUT_OF_DATE_KHR' -- -- - 'Vulkan.Core10.Enums.Result.SUBOPTIMAL_KHR' -- -- - Extending 'Vulkan.Core10.Enums.StructureType.StructureType': -- -- - 'Vulkan.Core10.Enums.StructureType.STRUCTURE_TYPE_PRESENT_INFO_KHR' -- -- - 'Vulkan.Core10.Enums.StructureType.STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR' -- -- If -- -- is supported: -- -- - Extending 'Vulkan.Core10.Enums.StructureType.StructureType': -- -- - 'Vulkan.Core10.Enums.StructureType.STRUCTURE_TYPE_ACQUIRE_NEXT_IMAGE_INFO_KHR' -- -- - 'Vulkan.Core10.Enums.StructureType.STRUCTURE_TYPE_BIND_IMAGE_MEMORY_SWAPCHAIN_INFO_KHR' -- -- - 'Vulkan.Core10.Enums.StructureType.STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_CAPABILITIES_KHR' -- -- - 'Vulkan.Core10.Enums.StructureType.STRUCTURE_TYPE_DEVICE_GROUP_PRESENT_INFO_KHR' -- -- - 'Vulkan.Core10.Enums.StructureType.STRUCTURE_TYPE_DEVICE_GROUP_SWAPCHAIN_CREATE_INFO_KHR' -- -- - 'Vulkan.Core10.Enums.StructureType.STRUCTURE_TYPE_IMAGE_SWAPCHAIN_CREATE_INFO_KHR' -- -- - Extending 'SwapchainCreateFlagBitsKHR': -- -- - 'SWAPCHAIN_CREATE_PROTECTED_BIT_KHR' -- -- - 'SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR' -- -- == Issues -- -- 1) Does this extension allow the application to specify the memory -- backing of the presentable images? -- -- __RESOLVED__: No. Unlike standard images, the implementation will -- allocate the memory backing of the presentable image. -- -- 2) What operations are allowed on presentable images? -- -- __RESOLVED__: This is determined by the image usage flags specified when -- creating the presentable image’s swapchain. -- -- 3) Does this extension support MSAA presentable images? -- -- __RESOLVED__: No. Presentable images are always single-sampled. -- Multi-sampled rendering must use regular images. To present the -- rendering results the application must manually resolve the multi- -- sampled image to a single-sampled presentable image prior to -- presentation. -- -- 4) Does this extension support stereo\/multi-view presentable images? -- -- __RESOLVED__: Yes. The number of views associated with a presentable -- image is determined by the @imageArrayLayers@ specified when creating a -- swapchain. All presentable images in a given swapchain use the same -- array size. -- -- 5) Are the layers of stereo presentable images half-sized? -- -- __RESOLVED__: No. The image extents always match those requested by the -- application. -- -- 6) Do the “present” and “acquire next image” commands operate on a -- queue? If not, do they need to include explicit semaphore objects to -- interlock them with queue operations? -- -- __RESOLVED__: The present command operates on a queue. The image -- ownership operation it represents happens in order with other operations -- on the queue, so no explicit semaphore object is required to synchronize -- its actions. -- -- Applications may want to acquire the next image in separate threads from -- those in which they manage their queue, or in multiple threads. To make -- such usage easier, the acquire next image command takes a semaphore to -- signal as a method of explicit synchronization. The application must -- later queue a wait for this semaphore before queuing execution of any -- commands using the image. -- -- 7) Does 'acquireNextImageKHR' block if no images are available? -- -- __RESOLVED__: The command takes a timeout parameter. Special values for -- the timeout are 0, which makes the call a non-blocking operation, and -- @UINT64_MAX@, which blocks indefinitely. Values in between will block -- for up to the specified time. The call will return when an image becomes -- available or an error occurs. It may, but is not required to, return -- before the specified timeout expires if the swapchain becomes out of -- date. -- -- 8) Can multiple presents be queued using one 'queuePresentKHR' call? -- -- __RESOLVED__: Yes. 'PresentInfoKHR' contains a list of swapchains and -- corresponding image indices that will be presented. When supported, all -- presentations queued with a single 'queuePresentKHR' call will be -- applied atomically as one operation. The same swapchain must not appear -- in the list more than once. Later extensions may provide applications -- stronger guarantees of atomicity for such present operations, and\/or -- allow them to query whether atomic presentation of a particular group of -- swapchains is possible. -- -- 9) How do the presentation and acquire next image functions notify the -- application the targeted surface has changed? -- -- __RESOLVED__: Two new result codes are introduced for this purpose: -- -- - 'Vulkan.Core10.Enums.Result.SUBOPTIMAL_KHR' - Presentation will -- still succeed, subject to the window resize behavior, but the -- swapchain is no longer configured optimally for the surface it -- targets. Applications should query updated surface information and -- recreate their swapchain at the next convenient opportunity. -- -- - 'Vulkan.Core10.Enums.Result.ERROR_OUT_OF_DATE_KHR' - Failure. The -- swapchain is no longer compatible with the surface it targets. The -- application must query updated surface information and recreate the -- swapchain before presentation will succeed. -- -- These can be returned by both 'acquireNextImageKHR' and -- 'queuePresentKHR'. -- -- 10) Does the 'acquireNextImageKHR' command return a semaphore to the -- application via an output parameter, or accept a semaphore to signal -- from the application as an object handle parameter? -- -- __RESOLVED__: Accept a semaphore to signal as an object handle. This -- avoids the need to specify whether the application must destroy the -- semaphore or whether it is owned by the swapchain, and if the latter, -- what its lifetime is and whether it can be reused for other operations -- once it is received from 'acquireNextImageKHR'. -- -- 11) What types of swapchain queuing behavior should be exposed? Options -- include swap interval specification, mailbox\/most recent vs. FIFO queue -- management, targeting specific vertical blank intervals or absolute -- times for a given present operation, and probably others. For some of -- these, whether they are specified at swapchain creation time or as -- per-present parameters needs to be decided as well. -- -- __RESOLVED__: The base swapchain extension will expose 3 possible -- behaviors (of which, FIFO will always be supported): -- -- - Immediate present: Does not wait for vertical blanking period to -- update the current image, likely resulting in visible tearing. No -- internal queue is used. Present requests are applied immediately. -- -- - Mailbox queue: Waits for the next vertical blanking period to update -- the current image. No tearing should be observed. An internal -- single-entry queue is used to hold pending presentation requests. If -- the queue is full when a new presentation request is received, the -- new request replaces the existing entry, and any images associated -- with the prior entry become available for reuse by the application. -- -- - FIFO queue: Waits for the next vertical blanking period to update -- the current image. No tearing should be observed. An internal queue -- containing @numSwapchainImages@ - 1 entries is used to hold pending -- presentation requests. New requests are appended to the end of the -- queue, and one request is removed from the beginning of the queue -- and processed during each vertical blanking period in which the -- queue is non-empty -- -- Not all surfaces will support all of these modes, so the modes supported -- will be returned using a surface information query. All surfaces must -- support the FIFO queue mode. Applications must choose one of these modes -- up front when creating a swapchain. Switching modes can be accomplished -- by recreating the swapchain. -- -- 12) Can 'Vulkan.Extensions.VK_KHR_surface.PRESENT_MODE_MAILBOX_KHR' -- provide non-blocking guarantees for 'acquireNextImageKHR'? If so, what -- is the proper criteria? -- -- __RESOLVED__: Yes. The difficulty is not immediately obvious here. -- Naively, if at least 3 images are requested, mailbox mode should always -- have an image available for the application if the application does not -- own any images when the call to 'acquireNextImageKHR' was made. However, -- some presentation engines may have more than one “current” image, and -- would still need to block in some cases. The right requirement appears -- to be that if the application allocates the surface’s minimum number of -- images + 1 then it is guaranteed non-blocking behavior when it does not -- currently own any images. -- -- 13) Is there a way to create and initialize a new swapchain for a -- surface that has generated a 'Vulkan.Core10.Enums.Result.SUBOPTIMAL_KHR' -- return code while still using the old swapchain? -- -- __RESOLVED__: Not as part of this specification. This could be useful to -- allow the application to create an “optimal” replacement swapchain and -- rebuild all its command buffers using it in a background thread at a low -- priority while continuing to use the “suboptimal” swapchain in the main -- thread. It could probably use the same “atomic replace” semantics -- proposed for recreating direct-to-device swapchains without incurring a -- mode switch. However, after discussion, it was determined some platforms -- probably could not support concurrent swapchains for the same surface -- though, so this will be left out of the base KHR extensions. A future -- extension could add this for platforms where it is supported. -- -- 14) Should there be a special value for -- 'Vulkan.Extensions.VK_KHR_surface.SurfaceCapabilitiesKHR'::@maxImageCount@ -- to indicate there are no practical limits on the number of images in a -- swapchain? -- -- __RESOLVED__: Yes. There will often be cases where there is no practical -- limit to the number of images in a swapchain other than the amount of -- available resources (i.e., memory) in the system. Trying to derive a -- hard limit from things like memory size is prone to failure. It is -- better in such cases to leave it to applications to figure such soft -- limits out via trial\/failure iterations. -- -- 15) Should there be a special value for -- 'Vulkan.Extensions.VK_KHR_surface.SurfaceCapabilitiesKHR'::@currentExtent@ -- to indicate the size of the platform surface is undefined? -- -- __RESOLVED__: Yes. On some platforms (Wayland, for example), the surface -- size is defined by the images presented to it rather than the other way -- around. -- -- 16) Should there be a special value for -- 'Vulkan.Extensions.VK_KHR_surface.SurfaceCapabilitiesKHR'::@maxImageExtent@ -- to indicate there is no practical limit on the surface size? -- -- __RESOLVED__: No. It seems unlikely such a system would exist. 0 could -- be used to indicate the platform places no limits on the extents beyond -- those imposed by Vulkan for normal images, but this query could just as -- easily return those same limits, so a special “unlimited” value does not -- seem useful for this field. -- -- 17) How should surface rotation and mirroring be exposed to -- applications? How do they specify rotation and mirroring transforms -- applied prior to presentation? -- -- __RESOLVED__: Applications can query both the supported and current -- transforms of a surface. Both are specified relative to the device’s -- “natural” display rotation and direction. The supported transforms -- indicate which orientations the presentation engine accepts images in. -- For example, a presentation engine that does not support transforming -- surfaces as part of presentation, and which is presenting to a surface -- that is displayed with a 90-degree rotation, would return only one -- supported transform bit: -- 'Vulkan.Extensions.VK_KHR_surface.SURFACE_TRANSFORM_ROTATE_90_BIT_KHR'. -- Applications must transform their rendering by the transform they -- specify when creating the swapchain in @preTransform@ field. -- -- 18) Can surfaces ever not support @VK_MIRROR_NONE@? Can they support -- vertical and horizontal mirroring simultaneously? Relatedly, should -- @VK_MIRROR_NONE@[_BIT] be zero, or bit one, and should applications be -- allowed to specify multiple pre and current mirror transform bits, or -- exactly one? -- -- __RESOLVED__: Since some platforms may not support presenting with a -- transform other than the native window’s current transform, and -- prerotation\/mirroring are specified relative to the device’s natural -- rotation and direction, rather than relative to the surface’s current -- rotation and direction, it is necessary to express lack of support for -- no mirroring. To allow this, the @MIRROR_NONE@ enum must occupy a bit in -- the flags. Since @MIRROR_NONE@ must be a bit in the bitmask rather than -- a bitmask with no values set, allowing more than one bit to be set in -- the bitmask would make it possible to describe undefined transforms such -- as @VK_MIRROR_NONE_BIT@ | @VK_MIRROR_HORIZONTAL_BIT@, or a transform -- that includes both “no mirroring” and “horizontal mirroring” -- simultaneously. Therefore, it is desirable to allow specifying all -- supported mirroring transforms using only one bit. The question then -- becomes, should there be a @VK_MIRROR_HORIZONTAL_AND_VERTICAL_BIT@ to -- represent a simultaneous horizontal and vertical mirror transform? -- However, such a transform is equivalent to a 180 degree rotation, so -- presentation engines and applications that wish to support or use such a -- transform can express it through rotation instead. Therefore, 3 -- exclusive bits are sufficient to express all needed mirroring -- transforms. -- -- 19) Should support for sRGB be required? -- -- __RESOLVED__: In the advent of UHD and HDR display devices, proper color -- space information is vital to the display pipeline represented by the -- swapchain. The app can discover the supported format\/color-space pairs -- and select a pair most suited to its rendering needs. Currently only the -- sRGB color space is supported, future extensions may provide support for -- more color spaces. See issues 23 and 24. -- -- 20) Is there a mechanism to modify or replace an existing swapchain with -- one targeting the same surface? -- -- __RESOLVED__: Yes. This is described above in the text. -- -- 21) Should there be a way to set prerotation and mirroring using native -- APIs when presenting using a Vulkan swapchain? -- -- __RESOLVED__: Yes. The transforms that can be expressed in this -- extension are a subset of those possible on native platforms. If a -- platform exposes a method to specify the transform of presented images -- for a given surface using native methods and exposes more transforms or -- other properties for surfaces than Vulkan supports, it might be -- impossible, difficult, or inconvenient to set some of those properties -- using Vulkan KHR extensions and some using the native interfaces. To -- avoid overwriting properties set using native commands when presenting -- using a Vulkan swapchain, the application can set the pretransform to -- “inherit”, in which case the current native properties will be used, or -- if none are available, a platform-specific default will be used. -- Platforms that do not specify a reasonable default or do not provide -- native mechanisms to specify such transforms should not include the -- inherit bits in the @supportedTransforms@ bitmask they return in -- 'Vulkan.Extensions.VK_KHR_surface.SurfaceCapabilitiesKHR'. -- -- 22) Should the content of presentable images be clipped by objects -- obscuring their target surface? -- -- __RESOLVED__: Applications can choose which behavior they prefer. -- Allowing the content to be clipped could enable more efficient -- presentation methods on some platforms, but some applications might rely -- on the content of presentable images to perform techniques such as -- partial updates or motion blurs. -- -- 23) What is the purpose of specifying a -- 'Vulkan.Extensions.VK_KHR_surface.ColorSpaceKHR' along with -- 'Vulkan.Core10.Enums.Format.Format' when creating a swapchain? -- -- __RESOLVED__: While Vulkan itself is color space agnostic (e.g. even the -- meaning of R, G, B and A can be freely defined by the rendering -- application), the swapchain eventually will have to present the images -- on a display device with specific color reproduction characteristics. If -- any color space transformations are necessary before an image can be -- displayed, the color space of the presented image must be known to the -- swapchain. A swapchain will only support a restricted set of color -- format and -space pairs. This set can be discovered via -- 'Vulkan.Extensions.VK_KHR_surface.getPhysicalDeviceSurfaceFormatsKHR'. -- As it can be expected that most display devices support the sRGB color -- space, at least one format\/color-space pair has to be exposed, where -- the color space is -- 'Vulkan.Extensions.VK_KHR_surface.COLOR_SPACE_SRGB_NONLINEAR_KHR'. -- -- 24) How are sRGB formats and the sRGB color space related? -- -- __RESOLVED__: While Vulkan exposes a number of SRGB texture formats, -- using such formats does not guarantee working in a specific color space. -- It merely means that the hardware can directly support applying the -- non-linear transfer functions defined by the sRGB standard color space -- when reading from or writing to images of those formats. Still, it is -- unlikely that a swapchain will expose a @*_SRGB@ format along with any -- color space other than -- 'Vulkan.Extensions.VK_KHR_surface.COLOR_SPACE_SRGB_NONLINEAR_KHR'. -- -- On the other hand, non-@*_SRGB@ formats will be very likely exposed in -- pair with a SRGB color space. This means, the hardware will not apply -- any transfer function when reading from or writing to such images, yet -- they will still be presented on a device with sRGB display -- characteristics. In this case the application is responsible for -- applying the transfer function, for instance by using shader math. -- -- 25) How are the lifetimes of surfaces and swapchains targeting them -- related? -- -- __RESOLVED__: A surface must outlive any swapchains targeting it. A -- 'Vulkan.Extensions.Handles.SurfaceKHR' owns the binding of the native -- window to the Vulkan driver. -- -- 26) How can the client control the way the alpha component of swapchain -- images is treated by the presentation engine during compositing? -- -- __RESOLVED__: We should add new enum values to allow the client to -- negotiate with the presentation engine on how to treat image alpha -- values during the compositing process. Since not all platforms can -- practically control this through the Vulkan driver, a value of -- 'Vulkan.Extensions.VK_KHR_surface.COMPOSITE_ALPHA_INHERIT_BIT_KHR' is -- provided like for surface transforms. -- -- 27) Is 'createSwapchainKHR' the right function to return -- 'Vulkan.Core10.Enums.Result.ERROR_NATIVE_WINDOW_IN_USE_KHR', or should -- the various platform-specific 'Vulkan.Extensions.Handles.SurfaceKHR' -- factory functions catch this error earlier? -- -- __RESOLVED__: For most platforms, the -- 'Vulkan.Extensions.Handles.SurfaceKHR' structure is a simple container -- holding the data that identifies a native window or other object -- representing a surface on a particular platform. For the surface factory -- functions to return this error, they would likely need to register a -- reference on the native objects with the native display server somehow, -- and ensure no other such references exist. Surfaces were not intended to -- be that heavyweight. -- -- Swapchains are intended to be the objects that directly manipulate -- native windows and communicate with the native presentation mechanisms. -- Swapchains will already need to communicate with the native display -- server to negotiate allocation and\/or presentation of presentable -- images for a native surface. Therefore, it makes more sense for -- swapchain creation to be the point at which native object exclusivity is -- enforced. Platforms may choose to enforce further restrictions on the -- number of 'Vulkan.Extensions.Handles.SurfaceKHR' objects that may be -- created for the same native window if such a requirement makes sense on -- a particular platform, but a global requirement is only sensible at the -- swapchain level. -- -- == Examples -- -- Note -- -- The example code for the @VK_KHR_surface@ and @VK_KHR_swapchain@ -- extensions was removed from the appendix after revision 1.0.29. This WSI -- example code was ported to the cube demo that is shipped with the -- official Khronos SDK, and is being kept up-to-date in that location -- (see: -- ). -- -- == Version History -- -- - Revision 1, 2015-05-20 (James Jones) -- -- - Initial draft, based on LunarG KHR spec, other KHR specs, -- patches attached to bugs. -- -- - Revision 2, 2015-05-22 (Ian Elliott) -- -- - Made many agreed-upon changes from 2015-05-21 KHR TSG meeting. -- This includes using only a queue for presentation, and having an -- explicit function to acquire the next image. -- -- - Fixed typos and other minor mistakes. -- -- - Revision 3, 2015-05-26 (Ian Elliott) -- -- - Improved the Description section. -- -- - Added or resolved issues that were found in improving the -- Description. For example, pSurfaceDescription is used -- consistently, instead of sometimes using pSurface. -- -- - Revision 4, 2015-05-27 (James Jones) -- -- - Fixed some grammatical errors and typos -- -- - Filled in the description of imageUseFlags when creating a -- swapchain. -- -- - Added a description of swapInterval. -- -- - Replaced the paragraph describing the order of operations on a -- queue for image ownership and presentation. -- -- - Revision 5, 2015-05-27 (James Jones) -- -- - Imported relevant issues from the (abandoned) -- vk_wsi_persistent_swapchain_images extension. -- -- - Added issues 6 and 7, regarding behavior of the acquire next -- image and present commands with respect to queues. -- -- - Updated spec language and examples to align with proposed -- resolutions to issues 6 and 7. -- -- - Revision 6, 2015-05-27 (James Jones) -- -- - Added issue 8, regarding atomic presentation of multiple -- swapchains -- -- - Updated spec language and examples to align with proposed -- resolution to issue 8. -- -- - Revision 7, 2015-05-27 (James Jones) -- -- - Fixed compilation errors in example code, and made related spec -- fixes. -- -- - Revision 8, 2015-05-27 (James Jones) -- -- - Added issue 9, and the related VK_SUBOPTIMAL_KHR result code. -- -- - Renamed VK_OUT_OF_DATE_KHR to VK_ERROR_OUT_OF_DATE_KHR. -- -- - Revision 9, 2015-05-27 (James Jones) -- -- - Added inline proposed resolutions (marked with [JRJ]) to some -- XXX questions\/issues. These should be moved to the issues -- section in a subsequent update if the proposals are adopted. -- -- - Revision 10, 2015-05-28 (James Jones) -- -- - Converted vkAcquireNextImageKHR back to a non-queue operation -- that uses a VkSemaphore object for explicit synchronization. -- -- - Added issue 10 to determine whether vkAcquireNextImageKHR -- generates or returns semaphores, or whether it operates on a -- semaphore provided by the application. -- -- - Revision 11, 2015-05-28 (James Jones) -- -- - Marked issues 6, 7, and 8 resolved. -- -- - Renamed VkSurfaceCapabilityPropertiesKHR to -- VkSurfacePropertiesKHR to better convey the mutable nature of -- the information it contains. -- -- - Revision 12, 2015-05-28 (James Jones) -- -- - Added issue 11 with a proposed resolution, and the related issue -- 12. -- -- - Updated various sections of the spec to match the proposed -- resolution to issue 11. -- -- - Revision 13, 2015-06-01 (James Jones) -- -- - Moved some structures to VK_EXT_KHR_swap_chain to resolve the -- specification’s issues 1 and 2. -- -- - Revision 14, 2015-06-01 (James Jones) -- -- - Added code for example 4 demonstrating how an application might -- make use of the two different present and acquire next image KHR -- result codes. -- -- - Added issue 13. -- -- - Revision 15, 2015-06-01 (James Jones) -- -- - Added issues 14 - 16 and related spec language. -- -- - Fixed some spelling errors. -- -- - Added language describing the meaningful return values for -- vkAcquireNextImageKHR and vkQueuePresentKHR. -- -- - Revision 16, 2015-06-02 (James Jones) -- -- - Added issues 17 and 18, as well as related spec language. -- -- - Removed some erroneous text added by mistake in the last update. -- -- - Revision 17, 2015-06-15 (Ian Elliott) -- -- - Changed special value from \"-1\" to \"0\" so that the data -- types can be unsigned. -- -- - Revision 18, 2015-06-15 (Ian Elliott) -- -- - Clarified the values of VkSurfacePropertiesKHR::minImageCount -- and the timeout parameter of the vkAcquireNextImageKHR function. -- -- - Revision 19, 2015-06-17 (James Jones) -- -- - Misc. cleanup. Removed resolved inline issues and fixed typos. -- -- - Fixed clarification of VkSurfacePropertiesKHR::minImageCount -- made in version 18. -- -- - Added a brief \"Image Ownership\" definition to the list of -- terms used in the spec. -- -- - Revision 20, 2015-06-17 (James Jones) -- -- - Updated enum-extending values using new convention. -- -- - Revision 21, 2015-06-17 (James Jones) -- -- - Added language describing how to use -- VK_IMAGE_LAYOUT_PRESENT_SOURCE_KHR. -- -- - Cleaned up an XXX comment regarding the description of which -- queues vkQueuePresentKHR can be used on. -- -- - Revision 22, 2015-06-17 (James Jones) -- -- - Rebased on Vulkan API version 126. -- -- - Revision 23, 2015-06-18 (James Jones) -- -- - Updated language for issue 12 to read as a proposed resolution. -- -- - Marked issues 11, 12, 13, 16, and 17 resolved. -- -- - Temporarily added links to the relevant bugs under the remaining -- unresolved issues. -- -- - Added issues 19 and 20 as well as proposed resolutions. -- -- - Revision 24, 2015-06-19 (Ian Elliott) -- -- - Changed special value for VkSurfacePropertiesKHR::currentExtent -- back to “-1” from “0”. This value will never need to be -- unsigned, and “0” is actually a legal value. -- -- - Revision 25, 2015-06-23 (Ian Elliott) -- -- - Examples now show use of function pointers for extension -- functions. -- -- - Eliminated extraneous whitespace. -- -- - Revision 26, 2015-06-25 (Ian Elliott) -- -- - Resolved Issues 9 & 10 per KHR TSG meeting. -- -- - Revision 27, 2015-06-25 (James Jones) -- -- - Added oldSwapchain member to VkSwapchainCreateInfoKHR. -- -- - Revision 28, 2015-06-25 (James Jones) -- -- - Added the “inherit” bits to the rotation and mirroring flags and -- the associated issue 21. -- -- - Revision 29, 2015-06-25 (James Jones) -- -- - Added the “clipped” flag to VkSwapchainCreateInfoKHR, and the -- associated issue 22. -- -- - Specified that presenting an image does not modify it. -- -- - Revision 30, 2015-06-25 (James Jones) -- -- - Added language to the spec that clarifies the behavior of -- vkCreateSwapchainKHR() when the oldSwapchain field of -- VkSwapchainCreateInfoKHR is not NULL. -- -- - Revision 31, 2015-06-26 (Ian Elliott) -- -- - Example of new VkSwapchainCreateInfoKHR members, “oldSwapchain” -- and “clipped”. -- -- - Example of using VkSurfacePropertiesKHR::{min|max}ImageCount to -- set VkSwapchainCreateInfoKHR::minImageCount. -- -- - Rename vkGetSurfaceInfoKHR()\'s 4th parameter to “pDataSize”, -- for consistency with other functions. -- -- - Add macro with C-string name of extension (just to header file). -- -- - Revision 32, 2015-06-26 (James Jones) -- -- - Minor adjustments to the language describing the behavior of -- “oldSwapchain” -- -- - Fixed the version date on my previous two updates. -- -- - Revision 33, 2015-06-26 (Jesse Hall) -- -- - Add usage flags to VkSwapchainCreateInfoKHR -- -- - Revision 34, 2015-06-26 (Ian Elliott) -- -- - Rename vkQueuePresentKHR()\'s 2nd parameter to “pPresentInfo”, -- for consistency with other functions. -- -- - Revision 35, 2015-06-26 (Jason Ekstrand) -- -- - Merged the VkRotationFlagBitsKHR and VkMirrorFlagBitsKHR enums -- into a single VkSurfaceTransformFlagBitsKHR enum. -- -- - Revision 36, 2015-06-26 (Jason Ekstrand) -- -- - Added a VkSurfaceTransformKHR enum that is not a bitmask. Each -- value in VkSurfaceTransformKHR corresponds directly to one of -- the bits in VkSurfaceTransformFlagBitsKHR so transforming from -- one to the other is easy. Having a separate enum means that -- currentTransform and preTransform are now unambiguous by -- definition. -- -- - Revision 37, 2015-06-29 (Ian Elliott) -- -- - Corrected one of the signatures of vkAcquireNextImageKHR, which -- had the last two parameters switched from what it is elsewhere -- in the specification and header files. -- -- - Revision 38, 2015-06-30 (Ian Elliott) -- -- - Corrected a typo in description of the vkGetSwapchainInfoKHR() -- function. -- -- - Corrected a typo in header file comment for -- VkPresentInfoKHR::sType. -- -- - Revision 39, 2015-07-07 (Daniel Rakos) -- -- - Added error section describing when each error is expected to be -- reported. -- -- - Replaced bool32_t with VkBool32. -- -- - Revision 40, 2015-07-10 (Ian Elliott) -- -- - Updated to work with version 138 of the @vulkan.h@ header. This -- includes declaring the VkSwapchainKHR type using the new -- VK_DEFINE_NONDISP_HANDLE macro, and no longer extending -- VkObjectType (which was eliminated). -- -- - Revision 41 2015-07-09 (Mathias Heyer) -- -- - Added color space language. -- -- - Revision 42, 2015-07-10 (Daniel Rakos) -- -- - Updated query mechanism to reflect the convention changes done -- in the core spec. -- -- - Removed “queue” from the name of -- VK_STRUCTURE_TYPE_QUEUE_PRESENT_INFO_KHR to be consistent with -- the established naming convention. -- -- - Removed reference to the no longer existing VkObjectType enum. -- -- - Revision 43, 2015-07-17 (Daniel Rakos) -- -- - Added support for concurrent sharing of swapchain images across -- queue families. -- -- - Updated sample code based on recent changes -- -- - Revision 44, 2015-07-27 (Ian Elliott) -- -- - Noted that support for VK_PRESENT_MODE_FIFO_KHR is required. -- That is ICDs may optionally support IMMEDIATE and MAILBOX, but -- must support FIFO. -- -- - Revision 45, 2015-08-07 (Ian Elliott) -- -- - Corrected a typo in spec file (type and variable name had wrong -- case for the imageColorSpace member of the -- VkSwapchainCreateInfoKHR struct). -- -- - Corrected a typo in header file (last parameter in -- PFN_vkGetSurfacePropertiesKHR was missing “KHR” at the end of -- type: VkSurfacePropertiesKHR). -- -- - Revision 46, 2015-08-20 (Ian Elliott) -- -- - Renamed this extension and all of its enumerations, types, -- functions, etc. This makes it compliant with the proposed -- standard for Vulkan extensions. -- -- - Switched from “revision” to “version”, including use of the -- VK_MAKE_VERSION macro in the header file. -- -- - Made improvements to several descriptions. -- -- - Changed the status of several issues from PROPOSED to RESOLVED, -- leaving no unresolved issues. -- -- - Resolved several TODOs, did miscellaneous cleanup, etc. -- -- - Revision 47, 2015-08-20 (Ian Elliott—​porting a 2015-07-29 change -- from James Jones) -- -- - Moved the surface transform enums to VK_WSI_swapchain so they -- could be reused by VK_WSI_display. -- -- - Revision 48, 2015-09-01 (James Jones) -- -- - Various minor cleanups. -- -- - Revision 49, 2015-09-01 (James Jones) -- -- - Restore single-field revision number. -- -- - Revision 50, 2015-09-01 (James Jones) -- -- - Update Example #4 to include code that illustrates how to use -- the oldSwapchain field. -- -- - Revision 51, 2015-09-01 (James Jones) -- -- - Fix example code compilation errors. -- -- - Revision 52, 2015-09-08 (Matthaeus G. Chajdas) -- -- - Corrected a typo. -- -- - Revision 53, 2015-09-10 (Alon Or-bach) -- -- - Removed underscore from SWAP_CHAIN left in -- VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR. -- -- - Revision 54, 2015-09-11 (Jesse Hall) -- -- - Described the execution and memory coherence requirements for -- image transitions to and from -- VK_IMAGE_LAYOUT_PRESENT_SOURCE_KHR. -- -- - Revision 55, 2015-09-11 (Ray Smith) -- -- - Added errors for destroying and binding memory to presentable -- images -- -- - Revision 56, 2015-09-18 (James Jones) -- -- - Added fence argument to vkAcquireNextImageKHR -- -- - Added example of how to meter a host thread based on -- presentation rate. -- -- - Revision 57, 2015-09-26 (Jesse Hall) -- -- - Replace VkSurfaceDescriptionKHR with VkSurfaceKHR. -- -- - Added issue 25 with agreed resolution. -- -- - Revision 58, 2015-09-28 (Jesse Hall) -- -- - Renamed from VK_EXT_KHR_device_swapchain to -- VK_EXT_KHR_swapchain. -- -- - Revision 59, 2015-09-29 (Ian Elliott) -- -- - Changed vkDestroySwapchainKHR() to return void. -- -- - Revision 60, 2015-10-01 (Jeff Vigil) -- -- - Added error result VK_ERROR_SURFACE_LOST_KHR. -- -- - Revision 61, 2015-10-05 (Jason Ekstrand) -- -- - Added the VkCompositeAlpha enum and corresponding structure -- fields. -- -- - Revision 62, 2015-10-12 (Daniel Rakos) -- -- - Added VK_PRESENT_MODE_FIFO_RELAXED_KHR. -- -- - Revision 63, 2015-10-15 (Daniel Rakos) -- -- - Moved surface capability queries to VK_EXT_KHR_surface. -- -- - Revision 64, 2015-10-26 (Ian Elliott) -- -- - Renamed from VK_EXT_KHR_swapchain to VK_KHR_swapchain. -- -- - Revision 65, 2015-10-28 (Ian Elliott) -- -- - Added optional pResult member to VkPresentInfoKHR, so that -- per-swapchain results can be obtained from vkQueuePresentKHR(). -- -- - Revision 66, 2015-11-03 (Daniel Rakos) -- -- - Added allocation callbacks to create and destroy functions. -- -- - Updated resource transition language. -- -- - Updated sample code. -- -- - Revision 67, 2015-11-10 (Jesse Hall) -- -- - Add reserved flags bitmask to VkSwapchainCreateInfoKHR. -- -- - Modify naming and member ordering to match API style -- conventions, and so the VkSwapchainCreateInfoKHR image property -- members mirror corresponding VkImageCreateInfo members but with -- an \'image\' prefix. -- -- - Make VkPresentInfoKHR::pResults non-const; it is an output array -- parameter. -- -- - Make pPresentInfo parameter to vkQueuePresentKHR const. -- -- - Revision 68, 2016-04-05 (Ian Elliott) -- -- - Moved the “validity” include for vkAcquireNextImage to be in its -- proper place, after the prototype and list of parameters. -- -- - Clarified language about presentable images, including how they -- are acquired, when applications can and cannot use them, etc. As -- part of this, removed language about “ownership” of presentable -- images, and replaced it with more-consistent language about -- presentable images being “acquired” by the application. -- -- - 2016-08-23 (Ian Elliott) -- -- - Update the example code, to use the final API command names, to -- not have so many characters per line, and to split out a new -- example to show how to obtain function pointers. This code is -- more similar to the LunarG “cube” demo program. -- -- - 2016-08-25 (Ian Elliott) -- -- - A note was added at the beginning of the example code, stating -- that it will be removed from future versions of the appendix. -- -- - Revision 69, 2017-09-07 (Tobias Hector) -- -- - Added interactions with Vulkan 1.1 -- -- - Revision 70, 2017-10-06 (Ian Elliott) -- -- - Corrected interactions with Vulkan 1.1 -- -- == See Also -- -- 'PresentInfoKHR', 'SwapchainCreateFlagBitsKHR', -- 'SwapchainCreateFlagsKHR', 'SwapchainCreateInfoKHR', -- 'Vulkan.Extensions.Handles.SwapchainKHR', 'acquireNextImageKHR', -- 'createSwapchainKHR', 'destroySwapchainKHR', 'getSwapchainImagesKHR', -- 'queuePresentKHR' -- -- == Document Notes -- -- For more information, see the -- -- -- This page is a generated document. Fixes and changes should be made to -- the generator scripts, not directly. module Vulkan.Extensions.VK_KHR_swapchain ( AcquireNextImageInfoKHR , BindImageMemorySwapchainInfoKHR , DeviceGroupPresentCapabilitiesKHR , DeviceGroupPresentInfoKHR , DeviceGroupSwapchainCreateInfoKHR , ImageSwapchainCreateInfoKHR , PresentInfoKHR , SwapchainCreateInfoKHR , DeviceGroupPresentModeFlagsKHR , DeviceGroupPresentModeFlagBitsKHR ) where import Vulkan.CStruct (FromCStruct) import Vulkan.CStruct (ToCStruct) import Data.Kind (Type) import {-# SOURCE #-} Vulkan.CStruct.Extends (Chain) import {-# SOURCE #-} Vulkan.CStruct.Extends (Extendss) import {-# SOURCE #-} Vulkan.CStruct.Extends (PeekChain) import {-# SOURCE #-} Vulkan.CStruct.Extends (PokeChain) data AcquireNextImageInfoKHR instance ToCStruct AcquireNextImageInfoKHR instance Show AcquireNextImageInfoKHR instance FromCStruct AcquireNextImageInfoKHR data BindImageMemorySwapchainInfoKHR instance ToCStruct BindImageMemorySwapchainInfoKHR instance Show BindImageMemorySwapchainInfoKHR instance FromCStruct BindImageMemorySwapchainInfoKHR data DeviceGroupPresentCapabilitiesKHR instance ToCStruct DeviceGroupPresentCapabilitiesKHR instance Show DeviceGroupPresentCapabilitiesKHR instance FromCStruct DeviceGroupPresentCapabilitiesKHR data DeviceGroupPresentInfoKHR instance ToCStruct DeviceGroupPresentInfoKHR instance Show DeviceGroupPresentInfoKHR instance FromCStruct DeviceGroupPresentInfoKHR data DeviceGroupSwapchainCreateInfoKHR instance ToCStruct DeviceGroupSwapchainCreateInfoKHR instance Show DeviceGroupSwapchainCreateInfoKHR instance FromCStruct DeviceGroupSwapchainCreateInfoKHR data ImageSwapchainCreateInfoKHR instance ToCStruct ImageSwapchainCreateInfoKHR instance Show ImageSwapchainCreateInfoKHR instance FromCStruct ImageSwapchainCreateInfoKHR type role PresentInfoKHR nominal data PresentInfoKHR (es :: [Type]) instance (Extendss PresentInfoKHR es, PokeChain es) => ToCStruct (PresentInfoKHR es) instance Show (Chain es) => Show (PresentInfoKHR es) instance (Extendss PresentInfoKHR es, PeekChain es) => FromCStruct (PresentInfoKHR es) type role SwapchainCreateInfoKHR nominal data SwapchainCreateInfoKHR (es :: [Type]) instance (Extendss SwapchainCreateInfoKHR es, PokeChain es) => ToCStruct (SwapchainCreateInfoKHR es) instance Show (Chain es) => Show (SwapchainCreateInfoKHR es) instance (Extendss SwapchainCreateInfoKHR es, PeekChain es) => FromCStruct (SwapchainCreateInfoKHR es) type DeviceGroupPresentModeFlagsKHR = DeviceGroupPresentModeFlagBitsKHR data DeviceGroupPresentModeFlagBitsKHR