| // Copyright 2014-2021 The Khronos Group, Inc. |
| // |
| // SPDX-License-Identifier: CC-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, each containing |
| 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 |
| `{full_header}` header file, or |
| * include `{core_header}` 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::{generated}/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 structure containing 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 specification, when it exists. |
| However, the information is not relevant to users of the API nor does it |
| affect conformance of a Vulkan implementation. |
| ==== |
| endif::editing-notes[] |
| |
| ifdef::VK_KHR_android_surface[] |
| include::{chapters}/VK_KHR_android_surface/platformCreateSurface_android.txt[] |
| endif::VK_KHR_android_surface[] |
| |
| ifdef::VK_KHR_wayland_surface[] |
| include::{chapters}/VK_KHR_wayland_surface/platformCreateSurface_wayland.txt[] |
| endif::VK_KHR_wayland_surface[] |
| |
| ifdef::VK_KHR_win32_surface[] |
| include::{chapters}/VK_KHR_win32_surface/platformCreateSurface_win32.txt[] |
| endif::VK_KHR_win32_surface[] |
| |
| ifdef::VK_KHR_xcb_surface[] |
| include::{chapters}/VK_KHR_xcb_surface/platformCreateSurface_xcb.txt[] |
| endif::VK_KHR_xcb_surface[] |
| |
| ifdef::VK_KHR_xlib_surface[] |
| include::{chapters}/VK_KHR_xlib_surface/platformCreateSurface_xlib.txt[] |
| endif::VK_KHR_xlib_surface[] |
| |
| ifdef::VK_EXT_directfb_surface[] |
| include::{chapters}/VK_EXT_directfb_surface/platformCreateSurface_directfb.txt[] |
| endif::VK_EXT_directfb_surface[] |
| |
| ifdef::VK_FUCHSIA_imagepipe_surface[] |
| include::{chapters}/VK_FUCHSIA_imagepipe_surface/platformCreateSurface_imagepipe.txt[] |
| endif::VK_FUCHSIA_imagepipe_surface[] |
| |
| ifdef::VK_GGP_stream_descriptor_surface[] |
| include::{chapters}/VK_GGP_stream_descriptor_surface/platformCreateSurface_streamdescriptor.txt[] |
| endif::VK_GGP_stream_descriptor_surface[] |
| |
| ifdef::VK_MVK_ios_surface[] |
| include::{chapters}/VK_MVK_ios_surface/platformCreateSurface_ios.txt[] |
| endif::VK_MVK_ios_surface[] |
| |
| ifdef::VK_MVK_macos_surface[] |
| include::{chapters}/VK_MVK_macos_surface/platformCreateSurface_macos.txt[] |
| endif::VK_MVK_macos_surface[] |
| |
| ifdef::VK_NN_vi_surface[] |
| include::{chapters}/VK_NN_vi_surface/platformCreateSurface_vi.txt[] |
| endif::VK_NN_vi_surface[] |
| |
| ifdef::VK_EXT_metal_surface[] |
| include::{chapters}/VK_EXT_metal_surface/platformCreateSurface_metal.txt[] |
| endif::VK_EXT_metal_surface[] |
| |
| ifdef::VK_QNX_screen_surface[] |
| include::{chapters}/VK_QNX_screen_surface/platformCreateSurface_screen.txt[] |
| endif::VK_QNX_screen_surface[] |
| |
| === Platform-Independent Information |
| |
| Once created, sname:VkSurfaceKHR objects can: be used in this and other |
| extensions, in particular the `apiext: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::{generated}/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::{generated}/validity/protos/vkDestroySurfaceKHR.txt[] |
| -- |
| |
| ifdef::VK_KHR_display[] |
| include::{chapters}/VK_KHR_display/display.txt[] |
| endif::VK_KHR_display[] |
| |
| ifdef::VK_EXT_headless_surface[] |
| include::{chapters}/VK_EXT_headless_surface/headless.txt[] |
| endif::VK_EXT_headless_surface[] |
| |
| |
| == 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::{generated}/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::{generated}/validity/protos/vkGetPhysicalDeviceSurfaceSupportKHR.txt[] |
| -- |
| |
| ifdef::VK_KHR_android_surface[] |
| include::{chapters}/VK_KHR_android_surface/platformQuerySupport_android.txt[] |
| endif::VK_KHR_android_surface[] |
| |
| ifdef::VK_KHR_wayland_surface[] |
| include::{chapters}/VK_KHR_wayland_surface/platformQuerySupport_wayland.txt[] |
| endif::VK_KHR_wayland_surface[] |
| |
| ifdef::VK_KHR_win32_surface[] |
| include::{chapters}/VK_KHR_win32_surface/platformQuerySupport_win32.txt[] |
| endif::VK_KHR_win32_surface[] |
| |
| ifdef::VK_KHR_xcb_surface[] |
| include::{chapters}/VK_KHR_xcb_surface/platformQuerySupport_xcb.txt[] |
| endif::VK_KHR_xcb_surface[] |
| |
| ifdef::VK_KHR_xlib_surface[] |
| include::{chapters}/VK_KHR_xlib_surface/platformQuerySupport_xlib.txt[] |
| endif::VK_KHR_xlib_surface[] |
| |
| ifdef::VK_EXT_directfb_surface[] |
| include::{chapters}/VK_EXT_directfb_surface/platformQuerySupport_directfb.txt[] |
| endif::VK_EXT_directfb_surface[] |
| |
| ifdef::VK_FUCHSIA_imagepipe_surface[] |
| include::{chapters}/VK_FUCHSIA_imagepipe_surface/platformQuerySupport_imagepipe.txt[] |
| endif::VK_FUCHSIA_imagepipe_surface[] |
| |
| ifdef::VK_GGP_stream_descriptor_surface[] |
| include::{chapters}/VK_GGP_stream_descriptor_surface/platformQuerySupport_streamdescriptor.txt[] |
| endif::VK_GGP_stream_descriptor_surface[] |
| |
| ifdef::VK_MVK_ios_surface[] |
| include::{chapters}/VK_MVK_ios_surface/platformQuerySupport_ios.txt[] |
| endif::VK_MVK_ios_surface[] |
| |
| ifdef::VK_MVK_macos_surface[] |
| include::{chapters}/VK_MVK_macos_surface/platformQuerySupport_macos.txt[] |
| endif::VK_MVK_macos_surface[] |
| |
| ifdef::VK_NN_vi_surface[] |
| include::{chapters}/VK_NN_vi_surface/platformQuerySupport_vi.txt[] |
| endif::VK_NN_vi_surface[] |
| |
| ifdef::VK_QNX_screen_surface[] |
| include::{chapters}/VK_QNX_screen_surface/platformQuerySupport_screen.txt[] |
| endif::VK_QNX_screen_surface[] |
| |
| == Surface Queries |
| |
| The capabilities of a swapchain targeting 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. |
| |
| [NOTE] |
| .Note |
| ==== |
| In addition to the surface capabilities as obtained by surface queries |
| below, swapchain images are also subject to ordinary image creation limits |
| as reported by flink:vkGetPhysicalDeviceImageFormatProperties. |
| As an application is instructed by the appropriate Valid Usage sections, |
| both the surface capabilities and the image creation limits have to be |
| satisfied whenever swapchain images are created. |
| ==== |
| |
| |
| === Surface Capabilities |
| |
| [open,refpage='vkGetPhysicalDeviceSurfaceCapabilitiesKHR',desc='Query surface capabilities',type='protos'] |
| -- |
| :refpage: vkGetPhysicalDeviceSurfaceCapabilitiesKHR |
| |
| To query the basic capabilities of a surface, needed in order to create a |
| swapchain, call: |
| |
| include::{generated}/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 a |
| slink:VkSurfaceCapabilitiesKHR structure in which the capabilities are |
| returned. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/surface_physical_device_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkGetPhysicalDeviceSurfaceCapabilitiesKHR.txt[] |
| -- |
| |
| [open,refpage='VkSurfaceCapabilitiesKHR',desc='Structure describing capabilities of a surface',type='structs'] |
| -- |
| The sname:VkSurfaceCapabilitiesKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkSurfaceCapabilitiesKHR.txt[] |
| |
| // These members are defined identically in VkSurfaceCapabilities2EXT, an |
| // extendable structure version of this query, so they are just reused from |
| // here. |
| |
| // tag::surface_capabilities_members[] |
| * 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. |
| Implementations may: support additional usages. |
| // end::surface_capabilities_members[] |
| |
| 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::{generated}/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'] |
| -- |
| :refpage: vkGetPhysicalDeviceSurfaceCapabilities2KHR |
| |
| To query the basic capabilities of a surface defined by the core or |
| extensions, call: |
| |
| include::{generated}/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 is a pointer to a |
| slink:VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface |
| and other fixed parameters that would be consumed by |
| flink:vkCreateSwapchainKHR. |
| * pname:pSurfaceCapabilities is a pointer to a |
| 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. |
| |
| ifdef::VK_EXT_full_screen_exclusive+VK_KHR_win32_surface[] |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/surface_info_physical_device_common.txt[] |
| * [[VUID-vkGetPhysicalDeviceSurfaceCapabilities2KHR-pNext-02671]] |
| If a slink:VkSurfaceCapabilitiesFullScreenExclusiveEXT structure is |
| included in the pname:pNext chain of pname:pSurfaceCapabilities, a |
| slink:VkSurfaceFullScreenExclusiveWin32InfoEXT structure must: be |
| included in the pname:pNext chain of pname:pSurfaceInfo |
| **** |
| endif::VK_EXT_full_screen_exclusive+VK_KHR_win32_surface[] |
| |
| include::{generated}/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::{generated}/api/structs/VkPhysicalDeviceSurfaceInfo2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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. |
| |
| ifdef::VK_EXT_full_screen_exclusive[] |
| Additional capabilities of a surface may: be available to swapchains created |
| with different full-screen exclusive settings - particularly if exclusive |
| full-screen access is application controlled. |
| These additional capabilities can: be queried by adding a |
| slink:VkSurfaceFullScreenExclusiveInfoEXT structure to the pname:pNext chain |
| of this structure when used to query surface properties. |
| ifdef::VK_KHR_win32_surface[] |
| Additionally, for Win32 surfaces with application controlled exclusive |
| full-screen access, chaining a |
| slink:VkSurfaceFullScreenExclusiveWin32InfoEXT structure may: also report |
| additional surface capabilities. |
| endif::VK_KHR_win32_surface[] |
| These additional capabilities only apply to swapchains created with the same |
| parameters included in the pname:pNext chain of |
| slink:VkSwapchainCreateInfoKHR. |
| endif::VK_EXT_full_screen_exclusive[] |
| |
| ifdef::VK_KHR_win32_surface+VK_EXT_full_screen_exclusive[] |
| .Valid Usage |
| **** |
| * [[VUID-VkPhysicalDeviceSurfaceInfo2KHR-pNext-02672]] |
| If the pname:pNext chain includes a |
| slink:VkSurfaceFullScreenExclusiveInfoEXT structure with its |
| pname:fullScreenExclusive member set to |
| ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT, and |
| pname:surface was created using flink:vkCreateWin32SurfaceKHR, a |
| slink:VkSurfaceFullScreenExclusiveWin32InfoEXT structure must: be |
| included in the pname:pNext chain |
| **** |
| endif::VK_KHR_win32_surface+VK_EXT_full_screen_exclusive[] |
| |
| include::{generated}/validity/structs/VkPhysicalDeviceSurfaceInfo2KHR.txt[] |
| -- |
| |
| ifdef::VK_EXT_full_screen_exclusive[] |
| [open,refpage='VkSurfaceFullScreenExclusiveInfoEXT',desc='Structure specifying the preferred full-screen transition behavior',type='structs'] |
| -- |
| If the pname:pNext chain of slink:VkSwapchainCreateInfoKHR includes a |
| sname:VkSurfaceFullScreenExclusiveInfoEXT structure, then that structure |
| specifies the application's preferred full-screen transition behavior. |
| |
| The sname:VkSurfaceFullScreenExclusiveInfoEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkSurfaceFullScreenExclusiveInfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:fullScreenExclusive is a elink:VkFullScreenExclusiveEXT value |
| specifying the preferred full-screen transition behavior. |
| |
| If this structure is not present, pname:fullScreenExclusive is considered to |
| be ename:VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT. |
| |
| include::{generated}/validity/structs/VkSurfaceFullScreenExclusiveInfoEXT.txt[] |
| -- |
| |
| [open,refpage='VkFullScreenExclusiveEXT',desc='Hint values an application can specify affecting full-screen transition behavior',type='enums'] |
| -- |
| Possible values of |
| sname:VkSurfaceFullScreenExclusiveInfoEXT::pname:fullScreenExclusive are: |
| |
| include::{generated}/api/enums/VkFullScreenExclusiveEXT.txt[] |
| |
| * ename:VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT indicates the implementation |
| should: determine the appropriate full-screen method by whatever means |
| it deems appropriate. |
| * ename:VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT indicates the implementation |
| may: use full-screen exclusive mechanisms when available. |
| Such mechanisms may: result in better performance and/or the |
| availability of different presentation capabilities, but may: require a |
| more disruptive transition during swapchain initialization, first |
| presentation and/or destruction. |
| * ename:VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT indicates the |
| implementation should: avoid using full-screen mechanisms which rely on |
| disruptive transitions. |
| * ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT indicates the |
| application will manage full-screen exclusive mode by using the |
| flink:vkAcquireFullScreenExclusiveModeEXT and |
| flink:vkReleaseFullScreenExclusiveModeEXT commands. |
| -- |
| |
| ifdef::VK_KHR_win32_surface[] |
| [open,refpage='VkSurfaceFullScreenExclusiveWin32InfoEXT',desc='Structure specifying additional creation parameters specific to Win32 fullscreen exclusive mode',type='structs'] |
| -- |
| The sname:VkSurfaceFullScreenExclusiveWin32InfoEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkSurfaceFullScreenExclusiveWin32InfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:hmonitor is the Win32 code:HMONITOR handle identifying the display |
| to create the surface with. |
| |
| [NOTE] |
| .Note |
| ==== |
| If pname:hmonitor is invalidated (e.g. the monitor is unplugged) during the |
| lifetime of a swapchain created with this structure, operations on that |
| swapchain will return ename:VK_ERROR_OUT_OF_DATE_KHR. |
| ==== |
| |
| [NOTE] |
| .Note |
| ==== |
| It is the responsibility of the application to change the display settings |
| of the targeted Win32 display using the appropriate platform APIs. |
| Such changes may: alter the surface capabilities reported for the created |
| surface. |
| ==== |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkSurfaceFullScreenExclusiveWin32InfoEXT-hmonitor-02673]] |
| pname:hmonitor must: be a valid code:HMONITOR |
| **** |
| |
| include::{generated}/validity/structs/VkSurfaceFullScreenExclusiveWin32InfoEXT.txt[] |
| -- |
| endif::VK_KHR_win32_surface[] |
| endif::VK_EXT_full_screen_exclusive[] |
| |
| [open,refpage='VkSurfaceCapabilities2KHR',desc='Structure describing capabilities of a surface',type='structs'] |
| -- |
| The sname:VkSurfaceCapabilities2KHR structure is defined as: |
| |
| include::{generated}/api/structs/VkSurfaceCapabilities2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:surfaceCapabilities is a slink:VkSurfaceCapabilitiesKHR structure |
| describing the capabilities of the specified surface. |
| |
| include::{generated}/validity/structs/VkSurfaceCapabilities2KHR.txt[] |
| -- |
| |
| ifdef::VK_KHR_surface_protected_capabilities[] |
| [open,refpage='VkSurfaceProtectedCapabilitiesKHR',desc='Structure describing capability of a surface to be protected',type='structs'] |
| -- |
| An application queries if a protected slink:VkSurfaceKHR is displayable on a |
| specific windowing system using sname:VkSurfaceProtectedCapabilitiesKHR, |
| which can: be passed in pname:pNext parameter of |
| sname:VkSurfaceCapabilities2KHR. |
| |
| The sname:VkSurfaceProtectedCapabilitiesKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkSurfaceProtectedCapabilitiesKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:supportsProtected specifies whether a protected swapchain created |
| from slink:VkPhysicalDeviceSurfaceInfo2KHR::pname:surface for a |
| particular windowing system can: be displayed on screen or not. |
| If pname:supportsProtected is ename:VK_TRUE, then creation of swapchains |
| with the ename:VK_SWAPCHAIN_CREATE_PROTECTED_BIT_KHR flag set must: be |
| supported for pname:surface. |
| |
| |
| include::{generated}/validity/structs/VkSurfaceProtectedCapabilitiesKHR.txt[] |
| -- |
| endif::VK_KHR_surface_protected_capabilities[] |
| |
| 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::{generated}/api/structs/VkSharedPresentSurfaceCapabilitiesKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| 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::{generated}/validity/structs/VkSharedPresentSurfaceCapabilitiesKHR.txt[] |
| -- |
| endif::VK_KHR_shared_presentable_image[] |
| |
| ifdef::VK_AMD_display_native_hdr[] |
| [open,refpage='VkDisplayNativeHdrSurfaceCapabilitiesAMD',desc='Structure describing display native HDR specific capabilities of a surface',type='structs'] |
| -- |
| The sname:VkDisplayNativeHdrSurfaceCapabilitiesAMD structure is defined as: |
| |
| include::{generated}/api/structs/VkDisplayNativeHdrSurfaceCapabilitiesAMD.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:localDimmingSupport specifies whether the surface supports local |
| dimming. |
| If this is ename:VK_TRUE, slink:VkSwapchainDisplayNativeHdrCreateInfoAMD |
| can: be used to explicitly enable or disable local dimming for the |
| surface. |
| Local dimming may also be overriden by flink:vkSetLocalDimmingAMD during |
| the lifetime of the swapchain. |
| |
| include::{generated}/validity/structs/VkDisplayNativeHdrSurfaceCapabilitiesAMD.txt[] |
| -- |
| endif::VK_AMD_display_native_hdr[] |
| |
| ifdef::VK_EXT_full_screen_exclusive[] |
| [open,refpage='VkSurfaceCapabilitiesFullScreenExclusiveEXT',desc='Structure describing full screen exclusive capabilities of a surface',type='structs'] |
| -- |
| The sname:VkSurfaceCapabilitiesFullScreenExclusiveEXT structure is defined |
| as: |
| |
| include::{generated}/api/structs/VkSurfaceCapabilitiesFullScreenExclusiveEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:fullScreenExclusiveControlSupported is a boolean describing |
| whether the surface is able to make use of exclusive full-screen access. |
| |
| This structure can: be included in the pname:pNext chain of |
| slink:VkSurfaceCapabilities2KHR to determine support for exclusive |
| full-screen access. |
| If pname:fullScreenExclusiveSupported is ename:VK_FALSE, it indicates that |
| exclusive full-screen access is not obtainable for this surface. |
| |
| Applications must: not attempt to create swapchains with |
| ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT set if |
| pname:fullScreenExclusiveSupported is ename:VK_FALSE. |
| |
| include::{generated}/validity/structs/VkSurfaceCapabilitiesFullScreenExclusiveEXT.txt[] |
| -- |
| endif::VK_EXT_full_screen_exclusive[] |
| endif::VK_KHR_get_surface_capabilities2[] |
| |
| ifdef::VK_EXT_display_surface_counter[] |
| include::{chapters}/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 indicating the |
| surface's current transform relative to the presentation engine's natural |
| orientation, are: |
| |
| include::{generated}/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='flags'] |
| -- |
| include::{generated}/api/flags/VkSurfaceTransformFlagsKHR.txt[] |
| |
| tname:VkSurfaceTransformFlagsKHR is a bitmask type for setting a mask of |
| zero or more elink: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::{generated}/api/enums/VkCompositeAlphaFlagBitsKHR.txt[] |
| |
| These values are described as follows: |
| |
| * ename:VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR: The alpha component, if it |
| exists, of the images is ignored in the compositing process. |
| Instead, the image is treated as if it has a constant alpha of 1.0. |
| * ename:VK_COMPOSITE_ALPHA_PRE_MULTIPLIED_BIT_KHR: The alpha component, if |
| it exists, of the images is respected in the compositing process. |
| The non-alpha components of the image are expected to already be |
| multiplied by the alpha component by the application. |
| * ename:VK_COMPOSITE_ALPHA_POST_MULTIPLIED_BIT_KHR: The alpha component, |
| if it exists, of the images is respected in the compositing process. |
| The non-alpha components of the image are not expected to already be |
| multiplied by the alpha component by the application; instead, the |
| compositor will multiply the non-alpha components of the image by the |
| alpha component during compositing. |
| * ename:VK_COMPOSITE_ALPHA_INHERIT_BIT_KHR: The way in which the |
| presentation engine treats the alpha component in the images is unknown |
| to the Vulkan API. |
| Instead, the application is responsible for setting the composite alpha |
| blending mode using native window system commands. |
| If the application does not set the blending mode using native window |
| system commands, then a platform-specific default will be used. |
| -- |
| |
| [open,refpage='VkCompositeAlphaFlagsKHR',desc='Bitmask of VkCompositeAlphaFlagBitsKHR',type='flags'] |
| -- |
| include::{generated}/api/flags/VkCompositeAlphaFlagsKHR.txt[] |
| |
| tname:VkCompositeAlphaFlagsKHR is a bitmask type for setting a mask of zero |
| or more elink:VkCompositeAlphaFlagBitsKHR. |
| -- |
| |
| |
| === Surface Format Support |
| |
| [open,refpage='vkGetPhysicalDeviceSurfaceFormatsKHR',desc='Query color formats supported by surface',type='protos'] |
| -- |
| :refpage: vkGetPhysicalDeviceSurfaceFormatsKHR |
| |
| To query the supported swapchain format-color space pairs for a surface, |
| call: |
| |
| include::{generated}/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. |
| 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, and ename:VK_INCOMPLETE will be returned instead of |
| ename:VK_SUCCESS, to indicate that not all the available format pairs were |
| returned. |
| |
| The number of format pairs supported must: be greater than or equal to 1. |
| pname:pSurfaceFormats must: not contain an entry whose value for |
| pname:format is ename:VK_FORMAT_UNDEFINED. |
| |
| 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. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/surface_physical_device_common.txt[] |
| **** |
| |
| include::{generated}/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::{generated}/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::{generated}/validity/structs/VkSurfaceFormatKHR.txt[] |
| -- |
| |
| ifdef::VK_KHR_get_surface_capabilities2[] |
| [open,refpage='vkGetPhysicalDeviceSurfaceFormats2KHR',desc='Query color formats supported by surface',type='protos'] |
| -- |
| :refpage: vkGetPhysicalDeviceSurfaceFormats2KHR |
| |
| To query the supported swapchain format tuples for a surface, call: |
| |
| include::{generated}/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 is a pointer to a |
| 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. |
| |
| flink:vkGetPhysicalDeviceSurfaceFormats2KHR behaves similarly to |
| flink:vkGetPhysicalDeviceSurfaceFormatsKHR, with the ability to be extended |
| via pname:pNext chains. |
| |
| If pname:pSurfaceFormats is `NULL`, then the number of format tuples |
| supported for the given pname:surface is returned in |
| pname:pSurfaceFormatCount. |
| 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, and ename:VK_INCOMPLETE will be returned instead of |
| ename:VK_SUCCESS, to indicate that not all the available values were |
| returned. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/surface_info_physical_device_common.txt[] |
| **** |
| |
| include::{generated}/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::{generated}/api/structs/VkSurfaceFormat2KHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:surfaceFormat is a slink:VkSurfaceFormatKHR structure describing a |
| format-color space pair that is compatible with the specified surface. |
| |
| include::{generated}/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::{generated}/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 to be displayed using an sRGB-like EOTF (defined |
| below). |
| * ename:VK_COLOR_SPACE_EXTENDED_SRGB_LINEAR_EXT specifies support for the |
| extended sRGB color space to be displayed using a linear EOTF. |
| * ename:VK_COLOR_SPACE_EXTENDED_SRGB_NONLINEAR_EXT specifies support for |
| the extended sRGB color space to be displayed using an sRGB EOTF. |
| * ename:VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT specifies support for the |
| Display-P3 color space to be displayed using a linear EOTF. |
| * ename:VK_COLOR_SPACE_DCI_P3_NONLINEAR_EXT specifies support for the |
| DCI-P3 color space to be displayed using the DCI-P3 EOTF. |
| Note that values in such an image are interpreted as XYZ encoded color |
| data by the presentation engine. |
| * ename:VK_COLOR_SPACE_BT709_LINEAR_EXT specifies support for the BT709 |
| color space to be displayed using a linear EOTF. |
| * ename:VK_COLOR_SPACE_BT709_NONLINEAR_EXT specifies support for the BT709 |
| color space to be displayed using the SMPTE 170M EOTF. |
| * ename:VK_COLOR_SPACE_BT2020_LINEAR_EXT specifies support for the BT2020 |
| color space to be displayed using a linear EOTF. |
| * ename:VK_COLOR_SPACE_HDR10_ST2084_EXT specifies support for the HDR10 |
| (BT2020 color) space to be displayed using the SMPTE ST2084 Perceptual |
| Quantizer (PQ) EOTF. |
| * ename:VK_COLOR_SPACE_DOLBYVISION_EXT specifies support for the Dolby |
| Vision (BT2020 color space), proprietary encoding, to be displayed using |
| the SMPTE ST2084 EOTF. |
| * ename:VK_COLOR_SPACE_HDR10_HLG_EXT specifies support for the HDR10 |
| (BT2020 color space) to be displayed using the Hybrid Log Gamma (HLG) |
| EOTF. |
| * ename:VK_COLOR_SPACE_ADOBERGB_LINEAR_EXT specifies support for the |
| AdobeRGB color space to be displayed using a linear EOTF. |
| * ename:VK_COLOR_SPACE_ADOBERGB_NONLINEAR_EXT specifies support for the |
| AdobeRGB color space to be displayed using the Gamma 2.2 EOTF. |
| * 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. |
| ifdef::VK_AMD_display_native_hdr[] |
| * ename:VK_COLOR_SPACE_DISPLAY_NATIVE_AMD specifies support for the |
| display's native color space. |
| This matches the color space expectations of AMD's FreeSync2 standard, |
| for displays supporting it. |
| endif::VK_AMD_display_native_hdr[] |
| |
| [NOTE] |
| .Note |
| ==== |
| In the initial release of the `VK_KHR_surface` and `apiext: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. |
| ==== |
| |
| [NOTE] |
| .Note |
| ==== |
| In older versions of this extension |
| ename:VK_COLOR_SPACE_DISPLAY_P3_LINEAR_EXT was misnamed |
| ename:VK_COLOR_SPACE_DCI_P3_LINEAR_EXT. |
| This has been updated to indicate that it uses RGB color encoding, not XYZ. |
| The old name is deprecated but is maintained for backwards compatibility. |
| ==== |
| |
| The color components of non-linear color space swap chain images must: have |
| had the appropriate transfer function applied. |
| The color space selected for the swap chain image will not affect the |
| processing of data written into the image by the implementation. |
| Vulkan requires that all implementations support the sRGB transfer function |
| by use of an SRGB pixel format. |
| Other transfer functions, such as SMPTE 170M or SMPTE2084, can: be performed |
| by the application shader. |
| This extension defines enums for 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 | 1.000, 0.000 | 0.000, 1.000 | 0.000, 0.000 | 0.3333, 0.3333 | DCI P3 |
| | Display-P3 | 0.680, 0.320 | 0.265, 0.690 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | Display-P3 |
| | BT709 | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | ITU (SMPTE 170M) |
| | sRGB | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | sRGB |
| | extended sRGB | 0.640, 0.330 | 0.300, 0.600 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | extended sRGB |
| | HDR10_ST2084 | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | ST2084 PQ |
| | DOLBYVISION | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | ST2084 PQ |
| | HDR10_HLG | 0.708, 0.292 | 0.170, 0.797 | 0.131, 0.046 | 0.3127, 0.3290 (D65) | HLG |
| | AdobeRGB | 0.640, 0.330 | 0.210, 0.710 | 0.150, 0.060 | 0.3127, 0.3290 (D65) | AdobeRGB |
| |==== |
| |
| The transfer functions are described in the "`Transfer Functions`" chapter |
| of the <<data-format,Khronos Data Format Specification>>. |
| |
| Except Display-P3 OETF, which is: |
| |
| [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} |
| +++++++++++++++++++ |
| |
| where [eq]#L# is the linear value of a color component and [eq]#E# is the |
| encoded value (as stored in the image in memory). |
| |
| [NOTE] |
| .Note |
| ==== |
| For most uses, the sRGB OETF is equivalent. |
| ==== |
| endif::VK_EXT_swapchain_colorspace[] |
| -- |
| |
| |
| === Surface Presentation Mode Support |
| |
| [open,refpage='vkGetPhysicalDeviceSurfacePresentModesKHR',desc='Query supported presentation modes',type='protos'] |
| -- |
| :refpage: vkGetPhysicalDeviceSurfacePresentModesKHR |
| |
| To query the supported presentation modes for a surface, call: |
| |
| include::{generated}/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, and ename:VK_INCOMPLETE will be returned instead of |
| ename:VK_SUCCESS, to indicate that not all the available modes were |
| returned. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/surface_physical_device_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkGetPhysicalDeviceSurfacePresentModesKHR.txt[] |
| -- |
| |
| ifdef::VK_EXT_full_screen_exclusive[] |
| [open,refpage='vkGetPhysicalDeviceSurfacePresentModes2EXT',desc='Query supported presentation modes',type='protos'] |
| -- |
| :refpage: vkGetPhysicalDeviceSurfacePresentModes2EXT |
| |
| Alternatively, to query the supported presentation modes for a surface |
| combined with select other fixed swapchain creation parameters, call: |
| |
| include::{generated}/api/protos/vkGetPhysicalDeviceSurfacePresentModes2EXT.txt[] |
| |
| * pname:physicalDevice is the physical device that will be associated with |
| the swapchain to be created, as described for |
| flink:vkCreateSwapchainKHR. |
| * pname:pSurfaceInfo is a pointer to a |
| slink:VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface |
| and other fixed parameters that would be consumed by |
| flink:vkCreateSwapchainKHR. |
| * 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. |
| |
| fname:vkGetPhysicalDeviceSurfacePresentModes2EXT behaves similarly to |
| flink:vkGetPhysicalDeviceSurfacePresentModesKHR, with the ability to specify |
| extended inputs via chained input structures. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/surface_info_physical_device_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkGetPhysicalDeviceSurfacePresentModes2EXT.txt[] |
| -- |
| endif::VK_EXT_full_screen_exclusive[] |
| |
| [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::{generated}/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_EXT_full_screen_exclusive[] |
| == Full Screen Exclusive Control |
| |
| Swapchains created with pname:fullScreenExclusive set to |
| ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT must: acquire and |
| release exclusive full-screen access explicitly, using the following |
| commands. |
| |
| [open,refpage='vkAcquireFullScreenExclusiveModeEXT',desc='Acquire full-screen exclusive mode for a swapchain',type='protos'] |
| -- |
| To acquire exclusive full-screen access for a swapchain, call: |
| |
| include::{generated}/api/protos/vkAcquireFullScreenExclusiveModeEXT.txt[] |
| |
| * pname:device is the device associated with pname:swapchain. |
| * pname:swapchain is the swapchain to acquire exclusive full-screen access |
| for. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkAcquireFullScreenExclusiveModeEXT-swapchain-02674]] |
| pname:swapchain must: not be in the retired state |
| * [[VUID-vkAcquireFullScreenExclusiveModeEXT-swapchain-02675]] |
| pname:swapchain must: be a swapchain created with a |
| slink:VkSurfaceFullScreenExclusiveInfoEXT structure, with |
| pname:fullScreenExclusive set to |
| ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT |
| * [[VUID-vkAcquireFullScreenExclusiveModeEXT-swapchain-02676]] |
| pname:swapchain must: not currently have exclusive full-screen access |
| **** |
| |
| A return value of ename:VK_SUCCESS indicates that the pname:swapchain |
| successfully acquired exclusive full-screen access. |
| The swapchain will retain this exclusivity until either the application |
| releases exclusive full-screen access with |
| flink:vkReleaseFullScreenExclusiveModeEXT, destroys the swapchain, or if any |
| of the swapchain commands return |
| ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT indicating that the mode |
| was lost because of platform-specific changes. |
| |
| If the swapchain was unable to acquire exclusive full-screen access to the |
| display then ename:VK_ERROR_INITIALIZATION_FAILED is returned. |
| An application can: attempt to acquire exclusive full-screen access again |
| for the same swapchain even if this command fails, or if |
| ename:VK_ERROR_FULL_SCREEN_EXCLUSIVE_MODE_LOST_EXT has been returned by a |
| swapchain command. |
| |
| include::{generated}/validity/protos/vkAcquireFullScreenExclusiveModeEXT.txt[] |
| -- |
| |
| [open,refpage='vkReleaseFullScreenExclusiveModeEXT',desc='Release full-screen exclusive mode from a swapchain',type='protos'] |
| -- |
| To release exclusive full-screen access from a swapchain, call: |
| |
| include::{generated}/api/protos/vkReleaseFullScreenExclusiveModeEXT.txt[] |
| |
| * pname:device is the device associated with pname:swapchain. |
| * pname:swapchain is the swapchain to release exclusive full-screen access |
| from. |
| |
| [NOTE] |
| .Note |
| ==== |
| Applications will not be able to present to pname:swapchain after this call |
| until exclusive full-screen access is reacquired. |
| This is usually useful to handle when an application is minimised or |
| otherwise intends to stop presenting for a time. |
| ==== |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkReleaseFullScreenExclusiveModeEXT-swapchain-02677]] |
| pname:swapchain must: not be in the retired state |
| * [[VUID-vkReleaseFullScreenExclusiveModeEXT-swapchain-02678]] |
| pname:swapchain must: be a swapchain created with a |
| slink:VkSurfaceFullScreenExclusiveInfoEXT structure, with |
| pname:fullScreenExclusive set to |
| ename:VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT |
| **** |
| -- |
| endif::VK_EXT_full_screen_exclusive[] |
| |
| |
| 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::{generated}/api/protos/vkGetDeviceGroupPresentCapabilitiesKHR.txt[] |
| |
| * pname:device is the logical device. |
| * pname:pDeviceGroupPresentCapabilities is a pointer to a |
| slink:VkDeviceGroupPresentCapabilitiesKHR structure in which the |
| device's capabilities are returned. |
| |
| include::{generated}/validity/protos/vkGetDeviceGroupPresentCapabilitiesKHR.txt[] |
| -- |
| |
| [open,refpage='VkDeviceGroupPresentCapabilitiesKHR',desc='Present capabilities from other physical devices',type='structs'] |
| -- |
| The sname:VkDeviceGroupPresentCapabilitiesKHR structure is defined as: |
| |
| include::{generated}/api/structs/VkDeviceGroupPresentCapabilitiesKHR.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:presentMask is an array of ename:VK_MAX_DEVICE_GROUP_SIZE |
| code:uint32_t 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::{generated}/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::{generated}/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='flags'] |
| -- |
| include::{generated}/api/flags/VkDeviceGroupPresentModeFlagsKHR.txt[] |
| |
| tname:VkDeviceGroupPresentModeFlagsKHR is a bitmask type for setting a mask |
| of zero or more elink: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::{generated}/api/protos/vkGetDeviceGroupSurfacePresentModesKHR.txt[] |
| |
| * pname:device is the logical device. |
| * pname:surface is the surface. |
| * pname:pModes is a pointer to a tlink:VkDeviceGroupPresentModeFlagsKHR in |
| which the supported device group present modes for the surface are |
| returned. |
| |
| 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. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetDeviceGroupSurfacePresentModesKHR-surface-06212]] |
| pname:surface must: be supported by all physical devices associated with |
| pname:device, as reported by flink:vkGetPhysicalDeviceSurfaceSupportKHR |
| or an equivalent platform-specific mechanism |
| **** |
| |
| include::{generated}/validity/protos/vkGetDeviceGroupSurfacePresentModesKHR.txt[] |
| -- |
| |
| ifdef::VK_EXT_full_screen_exclusive[] |
| [open,refpage='vkGetDeviceGroupSurfacePresentModes2EXT',desc='Query device group present capabilities for a surface',type='protos'] |
| -- |
| Alternatively, to query the supported device group presentation modes for a |
| surface combined with select other fixed swapchain creation parameters, |
| call: |
| |
| include::{generated}/api/protos/vkGetDeviceGroupSurfacePresentModes2EXT.txt[] |
| |
| * pname:device is the logical device. |
| * pname:pSurfaceInfo is a pointer to a |
| slink:VkPhysicalDeviceSurfaceInfo2KHR structure describing the surface |
| and other fixed parameters that would be consumed by |
| flink:vkCreateSwapchainKHR. |
| * pname:pModes is a pointer to a tlink:VkDeviceGroupPresentModeFlagsKHR in |
| which the supported device group present modes for the surface are |
| returned. |
| |
| fname:vkGetDeviceGroupSurfacePresentModes2EXT behaves similarly to |
| flink:vkGetDeviceGroupSurfacePresentModesKHR, with the ability to specify |
| extended inputs via chained input structures. |
| |
| .Valid Usage |
| **** |
| * [[VUID-vkGetDeviceGroupSurfacePresentModes2EXT-pSurfaceInfo-06213]] |
| pname:pSurfaceInfo->surface must: be supported by all physical devices |
| associated with pname:device, as reported by |
| flink:vkGetPhysicalDeviceSurfaceSupportKHR or an equivalent |
| platform-specific mechanism |
| **** |
| |
| include::{generated}/validity/protos/vkGetDeviceGroupSurfacePresentModes2EXT.txt[] |
| -- |
| endif::VK_EXT_full_screen_exclusive[] |
| |
| [open,refpage='vkGetPhysicalDevicePresentRectanglesKHR',desc='Query present rectangles for a surface on a physical device',type='protos'] |
| -- |
| :refpage: vkGetPhysicalDevicePresentRectanglesKHR |
| |
| 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::{generated}/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, and ename:VK_INCOMPLETE |
| will be returned instead of ename:VK_SUCCESS, to indicate that not all the |
| available rectangles 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. |
| |
| .Valid Usage |
| **** |
| include::{chapters}/commonvalidity/surface_physical_device_common.txt[] |
| **** |
| |
| include::{generated}/validity/protos/vkGetPhysicalDevicePresentRectanglesKHR.txt[] |
| -- |
| endif::VK_VERSION_1_1,VK_KHR_device_group[] |
| |
| ifdef::VK_GOOGLE_display_timing[] |
| include::{chapters}/VK_GOOGLE_display_timing/queries.txt[] |
| endif::VK_GOOGLE_display_timing[] |
| |
| ifdef::VK_KHR_present_wait[] |
| include::{chapters}/VK_KHR_present_wait/present_wait.txt[] |
| endif::VK_KHR_present_wait[] |
| |
| include::{chapters}/VK_KHR_swapchain/wsi.txt[] |
| endif::VK_KHR_swapchain[] |