diff --git a/developing-with-monado.md b/developing-with-monado.md
index 4bcf65bd0500e881339ea8ad986baa68da9043ad..12f1c9af674fb2d6518acc6e0314ea9165e07dee 100644
--- a/developing-with-monado.md
+++ b/developing-with-monado.md
@@ -5,45 +5,140 @@ layout: main
# Developing with OpenXR and Monado
-After installing Monado with the [Getting Started Guide]({% link getting-started.md %}) it is time to develop an OpenXR application.
+After installing the OpenXR SDK and Monado with the [Getting Started Guide]({% link getting-started.md %}) it is time to develop an OpenXR application.
# The OpenXR SDK
-The core of the OpenXR SDK consists of the OpenXR loader and the OpenXR headers. If you installed the OpenXR SDK from your distributions's package manager, make sure you installed the relevant -dev or header packages. If you installed OpenXR-SDK or OpenXR-SDK-Source from source, you should be fine.
+On Archlinux, the OpenXR loader installs these files
+
+* /usr/lib/libopenxr_loader.so*
+ * The library that applications use for linking to OpenXR. Usually with soname symlinks: libopenxr_loader.so, libopenxr_loader.so.1 and libopenxr_loader.so.1.0.11
+* /usr/lib/cmake/openxr/*.cmake
+ * cmake files that enable cmake directives like `PKG_SEARCH_MODULE(OPENXR REQUIRED openxr)`
+* /usr/lib/pkgconfig/openxr.pc
+ * pkg-config files that can be used by cmake with `FindPkgConfig` or non-cmake build systems.
+ * Run `pkg-config --libs --cflags openxr` to see what it provides.
+
+Other distributions may use different paths like `/usr/lib/x86_64-linux-gnu/...`.
+
+The OpenXR headers
+
+* /usr/include/openxr/openxr.h
+ * The main OpenXR API header.
+* /usr/include/openxr/openxr_platform_defines.h
+ * Various platform defines used by the main OpenXR API header. Usually you don't need to use it directly.
+* /usr/include/openxr/openxr_platform.h
+ * The part of the OpenXR API that is platform specific.
+ * Before including this header, add defines for the parts you want to use, e.g.
+ * `#define XR_USE_PLATFORM_XLIB`
+ * `#define XR_USE_GRAPHICS_API_OPENGL`
+* /usr/include/openxr/openxr_reflection.h
+ * Not necessary, but useful for iterating over OpenXR enums, or getting string representations of OpenXR enum values.
To start developing for OpenXR only those components are necessary. Similar to how Vulkan applications are developed by including Khronos' Vulkan headers and linking to Khronos' Vulkan loader, OpenXR applications include Khronos' OpenXR headers and link to Khronos' OpenXR loader. Just like compiling a Vulkan application does not require any Vulkan driver to be installed, compiling an OpenXR application does not require any OpenXR runtime to be installed.
-Khronos has not released a reference implementation for OpenXR, so for actually running an OpenXR application some vendor's OpenXR runtime has to be installed.
+Khronos has not released a reference implementation for OpenXR, so for actually running an OpenXR application some vendor's OpenXR runtime (for example Monado) has to be installed.
# Setting up the project
-The OpenXR SDK should have installed a file /usr/lib/pkgconfig/openxr.pc or similar. You can check with `pkg-config --cflags --libs openxr` whether the installation is correct.
## CMake
-To make use of OpenXR's pkg-config file you can use CMake's FindPkgConfig module.
+Here is a minimal cmake example to compile an `example` executable that can include OpenXR headers and links to the OpenXR loader.
```cmake
-INCLUDE(FindPkgConfig)
-PKG_SEARCH_MODULE(OPENXR REQUIRED openxr)
+cmake_minimum_required(VERSION 3.0.0)
+project(Example)
+
+add_executable(example main.c)
+
+find_package(OpenXR REQUIRED)
+if(OpenXR_FOUND)
+ target_include_directories(example PRIVATE OpenXR::Headers)
+ target_link_libraries(example PRIVATE OpenXR::openxr_loader)
+else()
+ MESSAGE(FATAL_ERROR "Please verify your OpenXR SDK installation")
+endif()
+```
+
+As an alternative you can use OpenXR's pkg-config file with CMake's FindPkgConfig module.
+
-target_link_libraries(<your_app> PRIVATE ${OPENXR_LIBRARIES})
-target_include_directories(demo PRIVATE ${OPENXR_HEADERS})
+```cmake
+cmake_minimum_required(VERSION 3.0.0)
+project(Example)
+
+add_executable(example main.c)
+
+INCLUDE(FindPkgConfig)
+PKG_SEARCH_MODULE(OpenXR REQUIRED openxr)
+if(OpenXR_FOUND)
+ target_link_libraries(example PRIVATE ${OpenXR_LIBRARIES})
+ target_include_directories(example PRIVATE ${OpenXRHEADERS})
+else()
+ MESSAGE(FATAL_ERROR "Please verify your OpenXR SDK installation")
+endif()
```
-If you prefer using your own FindOpenXR.cmake file, the xrtraits utility has an example: https://gitlab.freedesktop.org/monado/utilities/xrtraits/-/blob/master/cmake/FindOpenXR.cmake
+If you prefer using your own FindOpenXR.cmake file, [the xrtraits utility has an example](https://gitlab.freedesktop.org/monado/utilities/xrtraits/-/blob/master/cmake/FindOpenXR.cmake).
## meson
+Meson uses pkg-config by default for its dependency() mechanism.
+
```meson
+project('Example', ['c'])
+
openxr_dep = dependency('openxr')
-executable('<your_app>', sources, dependencies: [openxr_dep])
+executable('example', ['main.c'], dependencies: [openxr_dep])
```
# Application
With this project setup you can start including the `<openxr/openx.h>` header and start calling OpenXR functions.
+As a starting point, here is a minimal C example for starting an OpenGL application on Linux with the xlib graphics binding.
+
+```c
+// openxr_platform.h does not include all its dependencies, we have to include some headers before it
+#include <string.h>
+#include <X11/Xlib.h>
+#include <GL/glx.h>
+
+// before including openxr_platform.h we have to define which platform specific parts we want enabled
+#define XR_USE_PLATFORM_XLIB
+#define XR_USE_GRAPHICS_API_OPENGL
+#include <openxr/openxr.h>
+#include <openxr/openxr_platform.h>
+
+int main()
+{
+ char *extensions[] = { XR_KHR_OPENGL_ENABLE_EXTENSION_NAME };
+ int extension_count = sizeof(extensions) / sizeof(extensions[0]);
+
+ XrInstanceCreateInfo instanceCreateInfo = {
+ .type = XR_TYPE_INSTANCE_CREATE_INFO,
+ .next = NULL,
+ .createFlags = 0,
+ .enabledExtensionCount = extension_count,
+ .enabledExtensionNames = (const char * const *) extensions,
+ .enabledApiLayerCount = 0,
+ .applicationInfo = {
+ .applicationVersion = 1,
+ .engineVersion = 0,
+ .apiVersion = XR_CURRENT_API_VERSION,
+ },
+ };
+
+ strncpy(instanceCreateInfo.applicationInfo.applicationName, "Example Application", XR_MAX_APPLICATION_NAME_SIZE);
+ strncpy(instanceCreateInfo.applicationInfo.engineName, "Example Engine", XR_MAX_APPLICATION_NAME_SIZE);
+
+ XrInstance instance;
+ xrCreateInstance(&instanceCreateInfo, &instance);
+ return 0;
+}
+```
+
Explaining the entire basic OpenXR API is no short task. Instead, the commented [OpenXR-Simple-Example](https://gitlab.freedesktop.org/monado/demos/openxr-simple-example) tries to be as straightforward as possible in dealing with the OpenXR API.
You can also look at the [list of open source examples and applications]({% link openxr-resources.md %}) or a recording of the [OpenXR Master Class at Laval Virtual](https://www.youtube.com/watch?v=F6jZCwko1Qs).
diff --git a/getting-started.md b/getting-started.md
index 0ec4572b355229bf6d7633c2b8f20b102453fa33..912a5527774b20fcc24b9ca8ce0d0c07b6e752b8 100644
--- a/getting-started.md
+++ b/getting-started.md
@@ -10,15 +10,16 @@ Software that supports VR by using the OpenXR API requires two software packages
* 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. The OpenXR loader also comes with all necessary C headers to compile OpenXR applications.
+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 information about the background behind OpenXR and OpenXR runtimes can be found at [About Runtimes]({% link about-runtimes.md %}).
+More general background information about OpenXR and OpenXR runtimes can be found at [About Runtimes]({% link about-runtimes.md %}).
-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.
+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. Windows support is on the long term roadmap.
+Monado currently runs on Linux. A windows port is in progress.
The Monado compositor requires a Vulkan driver with the instance extensions:
@@ -44,27 +45,67 @@ and the Device extensions:
* VK_KHR_get_memory_requirements2
* VK_KHR_swapchain
-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](https://gitlab.freedesktop.org/mesa/mesa/-/issues/1824).
+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 Vulkan are supported with radv, intel anv and the nvidia proprietary driver.
+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](https://gitlab.freedesktop.org/mesa/mesa/-/issues/1824) but there are WIP MRs [for mesa/iris](https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/4337) and [for mesa/i965](https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/5594) that have been tested to work with Monado.
-# OpenXR Loader and Monado Installation
+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 are available for various distributions.
+Packages for the OpenXR SDK and Monado are available for various distributions.
* [Debian through OBS]({% link packages-debian.md %})
* [Ubuntu through a PPA or gitlab CI]({% link packages-ubuntu.md %})
-* Archlinux AUR: [openxr-loader-git](https://aur.archlinux.org/packages/openxr-loader-git/) and AUR: [monado-git](https://aur.archlinux.org/packages/monado-git/)
+* Archlinux [AUR: openxr-loader-git](https://aur.archlinux.org/packages/openxr-loader-git/) and [AUR: monado-git](https://aur.archlinux.org/packages/monado-git/)
+
+Up to date information can be found [on repology](https://repology.org/project/monado/versions).
+
+### 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:
-If your distribution does not provide packages for the OpenXR Loader and Monado, you can build them from source.
+* 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](#tools) for a detailed description
## Installation from Source
-### OpenXR Loader
+Install the meson and ninja build tools
-See [https://github.com/KhronosGroup/OpenXR-SDK#linux](https://github.com/KhronosGroup/OpenXR-SDK#linux) for a list of dependencies
+ 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](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
@@ -75,11 +116,11 @@ See [https://github.com/KhronosGroup/OpenXR-SDK#linux](https://github.com/Khrono
See [https://gitlab.freedesktop.org/monado/monado#getting-started](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.
+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:
+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
@@ -90,15 +131,36 @@ then compile and install Monado:
## 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.
+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`.
-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.
+### 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
-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](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:
+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
@@ -114,9 +176,14 @@ The environment variable `XR_RUNTIME_JSON` can be used in absense of, or to over
# Tools
+{: #tools}
Monado comes with a number of tools.
+## monado-service
+
+See [Running OpenXR applications with `monado-service`](#service)
+
## 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.
@@ -160,6 +227,14 @@ Available for monado-service:
* Do not use direct mode and run the Monado compositor in a window.
* `XRT_COMPOSITOR_FORCE_NVIDIA=1` and `XRT_COMPOSITOR_FORCE_RANDR=1`
* Force the use of nvidia or mesa/amdvlk direct mode. This should never be necessary.
+* `XRT_COMPOSITOR_SCALE_PERCENTAGE`
+ * Scales the render target size recommended to applications to render at. Affects all applications connecting to this service. Defaults to 140% supersampling.
+
+Available for OpenXR applications
+
+* `OXR_VIEWPORT_SCALE_PERCENTAGE`
+ * Scales 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`.
+
## Logging
diff --git a/index.md b/index.md
index 34ca562d83b08b8963ed2b151fbbeb196a1da726..1a9f8393dc8b7102f9093a4d2149b377ec1661ac 100644
--- a/index.md
+++ b/index.md
@@ -8,27 +8,27 @@ layout: main
## What is Monado?
Monado is an open source XR runtime delivering immersive experiences such as VR
-and AR on on mobile, PC/desktop, and any other device. Monado aims to be a complete
+and AR on mobile, PC/desktop, and other devices. Monado aims to be a complete
and conformant 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.
+is currently being developed for GNU/Linux and aims to support other operating
+systems such as Windows in the near future.
## Current status
-* Work in progress outside in-tracking
+* 6DoF tracking, initial implementation for PSVR and PS Move controllers
+ * Outside-in tracking framework with stereo cameras such as PS4 camera
+ * Work in progress on outside-in tracking with mono cameras such as consumer webcams
* Video stream and filter framework for tracking components
-* Work in progress 6DoF tracking for PSVR and PS Move controllers
* Initial [OpenXR](https://www.khronos.org/openxr) API support
- * Both Vulkan and OpenGL integration
- * Headless mode
- * Space relations and view getting
- * Basic frame timing
- * Basic input (actions)
-* Includes a XR Compositor
- * Supports direct mode on recent AMD, Intel and NVidia drivers
- * Mesh distortion shader with input from Panotools paramters and Vive/Index config
- * Support for multiple simultaneous projection and quad layers
-* Support for multiple XR devices with open source drivers
+ * Supports Vulkan, OpenGL and Headless applications
+ * Full support for Local, Stage and Action space relations
+ * Action based input
+* Includes an XR Compositor
+ * Direct mode on AMD, NVidia and Intel GPUs
+ * Mesh based distortion with generators for Panotools and Vive/Index parameters
+ * Supports multiple simultaneous projection layers and quad layers
+* Driver framework allowing easy integration of existing drivers
+ * Out of the box support for multiple XR devices with open source drivers
## Supported Hardware
@@ -36,52 +36,53 @@ These are the XR devices that are natively supported with open source drivers in
| Device | Rotation | Position | Distortion Correction | Additional Notes |
|:-----------------------:|:------------------:|:--------:|:---------------------:|:----:|
-| OSVR HDK 1.x, 2.x | Yes | No | No | Wrong colors on AMD GPUS. [Fixed by firmware update (3 dots menu -> "Download Artifacts")](https://dev.azure.com/osvr/OSVR-HDK-MCU-Firmware/_build/results?buildId=9&view=artifacts&type=publishedArtifacts) |
-| HTC Vive ("vive" driver) | Yes | No (LH 1.0) | Yes | |
-| Valve Index ("vive" driver) | Yes | WIP (early state, LH 2..0) | Yes | |
-| North Star | Yes | Yes, with T265 realsense | official northstar calibration may be integrated in the future | |
-| PSVR | Yes | WIP (prototype state) | Yes | distortion correction is WIP. Wrong colors on AMD GPUs: see [EDID override]({% link edid-override.md %}) for workaround |
-| Hydra Controller | Yes | Yes | - | |
+| OSVR HDK 1.x, 2.x | Yes | No | No | Requires workaround on AMD GPUs[^yuv_edid]. Firmware fix available[^hdk_edid_fix] |
+| HTC Vive | Yes | LH 1.0: No | Yes | |
+| HTC Vive Pro | Yes | LH 1.0: No, LH 2.0: Early WIP| Yes | |
+| Valve Index | Yes | LH 1.0: No, LH 2.0: Early WIP | Yes | |
+| North Star | Yes | Yes, with Intel Realsense T265| Yes, v1 and v2 | |
+| PSVR | Yes | [Yes, with PS4 camera or generic stereo camera]({% link positional-tracking-psmove.md %}) | Yes | distortion correction is WIP. Requires workaround on AMD GPUs[^yuv_edid]. |
| Playstation Move | Yes | [Yes, with PS4 or generic stereo camera]({% link positional-tracking-psmove.md %}) | - | rotational drift correction is WIP |
+| Hydra Controller | Yes | Yes | - | |
| Daydream Controller | Yes | - | - | |
| DIY arduino controller | Yes | - | - | |
-| T265 realsense | Yes | Yes | - | proprietary on-device SLAM tracking |
-Monado also leverages the open source drivers developed by the
-OpenHMD community for further hardware support.
+Monado also leverages the open source drivers developed by the OpenHMD community
+for further HMD support. Controllers from OpenHMD are currently not supported.\\
See the [OpenHMD support matrix](http://www.openhmd.net/index.php/devices/)
for a list of devices supported through OpenHMD.
-The Direct-Tek WVR2 / VR-Tek Windows VR Glasses 2560x1440 supported through OpenHMD
-is known to have wrong colors on AMD GPUs. See [EDID override]({% link edid-override.md %})
-for details.
+The Direct-Tek WVR2 / VR-Tek Windows VR Glasses with the 2560x1440 resolution
+supported through OpenHMD requires workaround on AMD GPUs[^yuv_edid].
Other 3rd party open source drivers Monado currently wraps are
-| Device | Rotation | Position | Distortion Correction | Additional Notes |
-|:-----------------------:|:------------------:|:--------:|:---------------------:|:----:|
-| HTC Vive ("[survive]({% link libsurvive.md %})" driver) | Yes | Yes | Yes | |
-| Valve Index ("[survive]({% link libsurvive.md %})" driver) | Yes | Yes | Yes | |
+| 3rd party driver | Device | Rotation | Position | Distortion Correction | Additional Notes |
+|:---:|:-----------------------:|:------------------:|:--------:|:---------------------:|:----:|
+| [libsurvive](https://github.com/cntools/libsurvive) | HTC Vive | Yes | Yes | Yes | [survive]({% link libsurvive.md %}) driver must be enabled at build time |
+| [libsurvive](https://github.com/cntools/libsurvive) | HTC Vive Pro | Yes | Yes | Yes | [survive]({% link libsurvive.md %}) driver must be enabled at build time |
+| [libsurvive](https://github.com/cntools/libsurvive) | Valve Index | Yes | Yes | Yes | [survive]({% link libsurvive.md %}) driver must be enabled at build time |
+| [librealsense](https://github.com/IntelRealSense/librealsense) | T265 realsense | Yes | Yes | - | proprietary on-device SLAM tracking |
### So what does that mean?
For end users it means Monado can be used to run OpenXR games and
-applications (e.g. Blender) on any of the supported hardware.
+applications like Blender on any of the supported hardware.
For developers it means you can start developing software for OpenXR
-with the ability to debug and inspect the entire source code of the XR
-software stack.
+with the ability to debug and inspect the source code of the entire XR
+software stack from your application to the HMD driver.
Monado transparently takes care of direct mode and distortion correction
without developers having to write a single line of X11 code.
## Getting Started with Monado
-* [Read our Getting Started Guide]({% link getting-started.md %})
-* [Learn about OpenXR through open source applications and examples]({% link openxr-resources.md %})
-* [Dive into the OpenXR specification](https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html)
+* [Find out how to install Monado and run applications with the Getting Started Guide]({% link getting-started.md %})
+* [The OpenXR 1.0 specification](https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html)
+* [List of Open Source applications and examples]({% link openxr-resources.md %})
* [See if Monado can run on your GPU configuration (e.g. Optimus)]({% link multi-gpu.md %})
-* [Read the online Doxygen documentation to start hacking on Monado](https://monado.pages.freedesktop.org/monado/)
+* [Read the online Doxygen documentation and start hacking on Monado](https://monado.pages.freedesktop.org/monado/)
## Code of Conduct
@@ -113,3 +114,8 @@ For other questions and just hanging out you can find us here:
* [#monado](https://webchat.freenode.net/?channels=monado) on [Freenode](freenode.net).
* [Discord](https://discord.gg/8RkJgRJ) server.
+
+# Footnotes
+
+[^yuv_edid]: An issue with the EDID results in wrong colors or black screen on AMD GPUS. See [EDID override]({% link edid-override.md %}) for details and workarounds.
+[^hdk_edid_fix]: Firmware was fixed [in this PR](https://github.com/OSVR/OSVR-HDK-MCU-Firmware/pull/31). Builds can be found [here](https://dev.azure.com/osvr/OSVR-HDK-MCU-Firmware/_build/results?buildId=9&view=artifacts&type=publishedArtifacts) - Choose a successful pipeline (green checkmark), choose "1 published", in the 3 dots menu choose "Download Artifacts".
diff --git a/packages-debian.md b/packages-debian.md
index 7076e6f3a07dacd8ea375cb485d1944ccd62e994..09ec9eb8e18ecf42f59fcadf08b26cdce9791413 100644
--- a/packages-debian.md
+++ b/packages-debian.md
@@ -29,19 +29,7 @@ echo 'deb http://download.opensuse.org/repositories/home:/rpavlik:/monado/Debian
sudo apt update
```
-Packages available include:
-
-- from source package [openxr-sdk-source, now in Debian](https://tracker.debian.org/pkg/openxr-sdk-source):
- - libopenxr-loader1 - the loader
- - libopenxr-dev - the headers
- - libopenxr-utils - hello_xr and openxr_runtime_list
- - openxr-layer-apidump
- - openxr-layer-corevalidation
-- xr-hardware from source package of the same name: recommended by Monado, provides udev rules
-- from source package monado:
- - libopenxr1-monado - the runtime
- - monado-cli
- - monado-gui
+For a description of the packages see [Getting Started]({% link getting-started.md %}).
More info about the packages is at: <https://build.opensuse.org/project/show/home:rpavlik:monado>
diff --git a/packages-ubuntu.md b/packages-ubuntu.md
index d2b3a09040695a5d857b93436cfe8ee5e79a9069..a7c6147a2054fd66f4bf358a9a485a8ce4090d52 100644
--- a/packages-ubuntu.md
+++ b/packages-ubuntu.md
@@ -31,4 +31,6 @@ echo 'deb https://monado.pages.freedesktop.org/monado/apt focal main' | sudo tee
sudo apt update
```
+For a description of the packages see [Getting Started]({% link getting-started.md %})
+
To install from a single, specific CI job on master, use `https://gitlab.freedesktop.org/monado/monado/-/jobs/<job-num>/artifacts/raw/repo` as the URL in the listfile instead.
diff --git a/positional-tracking-psmove.md b/positional-tracking-psmove.md
index 16939c36c1d08c977aee20c0c87c57b11ec7a38e..3693c20c1821fd3266b153773110e158d1acdb52 100644
--- a/positional-tracking-psmove.md
+++ b/positional-tracking-psmove.md
@@ -3,83 +3,95 @@ title: "Monado - Positional Tracking with Playstation Move"
layout: main
---
-Playstation Move tracking is a work in progress and the implementation described here will be improved/changed over time.
+# Playstation Move and PSVR 6DoF tracking
+
+Playstation Move and PSVR tracking is a work in progress and the implementation described here will be improved/changed over time.
+
+The camera setup has to be done once per camera and does not have to be repeated for PSVR and Playstation Move controller setup.
+
+The PSVR is fully set up after calibrating the camera. The Playstation Move controller setup requires an additional bluetooth pairing step.
# Requirements
-* Bluetooth adapter
+* Bluetooth adapter (for Playstation Move)
* Stereo Camera
* PS4 Camera
* Generic: 3d-1mp02 is supported out of the box, others may need some work
-# Controller setup
+# Camera Setup
-## USB/HID Permissions
+## PS4 camera: firmware
-Even when connected over bluetooth, your user will require the permissions to access the psmove's hid-over-bluetooth device.
+By default the ps4 camera does not work as a camera, a firmware file has to be loaded onto the device first. This procedure has to be done every time the camera is plugged in or the system is rebooted, though it can be automated with an udev rule.
-If you use the ["xr-hardware"](https://gitlab.freedesktop.org/monado/utilities/xr-hardware) udev rules, you don't need to do anything, it includes rules to set permissions for the psmove controllers.
+Download the firmware upload script, and a `firmware.bin` file to the same directory. The `firmware.bin` file used here with md5sum `99ca1e97ea2bb9edaf4c6f511292b4e2` comes with uvc support and has been tested with Monado.
-If you want to install only rules specific to the psmove instead, you can follow [the psmove documentation](https://github.com/thp/psmoveapi/blob/8bcc80d4fec9087fdb2890dc357f1af8f989c318/docs/pairing.rst#L79-L87).
+ wget https://raw.githubusercontent.com/ps4eye/ps4eye/master/python/ps4eye_init.py
+ wget -O firmware.bin 'https://github.com/psxdev/luke_firmwares/blob/master/101_85C8E0_64036.bin?raw=true'
-## Bluetooth pairing the controllers
+The `firmware.bin` file is uploaded with the command
-Bluetooth pairing the controllers requires a USB connection. However IMU data can only be read through bluetooth, once the controllers are paired, reading IMU data through USB is not supported.
+ sudo ./ps4eye_init.py
-The pairing procedure is detailed at [https://github.com/thp/psmoveapi/blob/master/docs/pairing.rst](https://github.com/thp/psmoveapi/blob/master/docs/pairing.rst).
+This should print `PS4 camera firmware uploaded and device reset`.
-In short:
+The camera should now work with standard UVC tools like `guvcview`. In Video Controls, choose the first entry called `USB Camera-OV580: USB Camera-OV`.
- git clone --recursive https://github.com/thp/psmoveapi.git
- cd psmoveapi
- cmake .
- make
- sudo ./psmove pair
+If the camera does not show up, or guvcview can not produce images, try a different USB port/host controller and especially without a USB hub. The ps4 camera is known to not work on all USB controllers and hubs.
-Pairing doesn't always work reliably, it might be necessary to restart the bluez daemon `sudo systemctl restart bluetooth` and repeat pairing until it works. When powering on the controller with its power button, it should automatically connect to the PC, and bluetooth tools should show the controller ("Motion Controller") as connected. Trying to initiate a connection from the PC usually does not work.
+## Calibrating the camera with monado
-# Camera Setup
+Currently Monado only supports interactive calibration with a checkerboard pattern. In the future a calibration file will be distributed with monado and calibration will be simplified, perhaps even unnecessary.
-## PS4 camera: firmware
+The `monado-gui` utility is used to calibrate the camera before using it with Monado. This is necessary to compensate for the usual camera/lens distortion. `monado-gui` is usually installed in /user/bin. In a monado build tree the gui utility is located at `./src/xrt/targets/gui/monado-gui`
-By default the ps4 camera does not work as a camera, a firmware file has to be loaded first.
+1. Get a checkerboard grid. It can be printed on a sheet of paper or displayed on a monitor. For example you can use a checkerboard generator:
+ 1. Go to https://calib.io/pages/camera-calibration-pattern-generator
+ 2. Set `Target Type` to `Checkerboard`. The calibration looks for black and white squares with no symbols.
+ 3. Set `Rows` to `7` and `Columns` to `9`. Other configurations can work too, but 7x9 is a good default.
+ 4. Show the resulting image/pdf on screen or print it.
+ 5. Measure the size of a single square.
+2. In the `monado-gui` menu choose `Calibrate`
+3. Choose the `USB Camera-OV580` camera (the PS4 camera)
+4. Choose the second resolution 1748x408 (the full resolution takes quite some CPU power)
+5. Confirm the `7 rows`, `9 columns` setting matches your checkerboard
+6. set `Checker Size` to the previously measured size of one square **in meters** and click Done.
+7. Move the camera around, until it captures enough images.
+ * tilt the camera and view the checkerboard from different angles
+ * capture the checkerboard in as much of the camera's field of view as possible
+8. After the calibration finishes, do not forget to click **save** before exiting.
-Download the firmware upload script, and a firmware.bin file (firmware.bin with md5sum `99ca1e97ea2bb9edaf4c6f511292b4e2` comes with uvc support and has been tested with Monado).
+Two configuration files should be stored. `~/.config/monado/config_v0.json` contains information about the calibration and `~/.config/monado/PS4.calibration` contains the actual calibration data.
- wget https://raw.githubusercontent.com/ps4eye/ps4eye/master/python/ps4eye_init.py
- wget -O firmware.bin 'https://github.com/psxdev/luke_firmwares/blob/master/101_85C8E0_64036.bin?raw=true'
+After these steps a PSVR HMD should automatically begin to track when Monado is started.
-Uploading the firmware file has to be repeated every time the camera is powered (after restarting the PC, or after plugging it in):
+# Controller setup
- sudo ./ps4eye_init.py
+## USB/HID Permissions
-This should print `PS4 camera firmware uploaded and device reset`.
+Even when connected over bluetooth, your user will require the permissions to access the psmove's hid-over-bluetooth device.
-The camera should now work with standard UVC tools like `guvcview` (in Video Controls, choose the first entry called `USB Camera-OV580: USB Camera-OV`).
+If you use the ["xr-hardware"](https://gitlab.freedesktop.org/monado/utilities/xr-hardware) udev rules, you don't need to do anything, it includes rules to set permissions for the psmove controllers.
-If the camera does not show up, or guvcview can not produce images, try a different USB port/host controller. The ps4 camera is known to not work on all USB controllers and hubs.
+If you want to install only rules specific to the psmove instead, you can follow [the psmove documentation](https://github.com/thp/psmoveapi/blob/8bcc80d4fec9087fdb2890dc357f1af8f989c318/docs/pairing.rst#L79-L87).
-## Calibrating the camera with monado
+## Bluetooth pairing the controllers
-In the future a calibration file will be distributed with monado. For now, calibration has to be performed by the user.
+Bluetooth pairing the controllers requires a USB connection. However IMU data can only be read through bluetooth, once the controllers are paired, reading IMU data through USB is not supported.
-The monado-gui utility is used to calibrate the camera before using it with Monado. This is necessary to compensate for the usual camera/lens distortion. In a monado build tree the gui utility is located at
+The pairing procedure is detailed at [https://github.com/thp/psmoveapi/blob/master/docs/pairing.rst](https://github.com/thp/psmoveapi/blob/master/docs/pairing.rst).
- ./src/xrt/targets/gui/monado-gui
+In short:
-The calibration procedure is
+ git clone --recursive https://github.com/thp/psmoveapi.git
+ cd psmoveapi
+ cmake .
+ make
+ sudo ./psmove pair
- 1. Get a Checkerboard grid ready, it can be displayed on your monitor
- a. Set up https://calib.io/pages/camera-calibration-pattern-generator for checkerboard pattern with 7 rows and 9 columns.
- b. Show the resulting image/pdf on screen or print it and measure the size of one square
- 2. Choose `Calibrate` from the monado-gui menu
- 3. Choose the `USB Camera-OV580` camera (PS4 camera)
- 4. Choose the second resolution 1748x408 (the full resolution takes quite some CPU power)
- 5. Leave the default 7 rows, 9 columns setting, set `Checker Size` to the previously measured size of one square and click Done.
- 6. Move the camera around, until it captures enough images. It's a good idea to tilt the camera and view the checkerboard from different angles, in different parts of the camera field of view.
- 7. After the calibration finishes, click exit. A calibration file should be stored at ~/.config/monado/PS4_EYE.calibration
+Pairing doesn't always work reliably, it may be necessary to restart the bluez daemon `sudo systemctl restart bluetooth` and repeat pairing until it works. When powering on the controller with its power button, it should automatically connect to the PC, and bluetooth tools should show the controller ("Motion Controller") as connected. Trying to initiate a connection from the PC usually does not work.
-# Usage
+# Controller Usage
The psmove poses and buttons are fully exposed through a monado specific interaction profile `/interaction_profiles/mnd/ball_on_stick_controller` (see bindings [in the code](https://gitlab.freedesktop.org/monado/monado/blob/f3803f7365c5df1e1d0681a8f5bcb736ea93c199/src/xrt/state_trackers/oxr/oxr_binding_data.h#L405-768)), and limited bindings are available through the khronos simple controller interaction profile.