| // 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_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_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[] |
