% OculusVR - How to setup the drivers for Oculus VR products.
%
% Psychtoolbox supports Virtual Reality Head mounted displays,
% (VR-HMDs) and some other hardware from Oculus VR LLC.
%
% Note: Oculus VR's trademarks, e.g., Oculus, Oculus Rift, etc.
% are registered trademarks owned by Oculus VR, LLC.
%
% Oculus Rift CV-1 and later models from Oculus on Windows:
% ---------------------------------------------------------
%
% The more recent Oculus Rift CV1 and Oculus Touch controllers, or more
% generally, Oculus VR hardware supported by the Oculus SDK and Oculus
% runtime v1.16 and later can be utilized with the newer PsychOculusVR1()
% driver. This requires use of an operating system and hardware platform
% supported by the Oculus runtime v1.16 or later. Currently the
% PsychOculusVR1() driver is known to work successfully on 64-Bit Microsoft
% Windows 7 and later for 64-Bit Intel compatible processors, with suitable
% graphics cards from AMD and NVidia. Use of the latest stable version of
% Windows 10 is recommended, as the driver is best tested on that system and
% Windows 10 is supposed to provide best VR performance and quality due to
% operating system features not present in earlier Windows versions. You will
% need to have the Oculus VR runtime version 1.16 or later installed and setup
% correctly for the driver to work.
%
% Oculus Rift CV-1 and later models from Oculus on Linux:
% -------------------------------------------------------
%
% Limited experimental support for the Oculus Rift CV1 on Linux is available
% by use of the PsychOpenHMDVR() driver, which utilizes OpenHMD to drive the
% device. Functionality and display quality is substantially limited compared to
% use of the PsychOculusVR1() driver though. See "help PsychOpenHMDVR".
%
% Oculus Rift DK-1 and DK-2 on Linux, macOS, Windows:
% ---------------------------------------------------
%
% Currently the older Oculus Rift DK1 and Oculus Rift DK2 are supported
% by Psychtoolbox on the 64-Bit editions of GNU/Linux, Apple OSX and
% Microsoft Windows-7 and later, both under 64-Bit GNU/Octave and
% 64-Bit Matlab by use of the PsychOculusVR() driver. This by use of
% the Oculus v0.5 SDK for these operating system platforms.
%
% In order to use such a HMD you need to install the Oculus VR
% runtime version 0.5.0.1 (-beta) for your operating system.
% This will not work with earlier or later versions of the runtime!
%
% The sdk and runtime for Linux is part of the Psychtoolbox GitHub and can be
% downloaded from the following folder:
%
% https://github.com/Psychtoolbox-3/Psychtoolbox-3/tree/master/PsychSourceGL/Cohorts/OculusSDK
%
% Due to filesize limits of GitHub unfortunately we weren't able to bundle the SDKs and
% runtimes for macOS and Windows in the same way. In the past those runtimes could be
% downloaded from:
%
% https://developer.oculus.com/downloads
%
% You had to select "Legacy", and the version as "0.5.0.1-beta"
% in the drop down menus. Then download the "Oculus Runtime for OSX",
% "Oculus Runtime for Windows", or "Oculus SDK for Linux (experimental)"
% and follow the installation and setup instructions contained in those
% installers / SDKs.
%
% Unfortunately this option no longer exists as of July 2021, so if you need those
% runtimes, you have to go on a hunt on the internet or maybe check on the Psychtoolbox
% forum if some kind user still would have a copy of it for you.
%
% Once the 0.5.0.1 runtime is installed according to instructions, and the HMD is
% properly connected via HDMI video and the USB ports for headset and tracking
% camera (in case of the Rift DK2), Psychtoolbox should detect the HMD and
% make use of it.
%
% Display setup for Rift DK-1/DK-2 with the legacy 0.5.0.1 runtime on Windows:
% ----------------------------------------------------------------------------
%
% On Windows this works with "Extended Desktop" mode.
%
% Display setup for Rift DK-1/DK-2 with the legacy 0.5.0.1 runtime on Linux/X11,
% or for the Oculus Rift CV-1 and later with the OpenHMD runtime on Linux/11:
% ---------------------------------------------------------------------------
%
% On Linux it works on a regular dual display setup, if your machine uses a Linux
% kernel of version 4.15 or earlier. On a modern distribution with a later kernel,
% or generally for best performance and timing you should set up a separate X-Screen
% for the Rift display. The Psychtoolbox/PsychHardware/LinuxX11ExampleXorgConfs
% subfolder contains an example xorg.conf files for setting up dual-X-screen setups
% for Linux, with the GUI on X-Screen 0 and the Rift on X-Screen 1. You will need
% to adapt the example file to your specific setup though. Running without a desktop
% compositor or the desktop compositor disabled may give another performance boost
% on Linux with not so high end cards.
%
% Our current experience shows that the Rift DK2 works best for more
% complex 3D VR scenes on Linux or Windows. Performance on OSX was much
% lower and the setup less reliable in general, as most things on macOS.
%
% If you want to write portable code that makes use of VR headsets, and
% not only of the Oculus Rift, but also future headsets from Oculus or
% from other vendors, then use only the functions of the PsychVRHMD()
% driver. It is expected to work also on future HMDs and HMDs of other
% vendors, once they become available. For use of Oculus Rift specific
% features you may need to use the PsychOculusVR() driver directly, but
% for most usage scenarios that should not be neccessary.
%
% Before use of the HMD, please read the "Health and safety instructions"
% carefully. They are included in the Psychtoolbox/PsychDocumentation/
% folder as file Oculus_Health_and_Safety_Warnings.pdf. This file is
% provided as part of the Oculus SDK runtime and included here for
% your convenience.
%
% The Oculus Rift runtime also comes with a setup tool named "RiftConfigUtil"
% that allows to adapt the rendering of stimuli to the properties of your
% subject, e.g. the interpupillary distance between both eyes.
%
%
% Some demos to get you started:
% ------------------------------
%
% VRHMDDemo -  Shows how to use a HMD as a regular monoscopic display
%              monitor via VRHMDDemo(0), or as a stereoscopic display
%              via VRHMDDemo(1), or simply VRHMDDemo. As you can see,
%              only one line of code is needed to setup a single HMD
%              properly as monoscopic or stereoscopic monitor "strapped
%              to the subjects head". Mono and stereo stimulus presentation
%              is done like in any other mono or stereo Psychtoolbox script.
%
% Various PTB stereo demos demonstrate use of HMDs, e.g, ImagingStereoDemo(103)
% for a random dot stereo display, ImagingStereoMoviePlayer(moviefile, 103) for
% playback of stereoscopic movies.
%
% The most interesting use is use of the HMDs head tracking to render complex 3D
% stimuli via OpenGL which can be navigated by the subjects head movements.
% Enabling an existing 3D stereoscopic script to use the HMD and make use of head
% tracking is a task that requires only a few more lines of code and can be
% accomplished in less than 15 minutes. The following demos demonstrate this use
% of the HMD: MorphDemo for rendering a morphing 3D object, SuperShapeDemo for
% rendering a complex organic "SuperShape", VRHMDDemo1 for rendering of the
% spinning Utah teapot in 3D, with head movement and mouse control of observer
% location and looking direction. VRHMDDemo1 also shows a few optimizations to
% get best performance for more complex scenes.
%
% More such demos will follow in the future.
%
% If you want to immerse your subjects in realistic 3D worlds, you can
% do this by use of the Horde3DForPsychtoolbox toolbox which allows you
% to use the Horde3D graphics engine with Psychtoolbox. That toolbox also
% supports VR HMDs, as demonstrated in the demo named "HordeVRHMDDemo1",
% which immerses you in a complex 3D VR scene and allows you to navigate
% it via mouse movements and head movements.
%
% You can get the Horde3DForPsychtoolbox addon toolkit from GitHub as
% git checkout or as a downloadable zip file:
%
% https://github.com/kleinerm/Horde3DForPsychtoolbox
%
% More such demos for full VR environments as part of Horde will follow
% in the future.
%
% Enjoy your immersion into new (virtual) worlds!