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 SurfaceKHR 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 SwapchainKHR objects created for surface must have been destroyed prior to destroying surface

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

Valid Usage (Implicit)

• instance must be a valid Instance handle

• If surface is not NULL_HANDLE, surface must be a valid SurfaceKHR handle
• If pAllocator is not NULL, pAllocator must be a valid pointer to a valid AllocationCallbacks 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

AllocationCallbacks, Instance, SurfaceKHR

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 Bool32, which is set to TRUE to indicate support, and FALSE otherwise.

Valid Usage

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

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

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

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_SURFACE_LOST_KHR

See Also

Bool32, PhysicalDevice, SurfaceKHR

vkGetPhysicalDeviceSurfaceCapabilitiesKHR - Query surface capabilities

Parameters

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

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

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

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

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_SURFACE_LOST_KHR

See Also

PhysicalDevice, SurfaceCapabilitiesKHR, SurfaceKHR

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

• 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 SurfaceFormatKHR structures.

Description

If pSurfaceFormats is NULL, then the number of format pairs supported for the given surface is returned in pSurfaceFormatCount. 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, INCOMPLETE will be returned instead of SUCCESS to indicate that not all the available values were returned.

The number of format pairs supported must be greater than or equal to 1. pSurfaceFormats must not contain an entry whose value for format is FORMAT_UNDEFINED.

If pSurfaceFormats includes an entry whose value for colorSpace is COLOR_SPACE_SRGB_NONLINEAR_KHR and whose value for format is a UNORM (or SRGB) format and the corresponding SRGB (or UNORM) format is a color renderable format for IMAGE_TILING_OPTIMAL, then pSurfaceFormats must also contain an entry with the same value for colorSpace and format equal to the corresponding SRGB (or UNORM) format.

Valid Usage

• 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

• surface must be a valid SurfaceKHR 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 SurfaceFormatKHR structures
• Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same Instance

Return Codes

Success

• SUCCESS
• INCOMPLETE

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_SURFACE_LOST_KHR

See Also

PhysicalDevice, SurfaceFormatKHR, SurfaceKHR

vkGetPhysicalDeviceSurfacePresentModesKHR - Query supported presentation modes

Parameters

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

• 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 PresentModeKHR 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, INCOMPLETE will be returned instead of SUCCESS to indicate that not all the available values were returned.

Valid Usage (Implicit)

• physicalDevice must be a valid PhysicalDevice handle

• surface must be a valid SurfaceKHR 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 PresentModeKHR values
• Both of physicalDevice, and surface must have been created, allocated, or retrieved from the same Instance

Return Codes

Success

• SUCCESS
• INCOMPLETE

Failure

• ERROR_OUT_OF_HOST_MEMORY
• ERROR_OUT_OF_DEVICE_MEMORY
• ERROR_SURFACE_LOST_KHR

See Also

PhysicalDevice, PresentModeKHR, SurfaceKHR

VkSurfaceCapabilitiesKHR - Structure describing capabilities of a surface

Description

Note

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.

Note

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

See Also

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

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

See Also

ColorSpaceKHR, Format, SurfaceFormat2KHR, getPhysicalDeviceSurfaceFormatsKHR

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, createDisplayPlaneSurfaceKHR, createHeadlessSurfaceEXT, createIOSSurfaceMVK, createImagePipeSurfaceFUCHSIA, createMacOSSurfaceMVK, createMetalSurfaceEXT, createStreamDescriptorSurfaceGGP, createViSurfaceNN, createWaylandSurfaceKHR, createWin32SurfaceKHR, createXcbSurfaceKHR, createXlibSurfaceKHR, destroySurfaceKHR, getDeviceGroupSurfacePresentModesKHR, getPhysicalDevicePresentRectanglesKHR, getPhysicalDeviceSurfaceCapabilities2EXT, getPhysicalDeviceSurfaceCapabilitiesKHR, getPhysicalDeviceSurfaceFormatsKHR, getPhysicalDeviceSurfacePresentModesKHR, getPhysicalDeviceSurfaceSupportKHR

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:

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

VkColorSpaceKHR - supported color space of the presentation engine

Description

Note

In the initial release of the VK_KHR_surface and https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/vkspec.html#VK_KHR_swapchain extensions, the token VK_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:

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:

See Also

CompositeAlphaFlagsKHR, SwapchainCreateInfoKHR

VkSurfaceTransformFlagBitsKHR - presentation transforms supported on a device

See Also

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