matrixfurry.com
The open source OpenXR runtime
1# Monado - XR Runtime (XRT)
2
3<!--
4Copyright 2018-2021, Collabora, Ltd.
5
6SPDX-License-Identifier: CC-BY-4.0
7
8This must stay in sync with the last section!
9-->
10
11> * Main homepage and documentation: <https://monado.freedesktop.org/>
12> * Promotional homepage: <https://monado.dev>
13> * Maintained at <https://gitlab.freedesktop.org/monado/monado>
14> * Latest API documentation: <https://monado.pages.freedesktop.org/monado>
15> * Continuously-updated changelog of the default branch:
16> <https://monado.pages.freedesktop.org/monado/_c_h_a_n_g_e_l_o_g.html>
17
18Monado is an open source XR runtime delivering immersive experiences such as VR
19and AR on mobile, PC/desktop, and any other device
20(because gosh darn people
21come up with a lot of weird hardware).
22Monado aims to be a complete and conforming implementation
23of the OpenXR API made by Khronos.
24The project is primarily developed on GNU/Linux, but also runs on Android and Windows.
25"Monado" has no specific meaning and is just a name.
26
27## Monado source tree
28
29* `src/xrt/include` - headers that define the internal interfaces of Monado.
30* `src/xrt/compositor` - code for doing distortion and driving the display hardware of a device.
31* `src/xrt/auxiliary` - utilities and other larger components.
32* `src/xrt/drivers` - hardware drivers.
33* `src/xrt/state_trackers/oxr` - OpenXR API implementation.
34* `src/xrt/targets` - glue code and build logic to produce final binaries.
35* `src/external` - a small collection of external code and headers.
36
37## Getting Started
38
39Dependencies include:
40
41* [CMake][] 3.13 or newer (Note Ubuntu 18.04 only has 3.10)
42* Python 3.6 or newer
43* Vulkan headers and loader - Fedora package `vulkan-loader-devel`
44* OpenGL headers
45* Eigen3 - Debian/Ubuntu package `libeigen3-dev`
46* glslangValidator - Debian/Ubuntu package `glslang-tools`, Fedora package `glslang`.
47* libusb
48* libudev - Debian/Ubuntu package `libudev-dev`, Fedora package `systemd-devel`
49* Video 4 Linux - Debian/Ubuntu package `libv4l-dev`.
50
51Optional (but recommended) dependencies:
52
53* libxcb and xcb-xrandr development packages
54* [OpenHMD][] 0.3.0 or newer (found using pkg-config)
55
56Truly optional dependencies, useful for some drivers, app support, etc.:
57
58* Doxygen - Debian/Ubuntu package `doxygen` and `graphviz`
59* Wayland development packages
60* Xlib development packages
61* libhidapi - Debian/Ubuntu package `libhidapi-dev`
62* OpenCV
63* libuvc - Debian/Ubuntu package `libuvc-dev`
64* libjpeg
65* libbluetooth - Debian/Ubuntu package `libbluetooth-dev`
66* libsdl - Debian/Ubuntu package `libsdl2-dev`
67
68Experimental Windows support requires the Vulkan SDK and also needs or works
69best with the following vcpkg packages installed:
70
71* pthreads eigen3 libusb hidapi zlib doxygen
72
73If you have a recent [vcpkg](https://vcpkg.io) installed and use the appropriate
74CMake toolchain file, the vcpkg manifest in the Monado repository will instruct
75vcpkg to locally install the dependencies automatically. The Vulkan SDK
76installer should set the `VULKAN_SDK` Windows environment variable to point
77at the installation location (for example, `C:/VulkanSDK/1.3.250.1`), though
78make sure you open a new terminal (or open the CMake GUI) *after* doing that
79install to make sure it is available.
80
81Monado has been tested on these distributions, but is expected to work on almost
82any modern distribution.
83
84* Ubuntu 24.04, 22.04, 20.04, (18.04 may not be fully supported)
85* Debian 11 `bookworm`, 10 `buster`
86 * Up-to-date package lists can be found in our CI config file,
87 `.gitlab-ci.yml`
88* Archlinux
89
90These distributions include recent-enough versions of all the
91software to use direct mode,
92without using any external, third-party, or backported
93package sources.
94
95See also [Status of DRM Leases][drm-lease]
96for more details on specific packages, versions, and commits.
97
98Due to the lack of a OpenGL extension: GL_EXT_memory_object_fd on Intel's
99OpenGL driver, only the AMD
100radeonsi driver and the proprietary NVIDIA driver will work for OpenGL OpenXR
101clients. This is due to a requirement of the Compositor. Support status of the
102extension can be found on the [mesamatrix website][mesamatrix-ext].
103
104### CMake
105
106Build process is similar to other CMake builds,
107so something like the following will build it.
108
109Go into the source directory, create a build directory,
110and change into it.
111
112```bash
113mkdir build
114cd build
115```
116
117Then, invoke [CMake to generate a project][cmake-generate].
118Feel free to change the build type or generator ("Ninja" is fast and parallel) as you see fit.
119
120```bash
121cmake .. -DCMAKE_BUILD_TYPE=Debug -G "Unix Makefiles"
122```
123
124If you plan to install the runtime,
125append something like `-DCMAKE_INSTALL_PREFIX=~/.local`
126to specify the root of the install directory.
127(The default install prefix is `/usr/local`.)
128
129To build, [the generic CMake build commands][cmake-build] below will work on all systems,
130though you can manually invoke your build tool (`make`, `ninja`, etc.) if you prefer.
131The first command builds the runtime and docs,
132and the second, which is optional, installs the runtime under `${CMAKE_INSTALL_PREFIX}`.
133
134```bash
135cmake --build .
136cmake --build . --target install
137```
138
139Alternately, if using Make, the following will build the runtime and docs, then install.
140Replace `make` with `ninja` if you used the Ninja generator.
141
142```bash
143make
144make install
145```
146
147Documentation can be browsed by opening `doc/html/index.html` in the build directory in a web browser.
148
149## Getting started using OpenXR with Monado
150
151This implements the [OpenXR][] API,
152so to do anything with it, you'll need an application
153that uses OpenXR, along with the OpenXR loader.
154The OpenXR loader is a glue library that connects OpenXR applications to OpenXR runtimes such as Monado
155It determines which runtime to use by looking for the config file `active_runtime.json` (either a symlink to
156or a copy of a runtime manifest) in the usual XDG config paths
157and processes environment variables such as `XR_RUNTIME_JSON=/usr/share/openxr/0/openxr_monado.json`.
158It can also insert OpenXR API Layers without the application or the runtime having to do it.
159
160You can use the `hello_xr` sample provided with the OpenXR SDK.
161
162The OpenXR loader can be pointed to a runtime json file in a nonstandard location with the environment variable `XR_RUNTIME_JSON`. Example:
163
164```bash
165XR_RUNTIME_JSON=~/monado/build/openxr_monado-dev.json ./openxr-example
166```
167
168For ease of development Monado creates a runtime manifest file in its build directory using an absolute path to the
169Monado runtime in the build directory called `openxr_monado-dev.json`. Pointing `XR_RUNTIME_JSON` to this
170file allows using Monado after building, without installing.
171
172Note that the loader can always find and load the runtime
173if the path to the runtime library given in the json manifest is an absolute path,
174but if a relative path like `libopenxr_monado.so.0` is given,
175then `LD_LIBRARY_PATH` must include the directory that contains `libopenxr_monado.so.0`.
176The absolute path in `openxr_monado-dev.json` takes care of this for you.
177
178Distribution packages for monado may provide the "active runtime" file `/etc/xdg/openxr/1/active_runtime.json`.
179In this case the loader will automatically use Monado when starting an OpenXR application. This global configuration
180can be overridden on a per user basis by creating `~/.config/openxr/1/active_runtime.json`.
181
182## Direct mode
183
184On AMD and Intel GPUs our direct mode code requires a connected HMD to have
185the `non-desktop` xrandr property set to 1.
186Only the most common HMDs have the needed quirks added to the linux kernel.
187
188If you know that your HMD lacks the quirk you can run this command **before** or
189after connecting the HMD and it will have it. Where `HDMI-A-0` is the xrandr
190output name where you plug the HMD in.
191
192```bash
193xrandr --output HDMI-A-0 --prop --set non-desktop 1
194```
195
196You can verify that it stuck with the command.
197
198```bash
199xrandr --prop
200```
201
202## Running Vulkan Validation
203
204To run Monado with Vulkan validation the loader's layer functionality can be used.
205```
206VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation ./build/src/xrt/targets/service/monado-service
207```
208The same can be done when launching a Vulkan client.
209
210If you want a backtrace to be produced at validation errors, create a `vk_layer_settings.txt`
211file with the following content:
212```
213khronos_validation.debug_action = VK_DBG_LAYER_ACTION_LOG_MSG,VK_DBG_LAYER_ACTION_BREAK
214khronos_validation.report_flags = error,warn
215khronos_validation.log_filename = stdout
216```
217
218## Coding style and formatting
219
220[clang-format][] is used,
221and a `.clang-format` config file is present in the repo
222to allow your editor to use them.
223
224To manually apply clang-format to every non-external source file in the tree,
225run this command in the source dir with a `sh`-compatible shell
226(Git for Windows git-bash should be OK):
227
228```bash
229scripts/format-project.sh
230```
231
232You can optionally put something like `CLANG_FORMAT=clang-format-7` before that command
233if your clang-format binary isn't named `clang-format`.
234**Note that you'll typically prefer** to use something like `git clang-format`
235to re-format only your changes, in case version differences in tools result in overall format changes.
236The CI "style" job currently runs on Debian Bullseye, so it has clang-format-11.
237
238[OpenHMD]: http://openhmd.net
239[drm-lease]: https://haagch.frickel.club/#!drmlease%2Emd
240[OpenXR]: https://khronos.org/openxr
241[clang-format]: https://releases.llvm.org/7.0.0/tools/clang/docs/ClangFormat.html
242[cmake-build]: https://cmake.org/cmake/help/v3.12/manual/cmake.1.html#build-tool-mode
243[cmake-generate]: https://cmake.org/cmake/help/v3.12/manual/cmake.1.html
244[CMake]: https://cmake.org
245[mesamatrix-ext]: https://mesamatrix.net/#Version_ExtensionsthatarenotpartofanyOpenGLorOpenGLESversion
246
247## Contributing, Code of Conduct
248
249See `CONTRIBUTING.md` for details of contribution guidelines. GitLab Issues and
250Merge Requests are the preferred way to discuss problems, suggest enhancements,
251or submit changes for review. **In case of a security issue**, you should choose
252the "confidential" option when using the GitLab issues page. For highest
253security, you can send encrypted email (using GPG/OpenPGP) to Rylie Pavlik at
254<rylie.pavlik@collabora.com> and using the associated key from
255<https://keys.openpgp.org/vks/v1/by-fingerprint/45207B2B1E53E1F2755FF63CC5A2D593A61DBC9D>.
256
257Please note that this project is released with a Contributor Code of Conduct.
258By participating in this project you agree to abide by its terms.
259
260We follow the standard freedesktop.org code of conduct,
261available at <https://www.freedesktop.org/wiki/CodeOfConduct/>,
262which is based on the [Contributor Covenant](https://www.contributor-covenant.org).
263
264Instances of abusive, harassing, or otherwise unacceptable behavior may be
265reported by contacting:
266
267* First-line project contacts:
268 * Rylie Pavlik <rylie.pavlik@collabora.com>
269 * Frederic Plourde <frederic.plourde@collabora.com>
270 * Jakob Bornecrantz <tbornecrantz@nvidia.com>
271* freedesktop.org contacts: see most recent list at <https://www.freedesktop.org/wiki/CodeOfConduct/>
272
273Code of Conduct section excerpt adapted from the
274[Contributor Covenant](https://www.contributor-covenant.org), version 1.4.1,
275available at
276<https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>, and
277from the freedesktop.org-specific version of that code, available at
278<https://www.freedesktop.org/wiki/CodeOfConduct/>, used under CC-BY-4.0.