home.md

+Monado is an open source OpenXR runtime. Currently it is developed for GNU/Linux. Support for other operating systems is very possible in the future. The initial focus for Monado lies on bring up for desktop VR usage. In the future a main goal will be to bring Monado to mobile and standalone AR devices, but this does not mean that support for desktop VR will go away.
+
+The main provider for HMD hardware support for the Monado runtime currently comes from its use of OpenHMD ([Recommended reading about OpenHMD and what it does](https://github.com/OpenHMD/OpenHMD/wiki/Getting-Started)).  
+Further hardware support is provided by a simple native OSVR HDK driver as well as an experimental branch with a libsurvive driver providing positional tracking for the Vive HMD.
+
+## What Monado provides
+
+Monado implements the OpenXR specification, which is a much more comprehensive API than that of "just" a driver library like OpenHMD.
+
+Some of the functionality it provides is similar to what OpenHMD provides, but in the context of the OpenXR API, for example:
+
+* The current pose of the HMD relative as an XrSpace relative to other XrSpaces (e.g. relative to a room scale coordinate system).
+* The current pose of each eye (or rather display, XrView) as quaternion and vector to build a view matrix from.
+* The XrView also contains the field of view of a HMD to build a projection matrix from.
+* The current poses of VR motion controllers as XrActionSpaces.
+* The trigger/touchpad/button input of VR controllers, mapped to XrActions.
+
+However OpenXR specifies that applications do not perform VR specific rendering themselves, instead they only submit textures to an OpenXR runtime. OpenXR applications do not have to care about things like lens distortion anymore, it is the task of the runtime's compositor to implement distortion correction based directly on the hardware drivers.
+
+Monado implements a Vulkan based compositor:
+
+* Supports direct mode and extended mode on Intel, AMD and Nvidia GPUs.
+* Applies the panotools lens distortion correction from OpenHMD. Alternatively applies the lens distortion correction stored in the Vive config. Mesh distortion correction is planned for the near future.
+* Applications can submit OpenGL (AMD and Nvidia) or Vulkan textures (Intel, AMD and Nvidia).
+
+Monado handles direct mode and extended mode similar to SteamVR. That is, if direct mode is available for a currently connected HMD, it will automatically be used. [If the graphics drivers are set up for extended mode, the Monado compositor will automatically start in extended mode](https://github.com/OpenHMD/OpenHMD/wiki/Extended-Mode).
+
+## What Monado does not provide
+
+* A fully featured replacement driver for any HMD hardware. Using OpenHMD drivers, it suffers the same limitations as OpenHMD. However there is experimental support for libsurvive providing positional tracking for the Vive, and a simple native OSVR HDK is also included. Further driver improvements are in progress.
+* A drop in replacement for other VR runtimes or SDKs. To use an application with Monado, it has to be developed for using the OpenXR API.
+  * Examples of applications for Linux that use OpenHMD: Godot games that include the godot-openxr addon (currently none). You can help by writing an OpenXR application.
+  * Translation layers for other APIs to OpenXR might be implemented. For example OpenComposite (formerly OpenOVR) might be a candidate for running existing OpenVR/SteamVR content on OpenXR/Monado once it implements an OpenXR backend.
+
+## Getting started with code
+
+To compile an application for Monado, the platform to be used needs to be defined before the openxr header is included.
+
+    #define XR_USE_PLATFORM_XLIB
+    #define XR_USE_GRAPHICS_API_OPENGL
+    #include <openxr/openxr.h>
+
+Applications do not link to OpenXR runtimes like Monado directly, instead applications link to the OpenXR loader. The OpenXR loader acts similar to the OpenCL or Vulkan loader: it is implemented as a shared library libopenxr_loader.so (or it can also be compiled into the application as a static library) which is responsible for finding and loading an OpenXR runtime like Monado and forwarding OpenXR API calls from the application to the runtime.
+
+The OpenXR API is too extensive to quickly present. The full specification can be found [here](https://www.khronos.org/registry/OpenXR/specs/0.90/html/xrspec.html).
+
+[A simple C example application for Linux can be found here](https://gitlab.freedesktop.org/monado/openxr-simple-example).
\ No newline at end of file