1256 lines
51 KiB
Plaintext
1256 lines
51 KiB
Plaintext
// Copyright (c) 2014-2018 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/by/4.0/
|
|
|
|
[[wsi]]
|
|
= Window System Integration (WSI)
|
|
|
|
This chapter discusses the window system integration (WSI) between the
|
|
Vulkan API and the various forms of displaying the results of rendering to a
|
|
user.
|
|
Since the Vulkan API can: be used without displaying results, WSI is
|
|
provided through the use of optional Vulkan extensions.
|
|
This chapter provides an overview of WSI.
|
|
See the appendix for additional details of each WSI extension, including
|
|
which extensions must: be enabled in order to use each of the functions
|
|
described in this chapter.
|
|
|
|
|
|
== WSI Platform
|
|
|
|
A platform is an abstraction for a window system, OS, etc.
|
|
Some examples include MS Windows, Android, and Wayland.
|
|
The Vulkan API may: be integrated in a unique manner for each platform.
|
|
|
|
The Vulkan API does not define any type of platform object.
|
|
Platform-specific WSI extensions are defined, which contain
|
|
platform-specific functions for using WSI.
|
|
Use of these extensions is guarded by preprocessor symbols as defined in the
|
|
<<boilerplate-wsi-header,Window System-Specific Header Control>> appendix.
|
|
|
|
In order for an application to be compiled to use WSI with a given platform,
|
|
it must either:
|
|
|
|
* #define the appropriate preprocessor symbol prior to including the
|
|
`vulkan.h` header file, or
|
|
* include `vulkan_core.h` and any native platform headers, followed by the
|
|
appropriate platform-specific header.
|
|
|
|
The preprocessor symbols and platform-specific headers are defined in the
|
|
<<boilerplate-wsi-header-table, Window System Extensions and Headers>>
|
|
table.
|
|
|
|
Each platform-specific extension is an instance extension.
|
|
The application must: enable instance extensions with fname:vkCreateInstance
|
|
before using them.
|
|
|
|
|
|
== WSI Surface
|
|
|
|
[open,refpage='VkSurfaceKHR',desc='Opaque handle to a surface object',type='handles']
|
|
--
|
|
|
|
Native platform surface or window objects are abstracted by surface objects,
|
|
which are represented by sname:VkSurfaceKHR handles:
|
|
|
|
include::../../api/handles/VkSurfaceKHR.txt[]
|
|
|
|
The `VK_KHR_surface` extension declares the sname:VkSurfaceKHR object, and
|
|
provides a function for destroying sname:VkSurfaceKHR objects.
|
|
Separate platform-specific extensions each provide a function for creating a
|
|
sname:VkSurfaceKHR object for the respective platform.
|
|
From the application's perspective this is an opaque handle, just like the
|
|
handles of other Vulkan objects.
|
|
|
|
ifdef::implementation-guide[]
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
On certain platforms, the Vulkan loader and ICDs may: have conventions that
|
|
treat the handle as a pointer to a struct that contains the
|
|
platform-specific information about the surface.
|
|
This will be described in the documentation for the loader-ICD interface,
|
|
and in the `vk_icd.h` header file of the LoaderAndTools source-code
|
|
repository.
|
|
This does not affect the loader-layer interface; layers may: wrap
|
|
sname:VkSurfaceKHR objects.
|
|
====
|
|
endif::implementation-guide[]
|
|
|
|
--
|
|
|
|
ifdef::editing-notes[]
|
|
[NOTE]
|
|
.editing-note
|
|
====
|
|
TODO: Consider replacing the above note editing note with a pointer to the
|
|
loader spec when it exists.
|
|
However, the information is not relevant to users of the API nor does it
|
|
affect conformance of a Vulkan implementation to this spec.
|
|
====
|
|
endif::editing-notes[]
|
|
|
|
ifdef::VK_KHR_android_surface[]
|
|
include::../VK_KHR_android_surface/platformCreateSurface_android.txt[]
|
|
endif::VK_KHR_android_surface[]
|
|
|
|
ifdef::VK_KHR_mir_surface[]
|
|
include::../VK_KHR_mir_surface/platformCreateSurface_mir.txt[]
|
|
endif::VK_KHR_mir_surface[]
|
|
|
|
ifdef::VK_KHR_wayland_surface[]
|
|
include::../VK_KHR_wayland_surface/platformCreateSurface_wayland.txt[]
|
|
endif::VK_KHR_wayland_surface[]
|
|
|
|
ifdef::VK_KHR_win32_surface[]
|
|
include::../VK_KHR_win32_surface/platformCreateSurface_win32.txt[]
|
|
endif::VK_KHR_win32_surface[]
|
|
|
|
ifdef::VK_KHR_xcb_surface[]
|
|
include::../VK_KHR_xcb_surface/platformCreateSurface_xcb.txt[]
|
|
endif::VK_KHR_xcb_surface[]
|
|
|
|
ifdef::VK_KHR_xlib_surface[]
|
|
include::../VK_KHR_xlib_surface/platformCreateSurface_xlib.txt[]
|
|
endif::VK_KHR_xlib_surface[]
|
|
|
|
ifdef::VK_FUCHSIA_imagepipe_surface[]
|
|
include::../VK_FUCHSIA_imagepipe_surface/platformCreateSurface_imagepipe.txt[]
|
|
endif::VK_FUCHSIA_imagepipe_surface[]
|
|
|
|
ifdef::VK_MVK_ios_surface[]
|
|
include::../VK_MVK_ios_surface/platformCreateSurface_ios.txt[]
|
|
endif::VK_MVK_ios_surface[]
|
|
|
|
ifdef::VK_MVK_macos_surface[]
|
|
include::../VK_MVK_macos_surface/platformCreateSurface_macos.txt[]
|
|
endif::VK_MVK_macos_surface[]
|
|
|
|
ifdef::VK_NN_vi_surface[]
|
|
include::../VK_NN_vi_surface/platformCreateSurface_vi.txt[]
|
|
endif::VK_NN_vi_surface[]
|
|
|
|
|
|
=== Platform-Independent Information
|
|
|
|
Once created, sname:VkSurfaceKHR objects can: be used in this and other
|
|
extensions, in particular the `<<VK_KHR_swapchain>>` extension.
|
|
|
|
Several WSI functions return ename:VK_ERROR_SURFACE_LOST_KHR if the surface
|
|
becomes no longer available.
|
|
After such an error, the surface (and any child swapchain, if one exists)
|
|
should: be destroyed, as there is no way to restore them to a not-lost
|
|
state.
|
|
Applications may: attempt to create a new sname:VkSurfaceKHR using the same
|
|
native platform window object, but whether such re-creation will succeed is
|
|
platform-dependent and may: depend on the reason the surface became
|
|
unavailable.
|
|
A lost surface does not otherwise cause devices to be
|
|
<<devsandqueues-lost-device,lost>>.
|
|
|
|
[open,refpage='vkDestroySurfaceKHR',desc='Destroy a VkSurfaceKHR object',type='protos']
|
|
--
|
|
|
|
To destroy a sname:VkSurfaceKHR object, call:
|
|
|
|
include::../../api/protos/vkDestroySurfaceKHR.txt[]
|
|
|
|
* pname:instance is the instance used to create the surface.
|
|
* pname:surface is the surface to destroy.
|
|
* pname:pAllocator is the allocator used for host memory allocated for the
|
|
surface object when there is no more specific allocator available (see
|
|
<<memory-allocation,Memory Allocation>>).
|
|
|
|
Destroying a sname:VkSurfaceKHR 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
|
|
****
|
|
* [[VUID-vkDestroySurfaceKHR-surface-01266]]
|
|
All sname:VkSwapchainKHR objects created for pname:surface must: have
|
|
been destroyed prior to destroying pname:surface
|
|
* [[VUID-vkDestroySurfaceKHR-surface-01267]]
|
|
If sname:VkAllocationCallbacks were provided when pname:surface was
|
|
created, a compatible set of callbacks must: be provided here
|
|
* [[VUID-vkDestroySurfaceKHR-surface-01268]]
|
|
If no sname:VkAllocationCallbacks were provided when pname:surface was
|
|
created, pname:pAllocator must: be `NULL`
|
|
****
|
|
|
|
include::../../validity/protos/vkDestroySurfaceKHR.txt[]
|
|
--
|
|
|
|
ifdef::VK_KHR_display[]
|
|
include::../VK_KHR_display/display.txt[]
|
|
endif::VK_KHR_display[]
|
|
|
|
|
|
== Querying for WSI Support
|
|
|
|
Not all physical devices will include WSI support.
|
|
Within a physical device, not all queue families will support presentation.
|
|
WSI support and compatibility can: be determined in a platform-neutral
|
|
manner (which determines support for presentation to a particular surface
|
|
object) and additionally may: be determined in platform-specific manners
|
|
(which determine support for presentation on the specified physical device
|
|
but do not guarantee support for presentation to a particular surface
|
|
object).
|
|
|
|
[open,refpage='vkGetPhysicalDeviceSurfaceSupportKHR',desc='Query if presentation is supported',type='protos']
|
|
--
|
|
|
|
To determine whether a queue family of a physical device supports
|
|
presentation to a given surface, call:
|
|
|
|
include::../../api/protos/vkGetPhysicalDeviceSurfaceSupportKHR.txt[]
|
|
|
|
* pname:physicalDevice is the physical device.
|
|
* pname:queueFamilyIndex is the queue family.
|
|
* pname:surface is the surface.
|
|
* pname:pSupported is a pointer to a basetype:VkBool32, which is set to
|
|
ename:VK_TRUE to indicate support, and ename:VK_FALSE otherwise.
|
|
|
|
.Valid Usage
|
|
****
|
|
* [[VUID-vkGetPhysicalDeviceSurfaceSupportKHR-queueFamilyIndex-01269]]
|
|
pname:queueFamilyIndex must: be less than
|
|
pname:pQueueFamilyPropertyCount returned by
|
|
fname:vkGetPhysicalDeviceQueueFamilyProperties for the given
|
|
pname:physicalDevice
|
|
****
|
|
|
|
include::../../validity/protos/vkGetPhysicalDeviceSurfaceSupportKHR.txt[]
|
|
--
|
|
|
|
ifdef::VK_KHR_android_surface[]
|
|
include::../VK_KHR_android_surface/platformQuerySupport_android.txt[]
|
|
endif::VK_KHR_android_surface[]
|
|
|
|
ifdef::VK_KHR_mir_surface[]
|
|
include::../VK_KHR_mir_surface/platformQuerySupport_mir.txt[]
|
|
endif::VK_KHR_mir_surface[]
|
|
|
|
ifdef::VK_KHR_wayland_surface[]
|
|
include::../VK_KHR_wayland_surface/platformQuerySupport_wayland.txt[]
|
|
endif::VK_KHR_wayland_surface[]
|
|
|
|
ifdef::VK_KHR_win32_surface[]
|
|
include::../VK_KHR_win32_surface/platformQuerySupport_win32.txt[]
|
|
endif::VK_KHR_win32_surface[]
|
|
|
|
ifdef::VK_KHR_xcb_surface[]
|
|
include::../VK_KHR_xcb_surface/platformQuerySupport_xcb.txt[]
|
|
endif::VK_KHR_xcb_surface[]
|
|
|
|
ifdef::VK_KHR_xlib_surface[]
|
|
include::../VK_KHR_xlib_surface/platformQuerySupport_xlib.txt[]
|
|
endif::VK_KHR_xlib_surface[]
|
|
|
|
ifdef::VK_FUCHSIA_imagepipe_surface[]
|
|
include::../VK_FUCHSIA_imagepipe_surface/platformQuerySupport_imagepipe.txt[]
|
|
endif::VK_FUCHSIA_imagepipe_surface[]
|
|
|
|
ifdef::VK_MVK_ios_surface[]
|
|
include::../VK_MVK_ios_surface/platformQuerySupport_ios.txt[]
|
|
endif::VK_MVK_ios_surface[]
|
|
|
|
ifdef::VK_MVK_macos_surface[]
|
|
include::../VK_MVK_macos_surface/platformQuerySupport_macos.txt[]
|
|
endif::VK_MVK_macos_surface[]
|
|
|
|
ifdef::VK_NN_vi_surface[]
|
|
include::../VK_NN_vi_surface/platformQuerySupport_vi.txt[]
|
|
endif::VK_NN_vi_surface[]
|
|
|
|
|
|
== Surface Queries
|
|
|
|
The capabilities of a swapchain targetting a surface are the intersection of
|
|
the capabilities of the WSI platform, the native window or display, and the
|
|
physical device.
|
|
The resulting capabilities can be obtained with the queries listed below in
|
|
this section.
|
|
Capabilities that correspond to image creation parameters are not
|
|
independent of each other: combinations of parameters that are not supported
|
|
as reported by flink:vkGetPhysicalDeviceImageFormatProperties are not
|
|
supported by the surface on that physical device, even if the capabilities
|
|
taken individually are supported as part of some other parameter
|
|
combinations.
|
|
|
|
[open,refpage='vkGetPhysicalDeviceSurfaceCapabilitiesKHR',desc='Query surface capabilities',type='protos']
|
|
--
|
|
|
|
To query the basic capabilities of a surface, needed in order to create a
|
|
swapchain, call:
|
|
|
|
include::../../api/protos/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.txt[]
|
|
|
|
* pname:physicalDevice is the physical device that will be associated with
|
|
the swapchain to be created, as described for
|
|
flink:vkCreateSwapchainKHR.
|
|
* pname:surface is the surface that will be associated with the swapchain.
|
|
* pname:pSurfaceCapabilities is a pointer to an instance of the
|
|
slink:VkSurfaceCapabilitiesKHR structure in which the capabilities are
|
|
returned.
|
|
|
|
include::../../validity/protos/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkSurfaceCapabilitiesKHR',desc='Structure describing capabilities of a surface',type='structs']
|
|
--
|
|
|
|
The sname:VkSurfaceCapabilitiesKHR structure is defined as:
|
|
|
|
include::../../api/structs/VkSurfaceCapabilitiesKHR.txt[]
|
|
|
|
* pname:minImageCount is the minimum number of images the specified device
|
|
supports for a swapchain created for the surface, and will be at least
|
|
one.
|
|
* pname: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 pname: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.
|
|
* pname:currentExtent is the current width and height of the surface, or
|
|
the special value [eq]#(0xFFFFFFFF, 0xFFFFFFFF)# indicating that the
|
|
surface size will be determined by the extent of a swapchain targeting
|
|
the surface.
|
|
* pname:minImageExtent contains the smallest valid swapchain extent for
|
|
the surface on the specified device.
|
|
The pname:width and pname:height of the extent will each be less than or
|
|
equal to the corresponding pname:width and pname:height of
|
|
pname:currentExtent, unless pname:currentExtent has the special value
|
|
described above.
|
|
* pname:maxImageExtent contains the largest valid swapchain extent for the
|
|
surface on the specified device.
|
|
The pname:width and pname:height of the extent will each be greater than
|
|
or equal to the corresponding pname:width and pname:height of
|
|
pname:minImageExtent.
|
|
The pname:width and pname:height of the extent will each be greater than
|
|
or equal to the corresponding pname:width and pname:height of
|
|
pname:currentExtent, unless pname:currentExtent has the special value
|
|
described above.
|
|
* pname: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.
|
|
* pname:supportedTransforms is a bitmask of
|
|
elink:VkSurfaceTransformFlagBitsKHR indicating the presentation
|
|
transforms supported for the surface on the specified device.
|
|
At least one bit will be set.
|
|
* pname:currentTransform is elink:VkSurfaceTransformFlagBitsKHR value
|
|
indicating the surface's current transform relative to the presentation
|
|
engine's natural orientation.
|
|
* pname:supportedCompositeAlpha is a bitmask of
|
|
elink:VkCompositeAlphaFlagBitsKHR, 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.
|
|
* pname:supportedUsageFlags is a bitmask of elink:VkImageUsageFlagBits
|
|
representing the ways the application can: use the presentable images of
|
|
a swapchain created
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
with elink:VkPresentModeKHR set to ename:VK_PRESENT_MODE_IMMEDIATE_KHR,
|
|
ename:VK_PRESENT_MODE_MAILBOX_KHR, ename:VK_PRESENT_MODE_FIFO_KHR or
|
|
ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
for the surface on the specified device.
|
|
ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT must: be included in the set
|
|
but implementations may: support additional usages.
|
|
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Supported usage flags of a presentable image when using
|
|
ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or
|
|
ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR presentation mode are
|
|
provided by
|
|
slink:VkSharedPresentSurfaceCapabilitiesKHR::pname:sharedPresentSupportedUsageFlags.
|
|
====
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
Formulas such as [eq]#min(N, pname:maxImageCount)# are not correct, since
|
|
pname:maxImageCount may: be zero.
|
|
====
|
|
|
|
include::../../validity/structs/VkSurfaceCapabilitiesKHR.txt[]
|
|
--
|
|
|
|
ifdef::VK_KHR_get_surface_capabilities2[]
|
|
|
|
[open,refpage='vkGetPhysicalDeviceSurfaceCapabilities2KHR',desc='Reports capabilities of a surface on a physical device',type='protos']
|
|
--
|
|
|
|
To query the basic capabilities of a surface defined by the core or
|
|
extensions, call:
|
|
|
|
include::../../api/protos/vkGetPhysicalDeviceSurfaceCapabilities2KHR.txt[]
|
|
|
|
* pname:physicalDevice is the physical device that will be associated with
|
|
the swapchain to be created, as described for
|
|
flink:vkCreateSwapchainKHR.
|
|
* pname:pSurfaceInfo points to an instance of the
|
|
slink:VkPhysicalDeviceSurfaceInfo2KHR structure, describing the surface
|
|
and other fixed parameters that would be consumed by
|
|
flink:vkCreateSwapchainKHR.
|
|
* pname:pSurfaceCapabilities points to an instance of the
|
|
slink:VkSurfaceCapabilities2KHR structure in which the capabilities are
|
|
returned.
|
|
|
|
fname:vkGetPhysicalDeviceSurfaceCapabilities2KHR behaves similarly to
|
|
flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with the ability to specify
|
|
extended inputs via chained input structures, and to return extended
|
|
information via chained output structures.
|
|
|
|
include::../../validity/protos/vkGetPhysicalDeviceSurfaceCapabilities2KHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPhysicalDeviceSurfaceInfo2KHR',desc='Structure specifying a surface and related swapchain creation parameters',type='structs']
|
|
--
|
|
|
|
The sname:VkPhysicalDeviceSurfaceInfo2KHR structure is defined as:
|
|
|
|
include::../../api/structs/VkPhysicalDeviceSurfaceInfo2KHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:surface is the surface that will be associated with the swapchain.
|
|
|
|
The members of sname:VkPhysicalDeviceSurfaceInfo2KHR correspond to the
|
|
arguments to flink:vkGetPhysicalDeviceSurfaceCapabilitiesKHR, with
|
|
pname:sType and pname:pNext added for extensibility.
|
|
|
|
include::../../validity/structs/VkPhysicalDeviceSurfaceInfo2KHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkSurfaceCapabilities2KHR',desc='Structure describing capabilities of a surface',type='structs']
|
|
--
|
|
|
|
The sname:VkSurfaceCapabilities2KHR structure is defined as:
|
|
|
|
include::../../api/structs/VkSurfaceCapabilities2KHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:surfaceCapabilities is a structure of type
|
|
slink:VkSurfaceCapabilitiesKHR describing the capabilities of the
|
|
specified surface.
|
|
|
|
include::../../validity/structs/VkSurfaceCapabilities2KHR.txt[]
|
|
--
|
|
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
[open,refpage='VkSharedPresentSurfaceCapabilitiesKHR',desc='structure describing capabilities of a surface for shared presentation',type='structs']
|
|
--
|
|
|
|
The sname:VkSharedPresentSurfaceCapabilitiesKHR structure is defined as:
|
|
|
|
include::../../api/structs/VkSharedPresentSurfaceCapabilitiesKHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:sharedPresentSupportedUsageFlags is a bitmask of
|
|
elink:VkImageUsageFlagBits representing the ways the application can:
|
|
use the shared presentable image from a swapchain created with
|
|
elink:VkPresentModeKHR set to
|
|
ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR or
|
|
ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR for the surface on
|
|
the specified device.
|
|
ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT must: be included in the set
|
|
but implementations may: support additional usages.
|
|
|
|
include::../../validity/structs/VkSharedPresentSurfaceCapabilitiesKHR.txt[]
|
|
|
|
--
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
endif::VK_KHR_get_surface_capabilities2[]
|
|
|
|
ifdef::VK_EXT_display_surface_counter[]
|
|
include::../VK_EXT_display_surface_counter/surface_capabilities.txt[]
|
|
endif::VK_EXT_display_surface_counter[]
|
|
|
|
[open,refpage='VkSurfaceTransformFlagBitsKHR',desc='presentation transforms supported on a device',type='enums']
|
|
--
|
|
|
|
Bits which may: be set in
|
|
slink:VkSurfaceCapabilitiesKHR::pname:supportedTransforms indicating the
|
|
presentation transforms supported for the surface on the specified device,
|
|
and possible values of
|
|
slink:VkSurfaceCapabilitiesKHR::pname:currentTransform is indicating the
|
|
surface's current transform relative to the presentation engine's natural
|
|
orientation, are:
|
|
|
|
include::../../api/enums/VkSurfaceTransformFlagBitsKHR.txt[]
|
|
|
|
* ename:VK_SURFACE_TRANSFORM_IDENTITY_BIT_KHR specifies that image content
|
|
is presented without being transformed.
|
|
* ename:VK_SURFACE_TRANSFORM_ROTATE_90_BIT_KHR specifies that image
|
|
content is rotated 90 degrees clockwise.
|
|
* ename:VK_SURFACE_TRANSFORM_ROTATE_180_BIT_KHR specifies that image
|
|
content is rotated 180 degrees clockwise.
|
|
* ename:VK_SURFACE_TRANSFORM_ROTATE_270_BIT_KHR specifies that image
|
|
content is rotated 270 degrees clockwise.
|
|
* ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_BIT_KHR specifies that
|
|
image content is mirrored horizontally.
|
|
* ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_90_BIT_KHR specifies
|
|
that image content is mirrored horizontally, then rotated 90 degrees
|
|
clockwise.
|
|
* ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_180_BIT_KHR
|
|
specifies that image content is mirrored horizontally, then rotated 180
|
|
degrees clockwise.
|
|
* ename:VK_SURFACE_TRANSFORM_HORIZONTAL_MIRROR_ROTATE_270_BIT_KHR
|
|
specifies that image content is mirrored horizontally, then rotated 270
|
|
degrees clockwise.
|
|
* ename:VK_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.
|
|
|
|
--
|
|
|
|
[open,refpage='VkSurfaceTransformFlagsKHR',desc='Bitmask of VkSurfaceTransformFlagBitsKHR',type='enums']
|
|
--
|
|
include::../../api/flags/VkSurfaceTransformFlagsKHR.txt[]
|
|
|
|
sname:VkSurfaceTransformFlagsKHR is a bitmask type for setting a mask of
|
|
zero or more slink:VkSurfaceTransformFlagBitsKHR.
|
|
--
|
|
|
|
|
|
[open,refpage='VkCompositeAlphaFlagBitsKHR',desc='alpha compositing modes supported on a device',type='enums']
|
|
--
|
|
|
|
The pname:supportedCompositeAlpha member is of type
|
|
elink:VkCompositeAlphaFlagBitsKHR, which contains the following values:
|
|
|
|
include::../../api/enums/VkCompositeAlphaFlagBitsKHR.txt[]
|
|
|
|
These values are described as follows:
|
|
|
|
* ename:VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha channel, 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.
|
|
* ename:VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha channel, if
|
|
it exists, of the images is respected in the compositing process.
|
|
The non-alpha channels of the image are expected to already be
|
|
multiplied by the alpha channel by the application.
|
|
* ename:VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha channel, if
|
|
it exists, of the images is respected in the compositing process.
|
|
The non-alpha channels of the image are not expected to already be
|
|
multiplied by the alpha channel by the application; instead, the
|
|
compositor will multiply the non-alpha channels of the image by the
|
|
alpha channel during compositing.
|
|
* ename:VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the
|
|
presentation engine treats the alpha channel 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.
|
|
|
|
--
|
|
|
|
[open,refpage='VkCompositeAlphaFlagsKHR',desc='Bitmask of VkCompositeAlphaFlagBitsKHR',type='enums']
|
|
--
|
|
include::../../api/flags/VkCompositeAlphaFlagsKHR.txt[]
|
|
|
|
sname:VkCompositeAlphaFlagsKHR is a bitmask type for setting a mask of zero
|
|
or more slink:VkCompositeAlphaFlagBitsKHR.
|
|
--
|
|
|
|
[open,refpage='vkGetPhysicalDeviceSurfaceFormatsKHR',desc='Query color formats supported by surface',type='protos']
|
|
--
|
|
|
|
To query the supported swapchain format-color space pairs for a surface,
|
|
call:
|
|
|
|
include::../../api/protos/vkGetPhysicalDeviceSurfaceFormatsKHR.txt[]
|
|
|
|
* pname:physicalDevice is the physical device that will be associated with
|
|
the swapchain to be created, as described for
|
|
flink:vkCreateSwapchainKHR.
|
|
* pname:surface is the surface that will be associated with the swapchain.
|
|
* pname:pSurfaceFormatCount is a pointer to an integer related to the
|
|
number of format pairs available or queried, as described below.
|
|
* pname:pSurfaceFormats is either `NULL` or a pointer to an array of
|
|
sname:VkSurfaceFormatKHR structures.
|
|
|
|
If pname:pSurfaceFormats is `NULL`, then the number of format pairs
|
|
supported for the given pname:surface is returned in
|
|
pname:pSurfaceFormatCount.
|
|
The number of format pairs supported will be greater than or equal to 1.
|
|
Otherwise, pname:pSurfaceFormatCount must: point to a variable set by the
|
|
user to the number of elements in the pname:pSurfaceFormats array, and on
|
|
return the variable is overwritten with the number of structures actually
|
|
written to pname:pSurfaceFormats.
|
|
If the value of pname:pSurfaceFormatCount is less than the number of format
|
|
pairs supported, at most pname:pSurfaceFormatCount structures will be
|
|
written.
|
|
If pname:pSurfaceFormatCount is smaller than the number of format pairs
|
|
supported for the given pname:surface, ename:VK_INCOMPLETE will be returned
|
|
instead of ename:VK_SUCCESS to indicate that not all the available values
|
|
were returned.
|
|
|
|
include::../../validity/protos/vkGetPhysicalDeviceSurfaceFormatsKHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkSurfaceFormatKHR',desc='Structure describing a supported swapchain format-color space pair',type='structs']
|
|
--
|
|
|
|
The sname:VkSurfaceFormatKHR structure is defined as:
|
|
|
|
include::../../api/structs/VkSurfaceFormatKHR.txt[]
|
|
|
|
* pname:format is a elink:VkFormat that is compatible with the specified
|
|
surface.
|
|
* pname:colorSpace is a presentation elink:VkColorSpaceKHR that is
|
|
compatible with the surface.
|
|
|
|
include::../../validity/structs/VkSurfaceFormatKHR.txt[]
|
|
--
|
|
|
|
ifdef::VK_KHR_get_surface_capabilities2[]
|
|
|
|
[open,refpage='vkGetPhysicalDeviceSurfaceFormats2KHR',desc='Query color formats supported by surface',type='protos']
|
|
--
|
|
|
|
To query the supported swapchain format tuples for a surface, call:
|
|
|
|
include::../../api/protos/vkGetPhysicalDeviceSurfaceFormats2KHR.txt[]
|
|
|
|
* pname:physicalDevice is the physical device that will be associated with
|
|
the swapchain to be created, as described for
|
|
flink:vkCreateSwapchainKHR.
|
|
* pname:pSurfaceInfo points to an instance of the
|
|
slink:VkPhysicalDeviceSurfaceInfo2KHR structure, describing the surface
|
|
and other fixed parameters that would be consumed by
|
|
flink:vkCreateSwapchainKHR.
|
|
* pname:pSurfaceFormatCount is a pointer to an integer related to the
|
|
number of format tuples available or queried, as described below.
|
|
* pname:pSurfaceFormats is either `NULL` or a pointer to an array of
|
|
slink:VkSurfaceFormat2KHR structures.
|
|
|
|
If pname:pSurfaceFormats is `NULL`, then the number of format tuples
|
|
supported for the given pname:surface is returned in
|
|
pname:pSurfaceFormatCount.
|
|
The number of format tuples supported will be greater than or equal to 1.
|
|
Otherwise, pname:pSurfaceFormatCount must: point to a variable set by the
|
|
user to the number of elements in the pname:pSurfaceFormats array, and on
|
|
return the variable is overwritten with the number of structures actually
|
|
written to pname:pSurfaceFormats.
|
|
If the value of pname:pSurfaceFormatCount is less than the number of format
|
|
tuples supported, at most pname:pSurfaceFormatCount structures will be
|
|
written.
|
|
If pname:pSurfaceFormatCount is smaller than the number of format tuples
|
|
supported for the surface parameters described in pname:pSurfaceInfo,
|
|
ename:VK_INCOMPLETE will be returned instead of ename:VK_SUCCESS to indicate
|
|
that not all the available values were returned.
|
|
|
|
include::../../validity/protos/vkGetPhysicalDeviceSurfaceFormats2KHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkSurfaceFormat2KHR',desc='Structure describing a supported swapchain format tuple',type='structs']
|
|
--
|
|
|
|
The sname:VkSurfaceFormat2KHR structure is defined as:
|
|
|
|
include::../../api/structs/VkSurfaceFormat2KHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:surfaceFormat is an instance of slink:VkSurfaceFormatKHR
|
|
describing a format-color space pair that is compatible with the
|
|
specified surface.
|
|
|
|
include::../../validity/structs/VkSurfaceFormat2KHR.txt[]
|
|
--
|
|
|
|
endif::VK_KHR_get_surface_capabilities2[]
|
|
|
|
While the pname:format of a presentable image refers to the encoding of each
|
|
pixel, the pname:colorSpace determines how the presentation engine
|
|
interprets the pixel values.
|
|
A color space in this document refers to a specific color space (defined by
|
|
the chromaticities of its primaries and a white point in CIE Lab), and a
|
|
transfer function that is applied before storing or transmitting color data
|
|
in the given color space.
|
|
|
|
[open,refpage='VkColorSpaceKHR',desc='supported color space of the presentation engine',type='enums']
|
|
--
|
|
|
|
Possible values of slink:VkSurfaceFormatKHR::pname:colorSpace, specifying
|
|
supported color spaces of a presentation engine, are:
|
|
|
|
include::../../api/enums/VkColorSpaceKHR.txt[]
|
|
|
|
* ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR specifies support for the sRGB
|
|
color space.
|
|
ifdef::VK_EXT_swapchain_colorspace[]
|
|
* ename:VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT specifies support for the
|
|
Display-P3 color space and applies an sRGB-like transfer function
|
|
(defined below).
|
|
* ename:VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT specifies support for the
|
|
extended sRGB color space and applies a linear transfer function.
|
|
* ename:VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT specifies support for
|
|
the extended sRGB color space and applies an sRGB transfer function.
|
|
* ename:VK_COLOR_SPACE_DCI_P3_LINEAR_EXT specifies support for the DCI-P3
|
|
color space and applies a linear OETF.
|
|
* ename:VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT specifies support for the
|
|
DCI-P3 color space and applies the Gamma 2.6 OETF.
|
|
* ename:VK_COLOR_SPACE_BT709_LINEAR_EXT specifies support for the BT709
|
|
color space and applies a linear OETF.
|
|
* ename:VK_COLOR_SPACE_BT709_NONLINEAR_EXT specifies support for the BT709
|
|
color space and applies the SMPTE 170M OETF.
|
|
* ename:VK_COLOR_SPACE_BT2020_LINEAR_EXT specifies support for the BT2020
|
|
color space and applies a linear OETF.
|
|
* ename:VK_COLOR_SPACE_HDR10_ST2084_EXT specifies support for the HDR10
|
|
(BT2020 color) space and applies the SMPTE ST2084 Perceptual Quantizer
|
|
(PQ) OETF.
|
|
* ename:VK_COLOR_SPACE_DOLBYVISION_EXT specifies support for the Dolby
|
|
Vision (BT2020 color space), proprietary encoding, and applies the SMPTE
|
|
ST2084 OETF.
|
|
* ename:VK_COLOR_SPACE_HDR10_HLG_EXT specifies support for the HDR10
|
|
(BT2020 color space) and applies the Hybrid Log Gamma (HLG) OETF.
|
|
* ename:VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT specifies support for the
|
|
AdobeRGB color space and applies a linear OETF.
|
|
* ename:VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT specifies support for the
|
|
AdobeRGB color space and applies the Gamma 2.2 OETF.
|
|
* ename:VK_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.
|
|
|
|
The color components of Non-linear color space swap chain images have had
|
|
the appropriate transfer function applied.
|
|
Vulkan requires that all implementations support the sRGB transfer function
|
|
when using an SRGB pixel format.
|
|
Other transfer functions, such as SMPTE 170M or SMPTE2084, must: not be
|
|
performed by the implementation, but can: be performed by the application
|
|
shader.
|
|
This extension defines enums for elink:VkColorSpaceKHR that correspond to
|
|
the following color spaces:
|
|
|
|
[[VK_EXT_swapchain_colorspace-table]]
|
|
.Color Spaces and Attributes
|
|
[options="header"]
|
|
|====
|
|
| Name | Red Primary | Green Primary | Blue Primary | White-point | Transfer function
|
|
| DCI-P3 | 0.680, 0.320 | 0.265, 0.690 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | Gamma 2.6
|
|
| 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) | 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
|
|
| DOLBYVISION | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | ST2084
|
|
| 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
|
|
|====
|
|
|
|
For Opto-Electrical Transfer Function (OETF), unless otherwise specified,
|
|
the values of [eq]#L# and [eq]#E# are defined as:
|
|
|
|
[eq]#L# - linear luminance of image latexmath:[0 \leq L \leq 1] for
|
|
conventional colorimetry
|
|
|
|
[eq]#E# - corresponding electrical signal (value stored in memory)
|
|
|
|
// @@@ The ref page is ended earlier than in the original markup due to
|
|
// asciidoctor issues described in internal MR 2201.
|
|
endif::VK_EXT_swapchain_colorspace[]
|
|
|
|
--
|
|
|
|
ifdef::VK_EXT_swapchain_colorspace[]
|
|
|
|
=== sRGB transfer function
|
|
|
|
[latexmath]
|
|
+++++++++++++++++++
|
|
\begin{aligned}
|
|
E & =
|
|
\begin{cases}
|
|
1.055 \times L^{1 \over 2.4} - 0.055 & \text{for}\ 0.0031308 \leq L \leq 1 \\
|
|
12.92 \times L & \text{for}\ 0 \leq L < 0.0031308
|
|
\end{cases}
|
|
\end{aligned}
|
|
+++++++++++++++++++
|
|
|
|
|
|
=== Display-P3 EOTF
|
|
|
|
[latexmath]
|
|
+++++++++++++++++++
|
|
\begin{aligned}
|
|
E & =
|
|
\begin{cases}
|
|
(a \times L + b)^{2.4} & \text{for}\ 0.039 \leq L \leq 1 \\
|
|
b \times L & \text{for}\ 0 \leq L < 0.039
|
|
\end{cases}
|
|
\end{aligned}
|
|
+++++++++++++++++++
|
|
|
|
latexmath:[a = 0.948] +
|
|
latexmath:[b = 0.052] +
|
|
latexmath:[c = 0.077] +
|
|
|
|
|
|
=== Display-P3 OETF
|
|
|
|
[latexmath]
|
|
+++++++++++++++++++
|
|
\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
|
|
\end{cases}
|
|
\end{aligned}
|
|
+++++++++++++++++++
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
For most uses, the sRGB OETF is equivalent.
|
|
====
|
|
|
|
|
|
=== Extended sRGB OETF
|
|
|
|
[latexmath]
|
|
+++++++++++++++++++
|
|
\begin{aligned}
|
|
E & =
|
|
\begin{cases}
|
|
1.055 \times L^{1 \over 2.4} - 0.055 & \text{for}\ 0.0031308 \leq L \leq 7.5913 \\
|
|
12.92 \times L & \text{for}\ 0 \leq L < 0.0031308 \\
|
|
-f(-L) & \text{for}\ L < 0
|
|
\end{cases}
|
|
\end{aligned}
|
|
+++++++++++++++++++
|
|
|
|
[eq]#L# - luminance of image is within [eq]#[-0.6038, 7.5913]#.
|
|
|
|
[eq]#E# can be negative and/or > 1.
|
|
That is how extended sRGB specifies colors outside the standard sRGB gamut.
|
|
This means extended sRGB needs a floating point pixel format to cover the
|
|
intended color range.
|
|
|
|
|
|
=== SMPTE 170M OETF
|
|
|
|
[latexmath]
|
|
+++++++++++++++++++
|
|
\begin{aligned}
|
|
E & =
|
|
\begin{cases}
|
|
\alpha \times L^{0.45} - (1 - \alpha) & \text{for}\ \beta \leq L \leq 1 \\
|
|
4.5 \times L & \text{for}\ 0 \leq L < \beta
|
|
\end{cases}
|
|
\end{aligned}
|
|
+++++++++++++++++++
|
|
|
|
latexmath:[\alpha = 1.099 \text{ and } \beta = 0.018 \text{ for 10-bits and
|
|
less per sample system (the values given in Rec.
|
|
709)}] +
|
|
latexmath:[\alpha = 1.0993 \text{ and } \beta = 0.0181 \text{ for 12-bits
|
|
per sample system}]
|
|
|
|
|
|
=== SMPTE ST2084 OETF (Inverse-EOTF)
|
|
|
|
[latexmath]
|
|
+++++++++++++++++++
|
|
\[
|
|
E = (\frac{c_1 + c_2 \times L^{m_1}}{1 + c_3 \times L^{m_1}})^{m_2}
|
|
\]
|
|
+++++++++++++++++++
|
|
|
|
where:
|
|
|
|
latexmath:[m_1 = 2610 / 4096 \times \frac{1}{4} = 0.1593017578125] +
|
|
latexmath:[m_2 = 2523 / 4096 \times 128 = 78.84375] +
|
|
latexmath:[c_1 = 3424 / 4096 = 0.8359375 = c3 - c2 + 1] +
|
|
latexmath:[c_2 = 2413 / 4096 \times 32 = 18.8515625] +
|
|
latexmath:[c_3 = 2392 / 4096 \times 32 = 18.6875] +
|
|
|
|
|
|
=== Hybrid Log Gamma (HLG)
|
|
|
|
[latexmath]
|
|
+++++++++++++++++++
|
|
\begin{aligned}
|
|
E & =
|
|
\begin{cases}
|
|
r \sqrt{L} & \text{for}\ 0 \leq L \leq 1 \\
|
|
a \times \ln(L - b) + c & \text{for}\ 1 < L
|
|
\end{cases}
|
|
\end{aligned}
|
|
+++++++++++++++++++
|
|
|
|
[eq]#_L_# -- is the signal normalized by the reference white level +
|
|
[eq]#_r_# -- is the reference white level and has a signal value of 0.5 +
|
|
[eq]#_a_ = 0.17883277# and [eq]#_b_ = 0.28466892# and [eq]#_c_ = 0.55991073#
|
|
|
|
|
|
=== Adobe RGB (1998) OETF
|
|
|
|
latexmath:[E = L^\frac{1}{2.19921875}]
|
|
|
|
|
|
=== Gamma 2.6 OETF
|
|
|
|
latexmath:[E = L^\frac{1}{2.6}]
|
|
|
|
An implementation supporting this extension indicates support for these
|
|
color spaces via slink:VkSurfaceFormatKHR structures returned from
|
|
flink:vkGetPhysicalDeviceSurfaceFormatsKHR.
|
|
|
|
Specifying the supported surface color space when calling
|
|
flink:vkCreateSwapchainKHR will create a swapchain using that color space.
|
|
|
|
Vulkan requires that all implementations support the sRGB Opto-Electrical
|
|
Transfer Function (OETF) and Electro-optical transfer function (EOTF) when
|
|
using an SRGB pixel format.
|
|
Other transfer functions, such as SMPTE 170M, must: not be performed by the
|
|
implementation, but can: be performed by the application shader.
|
|
|
|
endif::VK_EXT_swapchain_colorspace[]
|
|
|
|
If pname:pSurfaceFormats includes an entry whose value for pname:colorSpace
|
|
is ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR and whose value for pname:format
|
|
is a UNORM (or SRGB) format and the corresponding SRGB (or UNORM) format is
|
|
a color renderable format for ename:VK_IMAGE_TILING_OPTIMAL, then
|
|
pname:pSurfaceFormats must: also contain an entry with the same value for
|
|
pname:colorSpace and pname:format equal to the corresponding SRGB (or UNORM)
|
|
format.
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
If pname:pSurfaceFormats includes just one entry, whose value for
|
|
pname:format is ename:VK_FORMAT_UNDEFINED, pname:surface has no preferred
|
|
format.
|
|
In this case, the application can: use any valid elink:VkFormat value.
|
|
====
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
In the initial release of the `VK_KHR_surface` and `<<VK_KHR_swapchain>>`
|
|
extensions, the token ename:VK_COLORSPACE_SRGB_NONLINEAR_KHR was used.
|
|
Starting in the 2016-05-13 updates to the extension branches, matching
|
|
release 1.0.13 of the core API specification,
|
|
ename:VK_COLOR_SPACE_SRGB_NONLINEAR_KHR is used instead for consistency with
|
|
Vulkan naming rules.
|
|
The older enum is still available for backwards compatibility.
|
|
====
|
|
|
|
// @@@ originally, the VkColorSpaceKHR ref page ended here
|
|
// --
|
|
|
|
[open,refpage='vkGetPhysicalDeviceSurfacePresentModesKHR',desc='Query supported presentation modes',type='protos']
|
|
--
|
|
|
|
To query the supported presentation modes for a surface, call:
|
|
|
|
include::../../api/protos/vkGetPhysicalDeviceSurfacePresentModesKHR.txt[]
|
|
|
|
* pname:physicalDevice is the physical device that will be associated with
|
|
the swapchain to be created, as described for
|
|
flink:vkCreateSwapchainKHR.
|
|
* pname:surface is the surface that will be associated with the swapchain.
|
|
* pname:pPresentModeCount is a pointer to an integer related to the number
|
|
of presentation modes available or queried, as described below.
|
|
* pname:pPresentModes is either `NULL` or a pointer to an array of
|
|
elink:VkPresentModeKHR values, indicating the supported presentation
|
|
modes.
|
|
|
|
If pname:pPresentModes is `NULL`, then the number of presentation modes
|
|
supported for the given pname:surface is returned in
|
|
pname:pPresentModeCount.
|
|
Otherwise, pname:pPresentModeCount must: point to a variable set by the user
|
|
to the number of elements in the pname:pPresentModes array, and on return
|
|
the variable is overwritten with the number of values actually written to
|
|
pname:pPresentModes.
|
|
If the value of pname:pPresentModeCount is less than the number of
|
|
presentation modes supported, at most pname:pPresentModeCount values will be
|
|
written.
|
|
If pname:pPresentModeCount is smaller than the number of presentation modes
|
|
supported for the given pname:surface, ename:VK_INCOMPLETE will be returned
|
|
instead of ename:VK_SUCCESS to indicate that not all the available values
|
|
were returned.
|
|
|
|
include::../../validity/protos/vkGetPhysicalDeviceSurfacePresentModesKHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkPresentModeKHR',desc='presentation mode supported for a surface',type='enums']
|
|
--
|
|
|
|
Possible values of elements of the
|
|
flink:vkGetPhysicalDeviceSurfacePresentModesKHR::pname:pPresentModes array,
|
|
indicating the supported presentation modes for a surface, are:
|
|
|
|
include::../../api/enums/VkPresentModeKHR.txt[]
|
|
|
|
* ename:VK_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.
|
|
* ename:VK_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 re-use by the application.
|
|
One request is removed from the queue and processed during each vertical
|
|
blanking period in which the queue is non-empty.
|
|
* ename:VK_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 pname:presentMode that is required: to be
|
|
supported.
|
|
* ename:VK_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.
|
|
ifdef::VK_KHR_shared_presentable_image[]
|
|
* ename:VK_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.
|
|
* ename:VK_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 elink:VkImageUsageFlagBits 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
|
|
[width="100%",cols="<50%,<50%",options="header"]
|
|
|====
|
|
| Presentation mode | Image usage flags
|
|
| ename:VK_PRESENT_MODE_IMMEDIATE_KHR | slink:VkSurfaceCapabilitiesKHR::pname:supportedUsageFlags
|
|
| ename:VK_PRESENT_MODE_MAILBOX_KHR | slink:VkSurfaceCapabilitiesKHR::pname:supportedUsageFlags
|
|
| ename:VK_PRESENT_MODE_FIFO_KHR | slink:VkSurfaceCapabilitiesKHR::pname:supportedUsageFlags
|
|
| ename:VK_PRESENT_MODE_FIFO_RELAXED_KHR | slink:VkSurfaceCapabilitiesKHR::pname:supportedUsageFlags
|
|
| ename:VK_PRESENT_MODE_SHARED_DEMAND_REFRESH_KHR | slink:VkSharedPresentSurfaceCapabilitiesKHR::pname:sharedPresentSupportedUsageFlags
|
|
| ename:VK_PRESENT_MODE_SHARED_CONTINUOUS_REFRESH_KHR | slink:VkSharedPresentSurfaceCapabilitiesKHR::pname:sharedPresentSupportedUsageFlags
|
|
|====
|
|
endif::VK_KHR_shared_presentable_image[]
|
|
|
|
[NOTE]
|
|
.Note
|
|
====
|
|
For reference, the mode indicated by ename:VK_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 ename:VK_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).
|
|
====
|
|
|
|
--
|
|
|
|
ifdef::VK_KHR_swapchain[]
|
|
ifdef::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
|
|
|
|
== Device Group Queries
|
|
|
|
[open,refpage='vkGetDeviceGroupPresentCapabilitiesKHR',desc='Query present capabilities from other physical devices',type='protos']
|
|
--
|
|
|
|
A logical device that represents multiple physical devices may: support
|
|
presenting from images on more than one physical device, or combining images
|
|
from multiple physical devices.
|
|
|
|
To query these capabilities, call:
|
|
|
|
include::../../api/protos/vkGetDeviceGroupPresentCapabilitiesKHR.txt[]
|
|
|
|
* pname:device is the logical device.
|
|
* pname:pDeviceGroupPresentCapabilities is a pointer to a structure of
|
|
type slink:VkDeviceGroupPresentCapabilitiesKHR that is filled with the
|
|
logical device's capabilities.
|
|
|
|
include::../../validity/protos/vkGetDeviceGroupPresentCapabilitiesKHR.txt[]
|
|
--
|
|
|
|
[open,refpage='VkDeviceGroupPresentCapabilitiesKHR',desc='Present capabilities from other physical devices',type='structs']
|
|
--
|
|
|
|
The sname:VkDeviceGroupPresentCapabilitiesKHR structure is defined as:
|
|
|
|
include::../../api/structs/VkDeviceGroupPresentCapabilitiesKHR.txt[]
|
|
|
|
* pname:sType is the type of this structure.
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
|
* pname:presentMask is an array of masks, where the mask at element
|
|
[eq]#i# is non-zero if physical device [eq]#i# has a presentation
|
|
engine, and where bit [eq]#j# is set in element [eq]#i# if physical
|
|
device [eq]#i# can: present swapchain images from physical device
|
|
[eq]#j#.
|
|
If element [eq]#i# is non-zero, then bit [eq]#i# must: be set.
|
|
* pname:modes is a bitmask of elink:VkDeviceGroupPresentModeFlagBitsKHR
|
|
indicating which device group presentation modes are supported.
|
|
|
|
pname:modes always has ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR set.
|
|
|
|
The present mode flags are also used when presenting an image, in
|
|
slink:VkDeviceGroupPresentInfoKHR::pname:mode.
|
|
|
|
If a device group only includes a single physical device, then pname:modes
|
|
must: equal ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR.
|
|
|
|
include::../../validity/structs/VkDeviceGroupPresentCapabilitiesKHR.txt[]
|
|
--
|
|
|
|
|
|
[open,refpage='VkDeviceGroupPresentModeFlagBitsKHR',desc='Bitmask specifying supported device group present modes',type='enums']
|
|
--
|
|
|
|
Bits which may: be set in
|
|
slink:VkDeviceGroupPresentCapabilitiesKHR::pname:modes to indicate which
|
|
device group presentation modes are supported are:
|
|
|
|
include::../../api/enums/VkDeviceGroupPresentModeFlagBitsKHR.txt[]
|
|
|
|
* ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_BIT_KHR specifies that any
|
|
physical device with a presentation engine can: present its own
|
|
swapchain images.
|
|
* ename:VK_DEVICE_GROUP_PRESENT_MODE_REMOTE_BIT_KHR specifies that any
|
|
physical device with a presentation engine can: present swapchain images
|
|
from any physical device in its pname:presentMask.
|
|
* ename:VK_DEVICE_GROUP_PRESENT_MODE_SUM_BIT_KHR specifies that any
|
|
physical device with a presentation engine can: present the sum of
|
|
swapchain images from any physical devices in its pname:presentMask.
|
|
* ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR specifies
|
|
that multiple physical devices with a presentation engine can: each
|
|
present their own swapchain images.
|
|
|
|
--
|
|
|
|
[open,refpage='VkDeviceGroupPresentModeFlagsKHR',desc='Bitmask of VkDeviceGroupPresentModeFlagBitsKHR',type='enums']
|
|
--
|
|
include::../../api/flags/VkDeviceGroupPresentModeFlagsKHR.txt[]
|
|
|
|
sname:VkDeviceGroupPresentModeFlagsKHR is a bitmask type for setting a mask
|
|
of zero or more slink:VkDeviceGroupPresentModeFlagBitsKHR.
|
|
--
|
|
|
|
[open,refpage='vkGetDeviceGroupSurfacePresentModesKHR',desc='Query present capabilities for a surface',type='protos']
|
|
--
|
|
|
|
Some surfaces may: not be capable of using all the device group present
|
|
modes.
|
|
|
|
To query the supported device group present modes for a particular surface,
|
|
call:
|
|
|
|
include::../../api/protos/vkGetDeviceGroupSurfacePresentModesKHR.txt[]
|
|
|
|
* pname:device is the logical device.
|
|
* pname:surface is the surface.
|
|
* pname:pModes is a pointer to a value of type
|
|
sname:VkDeviceGroupPresentModeFlagsKHR that is filled with the supported
|
|
device group present modes for the surface.
|
|
|
|
The modes returned by this command are not invariant, and may: change in
|
|
response to the surface being moved, resized, or occluded.
|
|
These modes must: be a subset of the modes returned by
|
|
flink:vkGetDeviceGroupPresentCapabilitiesKHR.
|
|
|
|
include::../../validity/protos/vkGetDeviceGroupSurfacePresentModesKHR.txt[]
|
|
|
|
--
|
|
|
|
[open,refpage='vkGetPhysicalDevicePresentRectanglesKHR',desc='Query present rectangles for a surface on a physical device',type='protos']
|
|
--
|
|
|
|
When using ename:VK_DEVICE_GROUP_PRESENT_MODE_LOCAL_MULTI_DEVICE_BIT_KHR,
|
|
the application may: need to know which regions of the surface are used when
|
|
presenting locally on each physical device.
|
|
Presentation of swapchain images to this surface need only have valid
|
|
contents in the regions returned by this command.
|
|
|
|
To query a set of rectangles used in presentation on the physical device,
|
|
call:
|
|
|
|
include::../../api/protos/vkGetPhysicalDevicePresentRectanglesKHR.txt[]
|
|
|
|
* pname:physicalDevice is the physical device.
|
|
* pname:surface is the surface.
|
|
* pname:pRectCount is a pointer to an integer related to the number of
|
|
rectangles available or queried, as described below.
|
|
* pname:pRects is either `NULL` or a pointer to an array of slink:VkRect2D
|
|
structures.
|
|
|
|
If pname:pRects is `NULL`, then the number of rectangles used when
|
|
presenting the given pname:surface is returned in pname:pRectCount.
|
|
Otherwise, pname:pRectCount must: point to a variable set by the user to the
|
|
number of elements in the pname:pRects array, and on return the variable is
|
|
overwritten with the number of structures actually written to pname:pRects.
|
|
If the value of pname:pRectCount is less than the number of rectangles, at
|
|
most pname:pRectCount structures will be written.
|
|
If pname:pRectCount is smaller than the number of rectangles used for the
|
|
given pname:surface, ename:VK_INCOMPLETE will be returned instead of
|
|
ename:VK_SUCCESS to indicate that not all the available values were
|
|
returned.
|
|
|
|
The values returned by this command are not invariant, and may: change in
|
|
response to the surface being moved, resized, or occluded.
|
|
|
|
The rectangles returned by this command must: not overlap.
|
|
|
|
include::../../validity/protos/vkGetPhysicalDevicePresentRectanglesKHR.txt[]
|
|
|
|
--
|
|
|
|
endif::VK_VERSION_1_1,VK_KHR_device_group[]
|
|
|
|
ifdef::VK_GOOGLE_display_timing[]
|
|
include::../VK_GOOGLE_display_timing/queries.txt[]
|
|
endif::VK_GOOGLE_display_timing[]
|
|
|
|
include::../VK_KHR_swapchain/wsi.txt[]
|
|
endif::VK_KHR_swapchain[]
|