vkGetPhysicalDeviceSurfaceCapabilities2KHR - Reports capabilities of a surface on a physical device

Description

getPhysicalDeviceSurfaceCapabilities2KHR behaves similarly to getPhysicalDeviceSurfaceCapabilitiesKHR, with the ability to specify extended inputs via chained input structures, and to return extended information via chained output structures.

Valid Usage

• If the VK_GOOGLE_surfaceless_query extension is not enabled, pSurfaceInfo->surface must be a valid SurfaceKHR handle

• If pSurfaceInfo->surface is not NULL_HANDLE, pSurfaceInfo->surface must be supported by physicalDevice, as reported by getPhysicalDeviceSurfaceSupportKHR or an equivalent platform-specific mechanism
• If a SurfaceCapabilitiesFullScreenExclusiveEXT structure is included in the pNext chain of pSurfaceCapabilities, a SurfaceFullScreenExclusiveWin32InfoEXT structure must be included in the pNext chain of pSurfaceInfo
• If a SurfacePresentModeCompatibilityKHR structure is included in the pNext chain of pSurfaceCapabilities, a SurfacePresentModeKHR structure must be included in the pNext chain of pSurfaceInfo
• If a SurfacePresentScalingCapabilitiesKHR structure is included in the pNext chain of pSurfaceCapabilities, a SurfacePresentModeKHR structure must be included in the pNext chain of pSurfaceInfo
• If a SurfacePresentModeCompatibilityKHR structure is included in the pNext chain of pSurfaceCapabilities, pSurfaceInfo->surface must be a valid SurfaceKHR handle
• If a SurfacePresentScalingCapabilitiesKHR structure is included in the pNext chain of pSurfaceCapabilities, pSurfaceInfo->surface must be a valid SurfaceKHR handle

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

• pSurfaceInfo must be a valid pointer to a valid PhysicalDeviceSurfaceInfo2KHR structure
• pSurfaceCapabilities must be a valid pointer to a SurfaceCapabilities2KHR structure

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_OUT_OF_HOST_MEMORY
• ERROR_SURFACE_LOST_KHR
• ERROR_UNKNOWN
• ERROR_VALIDATION_FAILED

See Also

VK_KHR_get_surface_capabilities2, PhysicalDevice, PhysicalDeviceSurfaceInfo2KHR, SurfaceCapabilities2KHR

vkGetPhysicalDeviceSurfaceFormats2KHR - Query color formats supported by surface

Description

getPhysicalDeviceSurfaceFormats2KHR behaves similarly to getPhysicalDeviceSurfaceFormatsKHR, with the ability to be extended via pNext chains.

If pSurfaceFormats is NULL, then the number of format tuples supported for the given surface is returned in pSurfaceFormatCount. Otherwise, pSurfaceFormatCount must point to a variable set by the application 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 tuples supported, at most pSurfaceFormatCount structures will be written, and INCOMPLETE will be returned instead of SUCCESS, to indicate that not all the available values were returned.

Valid Usage

• If the VK_GOOGLE_surfaceless_query extension is not enabled, pSurfaceInfo->surface must be a valid SurfaceKHR handle

• If pSurfaceInfo->surface is not NULL_HANDLE, pSurfaceInfo->surface must be supported by physicalDevice, as reported by getPhysicalDeviceSurfaceSupportKHR or an equivalent platform-specific mechanism

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

• pSurfaceInfo must be a valid pointer to a valid PhysicalDeviceSurfaceInfo2KHR structure
• 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 SurfaceFormat2KHR structures

Return Codes

Success

• INCOMPLETE
• SUCCESS

Failure

• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_OUT_OF_HOST_MEMORY
• ERROR_SURFACE_LOST_KHR
• ERROR_UNKNOWN
• ERROR_VALIDATION_FAILED

See Also

VK_KHR_get_surface_capabilities2, PhysicalDevice, PhysicalDeviceSurfaceInfo2KHR, SurfaceFormat2KHR

VkPhysicalDeviceSurfaceInfo2KHR - Structure specifying a surface and related swapchain creation parameters

Description

The members of PhysicalDeviceSurfaceInfo2KHR correspond to the arguments to getPhysicalDeviceSurfaceCapabilitiesKHR, with sType and pNext added for extensibility.

Additional capabilities of a surface may be available to swapchains created with different full-screen exclusive settings - particularly if exclusive full-screen access is application controlled. These additional capabilities can be queried by adding a SurfaceFullScreenExclusiveInfoEXT structure to the pNext chain of this structure when used to query surface properties. Additionally, for Win32 surfaces with application controlled exclusive full-screen access, chaining a SurfaceFullScreenExclusiveWin32InfoEXT structure may also report additional surface capabilities. These additional capabilities only apply to swapchains created with the same parameters included in the pNext chain of SwapchainCreateInfoKHR.

Valid Usage

• 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 surface is not VK_NULL_HANDLE, and the VK_GOOGLE_surfaceless_query extension is not enabled, surface must be a valid SurfaceKHR handle

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_PHYSICAL_DEVICE_SURFACE_INFO_2_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 SurfaceFullScreenExclusiveInfoEXT, SurfaceFullScreenExclusiveWin32InfoEXT, or SurfacePresentModeKHR
• The sType value of each structure in the pNext chain must be unique

See Also

VK_KHR_get_surface_capabilities2, StructureType, SurfaceKHR, getDeviceGroupSurfacePresentModes2EXT, getPhysicalDeviceSurfaceCapabilities2KHR, getPhysicalDeviceSurfaceFormats2KHR, getPhysicalDeviceSurfacePresentModes2EXT

VkSurfaceCapabilities2KHR - Structure describing capabilities of a surface

Description

If the VK_GOOGLE_surfaceless_query extension is enabled and PhysicalDeviceSurfaceInfo2KHR::surface in the getPhysicalDeviceSurfaceCapabilities2KHR call is NULL_HANDLE, the values returned in minImageCount, maxImageCount, currentExtent, and currentTransform will not reflect that of any surface and will instead be as such:

• minImageCount and maxImageCount will be 0xFFFFFFFF
• currentExtent will be (0xFFFFFFFF, 0xFFFFFFFF)
• currentTransform will be SURFACE_TRANSFORM_INHERIT_BIT_KHR

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SURFACE_CAPABILITIES_2_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 DisplayNativeHdrSurfaceCapabilitiesAMD, LatencySurfaceCapabilitiesNV, PresentTimingSurfaceCapabilitiesEXT, SharedPresentSurfaceCapabilitiesKHR, SurfaceCapabilitiesFullScreenExclusiveEXT, SurfaceCapabilitiesPresentBarrierNV, SurfaceCapabilitiesPresentId2KHR, SurfaceCapabilitiesPresentWait2KHR, SurfacePresentModeCompatibilityKHR, SurfacePresentScalingCapabilitiesKHR, or SurfaceProtectedCapabilitiesKHR
• The sType value of each structure in the pNext chain must be unique

See Also

VK_KHR_get_surface_capabilities2, StructureType, SurfaceCapabilitiesKHR, getPhysicalDeviceSurfaceCapabilities2KHR

VkSurfaceFormat2KHR - Structure describing a supported swapchain format tuple

Description

If the imageCompressionControlSwapchain feature is supported and a ImageCompressionPropertiesEXT structure is included in the pNext chain of this structure, then it will be filled with the compression properties that are supported for the surfaceFormat.

Valid Usage

• If the VK_EXT_image_compression_control_swapchain extension is not supported, the pNext chain must not include an ImageCompressionPropertiesEXT structure

Valid Usage (Implicit)

• sType must be STRUCTURE_TYPE_SURFACE_FORMAT_2_KHR

• pNext must be NULL or a pointer to a valid instance of ImageCompressionPropertiesEXT
• The sType value of each structure in the pNext chain must be unique

See Also

VK_KHR_get_surface_capabilities2, StructureType, SurfaceFormatKHR, getPhysicalDeviceSurfaceFormats2KHR

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

VkSurfaceCapabilitiesKHR - Structure describing capabilities of a surface

Description

Supported usage flags of a presentable image when using PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR presentation mode are provided by SharedPresentSurfaceCapabilitiesKHR::sharedPresentSupportedUsageFlags.

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

See Also

VK_KHR_surface, CompositeAlphaFlagsKHR, Extent2D, ImageUsageFlags, SurfaceCapabilities2KHR, SurfaceTransformFlagBitsKHR, SurfaceTransformFlagsKHR, getPhysicalDeviceSurfaceCapabilitiesKHR

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

See Also

VK_KHR_surface, ColorSpaceKHR, Format, SurfaceFormat2KHR, getPhysicalDeviceSurfaceFormatsKHR

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