% 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!