HORIZON HASKELLDocslts/ghc-9.14.x45dd5372026-10-11Search names, modules, packages, or :: a typeCtrl K

GHC 9.14.1 · lts/ghc-9.14.x · 45dd537 · 2026-10-11

Modulevulkan-3.27GHC2021

Vulkan.Extensions.VK_KHR_surface

Name

VK_KHR_surface - instance extension

VK_KHR_surface

Name String

VK_KHR_surface

Extension Type

Instance extension

Registered Extension Number

1

Revision

25

Ratification Status

Ratified

Extension and Version Dependencies

None

Contact

Other Extension Metadata

Last Modified Date

2016-08-25

IP Status

No known IP claims.

Contributors

  • Patrick Doane, Blizzard

  • Ian Elliott, LunarG

  • Jesse Hall, Google

  • James Jones, NVIDIA

  • David Mao, AMD

  • Norbert Nopper, Freescale

  • Alon Or-bach, Samsung

  • Daniel Rakos, AMD

  • Graham Sellers, AMD

  • Jeff Vigil, Qualcomm

  • Chia-I Wu, LunarG

  • Faith Ekstrand, Intel

Description

The VK_KHR_surface extension is an instance extension. It introduces SurfaceKHR objects, which abstract native platform surface or window objects for use with Vulkan. It also provides a way to determine whether a queue family in a physical device supports presenting to particular surface.

Separate extensions for each platform provide the mechanisms for creating SurfaceKHR objects, but once created they may be used in this and other platform-independent extensions, in particular the VK_KHR_swapchain extension.

New Object Types

New Commands

New Structures

New Enums

New Bitmasks

New Enum Constants

Examples

The example code for the VK_KHR_surface and VK_KHR_swapchain extensions was removed from the appendix after revision 1.0.29. This WSI example code was ported to the cube demo that is shipped with the official Khronos SDK, and is being kept up-to-date in that location (see: https://github.com/KhronosGroup/Vulkan-Tools/blob/main/cube/cube.c).

Issues

1) Should this extension include a method to query whether a physical device supports presenting to a specific window or native surface on a given platform?

RESOLVED: Yes. Without this, applications would need to create a device instance to determine whether a particular window can be presented to. Knowing that a device supports presentation to a platform in general is not sufficient, as a single machine might support multiple seats, or instances of the platform that each use different underlying physical devices. Additionally, on some platforms, such as the X Window System, different drivers and devices might be used for different windows depending on which section of the desktop they exist on.

2) Should the getPhysicalDeviceSurfaceCapabilitiesKHR, getPhysicalDeviceSurfaceFormatsKHR, and getPhysicalDeviceSurfacePresentModesKHR functions be in this extension and operate on physical devices, rather than being in VK_KHR_swapchain (i.e. device extension) and being dependent on Device?

RESOLVED: Yes. While it might be useful to depend on Device (and therefore on enabled extensions and features) for the queries, Vulkan was released only with the PhysicalDevice versions. Many cases can be resolved by a Valid Usage statement, and/or by a separate pNext chain version of the query structure specific to a given extension or parameters, via extensible versions of the queries: getPhysicalDeviceSurfacePresentModes2EXT, getPhysicalDeviceSurfaceCapabilities2KHR, and getPhysicalDeviceSurfaceFormats2KHR.

3) Should Vulkan support Xlib or XCB as the API for accessing the X Window System platform?

RESOLVED: Both. XCB is a more modern and efficient API, but Xlib usage is deeply ingrained in many applications and likely will remain in use for the foreseeable future. Not all drivers necessarily need to support both, but including both as options in the core specification will probably encourage support, which should in turn ease adoption of the Vulkan API in older codebases. Additionally, the performance improvements possible with XCB likely will not have a measurable impact on the performance of Vulkan presentation and other minimal window system interactions defined here.

4) Should the GBM platform be included in the list of platform enums?

RESOLVED: Deferred, and will be addressed with a platform-specific extension to be written in the future.

Version History

  • Revision 1, 2015-05-20 (James Jones)

    • Initial draft, based on LunarG KHR spec, other KHR specs, patches attached to bugs.

  • Revision 2, 2015-05-22 (Ian Elliott)

    • Created initial Description section.

    • Removed query for whether a platform requires the use of a queue for presentation, since it was decided that presentation will always be modeled as being part of the queue.

    • Fixed typos and other minor mistakes.

  • Revision 3, 2015-05-26 (Ian Elliott)

    • Improved the Description section.

  • Revision 4, 2015-05-27 (James Jones)

    • Fixed compilation errors in example code.

  • Revision 5, 2015-06-01 (James Jones)

    • Added issues 1 and 2 and made related spec updates.

  • Revision 6, 2015-06-01 (James Jones)

    • Merged the platform type mappings table previously removed from VK_KHR_swapchain with the platform description table in this spec.

    • Added issues 3 and 4 documenting choices made when building the initial list of native platforms supported.

  • Revision 7, 2015-06-11 (Ian Elliott)

    • Updated table 1 per input from the KHR TSG.

    • Updated issue 4 (GBM) per discussion with Daniel Stone. He will create a platform-specific extension sometime in the future.

  • Revision 8, 2015-06-17 (James Jones)

    • Updated enum-extending values using new convention.

    • Fixed the value of VK_SURFACE_PLATFORM_INFO_TYPE_SUPPORTED_KHR.

  • Revision 9, 2015-06-17 (James Jones)

    • Rebased on Vulkan API version 126.

  • Revision 10, 2015-06-18 (James Jones)

    • Marked issues 2 and 3 resolved.

  • Revision 11, 2015-06-23 (Ian Elliott)

    • Examples now show use of function pointers for extension functions.

    • Eliminated extraneous whitespace.

  • Revision 12, 2015-07-07 (Daniel Rakos)

    • Added error section describing when each error is expected to be reported.

    • Replaced the term “queue node index” with “queue family index” in the spec as that is the agreed term to be used in the latest version of the core header and spec.

    • Replaced bool32_t with VkBool32.

  • Revision 13, 2015-08-06 (Daniel Rakos)

    • Updated spec against latest core API header version.

  • Revision 14, 2015-08-20 (Ian Elliott)

    • Renamed this extension and all of its enumerations, types, functions, etc. This makes it compliant with the proposed standard for Vulkan extensions.

    • Switched from “revision” to “version”, including use of the VK_MAKE_VERSION macro in the header file.

    • Did miscellaneous cleanup, etc.

  • Revision 15, 2015-08-20 (Ian Elliott—​porting a 2015-07-29 change from James Jones)

    • Moved the surface transform enums here from VK_WSI_swapchain so they could be reused by VK_WSI_display.

  • Revision 16, 2015-09-01 (James Jones)

    • Restore single-field revision number.

  • Revision 17, 2015-09-01 (James Jones)

    • Fix example code compilation errors.

  • Revision 18, 2015-09-26 (Jesse Hall)

    • Replaced VkSurfaceDescriptionKHR with the VkSurfaceKHR object, which is created via layered extensions. Added VkDestroySurfaceKHR.

  • Revision 19, 2015-09-28 (Jesse Hall)

    • Renamed from VK_EXT_KHR_swapchain to VK_EXT_KHR_surface.

  • Revision 20, 2015-09-30 (Jeff Vigil)

    • Add error result VK_ERROR_SURFACE_LOST_KHR.

  • Revision 21, 2015-10-15 (Daniel Rakos)

    • Updated the resolution of issue #2 and include the surface capability queries in this extension.

    • Renamed SurfaceProperties to SurfaceCapabilities as it better reflects that the values returned are the capabilities of the surface on a particular device.

    • Other minor cleanup and consistency changes.

  • Revision 22, 2015-10-26 (Ian Elliott)

    • Renamed from VK_EXT_KHR_surface to VK_KHR_surface.

  • Revision 23, 2015-11-03 (Daniel Rakos)

    • Added allocation callbacks to vkDestroySurfaceKHR.

  • Revision 24, 2015-11-10 (Jesse Hall)

    • Removed VkSurfaceTransformKHR. Use VkSurfaceTransformFlagBitsKHR instead.

    • Rename VkSurfaceCapabilitiesKHR member maxImageArraySize to maxImageArrayLayers.

  • Revision 25, 2016-01-14 (James Jones)

    • Moved VK_ERROR_NATIVE_WINDOW_IN_USE_KHR from the VK_KHR_android_surface to the VK_KHR_surface extension.

  • 2016-08-23 (Ian Elliott)

    • Update the example code, to not have so many characters per line, and to split out a new example to show how to obtain function pointers.

  • 2016-08-25 (Ian Elliott)

    • A note was added at the beginning of the example code, stating that it will be removed from future versions of the appendix.

See Also

No cross-references are available

Document Notes

For more information, see the Vulkan Specification.

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

  • 11 types
  • 5 values
  • Packagevulkan-3.27
  • Exports55
  • LanguageGHC2021
  • LicenceBSD-3-Clause
  • SourceVK_KHR_surface.hs
valuedestroySurfaceKHR
  1. :: MonadIO io
  2. => Instance

    instance is the instance used to create the surface.

  3. -> SurfaceKHR

    surface is the surface to destroy.

  4. -> "allocator" ::: Maybe AllocationCallbacks

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

  5. -> io ()
#

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

valuegetPhysicalDeviceSurfaceSupportKHR
  1. :: MonadIO io
  2. => PhysicalDevice

    physicalDevice is the physical device.

  3. -> "queueFamilyIndex" ::: Word32

    queueFamilyIndex is the queue family.

  4. -> SurfaceKHR

    surface is the surface.

  5. -> io ("supported" ::: Bool)
#

vkGetPhysicalDeviceSurfaceSupportKHR - Query if presentation is supported

Valid Usage

Valid Usage (Implicit)

  • 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
Failure

See Also

VK_KHR_surface, Bool32, PhysicalDevice, SurfaceKHR

valuegetPhysicalDeviceSurfaceCapabilitiesKHR
  1. :: MonadIO io
  2. => PhysicalDevice

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

  3. -> SurfaceKHR

    surface is the surface that will be associated with the swapchain.

  4. -> io SurfaceCapabilitiesKHR
#

vkGetPhysicalDeviceSurfaceCapabilitiesKHR - Query surface capabilities

Valid Usage

Valid Usage (Implicit)

  • 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
Failure

See Also

VK_KHR_surface, PhysicalDevice, SurfaceCapabilitiesKHR, SurfaceKHR

valuegetPhysicalDeviceSurfaceFormatsKHR
  1. :: MonadIO io
  2. => PhysicalDevice

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

  3. -> SurfaceKHR

    surface is the surface that will be associated with the swapchain.

  4. -> io (Result, "surfaceFormats" ::: Vector SurfaceFormatKHR)
#

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

Valid Usage (Implicit)

  • 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
Failure

See Also

VK_KHR_surface, PhysicalDevice, SurfaceFormatKHR, SurfaceKHR

valuegetPhysicalDeviceSurfacePresentModesKHR
  1. :: MonadIO io
  2. => PhysicalDevice

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

  3. -> SurfaceKHR

    surface is the surface that will be associated with the swapchain.

  4. -> io (Result, "presentModes" ::: Vector PresentModeKHR)
#

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

Valid Usage (Implicit)

  • 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
Failure

See Also

VK_KHR_surface, PhysicalDevice, PresentModeKHR, SurfaceKHR

datadata SurfaceCapabilitiesKHR
#

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

Constructors

  • SurfaceCapabilitiesKHR
    • minImageCount :: Word32

      minImageCount is the minimum number of images the specified device supports for a swapchain created for the surface, and will be at least one.

    • maxImageCount :: Word32

      maxImageCount is the maximum number of images the specified device supports for a swapchain created for the surface, and will be either 0, or greater than or equal to minImageCount. A value of 0 means that there is no limit on the number of images, though there may be limits related to the total amount of memory used by presentable images.

    • currentExtent :: Extent2D

      currentExtent is the current width and height of the surface, or the special value (0xFFFFFFFF, 0xFFFFFFFF) indicating that the surface size will be determined by the extent of a swapchain targeting the surface.

    • minImageExtent :: Extent2D

      minImageExtent contains the smallest valid swapchain extent for the surface on the specified device. The width and height of the extent will each be less than or equal to the corresponding width and height of currentExtent, unless currentExtent has the special value described above.

    • maxImageExtent :: Extent2D

      maxImageExtent contains the largest valid swapchain extent for the surface on the specified device. The width and height of the extent will each be greater than or equal to the corresponding width and height of minImageExtent. The width and height of the extent will each be greater than or equal to the corresponding width and height of currentExtent, unless currentExtent has the special value described above.

    • maxImageArrayLayers :: Word32

      maxImageArrayLayers is the maximum number of layers presentable images can have for a swapchain created for this device and surface, and will be at least one.

    • supportedTransforms :: SurfaceTransformFlagsKHR

      supportedTransforms is a bitmask of SurfaceTransformFlagBitsKHR indicating the presentation transforms supported for the surface on the specified device. At least one bit will be set.

    • currentTransform :: SurfaceTransformFlagBitsKHR

      currentTransform is SurfaceTransformFlagBitsKHR value indicating the surface’s current transform relative to the presentation engine’s natural orientation.

    • supportedCompositeAlpha :: CompositeAlphaFlagsKHR

      supportedCompositeAlpha is a bitmask of CompositeAlphaFlagBitsKHR, representing the alpha compositing modes supported by the presentation engine for the surface on the specified device, and at least one bit will be set. Opaque composition can be achieved in any alpha compositing mode by either using an image format that has no alpha component, or by ensuring that all pixels in the presentable images have an alpha value of 1.0.

    • supportedUsageFlags :: ImageUsageFlags

      supportedUsageFlags is a bitmask of ImageUsageFlagBits representing the ways the application can use the presentable images of a swapchain created with PresentModeKHR set to PRESENT_MODE_FIFO_LATEST_READY_KHR, PRESENT_MODE_IMMEDIATE_KHR, PRESENT_MODE_MAILBOX_KHR, PRESENT_MODE_FIFO_KHR or PRESENT_MODE_FIFO_RELAXED_KHR for the surface on the specified device. IMAGE_USAGE_COLOR_ATTACHMENT_BIT must be included in the set. Implementations may support additional usages.

Instances5Show, Storable, FromCStruct, ToCStruct, Zero
datadata SurfaceFormatKHR
#

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

See Also

VK_KHR_surface, ColorSpaceKHR, Format, SurfaceFormat2KHR, getPhysicalDeviceSurfaceFormatsKHR

Constructors

Instances6Eq, Show, Storable, FromCStruct, ToCStruct, Zero
newtypenewtype PresentModeKHR
#

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:

Presentation mode

Image usage flags

PRESENT_MODE_IMMEDIATE_KHR

SurfaceCapabilitiesKHR

::

supportedUsageFlags

PRESENT_MODE_MAILBOX_KHR

SurfaceCapabilitiesKHR

::

supportedUsageFlags

PRESENT_MODE_FIFO_KHR

SurfaceCapabilitiesKHR

::

supportedUsageFlags

PRESENT_MODE_FIFO_RELAXED_KHR

SurfaceCapabilitiesKHR

::

supportedUsageFlags

PRESENT_MODE_FIFO_LATEST_READY_KHR

SurfaceCapabilitiesKHR

::

supportedUsageFlags

PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR

SharedPresentSurfaceCapabilitiesKHR

::

sharedPresentSupportedUsageFlags

PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR

SharedPresentSurfaceCapabilitiesKHR

::

sharedPresentSupportedUsageFlags

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

Constructors

Instances6Eq, Ord, Read, Show, Storable, Zero
newtypenewtype ColorSpaceKHR
#

VkColorSpaceKHR - Supported color space of the presentation engine

Description

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:

Name

Red Primary

Green Primary

Blue Primary

White-point

Transfer function

DCI-P3

1.000, 0.000

0.000, 1.000

0.000, 0.000

0.3333, 0.3333

DCI P3

Display-P3

0.680, 0.320

0.265, 0.690

0.150, 0.060

0.3127, 0.3290 (D65)

Display-P3

BT709

0.640, 0.330

0.300, 0.600

0.150, 0.060

0.3127, 0.3290 (D65)

BT709

sRGB

0.640, 0.330

0.300, 0.600

0.150, 0.060

0.3127, 0.3290 (D65)

sRGB

extended sRGB

0.640, 0.330

0.300, 0.600

0.150, 0.060

0.3127, 0.3290 (D65)

scRGB

HDR10_ST2084

0.708, 0.292

0.170, 0.797

0.131, 0.046

0.3127, 0.3290 (D65)

ST2084 PQ

HDR10_HLG

0.708, 0.292

0.170, 0.797

0.131, 0.046

0.3127, 0.3290 (D65)

HLG

Adobe RGB

0.640, 0.330

0.210, 0.710

0.150, 0.060

0.3127, 0.3290 (D65)

Adobe RGB

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

Constructors

Instances6Eq, Ord, Read, Show, Storable, Zero
newtypenewtype CompositeAlphaFlagBitsKHR
#

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

Constructors

Instances8Eq, Ord, Read, Show, Bits, FiniteBits, …
newtypenewtype SurfaceTransformFlagBitsKHR
#

VkSurfaceTransformFlagBitsKHR - Presentation transforms supported on a device

Description

See Also

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

Constructors

Instances8Eq, Ord, Read, Show, Bits, FiniteBits, …
newtypenewtype SurfaceKHR
#

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

Constructors

Instances7Eq, Ord, Show, Storable, HasObjectType, IsHandle, …