README.md

   1 # Vulkan® Window System Integration Layer
   2
   3 ## Introduction
   4
   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.
   8
   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
  12 for mutual benefit.
  13
  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).
  17
  18 ## Building
  19
  20 ### Dependencies
  21
  22 * [CMake](https://cmake.org) version 3.4.3 or above.
  23 * C++11 compiler.
  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.
  26
  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
  36
  37 ### Building the Vulkan® loader
  38
  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.
  42
  43 ```
  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 ..
  49 make
  50 make install
  51 ```
  52
  53 ### Building with headless support
  54
  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:
  59
  60 ```
  61 cmake . -DVULKAN_CXX_INCLUDE="path/to/vulkan-headers"
  62 ```
  63
  64 If the loader and associated headers already meet the requirements of the layer
  65 then the build steps are straightforward:
  66
  67 ```
  68 cmake . -Bbuild
  69 make -C build
  70 ```
  71
  72 ### Building with Wayland support
  73
  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
  78 source.
  79
  80 ```
  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"
  86 ```
  87
  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.
  90
  91 Note that a custom graphics memory allocator implementation can be provided
  92 using the `EXTERNAL_WSIALLOC_LIBRARY` option. For example,
  93
  94 ```
  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"
  99 ```
 100
 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.
 112
 113 Wayland support is still **EXPERIMENTAL**. What this means in practice is that
 114 the support is incomplete and not ready for prime time.
 115
 116 ## Installation
 117
 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).
 121
 122 ## Contributing
 123
 124 We are open for contributions.
 125
 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
 137    configuration.
 138
 139 Contributors are expected to abide by the
 140 [freedesktop.org code of conduct](https://www.freedesktop.org/wiki/CodeOfConduct/).
 141
 142 ## Khronos® Conformance
 143
 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.