About OpenXR and Monado

Software that supports VR by using the OpenXR API requires two software packages to work:

OpenXR runtimes like Monado can be though of as “VR headset and VR controller drivers” and the OpenXR loader, analog to the Vulkan loader, is responsible for finding and connecting applications to this “driver” so that OpenXR applications do not need to interact directly with a runtime. The OpenXR loader also comes with all necessary C headers to compile OpenXR applications.

More general information about the background behind OpenXR and OpenXR runtimes can be found at About Runtimes.

The initial focus for Monado lies on desktop VR usage. In the future a main goal will be to bring Monado to mobile and standalone AR devices, but desktop VR support will be kept by Monado for the foreseeable future.

Monado Requirements

Monado currently runs on Linux. Windows support is on the long term roadmap.

The Monado compositor requires a Vulkan driver with the instance extensions:

and the Device extensions:

OpenXR applications using OpenGL require an OpenGL driver with support for the GL_EXT_memory_object_fd OpenGL extension. OpenGL applications are supported with radeonsi and the nvidia proprietary driver. Intel does not currently support this extension.

OpenXR applications using Vulkan are supported with radv, intel anv and the nvidia proprietary driver.

OpenXR Loader and Monado Installation

Distribution packages

Packages are available for various distributions.

If your distribution does not provide packages for the OpenXR Loader and Monado, you can build them from source.

Installation from Source

OpenXR Loader

See https://github.com/KhronosGroup/OpenXR-SDK#linux for a list of dependencies

git clone https://github.com/KhronosGroup/OpenXR-SDK.git
cd OpenXR-SDK
cmake -G Ninja -DCMAKE_INSTALL_PREFIX=/usr -Bbuild
ninja -C build install

Monado

See https://gitlab.freedesktop.org/monado/monado#getting-started for a list of dependencies.

This command will install required and optional dependencies that will enable most functionality of monado on Debian/Ubuntu.

apt install build-essential git wget unzip cmake meson ninja-build libeigen3-dev curl patch python3 pkg-config libx11-dev libx11-xcb-dev libxxf86vm-dev libxrandr-dev libxcb-randr0-dev libvulkan-dev glslang-tools libglvnd-dev libgl1-mesa-dev ca-certificates libusb-1.0-0-dev libudev-dev libhidapi-dev libwayland-dev libuvc-dev libavcodec-dev libopencv-dev libv4l-dev libcjson-dev libsdl2-dev libegl1-mesa-dev

then compile and install Monado:

git clone https://gitlab.freedesktop.org/monado/monado.git
cd monado
meson --prefix=/usr build
ninja -C build install

Running OpenXR Applications

Monado Service

Since version 0.2, Monado’s compositor and drivers run in a separate service process, /usr/bin/monado-service in a default installation. This service can either be started manually, or automatically by using systemd socket activation.

For manually starting the service, run /usr/bin/monado-service, then run your application. Most monado developers are expected to use this.

If systemd is available (and it’s not configured to disable this), a monado.socket and monado.service user unit files are installed in /usr/lib/systemd/user or similar. systemctl --user enable monado.socket will have systemd open the domain socket at login. Running an OpenXR application will spin up the service, while systemctl --user stop monado.service will stop it. This is expected to mainly be used by end users installing a package.

Selecting the Monado runtime for OpenXR applications

Most installations of Monado will ship an active_runtime.json symlink in a systemwide xdg config path, which will make the OpenXR loader to use Monado when starting OpenXR applications as described in the loader documentation. If the packager decided not to ship an active_runtime.json symlink, you can create it yourself:

sudo mkdir -p /etc/xdg/openxr/1/
sudo ln -s /usr/share/openxr/1/openxr_monado.json /etc/xdg/openxr/1/active_runtime.json

Alternatively the OpenXR Loader also knows user specific xdg config paths. Note that this will only be obeyed by applications that are not run as root.

mkdir -p ~/.config/openxr/1
ln -s /usr/share/openxr/1/openxr_monado.json ~/.config/openxr/1/active_runtime.json

The environment variable XR_RUNTIME_JSON can be used in absense of, or to override an active_runtime.json:

XR_RUNTIME_JSON=/usr/share/openxr/1/openxr_monado.json ./application

Developing with Monado

You can now start developing with Monado