Compare revisions

Mateo de Mayo · Babble Bones · Jakob Bornecrantz · Gabriele Musco · Jakob Bornecrantz · Gavin John
--- a/.gitignore
+++ b/.gitignore
 _site
 .sass-cache
 .jekyll-metadata
+.vscode/settings.json
--- a/build-additional-dependencies.md
+++ b/build-additional-dependencies.md
+---
+title: "Monado - Building Additional Dependencies"
+layout: main
+---
+
+* TOC
+{:toc}
+
+## Dependencies needed to build Monado's additional drivers
+
+#### Preliminary notes:
+These recipes have been checked on Ubuntu 22.04 LTS and Fedora 39.
+
+Using the commands listed below, packages are installed in ```/usr/local```. Fedora, by default, does not search libraries or package config files in ```/usr/local```. You could adapt /etc/ld.so.conf, or change the commands to install in ```/usr```, or, more simply, you can set two envvars in your ```.bashrc```:
+```sh
+export LD_LIBRARY_PATH=/usr/local/lib:/usr/local/lib64
+export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/usr/local/lib64/pkgconfig
+```
+
+### For the OpenHMD driver
+
+```sh
+git clone https://github.com/OpenHMD/OpenHMD.git
+cd OpenHMD
+cmake -G Ninja -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local -DBUILD_SHARED_LIBS=ON
+ninja -C build
+sudo ninja -C build install
+```
+
+### For the libsurvive driver
+
+Some other dependencies are needed.
+
+* On Debian/Ubuntu:
+  ```sh
+  sudo apt install libopenblas-dev liblapacke-dev libopenvr-dev
+  ```
+* On Fedora:
+  ```sh
+  sudo dnf install openblas-devel lapack-devel openvr-devel
+  ```
+  
+Then, libsurvive can be built and installed:
+```sh
+git clone https://github.com/cntools/libsurvive.git
+cd libsurvive
+cmake -G Ninja -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local
+ninja -C build
+sudo ninja -C build install
+```
+
+### For the Realsense driver
+
+* On Debian/Ubuntu:
+  ```sh
+curl -sSf https://librealsense.intel.com/Debian/librealsense.pgp | sudo tee /etc/apt/keyrings/librealsense.pgp > /dev/null
+echo "deb [signed-by=/etc/apt/keyrings/librealsense.pgp] https://librealsense.intel.com/Debian/apt-repo `lsb_release -cs` main" | \
+sudo tee /etc/apt/sources.list.d/librealsense.list
+sudo apt update
+sudo apt install librealsense2-dkms
+sudo apt install librealsense2-dev
+```
+* On Fedora:
+  ```sh
+  sudo dnf install librealsense-devel
+  ```
+
+### For the DepthAI driver
+
+```sh
+git clone --recurse-submodules https://github.com/luxonis/depthai-core.git
+cd depthai-core
+cmake -G Ninja -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local -DBUILD_SHARED_LIBS=ON
+ninja -C build
+sudo ninja -C build install
+```
+
+### For SLAM tracking support, using Basalt 
+
+Some other dependencies are needed.
+
+* On Debian/Ubuntu:
+  ```sh
+  sudo apt install libtbb-dev libglew-dev libpng-dev liblz4-dev libbz2-dev libboost-dev libboost-regex-dev libboost-filesystem-dev libboost-date-time-dev libboost-program-options-dev libboost-serialization-dev libgtest-dev libfmt-dev libuvc-dev
+  ```
+* On Fedora:
+  ```sh
+  sudo dnf install tbb-devel glew-devel libpng-devel lz4-devel bzip2-devel boost-devel boost-regex boost-filesystem boost-date-time boost-program-options boost-serialization gtest-devel fmt-devel libuvc-devel
+  ```
+
+Then, Basalt can be built and installed:
+```sh
+git clone --recurse-submodules https://gitlab.freedesktop.org/mateosss/basalt
+cd basalt
+cmake -G Ninja -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local
+ninja -C build
+sudo ninja -C build install
+```
+
+If you get `fatal error: Killed signal terminated program cc1plus` during the compilation, it could be due to memory exhaustion if too many compilation jobs are running in parallel. Using `ninja -j 1 -C build` to run one single compilation job should solve that issue.
+
+**_Note for Fedora_**: Pangolin (in the included version) fails to compile with GCC 13, due to missing inclusions of ```<cstdint>``` (see https://www.gnu.org/software/gcc/gcc-13/porting_to.html, Header dependency changes).\
+You need to add `#include <cstdint>` near the other inclusions in:
+
+* `thirdparty/Pangolin/src/image/image_io_jpg.cpp`
+* `thirdparty/Pangolin/include/pangolin/log/packetstream_tags.h`
+
+### For 'Mercury' Hand Tracking, using the ONNX Runtime
+
+**_Note for Ubuntu_**: ONNXRuntime needs a recent `cmake` (at least version 3.26), which is not available on Ubuntu 22.04. If you want to use the handtracking driver, then you'll have to update `cmake` using the Kitware's APT repository:
+```sh
+wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg >/dev/null
+echo 'deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ jammy main' | sudo tee /etc/apt/sources.list.d/kitware.list >/dev/null
+sudo apt update
+sudo apt upgrade cmake
+```
+
+Some other dependencies are needed.
+
+* On Debian/Ubuntu:
+  ```sh
+  sudo apt install libgmock-dev
+  ```
+* On Fedora:
+  ```sh
+  sudo dnf install gmock-devel
+  ```
+
+Then, onnxruntime can be built and installed:
+```sh
+git clone --recurse-submodules https://github.com/Microsoft/onnxruntime.git
+cd onnxruntime
+./build.sh --config Release --build_shared_lib --parallel --skip_tests --compile_no_warning_as_error --cmake_extra_defines CMAKE_INSTALL_PREFIX=/usr/local --cmake_extra_defines onnxruntime_BUILD_UNIT_TESTS=OFF
+cd build/Linux/Release
+sudo make install
+```
+
+### For the UltraLeap v5 driver
+
+* On Debian/Ubuntu:
+  ```sh
+  wget -qO - https://repo.ultraleap.com/keys/apt/gpg | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/ultraleap.gpg > /dev/null
+  echo 'deb [arch=amd64] https://repo.ultraleap.com/apt stable main' | sudo tee /etc/apt/sources.list.d/ultraleap.list > /dev/null
+  sudo apt update
+  sudo apt install ultraleap-hand-tracking
+  ```
+
+* On Fedora:
+
+  The Ultraleap v5 driver is not available for Fedora.
+
+### To use Tracy as a tracing backend
+
+Some other dependencies are needed.
+
+* On Debian/Ubuntu:
+  ```sh
+  sudo apt install libglfw3-dev libfreetype-dev libcapstone-dev libdbus-1-dev
+  ```
+
+* On Fedora:
+  ```sh
+  sudo dnf install glfw-devel freetype-devel capstone-devel dbus-devel
+  ```
+
+Then, tracy can be built:
+
+**Note**: Currently (as of 03/21/2024), Monado uses the Tracy protocol version 63 (see ```src/external/tracy/common/TracyProtocol.hpp```), which needs Tracy version 0.9.0 or 0.9.1
+
+```sh
+git clone https://github.com/wolfpld/tracy.git
+cd tracy
+git checkout v0.9.1
+cd profiler/build/unix
+make LEGACY=1
+```
+
+This produces Tracy-release which can be copied in ```/usr/local/bin/``` for instance.
+
+**Note**: Monado needs to be built with tracing support:
+
+    cmake .... -DXRT_HAVE_TRACY=ON -DXRT_FEATURE_TRACING=ON
+
--- a/getting-started.md
+++ b/getting-started.md
@@ -71,22 +71,36 @@ Other useful packages:

 ### Installation from Source

-Install the CMake and ninja build tools
+Install the needed development and build tools.

-    apt install cmake ninja-build
+* On Debian/Ubuntu, use:
+
+      apt install build-essential git wget unzip curl patch pkg-config cmake ninja-build python3 ca-certificates
+
+* On Fedora, use:
+
+      dnf group install "C Development Tools and Libraries"
+      dnf install cmake ninja-build

 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 some optional dependencies that will enable most of the commonly used functionality of monado on Debian/Ubuntu.
-Some features and drivers are only compiled with additional dependencies like libsurvive or librealsense.
+The next command will install required and some optional dependencies that will enable most of the commonly used functionality of Monado.
+Some features and drivers are only compiled with [additional dependencies]({% link build-additional-dependencies.md %}) like libsurvive or librealsense.
+
+* On Debian/Ubuntu, use:

-    apt install build-essential git wget unzip cmake 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
+      apt install libeigen3-dev libx11-dev libx11-xcb-dev libxxf86vm-dev libxrandr-dev libxcb-randr0-dev libvulkan-dev glslang-tools libglvnd-dev libgl1-mesa-dev libegl1-mesa-dev libusb-1.0-0-dev libsystemd-dev libudev-dev libhidapi-dev libuvc-dev libavcodec-dev libopencv-dev libv4l-dev libcjson-dev libsdl2-dev libbsd-dev libbluetooth-dev libopenxr-loader1 libopenxr-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libwayland-dev wayland-protocols

-then compile and install Monado. Monado can be built with either cmake or meson.
+* On Fedora, use:
+
+      dnf install eigen3-devel libX11-devel libxcb-devel libXrandr-devel vulkan-loader-devel glslang libglvnd-devel mesa-libGL-devel mesa-libEGL-devel libusb1-devel systemd-devel hidapi-devel libv4l-devel opencv-devel cjson-devel SDL2-devel libbsd-devel bluez-libs-devel openxr openxr-devel ffmpeg-free-devel libjpeg-turbo-devel gstreamer1-devel gstreamer1-plugins-base-devel wayland-devel wayland-protocols-devel 
+
+Then compile and install Monado. Monado is built with CMake.

    git clone https://gitlab.freedesktop.org/monado/monado.git
    cmake -G Ninja -S monado -B build -DCMAKE_INSTALL_PREFIX=/usr
-    ninja -C build install
+    ninja -C build
+    sudo ninja -C build install

 ### Monado Service

@@ -103,9 +117,7 @@ When monado is built with `monado-service`, Monado's compositor and drivers run

 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 `/run/user/1007/monado_comp_ipc`. If Monado's build configuration includes the `libbsd` library, this unused socket file will be automatically cleaned up by the next monado run. If Monado was built without support for `libbsd`, the Monado compositor will refuse to start if this file is found an error message. It safe to simply delete this file, as long as `monado-service` is not running - it holds no information, it is only used for live communication between monado-service and OpenXR applications.
+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 `/run/user/1007/monado_comp_ipc` that gets deleted when Monado starts again.


 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.

--- a/index.md
+++ b/index.md
@@ -74,6 +74,9 @@ These are the XR devices that are natively supported with open source drivers in
 | Daydream Controller | Yes | - | - | |
 | DIY arduino controller | Yes | - | - | |
 | Windows MR | Yes | Experimental* | Yes | HMD only, no controllers. Tested: HP Reverb, HP Reverb G2, Samsung Odyssey, Lenovo Explorer, others: *maybe*. |
+| Xreal Air | Yes | - | - | |
+| Xreal Air 2 | Yes | - | - | |
+| Xreal Air 2 Pro | Yes | - | - | |

 \* _Experimental 6DoF tracking support with external SLAM/VIO systems is upstreamed but still being worked on. Tested with RealSense D455 and Samsung Odyssey+, Reverb G2, Oculus Rift S._

@@ -114,6 +117,7 @@ without developers having to write a single line of X11 code.

 ## Getting Started with Monado

+* [Setup Monado, libsurvive and OpenComposite for the Valve Index]({% link valve-index-setup.md %})
 * [Getting Started installing and running applications with Monado]({% 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 %})
@@ -121,6 +125,10 @@ without developers having to write a single line of X11 code.
 * [For hacking on Monado (e.g. implementing OpenXR extensions), take a look at the online doxygen documentation](https://monado.pages.freedesktop.org/monado/)
 * [Use Monado's hardware drivers in SteamVR]({% link steamvr.md %})

+## Other Information
+
+* [Khronos' Monado-Improvements project 2023]({% link monado-improvements-project-2023.md %})
+
 ## Code of Conduct

 We follow the standard freedesktop.org code of conduct, available at

--- a/monado-improvements-project-2023.md
+++ b/monado-improvements-project-2023.md
+---
+title: "2023 Khronos' Monado Improvements Project"
+layout: main
+---
+
+- TOC
+{:toc}
+
+# Khronos' Monado Improvements Project 2023
+
+This project ran from September 2023 to January 2024, with the purpose of
+implementing specific features within the Monado OpenXR Runtime deemed useful
+by the Khronos OpenXR Working Group.
+
+Total hours: 480 hours
+
+## RFP
+
+The Khronos Group issued an [RFP][] for the Monado Improvements project on July
+3rd 2023. Collabora was selected as the contractor for the project, which ran
+from September 2023 to February 2024.
+
+[RFP]: https://www.khronos.org/news/permalink/the-khronos-group-has-issued-a-rfp-for-monado-improvements
+
+## Work done during this project
+
+### Refactoring the layer "squashing" code to process each view separately - #2
+
+**Closed**
+
+Rework of Monado's compute renderer to dispatch the rendering process once per
+view. This reduces the number of samplers required and allows a per-view target
+
+- [Monado MR !1955](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1955)
+- [Monado MR !1957](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1957)
+- [Monado MR !1967](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1967)
+
+### Refactoring of the compositor graphics pipeline code to the new render architecture - #3
+
+**Closed**
+
+Complete rework of Monado's graphics pipeline, improving our Vulkan code on
+all sides.
+
+- [Monado MR !1969](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1969)
+- [Monado MR !1970](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1970)
+- [Monado MR !1971](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1971)
+- [Monado MR !1972](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1972)
+- [Monado MR !1974](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1974)
+- [Monado MR !1976](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1976)
+- [Monado MR !1983](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1983)
+- [Monado MR !1995](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1995)
+- [Monado MR !2026](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2026)
+- [Monado MR !2101](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2101)
+- [Monado MR !2103](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2103)
+- [Monado MR !2105](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2105)
+
+### New code for cylinder and equirect2 layer types to compute path and equirect - #4
+
+**Closed**
+
+Follow up of #2, the cylinder and equirect2 layers were deactivated during
+the refactoring, the shaders were improved before plugging them back in.
+
+- [Monado MR !1994](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1994)
+- [Monado MR !1998](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1998)
+- [Monado MR !2001](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2001)
+
+### Addition of the layer "squasher" helper function(s) - #5
+
+**Closed**
+
+Refactor of the compositor's utils functions, to have better and more coherent
+helper functions to take account of the device pose and scratch images.
+
+- [Monado MR !1975](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1975)
+- [Monado MR !1981](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1981)
+
+### Implement `XR_KHR_visibility_mask` - #7
+
+**Closed**
+
+- [Monado MR !2016](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2016)
+- [Monado MR !2032](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2032)
+- [Monado MR !2034](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2034)
+
+### Implement `XR_KHR_vulkan_swapchain_format_list` - #8
+
+**Closed**
+
+- [Monado MR !2049](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2049)
+- [Monado MR !2052](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2052)
+- [Monado MR !2083](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2083)
+
+### Improve spaces - #9
+
+**Closed**
+
+Enhance the Monado "spaces" by implementing XR_EXT_local_floor and
+XR_MSFT_unbounded_reference_space, and adding the capability to recenter.
+
+- [Monado MR !2018](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2018)
+- [Monado MR !2047](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2047)
+- [Monado MR !2048](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2048)
+- [Monado MR !2055](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2055)
+- [Monado MR !2091](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2091)
+
+### Implement `XrEventDataReferenceSpaceChangePending` - #10
+
+**Closed**
+
+- [Monado MR !2062](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2062)
+- [Monado MR !2081](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2081)
+
+### IPC improvement - #11
+
+**Closed**
+
+Improve the general state of the Monado IPC, make it more flexible and generic.
+
+- [Monado MR !2009](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2009)
+- [Monado MR !2011](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2011)
+- [Monado MR !2012](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2012)
+- [Monado MR !2015](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2015)
+- [Monado MR !2022](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2022)
+- [Monado MR !2025](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2025)
+- [Monado MR !2028](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2028)
+- [Monado MR !2030](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2030)
+- [Monado MR !2046](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2046)
+- [Monado MR !2053](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2053)
+- [Monado MR !2079](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2079)
+- [Monado MR !2095](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2095)
+- [Monado MR !2096](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2096)
+
+### Implementation of an interface for tracking plugins - #12
+
+**Closed**
+
+Add a C interface to Monado (with a C++ helper) to dynamically load VIT
+(Visual Intertial Tracking) systems.
+
+The VIT interface has been implemented in [Basalt][] as a testing ground
+(not part of the Khronos-funded project).
+
+- [Monado MR !2058](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2058)
+- [Monado MR !2125](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2125)
+
+We moved the interface files into their own repo.
+
+- <https://gitlab.freedesktop.org/monado/utilities/vit>
+
+### Implement `XR_EXT_conformance_automation` - #13
+
+**In Progress**
+
+- [Monado MR !2119](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/2119)
+
+## Pending topics
+
+These were tasks that were in scope for the project but could not be completed
+in the funded time available.
+
+### Enhancements to the compositor so that it uses `xrt_space` for poses
+
+Follow up work for the Monado space work.
+
+### Implementation of "Direct Mode" compositor target on Windows
+
+Requires specialized hardware following the EDID extension for head-mounted
+and specialized monitors [2] spec.
+
+Some work has been on the subject 2 years ago.`
+[Monado MR !738](https://gitlab.freedesktop.org/monado/monado/-/merge_requests/738)
+
+### Implementation of Helper code and configuration format for device attachment hierarchy
+
+Improve the xrt_device creation process to logically group devices together
+without having to create a builder for every device combination.
+
+### Work on extension : `XR_EXT_debug_utils`
+
+All of the ground work is already done. The oxr_logger object in the
+state tracker needs to be extended to collect and push messages to the
+application. Optionally the work done on the IPC can be used to get data
+
+### Work on extension : `XR_EXT_eye_gaze_interaction`
+
+Parts of the work is already done in Monado, the state tracker part is done
+and some work in the service is to be done.
+
+Needs hardware supporting eyes tracking.
+
+### Work on extension : `XR_EXT_hand_joints_motion_range`
+
+A new interface in Monado to have hand-trackers per hand is needed.
+
+### Work on extension : `XR_EXT_palm_pose`
+
+The extension implementation is complete. The remaining work is to collect grip
+pose to palm pose offset data from as many controllers as possible.
+
+### Work on extension : `XR_EXT_win32_appcontainer_compatible`
+
+Requires more Windows knowledge, figure out the installer and a way to create
+the swapchain on the server and share the handles to the client due to
+permission restrictions.
+
+### Improvements to binding code to lay the foundations for user-driven input remapping, aka action based remapping
+
+Requires a lot of rework on Monado's input code, blocked by another project.
+
+### Mac support (Apple SoC)
+
+This issue is almost a project of its own. We outlined the work in an
+issue on the Monado repo.
+
+[Monado issue #318](https://gitlab.freedesktop.org/monado/monado/-/issues/318)
+
+[Basalt]: https://gitlab.freedesktop.org/mateosss/basalt
+[2]: https://learn.microsoft.com/en-us/windows-hardware/drivers/display/specialized-monitors-edid-extension
--- a/valve-index-setup.md
+++ b/valve-index-setup.md
+---
+title: "Monado - Setup Monado, libsurvive and OpenComposite for the Valve Index"
+layout: main
+---
+
+# Setup Monado, libsurvive and OpenComposite for the Valve Index
+
+* TOC
+{:toc}
+
+This guide will walk you through installing the free VR stack on an Arch Linux system.
+
+**Important note**: The following is a guide on how to **bypass steamvr entirely**. Make no mistake: this is not a SteamVR plugin, you will be entirely subverting the use of Valve's SteamVR. In any case, it is still possible to go back to SteamVR.
+
+It will focus on using a Valve Index HMD, lighthouses V2 and Valve Index knuckles. It will also assume you have a recent AMD GPU (Polaris and newer) running the latest stable mesa graphics stack.
+
+This stack is composed of:
+
+- [monado](https://gitlab.freedesktop.org/monado/monado) - OpenXR runtime and hardware drivers
+- [libsurvive](https://github.com/cntools/libsurvive) - Open source lighthouse tracking software
+- [OpenComposite](https://gitlab.com/znixian/OpenOVR) - Converts OpenVR calls to OpenXR
+
+## 1. Initial setup
+
+You will need to install `libsurvive-git` as well as `monado-git` (both available in the AUR), in this order. It's important to install libsurvive first since otherwise monado won't recognize it at build time and fail to use it for 6 degree of freedom (6dof) motion tracking.
+
+After installing these packages, it is *essential* to run the following:
+
+```bash
+sudo setcap CAP_SYS_NICE=eip /usr/bin/monado-service
+```
+
+Should you be using an AMD GPU, you will also need to set your GPU power state to VR mode for an acceptable experience:
+
+```bash
+sudo sh -c 'echo "4" > /sys/class/drm/card0/device/pp_power_profile_mode'
+```
+
+## 2. Calibration
+
+Make sure your lighthouses are powered on and in the "On" state (as opposed to "Sleep").
+
+Make sure your controllers, VR knuckles and VR trackers are powered off as they may disrupt the solve.
+
+Plug in your HMD and place it on the floor at the center of your room, making sure it has an uninterrupted line of sight with the lighthouses.
+
+Run the following:
+
+```bash
+survive-cli --steamvr-calibration
+```
+
+Wait approximately 20 to 30 seconds, then terminate the command with `^C`.
+
+Because of a bug, you will need to run the above command again, wait again around 20 to 30 seconds, then terminate the command with `^C`.
+
+### 2.1 Import the SteamVR calibration into libsurvive
+
+If you find that the calibration isn't working well enough for you (tracking is *still* inconsistent, it jumps a lot), you can try the following:
+
+_If you're coming back here after following section 5, make sure to relink your `openvrpaths` file back to the SteamVR one, then back to the OpenComposite one once you're done._
+
+The above section 2 method attempts to import your OpenVR/SteamVR calibration into libsurvive's config, bypassing the native lighthouse solving difficulties of libsurvive. Should you still notice tracking is poor it may actually be your OpenVR calibration at fault.
+
+Plug in your HMD (plugging in the DisplayPort cable is optional, we are purely looking to have it attached by USB so it can track on the proprietary drivers) and run steamvr as you are best able (either on Windows or Linux).
+
+Take your HMD while SteamVR is running and while the HMD icon is active green and gently carry it all around the room posing it in many different orientations your head would naturally assume while playing. SteamVR will produce a better quality solve that survive will naturally be able to import from this data.
+
+If you primarily use Windows for your playspace it would be a good idea to simply import the `lighthousedb.json` file directly from your Windows install drive/partition, as it will feature the strongest solve and highest runtime usage.
+
+Delete the existing libsurvive calibration:
+
+```bash
+rm ~/.config/libsurvive/config.json
+```
+
+Place again your headset in the middle of the room, on the floor, in direct line of sight with the lighthouses.
+
+Run the calibration like this twice, waiting 20-30 seconds before stopping each run:
+
+```bash
+survive-cli --steamvr-calibration ~/.steam/steam/config/lighthouse/lighthousedb.json
+```
+
+## 3. Configure the OpenXR runtime
+
+Edit this file: `~/.config/openxr/1/active_runtime.json`, changing its contents to the following:
+
+```json
+{
+    "file_format_version": "1.0.0",
+    "runtime": {
+        "library_path": "../../../../../usr/lib64/libopenxr_monado.so"
+    }
+}
+```
+
+Please note that `library_path` must be a **relative** path from the `~/.config/openxr/1/` directory to the monado libopenxr file.
+
+If you installed monado through the AUR, or via another system wide package, then the above should be set automatically at a system level in the file `/usr/share/openxr/1/openxr_monado.json`, if not please adjust it accordingly in the home folder.
+
+## 4. Testing the tracking
+
+Install `xrgears` (available in the AUR), then start the monado service with the following environment variables, like so:
+
+```bash
+XRT_COMPOSITOR_SCALE_PERCENTAGE=140 XRT_COMPOSITOR_COMPUTE=1 SURVIVE_GLOBALSCENESOLVER=0 SURVIVE_TIMECODE_OFFSET_MS=-6.94 monado-service
+```
+
+Then, in another terminal run:
+
+```bash
+xrgears
+```
+
+Make sure the tracking is working correctly, and that you experience the full 6dof (you can move around the room, not just rotate your head around a fixed point in space).
+
+If everything is working correctly, move on, otherwise repeat the steps detailed in section 2.
+
+At this point you might want to back up your libsurvive configuration:
+
+```bash
+cp ~/.config/libsurvive/config.json ~/.config/libsurvive/config.json.bak
+```
+
+You may shut down `monado-service` with `^C`.
+
+## 5. Setting up OpenComposite
+
+OpenComposite cannot be installed as a system package, otherwise it won't be picked up by the Steam runtime sandbox.
+
+Clone the OpenOVR repository. The official repository is <https://gitlab.com/znixian/OpenOVR>
+
+```bash
+git clone https://gitlab.com/znixian/OpenOVR.git --recurse-submodules
+cd OpenOVR
+mkdir build
+cd build
+cmake ..
+make -j16
+```
+
+If `make` fails, possibly after an update, you can try running `make clean`, then `make -j16` again.
+
+Back up your `openvrpaths` file:
+
+```bash
+cp ~/.config/openvr/openvrpaths.vrpath ~/.config/openvr/openvrpaths.vrpath.steamvr
+```
+
+Create a new file `~/.config/openvr/openvrpaths.vrpath.opencomp`, with the following content:
+
+```json
+{
+    "config": [
+        "/home/username/.local/share/Steam/config"
+    ],
+    "external_drivers": null,
+    "jsonid": "vrpathreg",
+    "log": [
+        "/home/username/.local/share/Steam/logs"
+    ],
+    "runtime": [
+        "/home/username/git/OpenOVR/build/"
+    ],
+    "version": 1
+}
+```
+
+Please replace `username` in the paths above with your username, or otherwise make sure `/home/username/` is replaced with your own home folder.
+
+Also make sure that the path listed under `runtime` reflects the correct path of your OpenComposite *build* directory.
+
+Make both files read only like this:
+
+```bash
+chmod 444 ~/.config/openvr/openvrpaths.vrpath.steamvr ~/.config/openvr/openvrpaths.vrpath.opencomp
+```
+
+Then link your new Open Composite file as your main `openvrpaths` file, like so:
+
+```bash
+ln -sf $HOME/.config/openvr/openvrpaths.vrpath.opencomp $HOME/.config/openvr/openvrpaths.vrpath
+```
+
+If later on you want to switch back to SteamVR, you can do so by linking `openvrpaths.vrpath.steamvr` back to `openvrpaths.vrpath`.
+
+## 6. Running Steam games through the free VR stack
+
+Set the following launch options for your Steam game:
+
+```bash
+XR_RUNTIME_JSON=/run/host/usr/share/openxr/1/openxr_monado.json PRESSURE_VESSEL_FILESYSTEMS_RW=$XDG_RUNTIME_DIR/monado_comp_ipc %command%
+```
+
+Turn on your Index knuckles first, then start the monado service:
+
+```bash
+XRT_COMPOSITOR_SCALE_PERCENTAGE=140 XRT_COMPOSITOR_COMPUTE=1 SURVIVE_GLOBALSCENESOLVER=0 SURVIVE_TIMECODE_OFFSET_MS=-6.94 monado-service
+```
+
+Finally, start your game from Steam.
+
+NOTE: If your game doesn't start, close steam and reopen it through the command line to see more logs. If there is an error related to `libcjson.so.1` you will need to build Monado with the cmake option `-DXRT_HAVE_SYSTEM_CJSON=off`.
+
+## 7. Setting up monado's systemd socket
+
+If you prefer, you can enable monado's systemd socket so that whenever you're running a VR application, monado-service is automatically started up, and shut down when you're done.
+
+To do so:
+
+```bash
+systemctl --user enable monado.socket
+```
+
+At this point you will need to tweak your game launch options to also include the environment variables you would normally pass to `monado-service`.
+
+Change your game launch options to the following:
+
+```bash
+XRT_COMPOSITOR_SCALE_PERCENTAGE=140 XRT_COMPOSITOR_COMPUTE=1 SURVIVE_GLOBALSCENESOLVER=0 SURVIVE_TIMECODE_OFFSET_MS=-6.94 XR_RUNTIME_JSON=/run/host/usr/share/openxr/1/openxr_monado.json PRESSURE_VESSEL_FILESYSTEMS_RW=$XDG_RUNTIME_DIR/monado_comp_ipc %command%
+```
+
+## Additional notes
+
+- Despite what the OpenComposite/OpenOVR readme tells you, **DO NOT** set the `VR_OVERRIDE` environment variable. We have not yet identified a functional configuration using this value as a replacement to the `openvrpaths.vrpath` symlink setup.
+- The Nvidia 530 driver is plagued by a bug which makes HMDs not appear in the display server. Please downgrade to the latest working 525 driver or feel free to beta test the latest 530+ driver should they happen to fix the issue.
+- Wayland absolutely works, and works best on AMD, but only on KDE Plasma and some wlroots based compositors. Hybrid graphics such as laptops are fully supported in an open mesa configuration for VR on Wayland.
+- Ensure you are launhing your Monado service and all associated games on the same GPU or the display will be garbled.
+- Without the proper launch options in place, and if the particular game doesn't work with OpenComposite, Steam Proton games will fail to launch until SteamVR is restored by switching back to the SteamVR `openvrpaths` file, as described at the bottom of section 5.
+  - This happens because Proton has to probe OpenVR as an init test. Disabling SteamVR and failing to provide a suitable replacement (OpenComposite) will make this test fail.
+- If your HMD is stuck showing only white or light gray inside the display when trying to run games, your calibration in libsurvive may be bad, you can re-run it by following section 2.
+- Both the current Monado tree driver, and libsurvive **do not support hotplugging**. If you turn off a controller while your session is active, or if you forget to turn it on in the first place, you will need to reset your entire Monado session to get it back. Survive improvements are planned. Contributors welcome.
+- OpenComposite does not yet support full body tracking. Work is being done at the time of writing.
+- Preliminary work on finger curls in OpenComposite is complete. There is an active merge request if you would like to patch it in, yourself, at the time of writing.
+
+### Credits
+
+Special thanks to [@BabbleBones](https://gitlab.com/BabbleBones) for helping with the setup and detailing all of the steps.
+
+This guide was written by [Gabriele Musco](https://gabmus.org).
No results found