Safe Haskell | None |
---|---|
Language | Haskell2010 |
Name
VK_KHR_display_swapchain - device extension
VK_KHR_display_swapchain
- Name String
VK_KHR_display_swapchain
- Extension Type
- Device extension
- Registered Extension Number
- 4
- Revision
- 10
- Extension and Version Dependencies
- Requires Vulkan 1.0
- Requires
VK_KHR_swapchain
- Requires
VK_KHR_display
- Contact
Other Extension Metadata
- Last Modified Date
- 2017-03-13
- IP Status
- No known IP claims.
- Contributors
- James Jones, NVIDIA
- Jeff Vigil, Qualcomm
- Jesse Hall, Google
Description
This extension provides an API to create a swapchain directly on a device’s display without any underlying window system.
New Commands
New Structures
Extending
PresentInfoKHR
:
New Enum Constants
KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION
Extending
Result
:Extending
StructureType
:
Issues
1) Should swapchains sharing images each hold a reference to the images, or should it be up to the application to destroy the swapchains and images in an order that avoids the need for reference counting?
RESOLVED: Take a reference. The lifetime of presentable images is already complex enough.
2) Should the srcRect
and dstRect
parameters be specified as part of
the present command, or at swapchain creation time?
RESOLVED: As part of the presentation command. This allows moving and scaling the image on the screen without the need to respecify the mode or create a new swapchain and presentable images.
3) Should srcRect
and dstRect
be specified as rects, or separate
offset/extent values?
RESOLVED: As rects. Specifying them separately might make it easier for hardware to expose support for one but not the other, but in such cases applications must just take care to obey the reported capabilities and not use non-zero offsets or extents that require scaling, as appropriate.
4) How can applications create multiple swapchains that use the same images?
RESOLVED: By calling createSharedSwapchainsKHR
.
An earlier resolution used
createSwapchainKHR
, chaining
multiple SwapchainCreateInfoKHR
structures through pNext
. In order to allow each swapchain to also
allow other extension structs, a level of indirection was used:
SwapchainCreateInfoKHR
::pNext
pointed to a different structure, which had both sType
and pNext
members for additional extensions, and also had a pointer to the next
SwapchainCreateInfoKHR
structure.
The number of swapchains to be created could only be found by walking
this linked list of alternating structures, and the pSwapchains
out
parameter was reinterpreted to be an array of
SwapchainKHR
handles.
Another option considered was a method to specify a “shared” swapchain when creating a new swapchain, such that groups of swapchains using the same images could be built up one at a time. This was deemed unusable because drivers need to know all of the displays an image will be used on when determining which internal formats and layouts to use for that image.
Examples
Note
The example code for the VK_KHR_display
and VK_KHR_display_swapchain
extensions was removed from the appendix after revision 1.0.43. The
display swapchain creation 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:
https://github.com/KhronosGroup/Vulkan-Tools/blob/master/cube/cube.c).
Version History
Revision 1, 2015-07-29 (James Jones)
- Initial draft
Revision 2, 2015-08-21 (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.
Revision 3, 2015-09-01 (James Jones)
- Restore single-field revision number.
Revision 4, 2015-09-08 (James Jones)
- Allow creating multiple swap chains that share the same images using a single call to vkCreateSwapChainKHR().
Revision 5, 2015-09-10 (Alon Or-bach)
- Removed underscores from SWAP_CHAIN in two enums.
Revision 6, 2015-10-02 (James Jones)
- Added support for smart panels/buffered displays.
Revision 7, 2015-10-26 (Ian Elliott)
- Renamed from VK_EXT_KHR_display_swapchain to VK_KHR_display_swapchain.
Revision 8, 2015-11-03 (Daniel Rakos)
- Updated sample code based on the changes to VK_KHR_swapchain.
Revision 9, 2015-11-10 (Jesse Hall)
- Replaced VkDisplaySwapchainCreateInfoKHR with vkCreateSharedSwapchainsKHR, changing resolution of issue #4.
Revision 10, 2017-03-13 (James Jones)
- Closed all remaining issues. The specification and implementations have been shipping with the proposed resolutions for some time now.
- Removed the sample code and noted it has been integrated into the official Vulkan SDK cube demo.
See Also
DisplayPresentInfoKHR
, createSharedSwapchainsKHR
Document Notes
For more information, see the Vulkan Specification
This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.
Synopsis
- createSharedSwapchainsKHR :: forall io. MonadIO io => Device -> ("createInfos" ::: Vector (SomeStruct SwapchainCreateInfoKHR)) -> ("allocator" ::: Maybe AllocationCallbacks) -> io ("swapchains" ::: Vector SwapchainKHR)
- data DisplayPresentInfoKHR = DisplayPresentInfoKHR {}
- type KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION = 10
- pattern KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION :: forall a. Integral a => a
- type KHR_DISPLAY_SWAPCHAIN_EXTENSION_NAME = "VK_KHR_display_swapchain"
- pattern KHR_DISPLAY_SWAPCHAIN_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a
- newtype SurfaceKHR = SurfaceKHR Word64
- newtype SwapchainKHR = SwapchainKHR Word64
- data SwapchainCreateInfoKHR (es :: [Type]) = SwapchainCreateInfoKHR {
- next :: Chain es
- flags :: SwapchainCreateFlagsKHR
- surface :: SurfaceKHR
- minImageCount :: Word32
- imageFormat :: Format
- imageColorSpace :: ColorSpaceKHR
- imageExtent :: Extent2D
- imageArrayLayers :: Word32
- imageUsage :: ImageUsageFlags
- imageSharingMode :: SharingMode
- queueFamilyIndices :: Vector Word32
- preTransform :: SurfaceTransformFlagBitsKHR
- compositeAlpha :: CompositeAlphaFlagBitsKHR
- presentMode :: PresentModeKHR
- clipped :: Bool
- oldSwapchain :: SwapchainKHR
- newtype PresentModeKHR where
- PresentModeKHR Int32
- pattern PRESENT_MODE_IMMEDIATE_KHR :: PresentModeKHR
- pattern PRESENT_MODE_MAILBOX_KHR :: PresentModeKHR
- pattern PRESENT_MODE_FIFO_KHR :: PresentModeKHR
- pattern PRESENT_MODE_FIFO_RELAXED_KHR :: PresentModeKHR
- pattern PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR :: PresentModeKHR
- pattern PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR :: PresentModeKHR
- newtype ColorSpaceKHR where
- ColorSpaceKHR Int32
- pattern COLOR_SPACE_DISPLAY_P3_LINEAR_EXT :: ColorSpaceKHR
- pattern COLOR_SPACE_SRGB_NONLINEAR_KHR :: ColorSpaceKHR
- pattern COLOR_SPACE_DISPLAY_NATIVE_AMD :: ColorSpaceKHR
- pattern COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT :: ColorSpaceKHR
- pattern COLOR_SPACE_PASS_THROUGH_EXT :: ColorSpaceKHR
- pattern COLOR_SPACE_ADOBERGB_NONLINEAR_EXT :: ColorSpaceKHR
- pattern COLOR_SPACE_ADOBERGB_LINEAR_EXT :: ColorSpaceKHR
- pattern COLOR_SPACE_HDR10_HLG_EXT :: ColorSpaceKHR
- pattern COLOR_SPACE_DOLBYVISION_EXT :: ColorSpaceKHR
- pattern COLOR_SPACE_HDR10_ST2084_EXT :: ColorSpaceKHR
- pattern COLOR_SPACE_BT2020_LINEAR_EXT :: ColorSpaceKHR
- pattern COLOR_SPACE_BT709_NONLINEAR_EXT :: ColorSpaceKHR
- pattern COLOR_SPACE_BT709_LINEAR_EXT :: ColorSpaceKHR
- pattern COLOR_SPACE_DCI_P3_NONLINEAR_EXT :: ColorSpaceKHR
- pattern COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT :: ColorSpaceKHR
- pattern COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT :: ColorSpaceKHR
- newtype CompositeAlphaFlagBitsKHR where
- CompositeAlphaFlagBitsKHR Flags
- pattern COMPOSITE_ALPHA_OPAQUE_BIT_KHR :: CompositeAlphaFlagBitsKHR
- pattern COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR :: CompositeAlphaFlagBitsKHR
- pattern COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR :: CompositeAlphaFlagBitsKHR
- pattern COMPOSITE_ALPHA_INHERIT_BIT_KHR :: CompositeAlphaFlagBitsKHR
- type CompositeAlphaFlagsKHR = CompositeAlphaFlagBitsKHR
- newtype SurfaceTransformFlagBitsKHR where
- SurfaceTransformFlagBitsKHR Flags
- pattern SURFACE_TRANSFORM_IDENTITY_BIT_KHR :: SurfaceTransformFlagBitsKHR
- pattern SURFACE_TRANSFORM_ROTATE_90_BIT_KHR :: SurfaceTransformFlagBitsKHR
- pattern SURFACE_TRANSFORM_ROTATE_180_BIT_KHR :: SurfaceTransformFlagBitsKHR
- pattern SURFACE_TRANSFORM_ROTATE_270_BIT_KHR :: SurfaceTransformFlagBitsKHR
- pattern SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR :: SurfaceTransformFlagBitsKHR
- pattern SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR :: SurfaceTransformFlagBitsKHR
- pattern SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR :: SurfaceTransformFlagBitsKHR
- pattern SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR :: SurfaceTransformFlagBitsKHR
- pattern SURFACE_TRANSFORM_INHERIT_BIT_KHR :: SurfaceTransformFlagBitsKHR
- type SurfaceTransformFlagsKHR = SurfaceTransformFlagBitsKHR
- newtype SwapchainCreateFlagBitsKHR where
- type SwapchainCreateFlagsKHR = SwapchainCreateFlagBitsKHR
Documentation
createSharedSwapchainsKHR Source #
:: forall io. MonadIO io | |
=> Device |
|
-> ("createInfos" ::: Vector (SomeStruct SwapchainCreateInfoKHR)) |
|
-> ("allocator" ::: Maybe AllocationCallbacks) |
|
-> io ("swapchains" ::: Vector SwapchainKHR) |
vkCreateSharedSwapchainsKHR - Create multiple swapchains that share presentable images
Description
createSharedSwapchainsKHR
is similar to
createSwapchainKHR
, except that it
takes an array of
SwapchainCreateInfoKHR
structures,
and returns an array of swapchain objects.
The swapchain creation parameters that affect the properties and number
of presentable images must match between all the swapchains. If the
displays used by any of the swapchains do not use the same presentable
image layout or are incompatible in a way that prevents sharing images,
swapchain creation will fail with the result code
ERROR_INCOMPATIBLE_DISPLAY_KHR
. If any
error occurs, no swapchains will be created. Images presented to
multiple swapchains must be re-acquired from all of them before
transitioning away from
IMAGE_LAYOUT_PRESENT_SRC_KHR
. After
destroying one or more of the swapchains, the remaining swapchains and
the presentable images can continue to be used.
Valid Usage (Implicit)
-
device
must be a validDevice
handle
-
pCreateInfos
must be a valid pointer to an array ofswapchainCount
validSwapchainCreateInfoKHR
structures - If
pAllocator
is notNULL
,pAllocator
must be a valid pointer to a validAllocationCallbacks
structure -
pSwapchains
must be a valid pointer to an array ofswapchainCount
SwapchainKHR
handles -
swapchainCount
must be greater than0
Host Synchronization
- Host access to
pCreateInfos
[].surface must be externally synchronized
- Host access to
pCreateInfos
[].oldSwapchain must be externally synchronized
Return Codes
See Also
AllocationCallbacks
,
Device
,
SwapchainCreateInfoKHR
,
SwapchainKHR
data DisplayPresentInfoKHR Source #
VkDisplayPresentInfoKHR - Structure describing parameters of a queue presentation to a swapchain
Description
If the extent of the srcRect
and dstRect
are not equal, the
presented pixels will be scaled accordingly.
Valid Usage
-
dstRect
must specify a rectangular region that is a subset of thevisibleRegion
parameter of the display mode the swapchain being presented uses - If the
persistentContent
member of theDisplayPropertiesKHR
structure returned bygetPhysicalDeviceDisplayPropertiesKHR
for the display the present operation targets thenpersistent
must beFALSE
Valid Usage (Implicit)
-
sType
must beSTRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR
See Also
DisplayPresentInfoKHR | |
|
Instances
type KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION = 10 Source #
pattern KHR_DISPLAY_SWAPCHAIN_SPEC_VERSION :: forall a. Integral a => a Source #
type KHR_DISPLAY_SWAPCHAIN_EXTENSION_NAME = "VK_KHR_display_swapchain" Source #
pattern KHR_DISPLAY_SWAPCHAIN_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a Source #
newtype SurfaceKHR Source #
VkSurfaceKHR - Opaque handle to a surface object
Description
The VK_KHR_surface
extension declares the SurfaceKHR
object, and
provides a function for destroying SurfaceKHR
objects. Separate
platform-specific extensions each provide a function for creating a
SurfaceKHR
object for the respective platform. From the application’s
perspective this is an opaque handle, just like the handles of other
Vulkan objects.
See Also
PhysicalDeviceSurfaceInfo2KHR
,
SwapchainCreateInfoKHR
,
createAndroidSurfaceKHR
,
createDirectFBSurfaceEXT
,
createDisplayPlaneSurfaceKHR
,
createHeadlessSurfaceEXT
,
createIOSSurfaceMVK
,
createImagePipeSurfaceFUCHSIA
,
createMacOSSurfaceMVK
,
createMetalSurfaceEXT
,
createStreamDescriptorSurfaceGGP
,
createViSurfaceNN
,
createWaylandSurfaceKHR
,
createWin32SurfaceKHR
,
createXcbSurfaceKHR
,
createXlibSurfaceKHR
,
destroySurfaceKHR
,
getDeviceGroupSurfacePresentModesKHR
,
getPhysicalDevicePresentRectanglesKHR
,
getPhysicalDeviceSurfaceCapabilities2EXT
,
getPhysicalDeviceSurfaceCapabilitiesKHR
,
getPhysicalDeviceSurfaceFormatsKHR
,
getPhysicalDeviceSurfacePresentModesKHR
,
getPhysicalDeviceSurfaceSupportKHR
Instances
newtype SwapchainKHR Source #
VkSwapchainKHR - Opaque handle to a swapchain object
Description
A swapchain is an abstraction for an array of presentable images that
are associated with a surface. The presentable images are represented by
Image
objects created by the platform. One image
(which can be an array image for multiview/stereoscopic-3D surfaces)
is displayed at a time, but multiple images can be queued for
presentation. An application renders to the image, and then queues the
image for presentation to the surface.
A native window cannot be associated with more than one non-retired swapchain at a time. Further, swapchains cannot be created for native windows that have a non-Vulkan graphics API surface associated with them.
Note
The presentation engine is an abstraction for the platform’s compositor or display engine.
The presentation engine may be synchronous or asynchronous with respect to the application and/or logical device.
Some implementations may use the device’s graphics queue or dedicated presentation hardware to perform presentation.
The presentable images of a swapchain are owned by the presentation
engine. An application can acquire use of a presentable image from the
presentation engine. Use of a presentable image must occur only after
the image is returned by
acquireNextImageKHR
, and before it
is presented by queuePresentKHR
.
This includes transitioning the image layout and rendering commands.
An application can acquire use of a presentable image with
acquireNextImageKHR
. After
acquiring a presentable image and before modifying it, the application
must use a synchronization primitive to ensure that the presentation
engine has finished reading from the image. The application can then
transition the image’s layout, queue rendering commands to it, etc.
Finally, the application presents the image with
queuePresentKHR
, which releases the
acquisition of the image.
The presentation engine controls the order in which presentable images are acquired for use by the application.
Note
This allows the platform to handle situations which require out-of-order return of images after presentation. At the same time, it allows the application to generate command buffers referencing all of the images in the swapchain at initialization time, rather than in its main loop.
See Also
AcquireNextImageInfoKHR
,
BindImageMemorySwapchainInfoKHR
,
ImageSwapchainCreateInfoKHR
,
PresentInfoKHR
,
SwapchainCreateInfoKHR
,
acquireFullScreenExclusiveModeEXT
,
acquireNextImageKHR
,
createSharedSwapchainsKHR
,
createSwapchainKHR
,
destroySwapchainKHR
,
getPastPresentationTimingGOOGLE
,
getRefreshCycleDurationGOOGLE
,
getSwapchainCounterEXT
,
getSwapchainImagesKHR
,
getSwapchainStatusKHR
,
releaseFullScreenExclusiveModeEXT
,
setHdrMetadataEXT
,
setLocalDimmingAMD
Instances
data SwapchainCreateInfoKHR (es :: [Type]) Source #
VkSwapchainCreateInfoKHR - Structure specifying parameters of a newly created swapchain object
Description
Note
On some platforms, it is normal that maxImageExtent
may become (0,
0)
, for example when the window is minimized. In such a case, it is not
possible to create a swapchain due to the Valid Usage requirements.
imageArrayLayers
is the number of views in a multiview/stereo surface. For non-stereoscopic-3D applications, this value is 1.imageUsage
is a bitmask ofImageUsageFlagBits
describing the intended usage of the (acquired) swapchain images.imageSharingMode
is the sharing mode used for the image(s) of the swapchain.queueFamilyIndexCount
is the number of queue families having access to the image(s) of the swapchain whenimageSharingMode
isSHARING_MODE_CONCURRENT
.pQueueFamilyIndices
is a pointer to an array of queue family indices having access to the images(s) of the swapchain whenimageSharingMode
isSHARING_MODE_CONCURRENT
.preTransform
is aSurfaceTransformFlagBitsKHR
value describing the transform, relative to the presentation engine’s natural orientation, applied to the image content prior to presentation. If it does not match thecurrentTransform
value returned bygetPhysicalDeviceSurfaceCapabilitiesKHR
, the presentation engine will transform the image content as part of the presentation operation.compositeAlpha
is aCompositeAlphaFlagBitsKHR
value indicating the alpha compositing mode to use when this surface is composited together with other surfaces on certain window systems.presentMode
is the presentation mode the swapchain will use. A swapchain’s present mode determines how incoming present requests will be processed and queued internally.clipped
specifies whether the Vulkan implementation is allowed to discard rendering operations that affect regions of the surface that are not visible.- If set to
TRUE
, the presentable images associated with the swapchain may not own all of their pixels. Pixels in the presentable images that correspond to regions of the target surface obscured by another window on the desktop, or subject to some other clipping mechanism will have undefined content when read back. Fragment shaders may not execute for these pixels, and thus any side effects they would have had will not occur.TRUE
value does not guarantee any clipping will occur, but allows more optimal presentation methods to be used on some platforms. - If set to
FALSE
, presentable images associated with the swapchain will own all of the pixels they contain.
- If set to
Note
Applications should set this value to
TRUE
if they do not expect to read back
the content of presentable images before presenting them or after
reacquiring them, and if their fragment shaders do not have any side
effects that require them to run for all pixels in the presentable
image.
oldSwapchain
isNULL_HANDLE
, or the existing non-retired swapchain currently associated withsurface
. Providing a validoldSwapchain
may aid in the resource reuse, and also allows the application to still present any images that are already acquired from it.
Upon calling createSwapchainKHR
with an oldSwapchain
that is not
NULL_HANDLE
, oldSwapchain
is
retired — even if creation of the new swapchain fails. The new swapchain
is created in the non-retired state whether or not oldSwapchain
is
NULL_HANDLE
.
Upon calling createSwapchainKHR
with an oldSwapchain
that is not
NULL_HANDLE
, any images from oldSwapchain
that are not acquired by the application may be freed by the
implementation, which may occur even if creation of the new swapchain
fails. The application can destroy oldSwapchain
to free all memory
associated with oldSwapchain
.
Note
Multiple retired swapchains can be associated with the same
SurfaceKHR
through multiple uses of
oldSwapchain
that outnumber calls to destroySwapchainKHR
.
After oldSwapchain
is retired, the application can pass to
queuePresentKHR
any images it had already acquired from
oldSwapchain
. E.g., an application may present an image from the old
swapchain before an image from the new swapchain is ready to be
presented. As usual, queuePresentKHR
may fail if oldSwapchain
has
entered a state that causes
ERROR_OUT_OF_DATE_KHR
to be returned.
The application can continue to use a shared presentable image
obtained from oldSwapchain
until a presentable image is acquired from
the new swapchain, as long as it has not entered a state that causes it
to return ERROR_OUT_OF_DATE_KHR
.
Valid Usage
-
surface
must be a surface that is supported by the device as determined usinggetPhysicalDeviceSurfaceSupportKHR
-
minImageCount
must be less than or equal to the value returned in themaxImageCount
member of theSurfaceCapabilitiesKHR
structure returned bygetPhysicalDeviceSurfaceCapabilitiesKHR
for the surface if the returnedmaxImageCount
is not zero - If
presentMode
is notPRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
norPRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
, thenminImageCount
must be greater than or equal to the value returned in theminImageCount
member of theSurfaceCapabilitiesKHR
structure returned bygetPhysicalDeviceSurfaceCapabilitiesKHR
for the surface -
minImageCount
must be1
ifpresentMode
is eitherPRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
orPRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
-
imageFormat
andimageColorSpace
must match theformat
andcolorSpace
members, respectively, of one of theSurfaceFormatKHR
structures returned bygetPhysicalDeviceSurfaceFormatsKHR
for the surface -
imageExtent
must be betweenminImageExtent
andmaxImageExtent
, inclusive, whereminImageExtent
andmaxImageExtent
are members of theSurfaceCapabilitiesKHR
structure returned bygetPhysicalDeviceSurfaceCapabilitiesKHR
for the surface -
imageExtent
memberswidth
andheight
must both be non-zero -
imageArrayLayers
must be greater than0
and less than or equal to themaxImageArrayLayers
member of theSurfaceCapabilitiesKHR
structure returned bygetPhysicalDeviceSurfaceCapabilitiesKHR
for the surface - If
presentMode
isPRESENT_MODE_IMMEDIATE_KHR
,PRESENT_MODE_MAILBOX_KHR
,PRESENT_MODE_FIFO_KHR
orPRESENT_MODE_FIFO_RELAXED_KHR
,imageUsage
must be a subset of the supported usage flags present in thesupportedUsageFlags
member of theSurfaceCapabilitiesKHR
structure returned bygetPhysicalDeviceSurfaceCapabilitiesKHR
forsurface
- If
presentMode
isPRESENT_MODE_SHARED_DEMAND_REFRESH_KHR
orPRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR
,imageUsage
must be a subset of the supported usage flags present in thesharedPresentSupportedUsageFlags
member of theSharedPresentSurfaceCapabilitiesKHR
structure returned bygetPhysicalDeviceSurfaceCapabilities2KHR
forsurface
- If
imageSharingMode
isSHARING_MODE_CONCURRENT
,pQueueFamilyIndices
must be a valid pointer to an array ofqueueFamilyIndexCount
uint32_t
values - If
imageSharingMode
isSHARING_MODE_CONCURRENT
,queueFamilyIndexCount
must be greater than1
- If
imageSharingMode
isSHARING_MODE_CONCURRENT
, each element ofpQueueFamilyIndices
must be unique and must be less thanpQueueFamilyPropertyCount
returned by eithergetPhysicalDeviceQueueFamilyProperties
orgetPhysicalDeviceQueueFamilyProperties2
for thephysicalDevice
that was used to createdevice
-
preTransform
must be one of the bits present in thesupportedTransforms
member of theSurfaceCapabilitiesKHR
structure returned bygetPhysicalDeviceSurfaceCapabilitiesKHR
for the surface -
compositeAlpha
must be one of the bits present in thesupportedCompositeAlpha
member of theSurfaceCapabilitiesKHR
structure returned bygetPhysicalDeviceSurfaceCapabilitiesKHR
for the surface -
presentMode
must be one of thePresentModeKHR
values returned bygetPhysicalDeviceSurfacePresentModesKHR
for the surface - If the
logical device was created with
DeviceGroupDeviceCreateInfo
::physicalDeviceCount
equal to 1,flags
must not containSWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR
- If
oldSwapchain
is notNULL_HANDLE
,oldSwapchain
must be a non-retired swapchain associated with native window referred to bysurface
- The
implied image creation parameters
of the swapchain must be supported as reported by
getPhysicalDeviceImageFormatProperties
- If
flags
containsSWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR
then thepNext
chain must include aImageFormatListCreateInfo
structure with aviewFormatCount
greater than zero andpViewFormats
must have an element equal toimageFormat
- If a
ImageFormatListCreateInfo
structure was included in thepNext
chain andImageFormatListCreateInfo
::viewFormatCount
is not zero then all of the formats inImageFormatListCreateInfo
::pViewFormats
must be compatible with theformat
as described in the compatibility table - If
flags
does not containSWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR
and thepNext
chain include aImageFormatListCreateInfo
structure thenImageFormatListCreateInfo
::viewFormatCount
must be0
or1
- If
flags
containsSWAPCHAIN_CREATE_PROTECTED_BIT_KHR
, thenSurfaceProtectedCapabilitiesKHR
::supportsProtected
must beTRUE
in theSurfaceProtectedCapabilitiesKHR
structure returned bygetPhysicalDeviceSurfaceCapabilities2KHR
forsurface
- If the
pNext
chain includes aSurfaceFullScreenExclusiveInfoEXT
structure with itsfullScreenExclusive
member set toFULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT
, andsurface
was created usingcreateWin32SurfaceKHR
, aSurfaceFullScreenExclusiveWin32InfoEXT
structure must be included in thepNext
chain
Valid Usage (Implicit)
-
sType
must beSTRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR
- Each
pNext
member of any structure (including this one) in thepNext
chain must be eitherNULL
or a pointer to a valid instance ofDeviceGroupSwapchainCreateInfoKHR
,ImageFormatListCreateInfo
,SurfaceFullScreenExclusiveInfoEXT
,SurfaceFullScreenExclusiveWin32InfoEXT
,SwapchainCounterCreateInfoEXT
, orSwapchainDisplayNativeHdrCreateInfoAMD
- The
sType
value of each struct in thepNext
chain must be unique -
flags
must be a valid combination ofSwapchainCreateFlagBitsKHR
values -
surface
must be a validSurfaceKHR
handle -
imageFormat
must be a validFormat
value -
imageColorSpace
must be a validColorSpaceKHR
value -
imageUsage
must be a valid combination ofImageUsageFlagBits
values -
imageUsage
must not be0
-
imageSharingMode
must be a validSharingMode
value -
preTransform
must be a validSurfaceTransformFlagBitsKHR
value -
compositeAlpha
must be a validCompositeAlphaFlagBitsKHR
value -
presentMode
must be a validPresentModeKHR
value - If
oldSwapchain
is notNULL_HANDLE
,oldSwapchain
must be a validSwapchainKHR
handle - If
oldSwapchain
is a valid handle, it must have been created, allocated, or retrieved fromsurface
- Both of
oldSwapchain
, andsurface
that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the sameInstance
See Also
Bool32
,
ColorSpaceKHR
,
CompositeAlphaFlagBitsKHR
,
Extent2D
,
Format
,
ImageUsageFlags
,
PresentModeKHR
,
SharingMode
,
StructureType
,
SurfaceKHR
,
SurfaceTransformFlagBitsKHR
,
SwapchainCreateFlagsKHR
, SwapchainKHR
,
createSharedSwapchainsKHR
,
createSwapchainKHR
SwapchainCreateInfoKHR | |
|
Instances
newtype PresentModeKHR Source #
VkPresentModeKHR - presentation mode supported for a surface
Description
The supported
ImageUsageFlagBits
of the
presentable images of a swapchain created for a surface may differ
depending on the presentation mode, and can be determined as per the
table below:
Presentation mode | Image usage flags |
---|---|
PRESENT_MODE_IMMEDIATE_KHR | SurfaceCapabilitiesKHR ::supportedUsageFlags |
PRESENT_MODE_MAILBOX_KHR | SurfaceCapabilitiesKHR ::supportedUsageFlags |
PRESENT_MODE_FIFO_KHR | SurfaceCapabilitiesKHR ::supportedUsageFlags |
PRESENT_MODE_FIFO_RELAXED_KHR | SurfaceCapabilitiesKHR ::supportedUsageFlags |
PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR | SharedPresentSurfaceCapabilitiesKHR ::sharedPresentSupportedUsageFlags |
PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR | SharedPresentSurfaceCapabilitiesKHR ::sharedPresentSupportedUsageFlags |
Presentable image usage queries
Note
For reference, the mode indicated by PRESENT_MODE_FIFO_KHR
is
equivalent to the behavior of {wgl|glX|egl}SwapBuffers with a swap
interval of 1, while the mode indicated by
PRESENT_MODE_FIFO_RELAXED_KHR
is equivalent to the behavior of
{wgl|glX}SwapBuffers with a swap interval of -1 (from the
{WGL|GLX}_EXT_swap_control_tear extensions).
See Also
SwapchainCreateInfoKHR
,
getPhysicalDeviceSurfacePresentModes2EXT
,
getPhysicalDeviceSurfacePresentModesKHR
pattern PRESENT_MODE_IMMEDIATE_KHR :: PresentModeKHR |
|
pattern PRESENT_MODE_MAILBOX_KHR :: PresentModeKHR |
|
pattern PRESENT_MODE_FIFO_KHR :: PresentModeKHR |
|
pattern PRESENT_MODE_FIFO_RELAXED_KHR :: PresentModeKHR |
|
pattern PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR :: PresentModeKHR |
|
pattern PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR :: PresentModeKHR |
|
Instances
newtype ColorSpaceKHR Source #
VkColorSpaceKHR - supported color space of the presentation engine
Description
Note
In the initial release of the VK_KHR_surface
and VK_KHR_swapchain
extensions, the token COLORSPACE_SRGB_NONLINEAR_KHR
was used. Starting
in the 2016-05-13 updates to the extension branches, matching release
1.0.13 of the core API specification, COLOR_SPACE_SRGB_NONLINEAR_KHR
is used instead for consistency with Vulkan naming rules. The older enum
is still available for backwards compatibility.
Note
In older versions of this extension COLOR_SPACE_DISPLAY_P3_LINEAR_EXT
was misnamed
COLOR_SPACE_DCI_P3_LINEAR_EXT
.
This has been updated to indicate that it uses RGB color encoding, not
XYZ. The old name is deprecated but is maintained for backwards
compatibility.
The color components of non-linear color space swap chain images must
have had the appropriate transfer function applied. The color space
selected for the swap chain image will not affect the processing of data
written into the image by the implementation. Vulkan requires that all
implementations support the sRGB transfer function by use of an SRGB
pixel format. Other transfer functions, such as SMPTE 170M or SMPTE2084,
can be performed by the application shader. This extension defines
enums for ColorSpaceKHR
that correspond to the following color spaces:
Name | Red Primary | Green Primary | Blue Primary | White-point | Transfer function |
---|---|---|---|---|---|
DCI-P3 | 1.000, 0.000 | 0.000, 1.000 | 0.000, 0.000 | 0.3333, 0.3333 | DCI P3 |
Display-P3 | 0.680, 0.320 | 0.265, 0.690 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | Display-P3 |
BT709 | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | ITU (SMPTE 170M) |
sRGB | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | sRGB |
extended sRGB | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | extended sRGB |
HDR10_ST2084 | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | ST2084 PQ |
DOLBYVISION | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | ST2084 PQ |
HDR10_HLG | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | HLG |
AdobeRGB | 0.640, 0.330 | 0.210, 0.710 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | AdobeRGB |
Color Spaces and Attributes
The transfer functions are described in the “Transfer Functions” chapter of the Khronos Data Format Specification.
Except Display-P3 OETF, which is:
[begin{aligned} E & = begin{cases} 1.055 times L^{1 over 2.4} - 0.055 & text{for} 0.0030186 leq L leq 1 -- 12.92 times L & text{for} 0 leq L < 0.0030186
pattern COLOR_SPACE_DISPLAY_P3_LINEAR_EXT :: ColorSpaceKHR |
|
pattern COLOR_SPACE_SRGB_NONLINEAR_KHR :: ColorSpaceKHR |
|
pattern COLOR_SPACE_DISPLAY_NATIVE_AMD :: ColorSpaceKHR |
|
pattern COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT :: ColorSpaceKHR |
|
pattern COLOR_SPACE_PASS_THROUGH_EXT :: ColorSpaceKHR |
|
pattern COLOR_SPACE_ADOBERGB_NONLINEAR_EXT :: ColorSpaceKHR |
|
pattern COLOR_SPACE_ADOBERGB_LINEAR_EXT :: ColorSpaceKHR |
|
pattern COLOR_SPACE_HDR10_HLG_EXT :: ColorSpaceKHR |
|
pattern COLOR_SPACE_DOLBYVISION_EXT :: ColorSpaceKHR |
|
pattern COLOR_SPACE_HDR10_ST2084_EXT :: ColorSpaceKHR |
|
pattern COLOR_SPACE_BT2020_LINEAR_EXT :: ColorSpaceKHR |
|
pattern COLOR_SPACE_BT709_NONLINEAR_EXT :: ColorSpaceKHR |
|
pattern COLOR_SPACE_BT709_LINEAR_EXT :: ColorSpaceKHR |
|
pattern COLOR_SPACE_DCI_P3_NONLINEAR_EXT :: ColorSpaceKHR |
|
pattern COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT :: ColorSpaceKHR |
|
pattern COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT :: ColorSpaceKHR |
|
Instances
newtype CompositeAlphaFlagBitsKHR Source #
VkCompositeAlphaFlagBitsKHR - alpha compositing modes supported on a device
Description
These values are described as follows:
See Also
pattern COMPOSITE_ALPHA_OPAQUE_BIT_KHR :: CompositeAlphaFlagBitsKHR |
|
pattern COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR :: CompositeAlphaFlagBitsKHR |
|
pattern COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR :: CompositeAlphaFlagBitsKHR |
|
pattern COMPOSITE_ALPHA_INHERIT_BIT_KHR :: CompositeAlphaFlagBitsKHR |
|
Instances
newtype SurfaceTransformFlagBitsKHR Source #
VkSurfaceTransformFlagBitsKHR - presentation transforms supported on a device
See Also
CommandBufferInheritanceRenderPassTransformInfoQCOM
,
CopyCommandTransformInfoQCOM
,
DisplaySurfaceCreateInfoKHR
,
RenderPassTransformBeginInfoQCOM
,
SurfaceCapabilities2EXT
,
SurfaceCapabilitiesKHR
, SurfaceTransformFlagsKHR
,
SwapchainCreateInfoKHR
Instances
newtype SwapchainCreateFlagBitsKHR Source #
VkSwapchainCreateFlagBitsKHR - Bitmask controlling swapchain creation
See Also
pattern SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR :: SwapchainCreateFlagBitsKHR |
|
pattern SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR :: SwapchainCreateFlagBitsKHR |
|
pattern SWAPCHAIN_CREATE_PROTECTED_BIT_KHR :: SwapchainCreateFlagBitsKHR |
|