getting-started.md

title: "Monado - Getting Started"
layout: main

About OpenXR and Monado

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

• The OpenXR Loader provided by Khronos
• An OpenXR runtime like Monado or SteamVR (with OpenXR support)

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.\ Applications link to only the libopenxr_loader.so or .dll library and use the C headers provided by the OpenXR SDK.

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

The initial focus of 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 remain an important aspect for Monado for the foreseeable future.

Monado Requirements

Monado currently runs on Linux. A windows port is in progress.

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

• VK_KHR_external_fence_capabilities
• VK_KHR_external_memory_capabilities
• VK_KHR_external_semaphore_capabilities
• VK_KHR_get_physical_device_properties2
• VK_KHR_surface
• for direct mode on Linux/X11
  • VK_KHR_display
  • VK_EXT_direct_mode_display
  • VK_EXT_acquire_xlib_display

and the Device extensions:

• VK_KHR_dedicated_allocation
• VK_KHR_external_fence
• VK_KHR_external_fence_fd
• VK_KHR_external_memory
• VK_KHR_external_memory_fd
• VK_KHR_external_semaphore
• VK_KHR_external_semaphore_fd
• VK_KHR_get_memory_requirements2
• VK_KHR_swapchain

OpenXR applications using Vulkan are supported with all Vulkan drivers that support the listed extensions. In particular radv, intel anv and the nvidia proprietary driver are tested and confirmed to work.

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 in mainline mesa but there are WIP MRs for mesa/iris and for mesa/i965 that have been tested to work with Monado.

Running Monado with the amdvlk Vulkan driver generally works but may not render OpenXR applications using OpenGL correctly.

OpenXR SDK and Monado Installation

There are no prebuilt generic binaries for monado available at this time.\ If your distribution does not provide packages for the OpenXR SDK and Monado, you will have to build Monado from source.

Distribution packages

Packages for the OpenXR SDK and Monado are available for various distributions.

• Debian through OBS
• Ubuntu through a PPA or gitlab CI
• Archlinux AUR: openxr-loader-git and AUR: monado-git

Up to date information can be found on repology.

Debian and Ubuntu packages

{: #deb} In Debian and Ubuntu the OpenXR SDK is split into several packages.

The core packages are

• libopenxr-loader1
  • This is libopenxr_loader.so library. OpenXR applications link to this library and can not be compiled/run without it.
• libopenxr-dev
  • The OpenXR headers are required to compile OpenXR C/C++ applications.
• libopenxr1-monado
  • The Monado OpenXR runtime

Useful packages:

• xr-hardware
  • udev rules allowing users without root permissions to use XR hardware, installation is highly recommended
• libopenxr-utils
  • OpenXR applications and demos, including the hello_xr example
• openxr-layer-corevalidation
  • A validation layer for OpenXR. Can be enabled with the environment variable XR_ENABLE_API_LAYERS=XR_APILAYER_LUNARG_core_validation
• openxr-layer-apidump
  • Another layer that can dump all OpenXR calls an application makes to a file
• monado-cli, monado-gui
  • See Tools for a detailed description

Installation from Source

Install the meson and ninja build tools

apt install meson ninja-build

OpenXR SDK

The OpenXR SDK contains the OpenXR loader and the OpenXR headers.

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

Build the OpenXR SDK with cmake, this example uses ninja.

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 of the 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. Monado can be built with either cmake or meson.

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 can be built in two different modes: With monado-service (this is the default) and without monado-service.

The service can be disabled with meson -Dservice=false or cmake -DXRT_FEATURE_SERVICE=OFF.

With monado-service

{: #service}

When monado is built with monado-service, Monado's compositor and drivers run in a separate service process that has to be started before running an OpenXR application. monado-service will be installed as /usr/bin/monado-service in a default installation.

monado-service can either be started manually by running the binary, or it can be run automatically by using systemd socket activation.

Most monado developers and users who want exact control over when Monado is running are expected to run monado-service manually.

A manually started monado-service is cleanly shut down by simply pressing enter in the terminal it was started in. An unclean shutdown (ctrl+c, crash) will leave a socket file /tmp/monado_comp_ipc around. The Monado compositor will refuse to start if this file is found with the message ERROR: Could not bind socket to path /tmp/monado_comp_ipc: is the service running already?. If monado-service is not running, it is safe to simply delete /tmp/monado_comp_ipc.

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.

Without monado-service

When monado is built with the service disabled, the monado-service binary is not built. Instead of connecting to a long running service instance, OpenXR applications load the entire monado runtime as a library, initialize it at startup and shut it down on exit.

This mode is very convenient for debugging the Monado runtime, but makes it impossible to run overlay applications with XR_EXTX_overlay.

Selecting the Monado runtime for OpenXR applications

The OpenXR loader chooses the OpenXR runtime to load by first looking at the environment variable XR_RUNTIME_JSON or if this variable is not set for a file called active_runtime.json in various locations.

Most installations of Monado will ship an active_runtime.json symlink in a systemwide xdg config path, which will make the OpenXR loader 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

Tools

{: #tools}

Monado comes with a number of tools.

monado-service

See Running OpenXR applications with monado-service

monado-gui