1 # Vulkan® Window System Integration Layer
5 This project is a Vulkan® layer which implements some of the Vulkan® window system
6 integration extensions such as `VK_KHR_swapchain`. The layer is designed to be
7 GPU vendor agnostic when used as part of the Vulkan® ICD/loader architecture.
9 Our vision for the project is to become the de facto implementation for Vulkan®
10 window system integration extensions so that they need not be implemented in the
11 ICD; instead, the implementation of these extensions are shared across vendors
14 The project currently implements support for `VK_EXT_headless_surface` and
15 its dependencies. Experimental support for `VK_KHR_wayland_surface` can be
16 enabled via a build option [as explained below](#building-with-wayland-support).
22 * [CMake](https://cmake.org) version 3.4.3 or above.
24 * Vulkan® loader and associated headers with support for the
25 `VK_EXT_headless_surface` extension and for the Vulkan 1.1, or later API.
27 The Vulkan WSI Layer uses Vulkan extensions to communicate with the Vulkan ICDs.
28 The ICDs installed in the system are required to support the Vulkan 1.1, or
29 later API, and the following device extensions:
30 * When Wayland support is enabled:
31 * VK_EXT_image_drm_format_modifier
32 * VK_KHR_image_format_list
33 * VK_EXT_external_memory_dma_buf
34 * VK_KHR_external_memory_fd
35 * VK_KHR_external_fence_fd
37 ### Building the Vulkan® loader
39 This step is not necessary if your system already has a loader and associated
40 headers with support for the `VK_EXT_headless_surface` extension. We include
41 these instructions for completeness.
44 git clone https://github.com/KhronosGroup/Vulkan-Loader.git
45 mkdir Vulkan-Loader/build
46 cd Vulkan-Loader/build
47 ../scripts/update_deps.py
48 cmake -C helper.cmake ..
53 ### Building with headless support
55 The layer requires a version of the loader and headers that includes support for
56 the `VK_EXT_headless_surface` extension. By default, the build system will use
57 the system Vulkan® headers as reported by `pkg-config`. This may be overriden by
58 specifying `VULKAN_CXX_INCLUDE` in the CMake configuration, for example:
61 cmake . -DVULKAN_CXX_INCLUDE="path/to/vulkan-headers"
64 If the loader and associated headers already meet the requirements of the layer
65 then the build steps are straightforward:
72 ### Building with Wayland support
74 In order to build with Wayland support the `BUILD_WSI_WAYLAND` build option
75 must be used, the `SELECT_EXTERNAL_ALLOCATOR` option has to be set to
76 a graphics memory allocator (currently only ion is supported) and
77 the `KERNEL_DIR` option must be defined as the root of the Linux kernel
81 cmake . -DVULKAN_CXX_INCLUDE="path/to/vulkan-header" \
82 -DBUILD_WSI_HEADLESS=0 \
83 -DBUILD_WSI_WAYLAND=1 \
84 -DSELECT_EXTERNAL_ALLOCATOR=ion \
85 -DKERNEL_DIR="path/to/linux-kernel-source"
88 In the command line above, `-DBUILD_WSI_HEADLESS=0` is used to disable support
89 for `VK_EXT_headless_surface`, which is otherwise enabled by default.
91 Note that a custom graphics memory allocator implementation can be provided
92 using the `EXTERNAL_WSIALLOC_LIBRARY` option. For example,
95 cmake . -DVULKAN_CXX_INCLUDE="path/to/vulkan-header" \
96 -DBUILD_WSI_WAYLAND=1 \
97 -DEXTERNAL_WSIALLOC_LIBRARY="path/to/custom/libwsialloc" \
98 -DKERNEL_DIR="path/to/linux-kernel-source"
101 The `EXTERNAL_WSIALLOC_LIBRARY` option allows to specify the path to a library
102 containing the implementation of the graphics memory allocator API, as
103 described in [the wsialloc.h header file](util/wsialloc/wsialloc.h).
104 The allocator is not only responsible for allocating graphics buffers, but is
105 also responsible for selecting a suitable format that can be
106 efficiently shared between the different devices in the system, e.g. GPU,
107 display. It is therefore an important point of integration. It is expected
108 that each system will need a tailored implementation, although the layer
109 provides a generic ion implementation that may work in systems that support
110 linear formats. This is selected by the `-DSELECT_EXTERNAL_ALLOCATOR=ion`
111 option, as shown above.
113 Wayland support is still **EXPERIMENTAL**. What this means in practice is that
114 the support is incomplete and not ready for prime time.
118 Copy the shared library `libVkLayer_window_system_integration.so` and JSON
119 configuration `VkLayer_window_system_integration.json` into a Vulkan®
120 [implicit layer directory](https://github.com/KhronosGroup/Vulkan-Loader/blob/master/docs/LoaderLayerInterface.md#linux-layer-discovery).
124 We are open for contributions.
126 * The software is provided under the MIT license. Contributions to this project
127 are accepted under the same license.
128 * Please also ensure that each commit in the series has at least one
129 `Signed-off-by:` line, using your real name and email address. The names in
130 the `Signed-off-by:` and `Author:` lines must match. If anyone else
131 contributes to the commit, they must also add their own `Signed-off-by:`
132 line. By adding this line the contributor certifies the contribution is made
133 under the terms of the [Developer Certificate of Origin (DCO)](DCO.txt).
134 * Questions, bug reports, et cetera are raised and discussed on the issues page.
135 * Please make merge requests into the master branch.
136 * Code should be formatted with clang-format using the project's .clang-format
139 Contributors are expected to abide by the
140 [freedesktop.org code of conduct](https://www.freedesktop.org/wiki/CodeOfConduct/).
142 ## Khronos® Conformance
144 This software is based on a published Khronos® Specification and is expected to
145 pass the relevant parts of the Khronos® Conformance Testing Process when used as
146 part of a conformant Vulkan® implementation.