vkDestroySurfaceKHR - Destroy a VkSurfaceKHR object

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

VK_KHR_surface, AllocationCallbacks, Instance, SurfaceKHR

vkGetPhysicalDeviceSurfaceSupportKHR - Query if presentation is supported

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_DEVICE_MEMORY
• ERROR_OUT_OF_HOST_MEMORY
• ERROR_SURFACE_LOST_KHR
• ERROR_UNKNOWN
• ERROR_VALIDATION_FAILED

See Also

VK_KHR_surface, Bool32, PhysicalDevice, SurfaceKHR

vkGetPhysicalDeviceSurfaceCapabilitiesKHR - Query surface capabilities

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
• 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_DEVICE_MEMORY
• ERROR_OUT_OF_HOST_MEMORY
• ERROR_SURFACE_LOST_KHR
• ERROR_UNKNOWN
• ERROR_VALIDATION_FAILED

See Also

VK_KHR_surface, PhysicalDevice, SurfaceCapabilitiesKHR, SurfaceKHR

vkGetPhysicalDeviceSurfaceFormatsKHR - Query color formats supported by surface

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 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 pairs supported, at most pSurfaceFormatCount structures will be written, and INCOMPLETE will be returned instead of SUCCESS, to indicate that not all the available format pairs 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.

If the VK_GOOGLE_surfaceless_query extension is enabled, the values returned in pSurfaceFormats will be identical for every valid surface created on this physical device, and so surface can be NULL_HANDLE.

Valid Usage

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

• If surface is not NULL_HANDLE, 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

• If surface is not NULL_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 that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Instance

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_surface, PhysicalDevice, SurfaceFormatKHR, SurfaceKHR

vkGetPhysicalDeviceSurfacePresentModesKHR - Query 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 application 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, and INCOMPLETE will be returned instead of SUCCESS, to indicate that not all the available modes were returned.

If the VK_GOOGLE_surfaceless_query extension is enabled and surface is NULL_HANDLE, the values returned in pPresentModes will only indicate support for PRESENT_MODE_FIFO_KHR, PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR, and PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR. To query support for any other present mode, a valid handle must be provided in surface.

Valid Usage

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

• If surface is not NULL_HANDLE, 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

• If surface is not NULL_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 that are valid handles of non-ignored parameters must have been created, allocated, or retrieved from the same Instance

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_surface, PhysicalDevice, PresentModeKHR, SurfaceKHR

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

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

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