From a0c71f87504c02b4089ec3d38db0bc7b5cd87f12 Mon Sep 17 00:00:00 2001
From: Ryan Pavlik <ryan.pavlik@collabora.com>
Date: Tue, 23 Feb 2021 16:14:33 -0600
Subject: [PATCH] Cleanups for getting started page.
---
getting-started.md | 65 +++++++++++++++++++++++-----------------------
1 file changed, 32 insertions(+), 33 deletions(-)
diff --git a/getting-started.md b/getting-started.md
index d802513..45601b5 100644
--- a/getting-started.md
+++ b/getting-started.md
@@ -6,7 +6,7 @@ layout: main
* TOC
{:toc}
-# About OpenXR and Monado
+## About OpenXR and Monado
Software that supports VR by using the OpenXR API requires two software packages to work:
@@ -20,9 +20,9 @@ More general background information about OpenXR and OpenXR runtimes can be foun
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 Requirements
-Monado currently runs on Linux. A windows port is in progress.
+Monado currently runs on Linux. A Windows port is in progress.
The Monado compositor requires a Vulkan driver with the instance extensions:
@@ -34,13 +34,13 @@ The Monado compositor requires a Vulkan driver with the instance extensions:
* for direct mode on Linux/X11
* VK_KHR_display
* VK_EXT_direct_mode_display
- * VK_EXT_acquire_xlib_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_dedicated_allocation
+* VK_KHR_external_fence
+* VK_KHR_external_fence_fd
* VK_KHR_external_memory
* VK_KHR_external_memory_fd
* VK_KHR_external_semaphore
@@ -55,12 +55,12 @@ OpenXR applications using OpenGL require an OpenGL driver with support for the `
Running Monado with the amdvlk Vulkan driver generally works but may not render OpenXR applications using OpenGL correctly.
-# OpenXR SDK and Monado Installation
+## 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
+### Distribution packages
Packages for the OpenXR SDK and Monado are available for various distributions.
@@ -70,7 +70,7 @@ Packages for the OpenXR SDK and Monado are available for various distributions.
Up to date information can be found [on repology](https://repology.org/project/monado/versions).
-### Debian and Ubuntu packages
+#### Debian and Ubuntu packages
{: #deb}
In Debian and Ubuntu the OpenXR SDK is split into several packages.
@@ -96,13 +96,13 @@ Useful packages:
* monado-cli, monado-gui
* See [Tools](#tools) for a detailed description
-## Installation from Source
+### Installation from Source
Install the meson and ninja build tools
apt install meson ninja-build
-### OpenXR SDK
+#### OpenXR SDK
The OpenXR SDK contains the OpenXR loader and the OpenXR headers.
@@ -115,7 +115,7 @@ Build the OpenXR SDK with cmake, this example uses ninja.
cmake . -G Ninja -DCMAKE_INSTALL_PREFIX=/usr -Bbuild
ninja -C build install
-### Monado
+#### Monado
See [https://gitlab.freedesktop.org/monado/monado#getting-started](https://gitlab.freedesktop.org/monado/monado#getting-started) for a list of dependencies.
@@ -131,15 +131,15 @@ then compile and install Monado. Monado can be built with either cmake or meson.
meson --prefix=/usr build
ninja -C build install
-# Running OpenXR Applications
+## Running OpenXR Applications
-## Monado Service
+### 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`
+#### 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.
@@ -153,24 +153,23 @@ A manually started `monado-service` is cleanly shut down by simply pressing ente
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`
+#### 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
+### 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](https://github.com/KhronosGroup/OpenXR-SDK-Source/blob/master/specification/loader/runtime.adoc). 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
@@ -178,32 +177,32 @@ The environment variable `XR_RUNTIME_JSON` can be used in absense of, or to over
XR_RUNTIME_JSON=/usr/share/openxr/1/openxr_monado.json ./application
-## Driver Selection
+### Driver Selection
Monado automatically initializes drivers in the order they appear in [target_lists.c](https://gitlab.freedesktop.org/monado/monado/-/blob/master/src/xrt/targets/common/target_lists.c).
For example for a connected HTC Vive, Monado will first attempt to use the "survive" driver, then the "vive" driver, and at last the "ohmd" (OpenHMD) driver. In this example, to use the "ohmd" driver, the "survive" and "vive" drivers should be disabled.
-# Tools
+## Tools
{: #tools}
Monado comes with a number of tools.
-## monado-service
+### monado-service
See [Running OpenXR applications with `monado-service`](#service)
-## monado-gui
+### monado-gui
`monado-gui` serves the important function of calibrating cameras for positional tracking. See [Setting up Playstation Move Controllers]({% link positional-tracking-psmove.md %}) for an example of using it for calibration.
`monado-gui` stores persistent configuration in `$XDG_CONFIG_HOME`, or by default `~/.config/monado/`. A configuration file is only required for setups that require camera calibration (PSVR, PS Move).
-## monado-cli
+### monado-cli
`monado-cli probe` and the more verbose `monado-cli test` provide an easy way to test which supported devices monado finds and can open.
-## monado-ctl
+### monado-ctl
Running concurrent non-overlay OpenXR applications will result in Monado only presenting the first started application. monado-ctl allows choosing the currently presented application. This command is only installed when the monado service is enabled at build time.
@@ -211,13 +210,13 @@ Running concurrent non-overlay OpenXR applications will result in Monado only pr
`monado-ctl -p 1` switches monado to present the application with id `1` in the list reported by `monado-ctl`.
-# Environment Variables
+## Environment Variables
Note: When compiling monado without monado-service, the environment variables that apply to the service can be used with the OpenXR application directly.
Either `TRUE`/`FALSE` or `1`/`0` can be used to set boolean variables.
-## General
+### General
Available for monado-service and OpenXR applications:
@@ -233,7 +232,7 @@ Available for monado-service:
* `PROBER_LOG=debug`: Print information about devices that are found and opened.
* `IPC_EXIT_ON_DISCONNECT=1`: Exit the service whenever a client quits.
-## Compositor
+### Compositor
Available for monado-service:
@@ -255,7 +254,7 @@ Available for OpenXR applications
* `OXR_VIEWPORT_SCALE_PERCENTAGE=100`: Scale the render target size recommended to this application to render at. Affects only this application. Defaults to 100%. Applied on top of `XRT_COMPOSITOR_SCALE_PERCENTAGE`.
* `OXR_DEBUG_IPD_MM=58`: Change the default IPD (63mm) for drivers that do not support dynamic IPD adjustment.
-## Logging
+### Logging
{: #loglevel}
Various components and drivers in Monado use a logging system with well known logging levels `trace`, `debug`, `info` `warn`, `error`.
@@ -268,14 +267,14 @@ Environment variables that make use of the log level system typically end with `
* `XRT_COMPOSITOR_LOG=debug`
* `XRT_LOG=debug`: Log messages from various systems around monado not hooked up to a more specific category.
-## Debug GUI
+### Debug GUI
Available for OpenXR applications and monado-service:
* `OXR_DEBUG_GUI=1`: Open a separate debug window for observing and manipulating certain state. For example changing a tracking origin virtually moves devices tracked on that tracking origin.
* the debug information shown for monado-service and OpenXR clients is different, for example monado-service shows a basic compositor frametiming graph.
-## SteamVR plugin
+### SteamVR plugin
These variables should be set for SteamVR, for example when starting from command line: `STEAMVR_EMULATE_INDEX_CONTROLLER=1 ~/.local/share/Steam/steamapps/common/SteamVR/bin/vrstartup.sh`
or in the Steam library properties for SteamvR: `STEAMVR_EMULATE_INDEX_CONTROLLER=1 %command%`
@@ -283,6 +282,6 @@ or in the Steam library properties for SteamvR: `STEAMVR_EMULATE_INDEX_CONTROLLE
* `STEAMVR_EMULATE_INDEX_CONTROLLER=1`: Use SteamVR's Index controller profile with hardcoded bindings instead of monado's generated input profiles. May be useful to make legacy games work.
* `XRT_COMPOSITOR_SCALE_PERCENTAGE=100`: Scales SteamVR's render target size, like for the Monado compositor.
-# Developing with Monado
+## Developing with Monado
You can now start [developing with Monado]({% link developing-with-monado.md %})
--
GitLab