OpenXR - How to set up and use Psychtoolbox OpenXR support.

Since Psychtoolbox version 3.0.19, Psychtoolbox supports the modern
Khronos open, cross-platform, cross-vendor, cross-device OpenXR api for
implementing (V)irtual (R)eality VR, (A)ugmented (R)ealtiy AR, and/or
(M)ixed (R)eality MR applications, summarized under the umbrella term
e(X)tended (R)eality XR, hence the name OpenXR. See:

Unless otherwise specified by a users script, the PsychVRHMD(‘AutoSetupHMD’)
function from now on will try to use a system installed OpenXR runtime to
run VR applications, with fallbacks to the older legacy drivers like
PsychOculusVR1 for recent Oculus devices on MS-Windows, PsychOculusVR for
Oculus Rift DK-1/DK-2 on Linux/X11 and MS-Windows, or to PsychOpenHMDVR
on Linux/X11. The driver is designed to be reasonably backwards compatible,
so most scripts should continue to work unmodified “plug & play”.

In the current release, we support the XR subset of VR virtual reality
applications by use of any VR Head mounted display (VR-HMD) and for VR
input devices which are supported by a OpenXR 1.0 compliant runtime that
provides the following minimum set of OpenXR 1.0 extensions:

  • All: XR_KHR_opengl_enable, XR_EXT_debug_utils, and XR_KHR_composition_layer_depth.
  • Additionally on MS-Windows: XR_KHR_WIN32_convert_performance_counter_time.
  • Additionally on Linux/Unix: XR_KHR_convert_timespec_time.
  • Optional, but not tested without it: XR_FB_display_refresh_rate.
  • Optional, for improved input controller support: XR_EXT_hp_mixed_reality_controller,
    XR_HTC_vive_cosmos_controller_interaction, XR_HTC_vive_focus3_controller_interaction,
    XR_KHR_binding_modification, XR_EXT_dpad_binding.
  • Optional, for basic eye gaze tracking: XR_EXT_eye_gaze_interaction.

On VR HMDs with a builtin eye gaze tracker, our OpenXR driver is also
capable of using such hardware to track and report eye gaze. Basic eye
gaze tracking should work with any HMD and OpenXR runtime that supports
the optional OpenXR XR_EXT_eye_gaze_interaction extension. This allows
reporting of a “cyclops eye” gaze vector and 2D gaze position, possibly
synthesized from separate eye gaze measurements on a binocular eye
tracker, or the single measurement from a monocular eye tracker.
Additionally, on MS-Windows only, with certain HTC HMDs only, more
advanced eye gaze tracking is supported via HTC’s SRAnipal eye tracker
runtime on suitable HMDs, e.g., the “HTC Vive Pro Eye”. This allows
additionally for binocular eye gaze reporting, reporting of eye opening,
and estimated eye pupil diameter. Some demos have support and demonstration
of eye gaze tracking. E.g., GazeContingentDemo.m for gaze contingent
manipulation of 2D monoscopic stimuli, VRHMDDemo.m for 2D tracking and
visualization of gaze wrt. monoscopic or stereoscopic stimuli.
VRInputStuffTest.m shows gaze tracking wrt. 3D VR stereoscopic scenes,
both showing 2D gaze position and 3D gaze rays. VREyetrackingTest.m
allows to test and assess various aspects of 2D gaze tracking of 2D or 3D
stimuli presented monoscopically or stereoscopically.

So far successfully tested with the PTB release are:

  • The open-source Monado(XR) runtime version 21.0.0 for Linux/X11, as shipping
    with Ubuntu 22.04-LTS and later, or as a 3rd party ppa for Ubuntu 20.04-LTS,
    as well as part of Debian GNU/Linux 12/unstable/testing. See the following link
    for more information about Monado:

    This has been tested on Ubuntu 20.04.6-LTS and 22.04-LTS with AMD and NVidia
    gpu’s so far.

  • The proprietary Valve SteamVR runtime version 1.24.7 and 1.25.7 on Linux
    (Ubuntu 20.04.6-LTS and 22.04.3-LTS), and SteamVR 1.25.7 and 2.0 on Microsoft
    Windows 10 21H2 - 22H2.

  • The proprietary OculusVR runtime version 1.81.0 on Microsoft Windows 10
    21H2 - 22H2.

Testing so far occured with a OculusVR Oculus Rift CV-1 HMD with 2 Oculus
tracking cameras and 2 Oculus touch controllers, as well as a Oculus
Remote control, and a Microsoft XBox 360 gamepad controller. Additionally
testing was performed under Monado and SteamVR with a HTC Vive Pro Eye
and its two “Vive Wand” controllers, tracked by a Valve Lighthouse
version 2 system with two Vive lighthouse emitter stations.

Eye gaze tracking was tested under Windows 10 22H2 under SteamVR 1.25.6
and and SteamVR 2.0 and HTC SRAnipal SDK, under Octave 7.3 and
Matlab R2022b and R2023b, using a HTC Vive Pro Eye VR headset. Both OpenXR
“cyclops” gaze tracking, and also binocular gaze tracking with eye opening
and pupil diameter reporting worked well.

A limitation of the current OpenXR spec is that it doesn’t provide any
means for reliable, robust, trustworthy, accurate and precise visual
stimulus onset timestamping. We are investigating a future solution for
reliable and trustworthy timestamping for the open-source MonadoXR
runtime on Linux and hope to find a solution there in the foreseeable
future, stay tuned. For now, as of Psychoolbox we have a hack
that only works on a modified version of Monado + a modified version of
Mesa, on AMD or Intel gpu’s under Linux. The hack has various restrictions
and it impacts performance. It is also not quite plug and play to set up.
See ‘help PsychOpenXR’, the section about the Monado metrics hack, for

Testing also showed that all tested proprietary OpenXR runtimes, ie.
both OculusVR and SteamVR, violate the OpenXR specs stimulus timing
requirements, as of December 2023. The only exception was the open-source
Monado(XR) runtime for Linux.

The same limitations are true for the old OculusVR runtimes on
MS-Windows. To get at least approximately correct timestamps, the driver
therefore will switch to a multi-threaded mode of operation if it detects
the need for timestamping or timing, or if that need is specified with
new ‘basicRequirements’ keywords to PsychVRHMD(‘AutoSetupHMD’) or to
PsychVRHMD(‘SetupRenderingParameters’), e.g., ‘TimestampingSupport’ for
timestamps, or ‘TimingSupport’ for onset timing. The switch to
multi-threading will cost some performance and possibly introduce extra
latency. In the case of SteamVR on MS-Windows it may even cause bugs and
hangs in some cases. Therefore additional keywords like
‘NoTimestampingSupport’, ‘NoTimingSupport’, or ‘ForbidMultiThreading’
allow your script to specify also if it doesn’t need precise timing or
timestamping or does not want multi-threading to be used.

Testing showed that MonadoXR was the most reliable and bug-free runtime,
whereas both OculusVR and SteamVR exposed various other serious bugs. Our
driver tries to work around such known bugs on those runtimes, sometimes
by use of multi-threading, which impacts performance. Therefore various new
keywords beyond the ones mentioned above exist to control these
quality/reliability vs. performance tradeoffs for your specific script
and paradigm.

‘help PsychVRHMD’ lists those new keywords in the section for
‘AutoSetupHMD’, and the ‘help PsychOpenXR’ sometimes gives more detailed

If you need precise timing at all costs, potentially to the detriment of
most other functionality, performance or quality, there is also the
keyword ‘TimingPrecisionIsCritical’ to specify, in addition to the other
timing/timestamping keywords. This keyword will force the selection of
the driver with the highest possible timing precision/reliability. At the
moment this means to probe for the PsychOculusVR driver for the old
Oculus v0.5 runtime for Linux/X11 and MS-Windows, only usable for the
original Oculus Rift developer kits DK-1 and DK-2. Then a fallback to a
potentially timing enhanced MonadoXR implementation, once such a thing
exists. Then back to standard OpenXR as a last resort measure, in which
case timestamps will not be reliable or trustworthy at all!

Basic Setup:


  • Oculus: If you bought and set up a Oculus HMD, then the OculusVR-1
    OpenXR runtime will have been installed and setup already and should
    just work(tm) with modern Oculus devices like Rift DK1/DK2/CV1/S and
    the new Meta Quest devices and associated controllers.

  • SteamVR: The same should be true for SteamVR supported HMDs if you
    followed the setup instructions, e.g., for the Valve Index HMDs or
    early HTC Vive HMDs, including the Vive Pro and Vive Pro Eye.If you
    chose a (W)indows(M)ixed(R)eality WMR-HMD, you need to install SteamVR
    and set it up as OpenXR runtime for those HMDs, as the Microsoft
    Windows built-in WMR OpenXR runtime does not support OpenGL interop, so
    SteamVR is needed as a middle-man and translator between Psychtoolbox
    OpenGL rendering and WMR’s Direct3D only rendering.

    If you want to use binocular eye tracking via SRAnipal on HTC HMDs with
    eye tracker, the following URLs may provide useful setup and getting
    started instructions:

    • HTC official guide:
    • Much more detailed webpage, very well done by some motivated volunteer:
  • Other OpenXR runtimes exist from HTC for their latest devices, or from
    other vendors like Varjo for their devices.


  • MonadoXR is provided via ‘sudo apt install monado’ on Ubuntu 22.04-LTS
    and later, Debian GNU/Linux 11 and later, and probably other distros.
    Also as a 3rd party ppa for Ubuntu 20.04-LTS, but we now recommend
    using at least Ubuntu 22.04-LTS. Note that for some HMDs, e.g., the
    Oculus Rift CV-1, you also need OpenHMD, and potentially build Monado
    from source against OpenHMD. See the “supported hardware” section on
    Monado’s website, for natively supported devices, and for devices that
    additionally need OpenHMD, and potentially building Monado from source
    code against an installed libOpenHMD. The HTC Vive devices do have
    basic 3 degree of freedom orientation tracking support in Monado, but
    for full 6 degrees of freedom tracking you will need to install
    libsurvive and compile Monado from source against libsurvive, as an
    external more capable tracking library at the moment.

  • SteamVR can be installed to use SteamVR supported HMD’s, e.g., HTC
    Vive, Valve Index, Oculus Rift. Follow setup instructions after
    installing SteamVR. Use of Oculus devices needs MonadoXR as a SteamVR
    driver plugin on Linux (see setup instructions under When displaying in
    ‘Monoscopic’ or ‘Stereoscopic’ 2D mode, it has been shown beneficial at
    least on Linux with Oculus Rift, to disable asynchronous reprojection,
    as this reduces jitter and tracking noise. HTC Vive devices do not need
    extra external Monado plugins for use with SteamVR.


No OpenXR (or other Psychtoolbox supported) virtual reality runtime
exists on Apples iToys operating system.

Path   Retrieve current version from GitHub | View changelog