// Copyright 2019-2022 The Khronos Group, Inc. // SPDX-License-Identifier: CC-BY-4.0 ifndef::chapters[:chapters:] [[wsi]] = Window System Integration (WSI) Since the Vulkan API can be used without displaying results, WSI is provided through the use of link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#wsi[optional Vulkan extensions]. Most implementations will include WSI support. The WSI design was created to abstract each platform's windowing mechanism from the core Vulkan API. image::images/wsi_setup.png[wsi_setup] == Surface The `VkSurfaceKHR` object is platform agnostic and designed so the rest of the Vulkan API can use it for all WSI operations. It is enabled using the `VK_KHR_surface` extension. Each platform that supports a Vulkan Surface has its own way to create a `VkSurfaceKHR` object from its respective platform-specific API. * Android - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkCreateAndroidSurfaceKHR[vkCreateAndroidSurfaceKHR] * DirectFB - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkCreateDirectFBSurfaceEXT[vkCreateDirectFBSurfaceEXT] * Fuchsia - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkCreateImagePipeSurfaceFUCHSIA[vkCreateImagePipeSurfaceFUCHSIA] * Google Games - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkCreateStreamDescriptorSurfaceGGP[vkCreateStreamDescriptorSurfaceGGP] * iOS - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkCreateIOSSurfaceMVK[vkCreateIOSSurfaceMVK] * macOS - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkCreateMacOSSurfaceMVK[vkCreateMacOSSurfaceMVK] * Metal - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkCreateMetalSurfaceEXT[vkCreateMetalSurfaceEXT] * VI - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkCreateViSurfaceNN[vkCreateViSurfaceNN] * Wayland - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkWaylandSurfaceCreateInfoKHR[vkWaylandSurfaceCreateInfoKHR] * QNX - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/vkCreateScreenSurfaceQNX.html[vkCreateScreenSurfaceQNX] * Windows - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkCreateWin32SurfaceKHR[vkCreateWin32SurfaceKHR] * XCB - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkCreateXcbSurfaceKHR[vkCreateXcbSurfaceKHR] * Xlib - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkCreateXlibSurfaceKHR[vkCreateXlibSurfaceKHR] * Direct-to-Display - link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkCreateDisplayPlaneSurfaceKHR[vkCreateDisplayPlaneSurfaceKHR] Once a `VkSurfaceKHR` is created there are various link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkGetPhysicalDeviceSurfaceCapabilitiesKHR[capabilities], link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkGetPhysicalDeviceSurfaceFormatsKHR[formats], and link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#vkGetPhysicalDeviceSurfacePresentModesKHR[presentation modes] to query for. == Swapchain The `VkSwapchainKHR` object provides the ability to present rendering results to a surface through an array of `VkImage` objects. The swapchain's various link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/html/vkspec.html#VkPresentModeKHR[present modes] determine how the presentation engine is implemented. image::images/wsi_engine.png[wsi_engine] Khronos' link:https://github.com/KhronosGroup/Vulkan-Samples/tree/master/samples/performance/swapchain_images[sample and tutorial] explain different considerations to make when creating a swapchain and selecting a presentation mode. == Pre-Rotation Mobile devices can be rotated, therefore the logical orientation of the application window and the physical orientation of the display may not match. Applications need to be able to operate in two modes: `portrait` and `landscape`. The difference between these two modes can be simplified to just a change in resolution. However, some display subsystems always work on the "`native`" (or "`physical`") orientation of the display panel. Since the device has been rotated, to achieve the desired effect the application output must also rotate. In order for your application to get the most out of Vulkan on mobile platforms, such as Android, implementing pre-rotation is a must. There is a link:https://android-developers.googleblog.com/2020/02/handling-device-orientation-efficiently.html?m=1[detailed blog post from Google] that goes over how to handle the surface rotation by specifying the orientation during swapchain creation and also comes with a link:https://github.com/google/vulkan-pre-rotation-demo[standalone example]. The link:https://github.com/KhronosGroup/Vulkan-Samples[Vulkan-Samples] also has both a link:https://github.com/KhronosGroup/Vulkan-Samples/tree/master/samples/performance/surface_rotation[great write up] of why pre-rotation is a problem as well as link:https://github.com/KhronosGroup/Vulkan-Samples/tree/master/samples/performance/surface_rotation[a sample to run] that shows a way to solve it in the shader. If using an Adreno GPU powered device, Qualcomm suggests making use of the link:https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VK_QCOM_render_pass_transform.html[VK_QCOM_render_pass_transform] extension to implement pre-rotation.