README.md 8.37 KB
Newer Older
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
1
2

# Monado - XR Runtime (XRT)
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
3

Ryan Pavlik's avatar
Ryan Pavlik committed
4
5
6
7
> * Promotional homepage: <https://monado.dev>
> * Maintained at <https://gitlab.freedesktop.org/monado/monado>
> * Latest API documentation: <https://monado.pages.freedesktop.org/monado>

Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Monado is an open source XR runtime delivering immersive experiences such as VR
and AR on on mobile, PC/desktop, and any other device
(because gosh darn people
come up with a lot of weird hardware).
Monado aims to be a complete and conforming implementation
of the OpenXR API made by Khronos.
The project currently is being developed for GNU/Linux
and aims to support other operating systems in the near future.
"Monado" has no specific meaning and is just a name.

## Monado source tree

* `src/xrt/include` - headers that define the internal interfaces of Monado.
* `src/xrt/compositor` - code for doing distortion and driving the display hardware of a device.
Ryan Pavlik's avatar
Ryan Pavlik committed
22
* `src/xrt/auxiliary` - utilities and other larger components.
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
23
24
25
26
27
28
29
30
31
32
33
* `src/xrt/drivers` - hardware drivers.
* `src/xrt/state_trackers/oxr` - OpenXR API implementation.
* `src/xrt/targets` - glue code and build logic to produce final binaries.
* `src/external` - a small collection of external code and headers.

## Getting Started

Dependencies include:

* [CMake][] 3.10 or newer
* Vulkan headers
Ryan Pavlik's avatar
Ryan Pavlik committed
34
* OpenGL headers
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
35
* Eigen3
36
* glslangValidator - Debian/Ubuntu package `glslang-tool`.
Ryan Pavlik's avatar
Ryan Pavlik committed
37
38
* libusb
* libudev
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
39
40
41
42

Optional (but recommended) dependencies:

* libxcb and xcb-xrandr development packages
Ryan Pavlik's avatar
Ryan Pavlik committed
43
* [OpenHMD][] (found using pkg-config)
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
44

Ryan Pavlik's avatar
Ryan Pavlik committed
45
Truly optional dependencies, useful for some drivers, app support, etc.:
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
46
47
48

* Doxygen
* Wayland development packages
Ryan Pavlik's avatar
Ryan Pavlik committed
49
50
51
52
53
54
* Xlib development packages
* libhidapi
* OpenCV
* libuvc
* ffmpeg
* libjpeg
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
55
56
57
58
59
60

Tested distributions that are fully compatible,
on Intel and AMD graphics:

* Ubuntu 18.10 (18.04 does not work)
* Debian 10 `buster`
Ryan Pavlik's avatar
Ryan Pavlik committed
61
62
  * Up-to-date package lists can be found in our CI config file,
    `.gitlab-ci.yml`
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
63
64
65
66
67
68

These distributions include recent-enough versions of all the
software to use direct mode,
without using any external, third-party, or backported
package sources.

69
See also [Status of DRM Leases][drm-lease]
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
70
71
72
73
74
75
76
77
for more details on specific packages, versions, and commits.

Build process is similar to other CMake builds,
so something like the following will build it.

Go into the source directory, create a build directory,
and change into it.

78
79
80
81
```bash
mkdir build
cd build
```
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
82
83
84
85

Then, invoke [CMake to generate a project][cmake-generate].
Feel free to change the build type or generator ("Ninja" is fast and parallel) as you see fit.

86
87
88
```bash
cmake .. -DCMAKE_BUILD_TYPE=Debug -G "Unix Makefiles"
```
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
89
90
91
92
93
94
95
96
97
98
99

If you plan to install the runtime,
append something like `-DCMAKE_INSTALL_PREFIX=~/.local`
to specify the root of the install directory.
(The default install prefix is `/usr/local`.)

To build, [the generic CMake build commands][cmake-build] below will work on all systems,
though you can manually invoke your build tool (`make`, `ninja`, etc.) if you prefer.
The first command builds the runtime and docs,
and the second, which is optional, installs the runtime under `${CMAKE_INSTALL_PREFIX}`.

100
101
102
103
```bash
cmake --build .
cmake --build . --target install
```
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
104
105
106
107

Alternately, if using Make, the following will build the runtime and docs, then install.
Replace `make` with `ninja` if you used the Ninja generator.

108
109
110
111
```bash
make
make install
```
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
112

113
Documentation can be browsed by opening `doc/html/index.html` in the build directory in a web browser.
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
114
115
116

## Getting started using OpenXR with Monado

117
This implements the [OpenXR][] API,
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
118
119
120
121
122
123
124
125
126
127
128
129
so to do anything with it, you'll need an application
that uses OpenXR, along with the OpenXR loader.
The OpenXR loader is a glue library that connects OpenXR applications to OpenXR runtimes such as Monado
It determines which runtime to use by reading config file default `/usr/local/share/openxr/0/active_runtime.json`
and processes environment variables such as `XR_RUNTIME_JSON=/usr/share/openxr/0/openxr_monado.json`.
It can also insert OpenXR API Layers without the application or the runtime having to do it.

You can use the `hello_xr` sample provided with the
OpenXR loader and API layers.

The OpenXR loader can be pointed to a runtime json file in a nonstandard location with the environment variable `XR_RUNTIME_JSON`. Example:

130
131
132
```bash
XR_RUNTIME_JSON=~/monado/build/openxr_monado-dev.json ./openxr-example
```
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172

For this reason this runtime creates two manifest files within the build directory:

* `openxr_monado.json` uses a relative path to the runtime, and is intended to be installed with `make install`.
* `openxr_monado_dev.json` uses an absolute path to the runtime in its build directory,
  and is intended to be used for development without installing the runtime.

If Monado has been installed through a distribution package
and provides the "active runtime" file /usr/local/share/openxr/0/active_runtime.json,
then the loader will automatically use Monado when starting any OpenXR application.

If Monado has been compiled in a custom directory like ~/monado/build,
the OpenXR loader can be pointed to the runtime when starting an OpenXR application
by setting the environment variable XR_RUNTIME_JSON to the `openxr_monado_dev.json` manifest
that was generated by the build: see above.

Note that the loader can always find and load the runtime
if the path to the runtime library given in the json manifest is an absolute path,
but if a relative path like `libopenxr_monado.so.0` is given,
then `LD_LIBRARY_PATH` must include the directory that contains `libopenxr_monado.so.0`.
The absolute path in `openxr_monado_dev.json` takes care of this for you.

## Direct mode

Our direct mode code requires a connected HMD to have the `non-desktop` xrandr
property set to 1.
Only the most common HMDs have the needed quirks added to the linux kernel.
Just keep on reading for more info on how to work around that.

If you know that your HMD lacks the quirk you can run this command **before** or
after connecting the HMD and it will have it. Where `HDMI-A-0` is the xrandr
output name where you plug the HMD in.

```bash
xrandr --output HDMI-A-0 --prop --set non-desktop 1
```

You can verify that it stuck with the command.

```bash
Benjamin Saunders's avatar
Benjamin Saunders committed
173
xrandr --prop
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
174
175
176
177
178
179
180
181
182
183
184
185
```

## Coding style and formatting

[clang-format][] is used,
and a `.clang-format` config file is present in the repo
to allow your editor to use them.

To manually apply clang-format to every non-external source file in the tree,
run this command in the source dir with a `sh`-compatible shell
(Git for Windows git-bash should be OK):

186
187
188
```bash
scripts/format-project.sh
```
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
189
190
191
192
193
194

You can optionally put something like `CLANG_FORMAT=clang-format-7` before that command
if your clang-format binary isn't named `clang-format`.
Note that you'll typically prefer to use something like `git clang-format`
to just re-format your changes, in case version differences in tools result in overall format changes.

195
[OpenHMD]: https://openhmd.net
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
196
[drm-lease]: https://haagch.frickel.club/#!drmlease%2Emd
197
[OpenXR]: https://khronos.org/openxr
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
[clang-format]: https://releases.llvm.org/7.0.0/tools/clang/docs/ClangFormat.html
[cmake-build]: https://cmake.org/cmake/help/v3.12/manual/cmake.1.html#build-tool-mode
[cmake-generate]: https://cmake.org/cmake/help/v3.12/manual/cmake.1.html
[CMake]: https://cmake.org

## Contributing, Code of Conduct

See `CONTRIBUTING.md` for details of contribution guidelines.

Please note that this project is released with a Contributor Code of Conduct.
By participating in this project you agree to abide by its terms.

We follow the standard freedesktop.org code of conduct,
available at <https://www.freedesktop.org/wiki/CodeOfConduct/>,
which is based on the [Contributor Covenant](https://www.contributor-covenant.org).

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting:

* First-line project contacts:
  * Jakob Bornecrantz <jakob@collabora.com>
  * Ryan Pavlik <ryan.pavlik@collabora.com>
* freedesktop.org contacts: see most recent list at <https://www.freedesktop.org/wiki/CodeOfConduct/>

## Copyright and License for this README.md file

For this file only:

> Copyright 2018-2019 Collabora, Ltd.
Ryan Pavlik's avatar
Ryan Pavlik committed
227
> Code of Conduct section: excerpt adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 1.4.1,
Jakob Bornecrantz's avatar
Jakob Bornecrantz committed
228
229
230
231
232
233
> available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>,
> and from the freedesktop.org-specific version of that code,
> available at <https://www.freedesktop.org/wiki/CodeOfConduct/>
>
>
> SPDX-License-Identifier: CC-BY-4.0