Oculus Rift GettingStarted Guide

2 | Introduction | Oculus Rift

2 |  | 

Copyrights and Trademarks© 2017 Oculus VR, LLC. All Rights Reserved.

OCULUS VR, OCULUS, and RIFT are trademarks of Oculus VR, LLC. (C) Oculus VR, LLC. All rights reserved.BLUETOOTH is a registered trademark of Bluetooth SIG, Inc. All other trademarks are the property of theirrespective owners. Certain materials included in this publication are reprinted with the permission of thecopyright holder.

Oculus Rift | Contents | 3

Contents

Getting Started with the SDK..............................................................................4

Oculus Rift SDK Setup.........................................................................................5Installation.......................................................................................................................................................... 5Directory Structure.............................................................................................................................................5Compiler Settings.............................................................................................................................................. 5Makefiles, Projects, and Build Solutions........................................................................................................... 5Terminology....................................................................................................................................................... 6

Getting Started with the Demos......................................................................... 7Getting Started.................................................................................................................................................. 7

OculusWorldDemo Controls........................................................................................................................ 7OculusWorldDemo Usage............................................................................................................................8Next Steps....................................................................................................................................................9

4 | Getting Started with the SDK | Oculus Rift

Getting Started with the SDKNow that your Oculus Rift is plugged in and the drivers are installed, you are ready to install the SDK and trythe demos.

Oculus Rift | Oculus Rift SDK Setup | 5

Oculus Rift SDK SetupThis section describes how to set up the SDK.

InstallationThe latest version of the Oculus SDK is always available from the Oculus Developer Center.

To download the latest package, go to http://developer.oculus.com.

SDK versions use a product.major.minor.patch format. For example, 0.5.0.1 means Product 0, Major 5, Minor 0,Patch 1.

Note: The instructions in this section assume you have installed the Oculus Rift and Oculus runtimepackage.

Directory StructureThe directory structure of the Oculus SDK package is straightforward.

It uses the following directory structure:

3rdParty—third party SDK components used by samples, such as TinyXml.Doc—SDK Documentation, including this document.Firmware—firmware files for the Oculus tracker.LibOVR—libraries, source code, projects, and makefiles for the SDK.LibOVR/Include—public include header files, including OVR.h.LibOVR/Lib—pre-built libraries for use in your project.LibOVR/Src—source code and internally referenced headers.Samples—samples that integrate and leverage the Oculus SDK.Tools—configuration utility.

Compiler SettingsThe LibOVR libraries do not require exception handling or RTTI support.

Your game or application can disable these features for efficiency.

Makefiles, Projects, and Build SolutionsDevelopers can rebuild the samples and LibOVR using the projects and solutions in the Samples and LibOVR/Projects directories.

6 | Oculus Rift SDK Setup | Oculus Rift

Windows

Solutions and project files for Visual Studio 2010, 2012 and 2013 are provided with the SDK. Samples/Projects/Windows/VSxxxx/Samples.sln, or the 2012/2013 equivalent, is the main solution that allowsyou to build and run the samples, and LibOVR itself.

MacOS

The included Xcode workspace Samples/Projects/Mac/Samples.xcworkspace allows you to build andrun the samples, and LibOVR itself. The project is configured to build universal binaries (x86 and x86\_64) for allrecent MacOS versions (10.8 and newer).

Linux (Experimental)

A makefile is provided in the root folder that allows you to build LibOVR and the OculusWorldDemo sample.The code is dependent on the udev and Xinerama runtime components. As a result, you must install therelevant packages before building. You must also install a udev/rules.d file to set the correct accesspermissions for Oculus HMD devices.

These steps can be performed by executing the provided script ConfigurePermissionsAndPackages.sh,located in the root folder of the SDK.

TerminologyYou should familiarize yourself with these terms, which are frequently used in the rest of this document.

Head-mounted display (HMD) A general term for any VR device such as the Rift.

Interpupillary distance (IPD) The distance between the eye pupils. The defaultvalue in the SDK is 64 millimeters, which correspondsto the average human distance, but values between54 and 72 millimeters are possible.

Field of view (FOV) The full vertical viewing angle used to configurerendering. This is computed based on the eyedistance and display size.

Tan Half FOV The tangent of half the FOV angle. Thus a FOV of60 degrees has a half-FOV of 30 degrees, and a tan-half-FOV value of tan(30) or 0.577. Tan half FOV isconsidered a more usable form in this use case thandirect use of FOV angles.

Aspect ratio The ratio of horizontal resolution to vertical resolution.The aspect ratio for the Oculus Rift DK2 is 1920x1080(960 x 1080 per eye or 0.89). The aspect ratio for eacheye on the Oculus Rift DK1 is 640/800 or 0.8.

Multisampling Hardware anti-aliasing mode supported by manyvideo cards.

Oculus Rift | Getting Started with the Demos | 7

Getting Started with the DemosNow that the Rift is plugged in, the drivers are installed, and the SDK is installed, you are ready to begin usingthe SDK.

Note: If you haven’t already, take a moment to adjust the Rift headset so that it’s comfortable for yourhead and eyes. More detailed information about configuring the Rift can be found in the Oculus RiftHardware Setup this guide.

After the hardware is configured, the next step is to test the development kit. The SDK comes with a set of full-source C++ samples designed to help you get started quickly. These include:

• OculusWorldDemo—A visually appealing scene with on-screen text and controls.• OculusRoomTiny— A minimal C++ sample showing sensor integration and rendering on the Rift (only

available for D3DX platforms as of 0.4. Support for GL platforms will be added in a future release).

Getting StartedOculus recommends running the pre-built OculusWorldDemo to explore the SDK. You can find a link to theexecutable file in the root of the Oculus SDK installation.

The following is a screenshot of the OculusWorldDemo application:

Figure 1: OculusWorldDemo Application

OculusWorldDemo ControlsThe OculusWorldDemo uses a mix of standard and specialized controls.

The following table describes keys and devices that you use for movement:

8 | Getting Started with the Demos | Oculus Rift

Table 1: Movement

Key or Input Movement

W, S Move forward, back

A, D Strafe left, right

Mouse Look left, right

Left gamepad stick Move

Right gamepad stick Turn

The following table describes keys that you use for functions:

Table 2: Functions

Key(s) Function

F4 Multisampling toggle

F7 Mono/stereo view mode toggle

F9 Hardware full-screen (low latency) *

F11 Windowed full-screen (no blinking) *

E Motion relative to head/body

R Reset sensor orientation

Esc Cancel full-screen

-, + Adjust eye height

L Adjust fourth view value

Tab Options Menu

Spacebar Toggle debug info overlay

T Reset player position

Ctrl+Q Quit

G Cycle grid overlay mode

U, J Adjust second view value

I, K Adjust third view value

; Cylce rendered scenes

+Shift Adjust values quickly

O Toggle Time-Warp

C Toggle FreezeEyeUpdate

V Toggle Vsync

* Only relevant in Extend Desktop display mode.

OculusWorldDemo UsageOnce you’ve launched OculusWorldDemo, you should see a window on your PC monitor similar to the previousscreenshot.

Oculus Rift | Getting Started with the Demos | 9

Depending on the settings chosen in the Display Mode dialog of the Oculus system tray, you might also seethe image displayed inside the Rift. If it is set to Direct Display, the Oculus display driver manages the OculusRift and will automatically display the rendered scene. If Extended Desktop is selected or you are using a DK1and the DK1 Legacy Support check box is selected, the Oculus Rift display uses extended desktop mode. Inthis case, you should press F9 or F11 to switch rendering to the Oculus Rift as follows:

• F9— switches to hardware full-screen mode. This will give best possible latency, but may blink monitors asthe operating system changes display settings. If no image shows up in the Rift, then press F9 again to cycleto the next monitor.

• F12—Instantly switches the rendering window to the Rift portion of the desktop. This mode has higherlatency and no vsync, but is convenient for development.

If you’re having problems (for example, no image in the headset, no head tracking, and so on), please view theDeveloper Forums.

When the image is correctly displayed inside the Rift then take a moment to look around in VR and double-check that all of the hardware is working properly. If you’re using a DK2 then you should be able to see thatphysical head translation is now also recreated in the virtual word as well as rotation.

Important: If you need to move the DK2 external camera for any reason after initial calibration, be sure tominimize the movement of the HMD for a few seconds while holding it within the tracking frustum. This will givethe system chance to recalibrate the camera pose.

If you would like to explore positional tracking in more detail, you can press the semicolon (;) key to bring the“sea of cubes” field that we use for debugging. In this mode, cubes are displayed that allow you to easilyobserve positional tracking behavior. Cubes are displayed in red when head position is being tracked and inblue when sensor fusion falls back onto the head model.

There are a number of interesting things to take note of the first time you experience OculusWorldDemo. First,the level is designed to scale. Thus, everything appears to be roughly the same height as it would be in thereal world. The sizes for everything, including the chairs, tables, doors, and ceiling, are based on measurementsfrom real world objects. All of the units are measured in meters.

Depending on your actual height, you may feel shorter or taller than normal. The default eye height of theplayer in OculusWorldDemo is 1.61 meters (approximately the average adult eye height), but this can beadjusted using the using the ‘+’ and ‘-’ keys. Alternatively, you can set your height in the Oculus ConfigurationUtility (accessed through the Oculus System Tray Icon).

OculusWorldDemo includes code that shows how to use values set in the player’s profile such as eye height,IPD, and head dimensions, and how to feed them into the SDK to achieve a realistic sense of scale for awide range of players. The scale of the world and the player is critical to an immersive VR experience. Moreinformation about scale is available in the Oculus Best Practices Guide.

Next StepsAfter trying the OculusWorldDemo, there are other samples and tools.

Software Developers and Integration EngineersIf you’re integrating the Oculus SDK into your game engine, Oculus recommend starting with the sampleprojects.

Open the following projects, build them, and experiment with the provided sample code:

• Samples/Projects/Windows/VSxxxx/Samples.sln• Samples/Projects/Mac/Samples.xcworkspace

10 | Getting Started with the Demos | Oculus Rift

OculusRoomTiny

This is a good place to start, because its source code compactly combines all critical features of the OculusSDK. It contains logic necessary to initialize LibOVR core, access Oculus devices, use the player’s profile,implement head-tracking, sensor fusion, stereoscopic 3D rendering, and distortion processing.

Figure 2: OculusRoomTiny

OculusWorldDemo

This is a more complex sample. It is intended to be portable and support many more features. These includewindowed/full-screen mode switching, XML 3D model and texture loading, movement collision detection,adjustable view size and quality controls, 2D UI text overlays, and so on.

This is a good application to experiment with after you are familiar with Oculus SDK basics. It also includes andoverlay menu with options and toggles that customize many aspects of rendering including FOV, render targetuse, timewarp and display settings. Experimenting with these options may provide developers with insight intowhat the related numbers mean and how they affect things behind the scenes.

Beyond experimenting with the provided sample code, Oculus recommends reading the rest of this guide. Itcovers LibOVR initialization, head-tracking, rendering for the Rift, and minimizing latency.

Artists and Game DesignersIf you’re integrating the Oculus SDK into your game engine, Oculus recommends starting with the sampleprojects.

If you’re an artist or game designer unfamiliar with C++, we recommend downloading UE3, UE4 or Unity alongwith the corresponding Oculus integration. You can use our out-of-the-box integrations to begin buildingOculus-based content immediately.

The Unreal Engine 3 Integration Overview document and the Unity Integration Overview document,available from the Oculus Developer Center, detail the steps required to set up your UE3/Unity plus Oculusdevelopment environment.

We also recommend reading through the Oculus Best Practices Guide, which has tips, suggestions, andresearch oriented around developing great VR experiences. Topics include control schemes, user interfaces,

Oculus Rift | Getting Started with the Demos | 11

cut-scenes, camera features, and gameplay. The Best Practices Guide should be a go-to reference whendesigning your Oculus-ready games.

Aside from that, the next step is to start building your own Oculus-ready game or application. Thousands ofother developers are out building the future of virtual reality gaming. To see what they are talking about, go toforums.oculus.com. To see what they are building, go to share.oculus.com.