Vulkan.Extensions.VK_KHR_display_swapchain

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 being modified. 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 valid Device handle

• pCreateInfos must be a valid pointer to an array of swapchainCount valid SwapchainCreateInfoKHR structures

• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks structure

• pSwapchains must be a valid pointer to an array of swapchainCount SwapchainKHR handles

• The device must have been created with at least 1 queue

• swapchainCount must be greater than 0

Return Codes

Success

• SUCCESS

Failure

• ERROR_DEVICE_LOST

• ERROR_INCOMPATIBLE_DISPLAY_KHR

• ERROR_OUT_OF_DEVICE_MEMORY

• ERROR_OUT_OF_HOST_MEMORY

• ERROR_SURFACE_LOST_KHR

• ERROR_UNKNOWN

• ERROR_VALIDATION_FAILED

See Also

VK_KHR_display_swapchain, AllocationCallbacks, Device, SwapchainCreateInfoKHR, SwapchainKHR

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

• srcRect must specify a rectangular region that is a subset of the image being presented

• dstRect must specify a rectangular region that is a subset of the visibleRegion parameter of the display mode the swapchain being presented uses

• If the persistentContent member of the DisplayPropertiesKHR structure returned by getPhysicalDeviceDisplayPropertiesKHR for the display the present operation targets is FALSE, then persistent must be FALSE

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_DISPLAY_PRESENT_INFO_KHR

Structure Chaining

Extends the structure

• PresentInfoKHR

See Also

VK_KHR_display_swapchain, Bool32, Rect2D, StructureType

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

VK_DEFINE_NON_DISPATCHABLE_HANDLE, VK_KHR_surface, PhysicalDeviceSurfaceInfo2KHR, SwapchainCreateInfoKHR, createAndroidSurfaceKHR, createDirectFBSurfaceEXT, createDisplayPlaneSurfaceKHR, createHeadlessSurfaceEXT, createIOSSurfaceMVK, createImagePipeSurfaceFUCHSIA, createMacOSSurfaceMVK, createMetalSurfaceEXT, createScreenSurfaceQNX, createStreamDescriptorSurfaceGGP, vkCreateSurfaceOHOS, vkCreateUbmSurfaceSEC, createViSurfaceNN, createWaylandSurfaceKHR, createWin32SurfaceKHR, createXcbSurfaceKHR, createXlibSurfaceKHR, destroySurfaceKHR, getDeviceGroupSurfacePresentModesKHR, getPhysicalDevicePresentRectanglesKHR, getPhysicalDeviceSurfaceCapabilities2EXT, getPhysicalDeviceSurfaceCapabilitiesKHR, getPhysicalDeviceSurfaceFormatsKHR, getPhysicalDeviceSurfacePresentModesKHR, getPhysicalDeviceSurfaceSupportKHR

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.

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 released 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 application can also release the acquisition of the image through releaseSwapchainImagesKHR, if the image is not in use by the device, and skip the present operation.

The presentation engine controls the order in which presentable images are acquired for use by the application.

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

VK_DEFINE_NON_DISPATCHABLE_HANDLE, VK_KHR_swapchain, AcquireNextImageInfoKHR, BindImageMemorySwapchainInfoKHR, ImageSwapchainCreateInfoKHR, PastPresentationTimingInfoEXT, PresentInfoKHR, ReleaseSwapchainImagesInfoKHR, SwapchainCalibratedTimestampInfoEXT, SwapchainCreateInfoKHR, acquireFullScreenExclusiveModeEXT, acquireNextImageKHR, createSharedSwapchainsKHR, createSwapchainKHR, destroySwapchainKHR, getLatencyTimingsNV, getPastPresentationTimingGOOGLE, getRefreshCycleDurationGOOGLE, getSwapchainCounterEXT, getSwapchainImagesKHR, getSwapchainStatusKHR, getSwapchainTimeDomainPropertiesEXT, getSwapchainTimingPropertiesEXT, latencySleepNV, queuePresentKHR, releaseFullScreenExclusiveModeEXT, setHdrMetadataEXT, setLatencyMarkerNV, setLatencySleepModeNV, setLocalDimmingAMD, setSwapchainPresentTimingQueueSizeEXT, waitForPresent2KHR, waitForPresentKHR

VkSwapchainCreateInfoKHR - Structure specifying parameters of a newly created swapchain object

Description

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.

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 using getPhysicalDeviceSurfaceSupportKHR

• minImageCount must be less than or equal to the value returned in the maxImageCount member of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for the surface if the returned maxImageCount is not zero

• If the swapchainMaintenance1 feature is not enabled, then the pNext chain must not include a SwapchainPresentModesCreateInfoKHR structure

• If presentMode is not PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR nor PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, then minImageCount must be greater than or equal to the value returned in the minImageCount member of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for the surface

• minImageCount must be 1 if presentMode is either PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR

• imageFormat and imageColorSpace must match the format and colorSpace members, respectively, of one of the SurfaceFormatKHR structures returned by getPhysicalDeviceSurfaceFormatsKHR for the surface

• If a SwapchainPresentScalingCreateInfoKHR structure was not included in the pNext chain, or it is included and SwapchainPresentScalingCreateInfoKHR::scalingBehavior is zero then imageExtent must be between minImageExtent and maxImageExtent, inclusive, where minImageExtent and maxImageExtent are members of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for the surface

• If a SwapchainPresentScalingCreateInfoKHR structure was included in the pNext chain and SwapchainPresentScalingCreateInfoKHR::scalingBehavior is not zero then imageExtent must be between minScaledImageExtent and maxScaledImageExtent, inclusive, where minScaledImageExtent and maxScaledImageExtent are members of the SurfacePresentScalingCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilities2KHR for the surface and presentMode

• If the swapchainMaintenance1 feature is not enabled, then flags must not include SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_KHR

• imageExtent members width and height must both be non-zero

• imageArrayLayers must be greater than 0 and less than or equal to the maxImageArrayLayers member of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for the surface

• If presentMode is PRESENT_MODE_FIFO_LATEST_READY_KHR, PRESENT_MODE_IMMEDIATE_KHR, PRESENT_MODE_MAILBOX_KHR, PRESENT_MODE_FIFO_KHR or PRESENT_MODE_FIFO_RELAXED_KHR, imageUsage must be a subset of the supported usage flags present in the supportedUsageFlags member of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for surface

• If presentMode is PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR, imageUsage must be a subset of the supported usage flags present in the sharedPresentSupportedUsageFlags member of the SharedPresentSurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilities2KHR for surface

• If imageSharingMode is SHARING_MODE_CONCURRENT, pQueueFamilyIndices must be a valid pointer to an array of queueFamilyIndexCount uint32_t values

• If imageSharingMode is SHARING_MODE_CONCURRENT, queueFamilyIndexCount must be greater than 1

• If imageSharingMode is SHARING_MODE_CONCURRENT, each element of pQueueFamilyIndices must be unique and must be less than pQueueFamilyPropertyCount returned by either getPhysicalDeviceQueueFamilyProperties or getPhysicalDeviceQueueFamilyProperties2 for the physicalDevice that was used to create device

• preTransform must be one of the bits present in the supportedTransforms member of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for the surface

• compositeAlpha must be one of the bits present in the supportedCompositeAlpha member of the SurfaceCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilitiesKHR for the surface

• presentMode must be one of the PresentModeKHR values returned by getPhysicalDeviceSurfacePresentModesKHR for the surface

• If the presentModeFifoLatestReady feature is not enabled, presentMode must not be PRESENT_MODE_FIFO_LATEST_READY_KHR

• If the logical device was created with DeviceGroupDeviceCreateInfo::physicalDeviceCount equal to 1, flags must not contain SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR

• If oldSwapchain is not NULL_HANDLE, oldSwapchain must be a non-retired swapchain associated with native window referred to by surface

• The implied image creation parameters of the swapchain must be supported as reported by getPhysicalDeviceImageFormatProperties

• If flags contains SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR then the pNext chain must include a ImageFormatListCreateInfo structure with a viewFormatCount greater than zero and pViewFormats must have an element equal to imageFormat

• If a ImageFormatListCreateInfo structure was included in the pNext chain and ImageFormatListCreateInfo::viewFormatCount is not zero then all of the formats in ImageFormatListCreateInfo::pViewFormats must be compatible with the format as described in the compatibility table

• If flags does not contain SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR and the pNext chain include a ImageFormatListCreateInfo structure then ImageFormatListCreateInfo::viewFormatCount must be 0 or 1

• If flags contains SWAPCHAIN_CREATE_PROTECTED_BIT_KHR, then SurfaceProtectedCapabilitiesKHR::supportsProtected must be TRUE in the SurfaceProtectedCapabilitiesKHR structure returned by getPhysicalDeviceSurfaceCapabilities2KHR for surface

• If the pNext chain includes a SurfaceFullScreenExclusiveInfoEXT structure with its fullScreenExclusive member set to FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT, and surface was created using createWin32SurfaceKHR, a SurfaceFullScreenExclusiveWin32InfoEXT structure must be included in the pNext chain

• If the imageCompressionControlSwapchain feature is not enabled, the pNext chain must not include an ImageCompressionControlEXT structure

• If none of the presentTiming, presentAtAbsoluteTime, or presentAtRelativeTime features are enabled, flags must not contain SWAPCHAIN_CREATE_PRESENT_TIMING_BIT_EXT

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR

• Each pNext member of any structure (including this one) in the pNext chain must be either NULL or a pointer to a valid instance of DeviceGroupSwapchainCreateInfoKHR, ImageCompressionControlEXT, ImageFormatListCreateInfo, SurfaceFullScreenExclusiveInfoEXT, SurfaceFullScreenExclusiveWin32InfoEXT, SwapchainCounterCreateInfoEXT, SwapchainDisplayNativeHdrCreateInfoAMD, SwapchainLatencyCreateInfoNV, SwapchainPresentBarrierCreateInfoNV, SwapchainPresentModesCreateInfoKHR, or SwapchainPresentScalingCreateInfoKHR

• The sType value of each structure in the pNext chain must be unique

• flags must be a valid combination of SwapchainCreateFlagBitsKHR values

• surface must be a valid SurfaceKHR handle

• imageFormat must be a valid Format value

• imageColorSpace must be a valid ColorSpaceKHR value

• imageUsage must be a valid combination of ImageUsageFlagBits values

• imageUsage must not be 0

• imageSharingMode must be a valid SharingMode value

• preTransform must be a valid SurfaceTransformFlagBitsKHR value

• compositeAlpha must be a valid CompositeAlphaFlagBitsKHR value

• presentMode must be a valid PresentModeKHR value

• If oldSwapchain is not NULL_HANDLE, oldSwapchain must be a valid SwapchainKHR handle

• Both of oldSwapchain, and surface that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Instance

Host Synchronization

• Host access to surface must be externally synchronized

• Host access to oldSwapchain must be externally synchronized

See Also

VK_KHR_swapchain, Bool32, ColorSpaceKHR, CompositeAlphaFlagBitsKHR, Extent2D, Format, ImageUsageFlags, PresentModeKHR, SharingMode, StructureType, SurfaceKHR, SurfaceTransformFlagBitsKHR, SwapchainCreateFlagsKHR, SwapchainKHR, createSharedSwapchainsKHR, createSwapchainKHR

VkPresentModeKHR - Presentation mode supported for a surface

Description

• PRESENT_MODE_IMMEDIATE_KHR specifies that the presentation engine does not wait for a vertical blanking period to update the current image, meaning this mode may result in visible tearing. No internal queuing of presentation requests is needed, as the requests are applied immediately.

• PRESENT_MODE_MAILBOX_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot 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. One request is removed from the queue and processed during each vertical blanking period in which the queue is non-empty.

• PRESENT_MODE_FIFO_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue 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. This is the only value of presentMode that is required to be supported.

• PRESENT_MODE_FIFO_RELAXED_KHR specifies that the presentation engine generally waits for the next vertical blanking period to update the current image. If a vertical blanking period has already passed since the last update of the current image then the presentation engine does not wait for another vertical blanking period for the update, meaning this mode may result in visible tearing in this case. This mode is useful for reducing visual stutter with an application that will mostly present a new image before the next vertical blanking period, but may occasionally be late, and present a new image just after the next vertical blanking period. An internal queue 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 or after each vertical blanking period in which the queue is non-empty.

• PRESENT_MODE_FIFO_LATEST_READY_KHR specifies that the presentation engine waits for the next vertical blanking period to update the current image. Tearing cannot be observed. An internal queue is used to hold pending presentation requests. New requests are appended to the end of the queue. At each vertical blanking period, the presentation engine dequeues all successive requests that are ready to be presented from the beginning of the queue. If using the VK_GOOGLE_display_timing extension or the presentAtAbsoluteTime feature to provide a target present time, the presentation engine checks the specified time for each image. If the target present time is less-than or equal-to the current time, the presentation engine dequeues the image and checks the next one. The image of the last dequeued request is presented. The other dequeued requests are dropped.

• PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine is only required to update the current image after a new presentation request is received. Therefore the application must make a presentation request whenever an update is required. However, the presentation engine may update the current image at any point, meaning this mode may result in visible tearing.

• PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR specifies that the presentation engine and application have concurrent access to a single image, which is referred to as a shared presentable image. The presentation engine periodically updates the current image on its regular refresh cycle. The application is only required to make one initial presentation request, after which the presentation engine must update the current image without any need for further presentation requests. The application can indicate the image contents have been updated by making a presentation request, but this does not guarantee the timing of when it will be updated. This mode may result in visible tearing if rendering to the image is not timed correctly.

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:

Presentable Image Usage Queries

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

VK_KHR_surface, LatencySurfaceCapabilitiesNV, SurfacePresentModeCompatibilityKHR, SurfacePresentModeKHR, SwapchainCreateInfoKHR, SwapchainPresentModeInfoKHR, SwapchainPresentModesCreateInfoKHR, getPhysicalDeviceSurfacePresentModes2EXT, getPhysicalDeviceSurfacePresentModesKHR

VkColorSpaceKHR - Supported color space of the presentation engine

Description

• COLOR_SPACE_SRGB_NONLINEAR_KHR specifies support for the images in sRGB color space, encoded according to the sRGB specification.

• COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT specifies support for the images in Display-P3 color space, encoded using a Display-P3 transfer function.

• COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT specifies support for the images in extended sRGB color space, encoded using a linear transfer function.

• COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT specifies support for the images in extended sRGB color space, encoded according to the scRGB specification.

• COLOR_SPACE_DISPLAY_P3_LINEAR_EXT specifies support for the images in Display-P3 color space, encoded using a linear transfer function.

• COLOR_SPACE_DCI_P3_NONLINEAR_EXT specifies support for the images in DCI-P3 color space, encoded according to the DCI-P3 specification. Note that values in such an image are interpreted as XYZ encoded color data by the presentation engine.

• COLOR_SPACE_BT709_LINEAR_EXT specifies support for the images in BT709 color space, encoded using a linear transfer function.

• COLOR_SPACE_BT709_NONLINEAR_EXT specifies support for the images in BT709 color space, encoded according to the BT709 specification.

• COLOR_SPACE_BT2020_LINEAR_EXT specifies support for the images in BT2020 color space, encoded using a linear transfer function.

• COLOR_SPACE_HDR10_ST2084_EXT specifies support for the images in HDR10 (BT2020) color space, encoded according to SMPTE ST2084 Perceptual Quantizer (PQ) specification.

• COLOR_SPACE_HDR10_HLG_EXT specifies support for the images in HDR10 (BT2020) color space, encoded according to the Hybrid Log Gamma (HLG) specification.

• COLOR_SPACE_ADOBERGB_LINEAR_EXT specifies support for images in Adobe RGB color space, encoded using a linear transfer function.

• COLOR_SPACE_ADOBERGB_NONLINEAR_EXT specifies support for the images in Adobe RGB color space, encoded according to the Adobe RGB specification (approximately Gamma 2.2).

• COLOR_SPACE_PASS_THROUGH_EXT specifies that color components are used “as is”. This is intended to allow applications to supply data for color spaces not described here.

• COLOR_SPACE_DISPLAY_NATIVE_AMD specifies support for the display’s native color space. This matches the color space expectations of AMD’s FreeSync2 standard, for displays supporting it.

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.

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 legacy but is maintained for backwards compatibility.

In older versions of the VK_EXT_swapchain_colorspace extension, COLOR_SPACE_DOLBYVISION_EXT was exposed. The intent was to indicate the presentation engine shall decode an image using the SMPTE ST 2084 Perceptual Quantizer (PQ) EOTF, and then apply a proprietary OOTF to process the image. However, Dolby Vision profile 8.4 describes an encoding using the Hybrid Log Gamma (HLG) OETF, and there is no swapchain extension for signaling Dolby Vision metadata to be used by a proprietary OOTF. This enum is legacy but is maintained for backwards compatibility.

For a traditional “Linear” or non-gamma transfer function color space use COLOR_SPACE_PASS_THROUGH_EXT.

On Wayland, COLOR_SPACE_PASS_THROUGH_EXT can be used to disable color management by the WSI on a surface, which makes it possible for the application to create a wp_color_management_surface_v1 object without triggering a surface_exists protocol error.

See createWaylandSurfaceKHR

The presentation engine interprets the pixel values of the R, G, and B components as having been encoded using an appropriate transfer function. Applications should ensure that the appropriate transfer function has been applied. Texel encode requires that all implementations implicitly apply the sRGB EOTF-1 on R, G, and B components when shaders write to an sRGB pixel format image, which is useful for sRGB color spaces. For sRGB color spaces with other pixel formats, or other non-linear color spaces, applications can apply the transfer function explicitly in a shader. The A channel is always interpreted as linearly encoded.

This extension defines enums for ColorSpaceKHR that correspond to the following color spaces:

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

VkCompositeAlphaFlagBitsKHR - Alpha compositing modes supported on a device

Description

These values are described as follows:

• COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha component, if it exists, of the images is ignored in the compositing process. Instead, the image is treated as if it has a constant alpha of 1.0.

• COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are expected to already be multiplied by the alpha component by the application.

• COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha component, if it exists, of the images is respected in the compositing process. The non-alpha components of the image are not expected to already be multiplied by the alpha component by the application; instead, the compositor will multiply the non-alpha components of the image by the alpha component during compositing.

• COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the presentation engine treats the alpha component in the images is unknown to the Vulkan API. Instead, the application is responsible for setting the composite alpha blending mode using native window system commands. If the application does not set the blending mode using native window system commands, then a platform-specific default will be used.

See Also

VK_KHR_surface, CompositeAlphaFlagsKHR, SwapchainCreateInfoKHR

VkSurfaceTransformFlagBitsKHR - Presentation transforms supported on a device

Description

• SURFACE_TRANSFORM_IDENTITY_BIT_KHR specifies that image content is presented without being transformed.

• SURFACE_TRANSFORM_ROTATE_90_BIT_KHR specifies that image content is rotated 90 degrees clockwise.

• SURFACE_TRANSFORM_ROTATE_180_BIT_KHR specifies that image content is rotated 180 degrees clockwise.

• SURFACE_TRANSFORM_ROTATE_270_BIT_KHR specifies that image content is rotated 270 degrees clockwise.

• SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR specifies that image content is mirrored horizontally.

• SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR specifies that image content is mirrored horizontally, then rotated 90 degrees clockwise.

• SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR specifies that image content is mirrored horizontally, then rotated 180 degrees clockwise.

• SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR specifies that image content is mirrored horizontally, then rotated 270 degrees clockwise.

• SURFACE_TRANSFORM_INHERIT_BIT_KHR specifies that the presentation transform is not specified, and is instead determined by platform-specific considerations and mechanisms outside Vulkan.

See Also

VK_KHR_surface, CommandBufferInheritanceRenderPassTransformInfoQCOM, CopyCommandTransformInfoQCOM, DisplaySurfaceCreateInfoKHR, RenderPassTransformBeginInfoQCOM, SurfaceCapabilities2EXT, SurfaceCapabilitiesKHR, SurfaceTransformFlagsKHR, SwapchainCreateInfoKHR

VkSwapchainCreateFlagBitsKHR - Bitmask controlling swapchain creation

Description

• SWAPCHAIN_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT_KHR specifies that images created from the swapchain (i.e. with the swapchain member of ImageSwapchainCreateInfoKHR set to this swapchain’s handle) must use IMAGE_CREATE_SPLIT_INSTANCE_BIND_REGIONS_BIT.

• SWAPCHAIN_CREATE_PROTECTED_BIT_KHR specifies that images created from the swapchain are protected images.

• SWAPCHAIN_CREATE_MUTABLE_FORMAT_BIT_KHR specifies that the images of the swapchain can be used to create a ImageView with a different format than what the swapchain was created with. The list of allowed image view formats is specified by adding a ImageFormatListCreateInfo structure to the pNext chain of SwapchainCreateInfoKHR. In addition, this flag also specifies that the swapchain can be created with usage flags that are not supported for the format the swapchain is created with but are supported for at least one of the allowed image view formats.

• SWAPCHAIN_CREATE_DEFERRED_MEMORY_ALLOCATION_BIT_KHR specifies that the implementation may defer allocation of memory associated with each swapchain image until its index is to be returned from acquireNextImageKHR or acquireNextImage2KHR for the first time.

• SWAPCHAIN_CREATE_PRESENT_ID_2_BIT_KHR specifies that applications can include the PresentId2KHR structure in the pNext chain of the PresentInfoKHR structure to associate an identifier with each presentation request.

• SWAPCHAIN_CREATE_PRESENT_WAIT_2_BIT_KHR specifies that applications can use waitForPresent2KHR to wait for the presentation engine to have begun presentation of the presentation request associated with PresentWait2InfoKHR::presentId on swapchain.

• SWAPCHAIN_CREATE_PRESENT_TIMING_BIT_EXT specifies that features supported by the swapchain device in PhysicalDevicePresentTimingFeaturesEXT can be used to collect timing information or schedule presentation requests at specific times.

See Also

VK_KHR_swapchain, SwapchainCreateFlagsKHR