vulkan-3.26.1: Bindings to the Vulkan graphics API.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Vulkan.Extensions.VK_KHR_surface

Description

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; 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

Note

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/master/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 struct 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

ColorSpaceKHR, CompositeAlphaFlagBitsKHR, CompositeAlphaFlagsKHR, PresentModeKHR, SurfaceCapabilitiesKHR, SurfaceFormatKHR, SurfaceKHR, SurfaceTransformFlagBitsKHR, destroySurfaceKHR, getPhysicalDeviceSurfaceCapabilitiesKHR, getPhysicalDeviceSurfaceFormatsKHR, getPhysicalDeviceSurfacePresentModesKHR, getPhysicalDeviceSurfaceSupportKHR

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.

Synopsis

Documentation

destroySurfaceKHR Source #

Arguments

:: forall io. MonadIO io 
=> Instance

instance is the instance used to create the surface.

-> SurfaceKHR

surface is the surface to destroy.

-> ("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).

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

getPhysicalDeviceSurfaceSupportKHR Source #

Arguments

:: forall io. MonadIO io 
=> PhysicalDevice

physicalDevice is the physical device.

-> ("queueFamilyIndex" ::: Word32)

queueFamilyIndex is the queue family.

-> SurfaceKHR

surface is the surface.

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

getPhysicalDeviceSurfaceCapabilitiesKHR Source #

Arguments

:: forall io. MonadIO io 
=> PhysicalDevice

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

-> SurfaceKHR

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

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

getPhysicalDeviceSurfaceFormatsKHR Source #

Arguments

:: forall io. MonadIO io 
=> PhysicalDevice

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

-> SurfaceKHR

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

-> 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 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, 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

getPhysicalDeviceSurfacePresentModesKHR Source #

Arguments

:: forall io. MonadIO io 
=> PhysicalDevice

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

-> SurfaceKHR

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

-> 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 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, 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

data SurfaceCapabilitiesKHR Source #

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

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

Constructors

SurfaceCapabilitiesKHR 

Fields

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

Instances

Instances details
Storable SurfaceCapabilitiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Show SurfaceCapabilitiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

FromCStruct SurfaceCapabilitiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

ToCStruct SurfaceCapabilitiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Zero SurfaceCapabilitiesKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

data SurfaceFormatKHR Source #

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

See Also

VK_KHR_surface, ColorSpaceKHR, Format, SurfaceFormat2KHR, getPhysicalDeviceSurfaceFormatsKHR

Constructors

SurfaceFormatKHR 

Fields

Instances

Instances details
Storable SurfaceFormatKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Show SurfaceFormatKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Eq SurfaceFormatKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

FromCStruct SurfaceFormatKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

ToCStruct SurfaceFormatKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Zero SurfaceFormatKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

newtype PresentModeKHR Source #

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:

Presentation modeImage usage flags
PRESENT_MODE_IMMEDIATE_KHRSurfaceCapabilitiesKHR::supportedUsageFlags
PRESENT_MODE_MAILBOX_KHRSurfaceCapabilitiesKHR::supportedUsageFlags
PRESENT_MODE_FIFO_KHRSurfaceCapabilitiesKHR::supportedUsageFlags
PRESENT_MODE_FIFO_RELAXED_KHRSurfaceCapabilitiesKHR::supportedUsageFlags
PRESENT_MODE_SHARED_DEMAND_REFRESH_KHRSharedPresentSurfaceCapabilitiesKHR::sharedPresentSupportedUsageFlags
PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHRSharedPresentSurfaceCapabilitiesKHR::sharedPresentSupportedUsageFlags

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

VK_KHR_surface, LatencySurfaceCapabilitiesNV, SurfacePresentModeCompatibilityEXT, SurfacePresentModeEXT, SwapchainCreateInfoKHR, SwapchainPresentModeInfoEXT, SwapchainPresentModesCreateInfoEXT, getPhysicalDeviceSurfacePresentModes2EXT, getPhysicalDeviceSurfacePresentModesKHR

Constructors

PresentModeKHR Int32 

Bundled Patterns

pattern PRESENT_MODE_IMMEDIATE_KHR :: PresentModeKHR

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.

pattern PRESENT_MODE_MAILBOX_KHR :: PresentModeKHR

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.

pattern PRESENT_MODE_FIFO_KHR :: PresentModeKHR

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.

pattern PRESENT_MODE_FIFO_RELAXED_KHR :: PresentModeKHR

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.

pattern PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR :: PresentModeKHR

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.

pattern PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR :: PresentModeKHR

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.

Instances

Instances details
Storable PresentModeKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Read PresentModeKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Show PresentModeKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Eq PresentModeKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Ord PresentModeKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Zero PresentModeKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

newtype ColorSpaceKHR Source #

VkColorSpaceKHR - Supported color space of the presentation engine

Description

Note

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.

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.

Note

For a traditional “Linear” or non-gamma transfer function color space use COLOR_SPACE_PASS_THROUGH_EXT.

The color components of non-linear color space swapchain images must have had the appropriate transfer function applied. The color space selected for the swapchain 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:

Name Red PrimaryGreen PrimaryBlue PrimaryWhite-point Transfer function
DCI-P3 1.000, 0.0000.000, 1.0000.000, 0.0000.3333, 0.3333DCI 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)ITU (SMPTE 170M)
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)extended sRGB
HDR10_ST2084 0.708, 0.292 0.170, 0.797 0.131, 0.046 0.3127, 0.3290 (D65)ST2084 PQ
DOLBYVISION 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
AdobeRGB 0.640, 0.330 0.210, 0.710 0.150, 0.060 0.3127, 0.3290 (D65)AdobeRGB

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

ColorSpaceKHR Int32 

Bundled Patterns

pattern COLOR_SPACE_SRGB_NONLINEAR_KHR :: ColorSpaceKHR

COLOR_SPACE_SRGB_NONLINEAR_KHR specifies support for the sRGB color space.

pattern COLOR_SPACE_DISPLAY_NATIVE_AMD :: ColorSpaceKHR

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.

pattern COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT :: ColorSpaceKHR

COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT specifies support for the extended sRGB color space to be displayed using an sRGB EOTF.

pattern COLOR_SPACE_PASS_THROUGH_EXT :: ColorSpaceKHR

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.

pattern COLOR_SPACE_ADOBERGB_NONLINEAR_EXT :: ColorSpaceKHR

COLOR_SPACE_ADOBERGB_NONLINEAR_EXT specifies support for the AdobeRGB color space to be displayed using the Gamma 2.2 EOTF.

pattern COLOR_SPACE_ADOBERGB_LINEAR_EXT :: ColorSpaceKHR

COLOR_SPACE_ADOBERGB_LINEAR_EXT specifies support for the AdobeRGB color space to be displayed using a linear EOTF.

pattern COLOR_SPACE_HDR10_HLG_EXT :: ColorSpaceKHR

COLOR_SPACE_HDR10_HLG_EXT specifies support for the HDR10 (BT2020 color space) to be displayed using the Hybrid Log Gamma (HLG) EOTF.

pattern COLOR_SPACE_DOLBYVISION_EXT :: ColorSpaceKHR

COLOR_SPACE_DOLBYVISION_EXT specifies support for the Dolby Vision (BT2020 color space), proprietary encoding, to be displayed using the SMPTE ST2084 EOTF.

pattern COLOR_SPACE_HDR10_ST2084_EXT :: ColorSpaceKHR

COLOR_SPACE_HDR10_ST2084_EXT specifies support for the HDR10 (BT2020 color) space to be displayed using the SMPTE ST2084 Perceptual Quantizer (PQ) EOTF.

pattern COLOR_SPACE_BT2020_LINEAR_EXT :: ColorSpaceKHR

COLOR_SPACE_BT2020_LINEAR_EXT specifies support for the BT2020 color space to be displayed using a linear EOTF.

pattern COLOR_SPACE_BT709_NONLINEAR_EXT :: ColorSpaceKHR

COLOR_SPACE_BT709_NONLINEAR_EXT specifies support for the BT709 color space to be displayed using the SMPTE 170M EOTF.

pattern COLOR_SPACE_BT709_LINEAR_EXT :: ColorSpaceKHR

COLOR_SPACE_BT709_LINEAR_EXT specifies support for the BT709 color space to be displayed using a linear EOTF.

pattern COLOR_SPACE_DCI_P3_NONLINEAR_EXT :: ColorSpaceKHR

COLOR_SPACE_DCI_P3_NONLINEAR_EXT specifies support for the DCI-P3 color space to be displayed using the DCI-P3 EOTF. Note that values in such an image are interpreted as XYZ encoded color data by the presentation engine.

pattern COLOR_SPACE_DISPLAY_P3_LINEAR_EXT :: ColorSpaceKHR

COLOR_SPACE_DISPLAY_P3_LINEAR_EXT specifies support for the Display-P3 color space to be displayed using a linear EOTF.

pattern COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT :: ColorSpaceKHR

COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT specifies support for the extended sRGB color space to be displayed using a linear EOTF.

pattern COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT :: ColorSpaceKHR

COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT specifies support for the Display-P3 color space to be displayed using an sRGB-like EOTF (defined below).

Instances

Instances details
Storable ColorSpaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Read ColorSpaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Show ColorSpaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Eq ColorSpaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Ord ColorSpaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Zero ColorSpaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

newtype CompositeAlphaFlagBitsKHR Source #

VkCompositeAlphaFlagBitsKHR - Alpha compositing modes supported on a device

Description

These values are described as follows:

See Also

VK_KHR_surface, CompositeAlphaFlagsKHR, SwapchainCreateInfoKHR

Bundled Patterns

pattern COMPOSITE_ALPHA_OPAQUE_BIT_KHR :: CompositeAlphaFlagBitsKHR

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.

pattern COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR :: CompositeAlphaFlagBitsKHR

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.

pattern COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR :: CompositeAlphaFlagBitsKHR

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.

pattern COMPOSITE_ALPHA_INHERIT_BIT_KHR :: CompositeAlphaFlagBitsKHR

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.

Instances

Instances details
Storable CompositeAlphaFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Bits CompositeAlphaFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Methods

(.&.) :: CompositeAlphaFlagBitsKHR -> CompositeAlphaFlagBitsKHR -> CompositeAlphaFlagBitsKHR #

(.|.) :: CompositeAlphaFlagBitsKHR -> CompositeAlphaFlagBitsKHR -> CompositeAlphaFlagBitsKHR #

xor :: CompositeAlphaFlagBitsKHR -> CompositeAlphaFlagBitsKHR -> CompositeAlphaFlagBitsKHR #

complement :: CompositeAlphaFlagBitsKHR -> CompositeAlphaFlagBitsKHR #

shift :: CompositeAlphaFlagBitsKHR -> Int -> CompositeAlphaFlagBitsKHR #

rotate :: CompositeAlphaFlagBitsKHR -> Int -> CompositeAlphaFlagBitsKHR #

zeroBits :: CompositeAlphaFlagBitsKHR #

bit :: Int -> CompositeAlphaFlagBitsKHR #

setBit :: CompositeAlphaFlagBitsKHR -> Int -> CompositeAlphaFlagBitsKHR #

clearBit :: CompositeAlphaFlagBitsKHR -> Int -> CompositeAlphaFlagBitsKHR #

complementBit :: CompositeAlphaFlagBitsKHR -> Int -> CompositeAlphaFlagBitsKHR #

testBit :: CompositeAlphaFlagBitsKHR -> Int -> Bool #

bitSizeMaybe :: CompositeAlphaFlagBitsKHR -> Maybe Int #

bitSize :: CompositeAlphaFlagBitsKHR -> Int #

isSigned :: CompositeAlphaFlagBitsKHR -> Bool #

shiftL :: CompositeAlphaFlagBitsKHR -> Int -> CompositeAlphaFlagBitsKHR #

unsafeShiftL :: CompositeAlphaFlagBitsKHR -> Int -> CompositeAlphaFlagBitsKHR #

shiftR :: CompositeAlphaFlagBitsKHR -> Int -> CompositeAlphaFlagBitsKHR #

unsafeShiftR :: CompositeAlphaFlagBitsKHR -> Int -> CompositeAlphaFlagBitsKHR #

rotateL :: CompositeAlphaFlagBitsKHR -> Int -> CompositeAlphaFlagBitsKHR #

rotateR :: CompositeAlphaFlagBitsKHR -> Int -> CompositeAlphaFlagBitsKHR #

popCount :: CompositeAlphaFlagBitsKHR -> Int #

FiniteBits CompositeAlphaFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Read CompositeAlphaFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Show CompositeAlphaFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Eq CompositeAlphaFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Ord CompositeAlphaFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Zero CompositeAlphaFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

newtype SurfaceTransformFlagBitsKHR Source #

Bundled Patterns

pattern SURFACE_TRANSFORM_IDENTITY_BIT_KHR :: SurfaceTransformFlagBitsKHR

SURFACE_TRANSFORM_IDENTITY_BIT_KHR specifies that image content is presented without being transformed.

pattern SURFACE_TRANSFORM_ROTATE_90_BIT_KHR :: SurfaceTransformFlagBitsKHR

SURFACE_TRANSFORM_ROTATE_90_BIT_KHR specifies that image content is rotated 90 degrees clockwise.

pattern SURFACE_TRANSFORM_ROTATE_180_BIT_KHR :: SurfaceTransformFlagBitsKHR

SURFACE_TRANSFORM_ROTATE_180_BIT_KHR specifies that image content is rotated 180 degrees clockwise.

pattern SURFACE_TRANSFORM_ROTATE_270_BIT_KHR :: SurfaceTransformFlagBitsKHR

SURFACE_TRANSFORM_ROTATE_270_BIT_KHR specifies that image content is rotated 270 degrees clockwise.

pattern SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR :: SurfaceTransformFlagBitsKHR

SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR specifies that image content is mirrored horizontally.

pattern SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR :: SurfaceTransformFlagBitsKHR

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

pattern SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR :: SurfaceTransformFlagBitsKHR

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

pattern SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR :: SurfaceTransformFlagBitsKHR

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

pattern SURFACE_TRANSFORM_INHERIT_BIT_KHR :: SurfaceTransformFlagBitsKHR

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.

Instances

Instances details
Storable SurfaceTransformFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Bits SurfaceTransformFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Methods

(.&.) :: SurfaceTransformFlagBitsKHR -> SurfaceTransformFlagBitsKHR -> SurfaceTransformFlagBitsKHR #

(.|.) :: SurfaceTransformFlagBitsKHR -> SurfaceTransformFlagBitsKHR -> SurfaceTransformFlagBitsKHR #

xor :: SurfaceTransformFlagBitsKHR -> SurfaceTransformFlagBitsKHR -> SurfaceTransformFlagBitsKHR #

complement :: SurfaceTransformFlagBitsKHR -> SurfaceTransformFlagBitsKHR #

shift :: SurfaceTransformFlagBitsKHR -> Int -> SurfaceTransformFlagBitsKHR #

rotate :: SurfaceTransformFlagBitsKHR -> Int -> SurfaceTransformFlagBitsKHR #

zeroBits :: SurfaceTransformFlagBitsKHR #

bit :: Int -> SurfaceTransformFlagBitsKHR #

setBit :: SurfaceTransformFlagBitsKHR -> Int -> SurfaceTransformFlagBitsKHR #

clearBit :: SurfaceTransformFlagBitsKHR -> Int -> SurfaceTransformFlagBitsKHR #

complementBit :: SurfaceTransformFlagBitsKHR -> Int -> SurfaceTransformFlagBitsKHR #

testBit :: SurfaceTransformFlagBitsKHR -> Int -> Bool #

bitSizeMaybe :: SurfaceTransformFlagBitsKHR -> Maybe Int #

bitSize :: SurfaceTransformFlagBitsKHR -> Int #

isSigned :: SurfaceTransformFlagBitsKHR -> Bool #

shiftL :: SurfaceTransformFlagBitsKHR -> Int -> SurfaceTransformFlagBitsKHR #

unsafeShiftL :: SurfaceTransformFlagBitsKHR -> Int -> SurfaceTransformFlagBitsKHR #

shiftR :: SurfaceTransformFlagBitsKHR -> Int -> SurfaceTransformFlagBitsKHR #

unsafeShiftR :: SurfaceTransformFlagBitsKHR -> Int -> SurfaceTransformFlagBitsKHR #

rotateL :: SurfaceTransformFlagBitsKHR -> Int -> SurfaceTransformFlagBitsKHR #

rotateR :: SurfaceTransformFlagBitsKHR -> Int -> SurfaceTransformFlagBitsKHR #

popCount :: SurfaceTransformFlagBitsKHR -> Int #

FiniteBits SurfaceTransformFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Read SurfaceTransformFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Show SurfaceTransformFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Eq SurfaceTransformFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Ord SurfaceTransformFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

Zero SurfaceTransformFlagBitsKHR Source # 
Instance details

Defined in Vulkan.Extensions.VK_KHR_surface

pattern KHR_SURFACE_SPEC_VERSION :: forall a. Integral a => a Source #

type KHR_SURFACE_EXTENSION_NAME = "VK_KHR_surface" Source #

pattern KHR_SURFACE_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a Source #

newtype SurfaceKHR Source #

Constructors

SurfaceKHR Word64 

Instances

Instances details
Storable SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Show SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Eq SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Ord SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

HasObjectType SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

IsHandle SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles

Zero SurfaceKHR Source # 
Instance details

Defined in Vulkan.Extensions.Handles