matrixfurry.com
The open source OpenXR runtime
readme: Add meson build and update a bit
+39
-49
+39
-49
README.md
+39
-49
README.md
···
28
28
29
29
Dependencies include:
30
30
31
-
* [CMake][] 3.13 or newer (Note Ubuntu 18.04 only has 3.10)
31
+
* [CMake][] 3.13 or newer (Note Ubuntu 18.04 only has 3.10) or meson >= 0.49
32
32
* Vulkan headers
33
33
* OpenGL headers
34
34
* Eigen3
···
60
60
* Debian 10 `buster`
61
61
* Up-to-date package lists can be found in our CI config file,
62
62
`.gitlab-ci.yml`
63
+
* Archlinux
63
64
64
65
These distributions include recent-enough versions of all the
65
66
software to use direct mode,
···
69
70
See also [Status of DRM Leases][drm-lease]
70
71
for more details on specific packages, versions, and commits.
71
72
72
-
Due to the lack of a OpenGL extension: GL_EXT_memory_object_fd, only the AMD
73
+
Due to the lack of a OpenGL extension: GL_EXT_memory_object_fd on Intel's
74
+
OpenGL driver, only the AMD
73
75
radeonsi driver and the proprietary NVIDIA driver will work for OpenGL OpenXR
74
76
clients. This is due to a requirement of the Compositor. Support status of the
75
77
extension can be found on the [mesamatrix website][mesamatrix-ext].
76
78
79
+
### CMake
80
+
77
81
Build process is similar to other CMake builds,
78
82
so something like the following will build it.
79
83
···
117
121
118
122
Documentation can be browsed by opening `doc/html/index.html` in the build directory in a web browser.
119
123
124
+
### Meson
125
+
126
+
The build process is similar to other Meson builds.
127
+
For a system wide installation requiring root privileges:
128
+
129
+
```bash
130
+
meson --prefix=/usr build
131
+
ninja -C build install
132
+
```
133
+
134
+
For a local installation in ~/.local:
135
+
136
+
```bash
137
+
meson --prefix=~/.local -Dinstall-active-runtime=false build
138
+
ninja -C build install
139
+
```
140
+
141
+
Note that the installation of the `active_runtime.json` file should be disabled for installations without
142
+
root privileges because this file is always installed in meson's syconfdir (usually /etc).
143
+
120
144
## Getting started using OpenXR with Monado
121
145
122
146
This implements the [OpenXR][] API,
123
147
so to do anything with it, you'll need an application
124
148
that uses OpenXR, along with the OpenXR loader.
125
149
The OpenXR loader is a glue library that connects OpenXR applications to OpenXR runtimes such as Monado
126
-
It determines which runtime to use by reading config file default `/usr/local/share/openxr/0/active_runtime.json`
150
+
It determines which runtime to use by looking for the config file `active_runtime.json` (either a symlink to
151
+
or a copy of a runtime manifest) in the usual XDG config paths
127
152
and processes environment variables such as `XR_RUNTIME_JSON=/usr/share/openxr/0/openxr_monado.json`.
128
153
It can also insert OpenXR API Layers without the application or the runtime having to do it.
129
154
130
-
You can use the `hello_xr` sample provided with the
131
-
OpenXR loader and API layers.
155
+
You can use the `hello_xr` sample provided with the OpenXR SDK.
132
156
133
157
The OpenXR loader can be pointed to a runtime json file in a nonstandard location with the environment variable `XR_RUNTIME_JSON`. Example:
134
158
···
136
160
XR_RUNTIME_JSON=~/monado/build/openxr_monado-dev.json ./openxr-example
137
161
```
138
162
139
-
For this reason this runtime creates two manifest files within the build directory:
140
-
141
-
* `openxr_monado.json` uses a relative path to the runtime, and is intended to be installed with `make install`.
142
-
* `openxr_monado_dev.json` uses an absolute path to the runtime in its build directory,
143
-
and is intended to be used for development without installing the runtime.
144
-
145
-
If Monado has been installed through a distribution package
146
-
and provides the "active runtime" file /usr/local/share/openxr/0/active_runtime.json,
147
-
then the loader will automatically use Monado when starting any OpenXR application.
148
-
149
-
If Monado has been compiled in a custom directory like ~/monado/build,
150
-
the OpenXR loader can be pointed to the runtime when starting an OpenXR application
151
-
by setting the environment variable XR_RUNTIME_JSON to the `openxr_monado_dev.json` manifest
152
-
that was generated by the build: see above.
163
+
For ease of development Monado creates a runtime manifest file in its build directory using an absolute path to the
164
+
Monado runtime in the build directory called `openxr_monado-dev.json`. Pointing `XR_RUNTIME_JSON` to this
165
+
file allows using Monado after building, without installing.
153
166
154
167
Note that the loader can always find and load the runtime
155
168
if the path to the runtime library given in the json manifest is an absolute path,
156
169
but if a relative path like `libopenxr_monado.so.0` is given,
157
170
then `LD_LIBRARY_PATH` must include the directory that contains `libopenxr_monado.so.0`.
158
-
The absolute path in `openxr_monado_dev.json` takes care of this for you.
171
+
The absolute path in `openxr_monado-dev.json` takes care of this for you.
172
+
173
+
Distribution packages for monado may provide the "active runtime" file `/etc/xdg/openxr/1/active_runtime.json`.
174
+
In this case the loader will automatically use Monado when starting an OpenXR application. This global configuration
175
+
can be overridden on a per user basis by creating `~/.config/openxr/1/active_runtime.json`.
159
176
160
177
## Direct mode
161
178
162
-
Our direct mode code requires a connected HMD to have the `non-desktop` xrandr
163
-
property set to 1.
179
+
On AMD and Intel GPUs our direct mode code requires a connected HMD to have
180
+
the `non-desktop` xrandr property set to 1.
164
181
Only the most common HMDs have the needed quirks added to the linux kernel.
165
-
Just keep on reading for more info on how to work around that.
166
182
167
183
If you know that your HMD lacks the quirk you can run this command **before** or
168
184
after connecting the HMD and it will have it. Where `HDMI-A-0` is the xrandr
···
192
208
khronos_validation.debug_action = VK_DBG_LAYER_ACTION_LOG_MSG,VK_DBG_LAYER_ACTION_BREAK
193
209
khronos_validation.report_flags = error,warn
194
210
khronos_validation.log_filename = stdout
195
-
```
196
-
197
-
## Using libsurvive
198
-
199
-
To enable the libsurvive driver, libsurvive has to be installed as a library with a pkgconfig file
200
-
(https://github.com/cntools/libsurvive/pull/187).
201
-
202
-
When starting any libsrvive or OpenXR application, libsurvive will run calibration and save
203
-
configuration and calibration data in the current working directory.
204
-
205
-
Make sure the HMD can see both basestations and is not moved during calibration.
206
-
207
-
To remove libsurvive's calibration data (e.g. to force recalibration) delete the following
208
-
files/directories:
209
-
210
-
rm -r *config.json calinfo
211
-
212
-
Though working and somewhat usable, support for the libsurvive driver is **experimental**.
213
-
Therefore with both meson and cmake, the survive driver has to be explicitly enabled with
214
-
215
-
```
216
-
#cmake
217
-
-DBUILD_WITH_LIBSURVIVE=On
218
-
219
-
#meson
220
-
-Ddrivers=auto,survive
221
211
```
222
212
223
213
## Coding style and formatting