openxr.md

+# Status
+
+xrdesktop 0.14 supports the scene mode on OpenXR, but not the overlay mode.
+
+The just released `XR_EXTX_overlay` extension for OpenXR can be used to render content on top of another OpenXR application, at this time support for this extension is not implemented in xrdesktop.
+
+xrdesktop 0.14 ships with simplified default bindings for the Khronos Simple Controller, and full default bindings for the Valve Index Controllers.
+
+With xrdesktop 0.14, adding additional default bindings requires adding a json file to xrdesktop's resource build, as well as recompiling the `xrdesktop` library. OpenXR runtimes may offer a binding UI to support more controllers without requiring default bindings.
+
+# xrdesktop on the Monado OpenXR runtime
+
+At this time the only viable OpenXR runtime for Linux is Collabora's "Monado" runtime.
+
+The best way to try out xrdesktop on Monado is by using a Valve Index and the `experimental/libsurvive-controllers-wip` branch from Monado (Future plans include mainlining this branch to master, and creating a native lighthouse driver for Monado).
+
+## Monado with Valve Index support via libsurvive
+
+Make sure your `gxr` build has been compiled with support. Use `xrd-settings` to ensure sure that `openxr` is the default API , or run `gsettings set org.xrdesktop default-api openxr`. Alternatively the environment variable `GXR_API=openxr` forces `gxr` to use openxr instead of xrdesktops default API setting.
+
+Make sure to read the [notes about the libsurvive branch in the readme](https://gitlab.freedesktop.org/monado/monado/-/tree/experimental/libsurvive-controllers-wip/#about-the-libsurvive-branch) about the basics of using libsurvive.
+
+```
+git clone --recursive https://gitlab.freedesktop.org/monado/monado.git -b experimental/libsurvive-controllers-wip
+cd monado
+mkdir build
+cd build
+cmake ..
+make -j$(nproc)
+```
+
+xrdesktop can now be used on OpenXR with the environment variable `XR_RUNTIME_JSON=/path/to/monado/build/openxr_monado-dev.json`, for example
+
+    XR_RUNTIME_JSON=/path/to/monado/build/openxr_monado-dev.json /path/to/xrdesktop/build/examples/client
+
+or
+
+    XR_RUNTIME_JSON=/path/to/monado/build/openxr_monado-dev.json kwin_x11 --replace
+
+Note that at this time Monado does not have an out-of-process compositor that runs independently of OpenXR applications. The compositor (and entire runtime) is only startet once xrdesktop is enabled, and quits once xrdesktop is disabled.
+
+# OpenXR bindings json format
+
+At this time the OpenXR specification requires actions and bindings to be created and communicated to runtimes programmatically. This means there is no established file format to store bindings in.
+
+xrdesktop opts to store OpenXR bindings in a format heavily inspired by OpenVR bindings.
+
+## actions.json
+
+This format very closely follows OpenVR's `actions.json` manifest. To add default bindings for a new controller, one `default_binding` entry has to be added:
+
+
+    {
+      "controller_type": "foo",
+      "binding_url": "bindings_foo.json"
+    }
+
+## bindings_foo.json
+
+This format has two main differences to OpenVR's bindings manifests:
+
+* A new top level field `"interaction_profile": "/interaction_profiles/foo_vendor/foo_controller"`
+* The inputs have no `mode` entry
+
+OpenVR - like input component names are translated to OpenXR specified input suffixes by `gxr`  (gxr-manifest.c). The non-trivial mappings are:
+
+* `pull` -> `/value`
+* `position` -> ` `
+ 
+ Examples:
+ 
+ The snippet
+ 
+         {
+          "path": "/user/hand/right/input/trigger",
+          "inputs": {
+            "pull": {
+              "output": "/actions/wm/in/grab_window"
+            }
+          }
+
+ maps the input `/user/hand/right/input/trigger/value` to the action `/actions/wm/in/grab_window`.
+ 
+ And the snippet
+ 
+         {
+          "path": "/user/hand/right/input/thumbstick",
+          "inputs": {
+            "position": {
+              "output": "/actions/wm/in/push_pull_scale"
+            }
+          }
+        },
+ 
+maps the input `/user/hand/right/input/thumbstick` to the action `/actions/wm/in/push_pull_scale`, since OpenXR specifies that the thumbstick path without the `/x` or `/y` suffix binds the position as `Vector2F`.
+
+## About the format
+
+The intention of this format is to make it similar to OpenVR manifests and be easily transferable. However this format is not set in stone. It might be changed or abandoned in the future. Future directions could be either a simple homegrown format that directly maps an OpenXR input path from an interaction profile to an action name, or OpenXR could gain an extension that defines a manifest format to be loaded by runtimes.
\ No newline at end of file