VkColorSpaceKHR - supported color space of the presentation engine

Description

• VK_COLOR_SPACE_SRGB_NONLINEAR_KHR specifies support for the sRGB color space.

• VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT specifies support for the Display-P3 color space and applies an sRGB-like transfer function (defined below).
• VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT specifies support for the extended sRGB color space and applies a linear transfer function.
• VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT specifies support for the extended sRGB color space and applies an sRGB transfer function.
• VK_COLOR_SPACE_DCI_P3_LINEAR_EXT specifies support for the DCI-P3 color space and applies a linear OETF.
• VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT specifies support for the DCI-P3 color space and applies the Gamma 2.6 OETF.
• VK_COLOR_SPACE_BT709_LINEAR_EXT specifies support for the BT709 color space and applies a linear OETF.
• VK_COLOR_SPACE_BT709_NONLINEAR_EXT specifies support for the BT709 color space and applies the SMPTE 170M OETF.
• VK_COLOR_SPACE_BT2020_LINEAR_EXT specifies support for the BT2020 color space and applies a linear OETF.
• VK_COLOR_SPACE_HDR10_ST2084_EXT specifies support for the HDR10 (BT2020 color) space and applies the SMPTE ST2084 Perceptual Quantizer (PQ) OETF.
• VK_COLOR_SPACE_DOLBYVISION_EXT specifies support for the Dolby Vision (BT2020 color space), proprietary encoding, and applies the SMPTE ST2084 OETF.
• VK_COLOR_SPACE_HDR10_HLG_EXT specifies support for the HDR10 (BT2020 color space) and applies the Hybrid Log Gamma (HLG) OETF.
• VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT specifies support for the AdobeRGB color space and applies a linear OETF.
• VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT specifies support for the AdobeRGB color space and applies the Gamma 2.2 OETF.
• VK_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.

The color components of Non-linear color space swap chain images have had the appropriate transfer function applied. Vulkan requires that all implementations support the sRGB transfer function when using an SRGB pixel format. Other transfer functions, such as SMPTE 170M or SMPTE2084, must not be performed by the implementation, but can be performed by the application shader. This extension defines enums for VkColorSpaceKHR that correspond to the following color spaces:

Color Spaces and Attributes

For Opto-Electrical Transfer Function (OETF), unless otherwise specified, the values of L and E are defined as:

L - linear luminance of image \(0 \leq L \leq 1\) for conventional colorimetry

E - corresponding electrical signal (value stored in memory)

See Also

VkSurfaceFormatKHR, VkSwapchainCreateInfoKHR

VkPresentModeKHR - presentation mode supported for a surface

Description

• VK_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.

• VK_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 re-use by the application. One request is removed from the queue and processed during each vertical blanking period in which the queue is non-empty.
• VK_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.
• VK_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.
• VK_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.
• VK_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 VkImageUsageFlagBits 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

Note

For reference, the mode indicated by VK_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 VK_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

VkSwapchainCreateInfoKHR, vkGetPhysicalDeviceSurfacePresentModesKHR

VkCompositeAlphaFlagBitsKHR - alpha compositing modes supported on a device

Description

These values are described as follows:

• VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha channel, 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.
• VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha channel, if it exists, of the images is respected in the compositing process. The non-alpha channels of the image are expected to already be multiplied by the alpha channel by the application.
• VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha channel, if it exists, of the images is respected in the compositing process. The non-alpha channels of the image are not expected to already be multiplied by the alpha channel by the application; instead, the compositor will multiply the non-alpha channels of the image by the alpha channel during compositing.
• VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the presentation engine treats the alpha channel 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

VkCompositeAlphaFlagsKHR, VkSwapchainCreateInfoKHR

VkSurfaceTransformFlagBitsKHR - presentation transforms supported on a device

See Also

VkDisplaySurfaceCreateInfoKHR, VkSurfaceCapabilities2EXT, VkSurfaceCapabilitiesKHR, VkSurfaceTransformFlagsKHR, VkSwapchainCreateInfoKHR

VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR specifies that image content is presented without being transformed.

VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR specifies that image content is rotated 90 degrees clockwise.

VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR specifies that image content is rotated 180 degrees clockwise.

VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR specifies that image content is rotated 270 degrees clockwise.

VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR specifies that image content is mirrored horizontally.

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

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

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

VK_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.

VkSurfaceKHR - Opaque handle to a surface object

Description

The VK_KHR_surface extension declares the VkSurfaceKHR object, and provides a function for destroying VkSurfaceKHR objects. Separate platform-specific extensions each provide a function for creating a VkSurfaceKHR 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

VkPhysicalDeviceSurfaceInfo2KHR, VkSwapchainCreateInfoKHR, vkCreateAndroidSurfaceKHR, vkCreateDisplayPlaneSurfaceKHR, vkCreateIOSSurfaceMVK, vkCreateMacOSSurfaceMVK, vkCreateMirSurfaceKHR, vkCreateViSurfaceNN, vkCreateWaylandSurfaceKHR, vkCreateWin32SurfaceKHR, vkCreateXcbSurfaceKHR, vkCreateXlibSurfaceKHR, vkDestroySurfaceKHR, vkGetDeviceGroupSurfacePresentModesKHR, vkGetPhysicalDevicePresentRectanglesKHR, vkGetPhysicalDeviceSurfaceCapabilities2EXT, vkGetPhysicalDeviceSurfaceCapabilitiesKHR, vkGetPhysicalDeviceSurfaceFormatsKHR, vkGetPhysicalDeviceSurfacePresentModesKHR, vkGetPhysicalDeviceSurfaceSupportKHR

vkDestroySurfaceKHR - Destroy a VkSurfaceKHR object

Parameters

• instance is the instance used to create the surface.

• surface is the surface to destroy.
• pAllocator is the allocator used for host memory allocated for the surface object when there is no more specific allocator available (see Memory Allocation).

Description

Destroying a VkSurfaceKHR merely severs the connection between Vulkan and the native surface, and does not imply destroying the native surface, closing a window, or similar behavior.

Valid Usage

• All VkSwapchainKHR objects created for surface must have been destroyed prior to destroying surface

• If VkAllocationCallbacks were provided when surface was created, a compatible set of callbacks must be provided here
• If no VkAllocationCallbacks were provided when surface was created, pAllocator must be NULL

Valid Usage (Implicit)

• instance must be a valid VkInstance handle

• If surface is not VK_NULL_HANDLE, surface must be a valid VkSurfaceKHR handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure
• If surface is a valid handle, it must have been created, allocated, or retrieved from instance

Host Synchronization

• Host access to surface must be externally synchronized

See Also

VkAllocationCallbacks, VkInstance, VkSurfaceKHR

vkGetPhysicalDeviceSurfaceSupportKHR - Query if presentation is supported

Parameters

• physicalDevice is the physical device.

• queueFamilyIndex is the queue family.
• surface is the surface.
• pSupported is a pointer to a VkBool32, which is set to VK_TRUE to indicate support, and VK_FALSE otherwise.

Valid Usage

• queueFamilyIndex must be less than pQueueFamilyPropertyCount returned by vkGetPhysicalDeviceQueueFamilyProperties for the given physicalDevice

Valid Usage (Implicit)

• physicalDevice must be a valid VkPhysicalDevice handle

• surface must be a valid VkSurfaceKHR handle
• pSupported must be a valid pointer to a VkBool32 value
• Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same VkInstance

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_SURFACE_LOST_KHR

See Also

VkBool32, VkPhysicalDevice, VkSurfaceKHR

vkGetPhysicalDeviceSurfaceCapabilitiesKHR - Query surface capabilities

Parameters

• physicalDevice is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR.

• surface is the surface that will be associated with the swapchain.
• pSurfaceCapabilities is a pointer to an instance of the VkSurfaceCapabilitiesKHR structure in which the capabilities are returned.

Valid Usage (Implicit)

• physicalDevice must be a valid VkPhysicalDevice handle

• surface must be a valid VkSurfaceKHR handle
• pSurfaceCapabilities must be a valid pointer to a VkSurfaceCapabilitiesKHR structure
• Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same VkInstance

Return Codes

[Success] - VK_SUCCESS

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_SURFACE_LOST_KHR

See Also

VkPhysicalDevice, VkSurfaceCapabilitiesKHR, VkSurfaceKHR

vkGetPhysicalDeviceSurfaceFormatsKHR - Query color formats supported by surface

Parameters

• physicalDevice is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR.

• surface is the surface that will be associated with the swapchain.
• pSurfaceFormatCount is a pointer to an integer related to the number of format pairs available or queried, as described below.
• pSurfaceFormats is either NULL or a pointer to an array of VkSurfaceFormatKHR structures.

Description

If pSurfaceFormats is NULL, then the number of format pairs supported for the given surface is returned in pSurfaceFormatCount. The number of format pairs supported will be greater than or equal to 1. Otherwise, pSurfaceFormatCount must point to a variable set by the user to the number of elements in the pSurfaceFormats array, and on return the variable is overwritten with the number of structures actually written to pSurfaceFormats. If the value of pSurfaceFormatCount is less than the number of format pairs supported, at most pSurfaceFormatCount structures will be written. If pSurfaceFormatCount is smaller than the number of format pairs supported for the given surface, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

Valid Usage (Implicit)

• physicalDevice must be a valid VkPhysicalDevice handle

• surface must be a valid VkSurfaceKHR handle
• pSurfaceFormatCount must be a valid pointer to a uint32_t value
• If the value referenced by pSurfaceFormatCount is not 0, and pSurfaceFormats is not NULL, pSurfaceFormats must be a valid pointer to an array of pSurfaceFormatCount VkSurfaceFormatKHR structures
• Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same VkInstance

Return Codes

[Success] - VK_SUCCESS

• VK_INCOMPLETE

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_SURFACE_LOST_KHR

See Also

VkPhysicalDevice, VkSurfaceFormatKHR, VkSurfaceKHR

vkGetPhysicalDeviceSurfacePresentModesKHR - Query supported presentation modes

Parameters

• physicalDevice is the physical device that will be associated with the swapchain to be created, as described for vkCreateSwapchainKHR.

• surface is the surface that will be associated with the swapchain.
• pPresentModeCount is a pointer to an integer related to the number of presentation modes available or queried, as described below.
• pPresentModes is either NULL or a pointer to an array of VkPresentModeKHR values, indicating the supported presentation modes.

Description

If pPresentModes is NULL, then the number of presentation modes supported for the given surface is returned in pPresentModeCount. Otherwise, pPresentModeCount must point to a variable set by the user to the number of elements in the pPresentModes array, and on return the variable is overwritten with the number of values actually written to pPresentModes. If the value of pPresentModeCount is less than the number of presentation modes supported, at most pPresentModeCount values will be written. If pPresentModeCount is smaller than the number of presentation modes supported for the given surface, VK_INCOMPLETE will be returned instead of VK_SUCCESS to indicate that not all the available values were returned.

Valid Usage (Implicit)

• physicalDevice must be a valid VkPhysicalDevice handle

• surface must be a valid VkSurfaceKHR handle
• pPresentModeCount must be a valid pointer to a uint32_t value
• If the value referenced by pPresentModeCount is not 0, and pPresentModes is not NULL, pPresentModes must be a valid pointer to an array of pPresentModeCount VkPresentModeKHR values
• Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same VkInstance

Return Codes

[Success] - VK_SUCCESS

• VK_INCOMPLETE

[Failure] - VK_ERROR_OUT_OF_HOST_MEMORY

• VK_ERROR_OUT_OF_DEVICE_MEMORY

• VK_ERROR_SURFACE_LOST_KHR

See Also

VkPhysicalDevice, VkPresentModeKHR, VkSurfaceKHR

VkSurfaceCapabilitiesKHR - Structure describing capabilities of a surface

Description

Note

Supported usage flags of a presentable image when using VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR presentation mode are provided by VkSharedPresentSurfaceCapabilitiesKHR::sharedPresentSupportedUsageFlags.

Note

Formulas such as min(N, maxImageCount) are not correct, since maxImageCount may be zero.

See Also

VkCompositeAlphaFlagsKHR, VkExtent2D, VkImageUsageFlags, VkSurfaceCapabilities2KHR, VkSurfaceTransformFlagBitsKHR, VkSurfaceTransformFlagsKHR, vkGetPhysicalDeviceSurfaceCapabilitiesKHR

VkSurfaceFormatKHR - Structure describing a supported swapchain format-color space pair

See Also

VkColorSpaceKHR, VkFormat, VkSurfaceFormat2KHR, vkGetPhysicalDeviceSurfaceFormatsKHR

VkCompositeAlphaFlagsKHR - Bitmask of VkCompositeAlphaFlagBitsKHR

Description

VkCompositeAlphaFlagsKHR is a bitmask type for setting a mask of zero or more VkCompositeAlphaFlagBitsKHR.

See Also

VkCompositeAlphaFlagBitsKHR, VkSurfaceCapabilities2EXT, VkSurfaceCapabilitiesKHR

VkSurfaceTransformFlagsKHR - Bitmask of VkSurfaceTransformFlagBitsKHR

Description

VkSurfaceTransformFlagsKHR is a bitmask type for setting a mask of zero or more VkSurfaceTransformFlagBitsKHR.

See Also

VkDisplayPropertiesKHR, VkSurfaceCapabilities2EXT, VkSurfaceCapabilitiesKHR, VkSurfaceTransformFlagBitsKHR