This section examines the Utilities package, including its directory structure, the supplied prefabs, and several key C# scripts.
Contents
OVR
The contents of the OVR folder in OculusUtilities.unitypackage are uniquely named and should be safe to import into an existing project.
The OVR directory contains the following subdirectories:
Editor |
Contains scripts that add functionality to the Unity Editor, and enhance several C# component scripts. |
Materials |
Contains materials that are used for graphical components within the Utilities package, such as the main GUI display. |
Meshes |
Contains meshes that are required by some OVR scripts, such as the TrackerBounds. |
Moonlight |
Contains classes designed for Gear VR development. It includes sub-folders with mobile equivalents of all top-level folders (Editor, Materials, Prefabs, et cetera). |
Prefabs |
Contains the main Unity prefabs that are used to provide the VR support for a Unity scene: OVRCameraRig and OVRPlayerController. These prefabs are not required to provide tracked VR in Unity 5 (see Unity VR Support). |
Scenes |
Contains sample scenes illustrating common concepts. |
Scripts |
Contains the C# files that are used to tie the VR framework and Unity components together. Many of these scripts work together within the various Prefabs. |
Textures |
Contains image assets that are required by some of the script components. |
Plugins
The Plugins folder contains the OVRGamepad.dll, which enables scripts to communicate with the Xbox gamepad on Windows (both 32 and 64-bit versions).
This folder also contains the plugin for Mac OS: OVRGamepad.bundle.
Prefabs
Utilities for Unity 5 provides prefabs in Assets/OVR/Prefabs:
- OVRCameraRig
- OVRPlayerController
- OVRCubemapCaptureProbe
- OVRTrackerBounds (deprecated)
To use, simply drag and drop one of the prefabs into your scene.
OVRCameraRig
OVRCameraRig replaces the regular Unity Camera within a scene. You can drag an OVRCameraRig into your scene and you will be able to start viewing the scene with the Gear VR and Rift.
Figure 1. OVRCameraRig and OVRManager
OVRCameraRig contains one Unity camera, the pose of which is controlled by head tracking; two “anchor” GameObjects for the left and right eyes; and one “tracking space” GameObject that allows you to fine-tune the relationship between the head tracking reference frame and your world. The rig is meant to be attached to a moving object, such as a character walking around, a car, a gun turret, et cetera. This replaces the conventional Camera.
The following scripts (components) are attached to the OVRCameraRig prefab:
- OVRCameraRig.cs
- OVRManager.cs
OVRPlayerController
The OVRPlayerController is the easiest way to start navigating a virtual environment. It is basically an OVRCameraRig prefab attached to a simple character controller. It includes a physics capsule, a movement system, a simple menu system with stereo rendering of text fields, and a cross-hair component.
To use, drag the player controller into an environment and begin moving around using a gamepad, or a keyboard and mouse.
One script (Components) is attached to the OVRPlayerController prefab:
- OVRPlayerController.cs
Figure 2. OVRPlayerController
OVRCubemapCaptureProbe
This prefab allows you to capture a static 360 screenshot of your application while it is running, either at a specified time after launch, when a specified key is pressed, or when the static function OVRCubemapCapture.TriggerCubemapCapture is called. For more information on this function, see our Unity Developer Reference.
OVRCubemapCaptureProbe is based on OVR Screenshot (see OVR Screenshot for more information).
Screenshots are taken from the perspective of your scene camera. They are written to a specified directory and may be either JPEG or PNG. File type is specified by the file extension entered in the Path Name field; default is PNG. Resolution is configurable.
Basic Use
Drag OVRCubemapCaptureProbe into the scene and set the parameters as desired in the Inspector view.
Parameters
Auto Trigger After Launch |
Select to enable capture after a delay specified in Auto Trigger Delay. Otherwise capture is triggered by the keypress specified in Triggered by Key. |
Auto Trigger Delay |
Specify delay after application launch before cubemap is taken. (requires Auto Trigger After Launch selected). |
Triggered By Key |
Specifies key to trigger image capture (requires Auto Trigger After Launch not selected). |
Path Name |
Specifies directory, file name, and file type (JPEG or PNG) for screen capture. Windows default path: C:\Users\$username\AppData\LocalLow\Sample\$yourAppName\OVR_ScreenShot306\ Android default path: /storage/emulated/0/Android/data/com.unity3d.$yourAppName/files/OVR_ScreenShot360/ Default file type: PNG. |
Cubemap Size |
Specify size (2048 x 2048 is default, and is the resolution required for preview cubemaps submitted to the Oculus Store). |
OVRTrackerBounds (Deprecated)
Drag OVRTrackerBounds into your scene, as a child of the OVRCameraRig’s CenterEyeAnchor. It will add an arrow that will appear and cue users that they are approaching the limits of the tracking frustum. Parameters are configured in the Inspector view.
Unity Components
This section gives a general overview of the Components provided by the Utilities package.
OVRCameraRig
OVRCameraRig is a Component that controls stereo rendering and head tracking. It maintains three child “anchor” Transforms at the poses of the left and right eyes, as well as a virtual “center” eye that is halfway between them.
This Component is the main interface between Unity and the cameras. It is attached to a prefab that makes it easy to add comfortable VR support to a scene.
Important: All camera control should be done through this component. You should understand this script when implementing your own camera control mechanism.
Mobile and PC Public Members
Updated Anchors |
Allows clients to filter the poses set by tracking. Used to modify or ignore positional tracking. |
GameObject Structure
TrackingSpace |
A GameObject that defines the reference frame used by tracking. You can move this relative to the OVRCameraRig for use cases in which the rig needs to respond to tracker input. For example, OVRPlayerController changes the position and rotation of TrackingSpace to make the character controller follow the yaw of the current head pose. |
OVRManager
OVRManager is the main interface to the VR hardware. It is a singleton that exposes the Oculus SDK to Unity, and includes helper functions that use the stored Oculus variables to help configure camera behavior.
This component is added to the OVRCameraRig prefab. It can be part of any application object. However, it should only be declared once, because it includes public members that allow for changing certain values in the Unity Inspector.
OVRManager.cs contains the following public members:
Monoscopic |
If true, rendering will try to optimize for a single viewpoint rather than rendering once for each eye. Not supported on all platforms. |
Use Position Tracking |
Disables the IR tracker and causes head position to be inferred from the current rotation using the head model. |
Reset Tracker On Load |
This value defaults to True. When turned off, subsequent scene loads will not reset the tracker. This will keep the tracker orientation the same from scene to scene, as well as keep magnetometer settings intact. |
Tracking Origin Type |
Set to Eye Level to track the position and orientation y-axis relative to the HMD’s position. Set to Floor Level to track position and orientation relative to the floor, based on the user’s standing height as specified in the Oculus Configuration Utility. Default is Eye Level. |
Helper Classes
In addition to the above components, your scripts can always access the HMD state via static members of OVRManager.
OVRDisplay |
Provides the pose and rendering state of the HMD. |
OVRTracker |
Provides the pose, frustum, and tracking status of the infrared tracking sensor. |
Rift Recentering
OVRManager.display.RecenterPose() recenters the head pose and the tracked controller pose, if present (see OVRInput for more information on tracking controllers).
If Tracking Origin Type is set to Floor Level, OVRManager.display.RecenterPose() resets the x-, y-, and z-axis position to origin. If it is set to Eye Level, the x-, y-, and z-axis are all reset to origin, with the y-value corresponding to the height calibration performed with the Oculus Configuration Utility. In both cases, the y rotation is reset to 0, but the x and z rotation are unchanged to maintain a consistent ground plane.
Recenter requests are passed to the Oculus C API. For a more detailed description of what happens subsequently, please see VR Focus Management in our PC SDK Developer Guide.
Utilities
OVRPlayerController |
OVRPlayerController implements a basic first-person controller for the VR framework. It is attached to the OVRPlayerController prefab, which has an OVRCameraRig attached to it. The controller will interact properly with a Unity scene, provided that the scene has collision detection assigned to it. OVRPlayerController contains a few variables attached to sliders that change the physics properties of the controller. This includes Acceleration (how fast the player will increase speed), Dampening (how fast a player will decrease speed when movement input is not activated), Back and Side Dampen (how much to reduce side and back Acceleration), Rotation Amount (the amount in degrees per frame to rotate the user in the Y axis) and Gravity Modifier (how fast to accelerate player down when in the air). When HMD Rotates Y is set, the actual Y rotation of the cameras will set the Y rotation value of the parent transform that it is attached to. The OVRPlayerController prefab has an empty GameObject attached to it called ForwardDirection. This GameObject contains the matrix which motor control bases it direction on. This GameObject should also house the body geometry which will be seen by the player. |
OVRGridCube |
OVRGridCube is a helper class that shows a grid of cubes when activated. Its main purpose is to be used as a way to know where the ideal center of location is for the user’s eye position. This is especially useful when positional tracking is activated. The cubes will change color to red when positional data is available, and will remain blue if position tracking is not available, or change back to blue if vision is lost. |
OVRTrackerBounds |
Warns players when the HMD moves outside the trackable range. |
GameObject Structure
ForwardDirection |
An empty GameObject attached to the OVRPlayerController prefab containing the matrix upon which motor control bases its direction. This GameObject should also house the body geometry which will be seen by the player. See TrackingSpace in “OVRCameraRig” for more information |
For information on OVRInput, see link.
Oculus Scripts and Scenes
You will find the following sample scenes located in Assets/OVR/Scenes:
Trivial |
An empty scene with one cube and a plain Unity camera. |
Room |
A cubic room formed from six cubes enclosing an OVRPlayerController. |
Cubes |
A 3D array of cubes and an OVRCameraRig. |
These scripts for assisting with mobile development are located in Assets/OVR/Moonlight/:
OVRDebugHeadController.cs |
A simple behavior that can be attached to the parent of the CameraRig to provide movement via the gamepad, useful for testing applications in Unity without an HMD. |
OVROverlay.cs |
Add to an object with a Quad mesh filter to have the quad rendered as a TimeWarp overlay instead by drawing it into the eye buffer. |
OVRPlatformMenu.cs |
Helper component for detecting Back Key long-press to bring-up the Universal Menu and Back Key short-press to bring up the Confirm-Quit to Home Menu. Additionally implements a Wait Timer for displaying Long Press Time. For more information on interface guidelines and requirements, please review Interface Guidelines and Universal Menu in the Mobile SDK documentation. |
OVRTouchpad.cs |
Interface class to a touchpad. |
These simple scripts for assisting with mobile development are located in Assets/OVR/Moonlight/Utils:
OVRChromaticAberration.cs |
Drop-in component for toggling chromatic aberration correction on and off for Android. |
OVRDebugGraph.cs |
Drop-in component for toggling the TimeWarp debug graph on and off. Information regarding the TimeWarp Debug Graph may be found in the TimeWarp technical note in the Mobile SDK documentation. |
OVRModeParms.cs |
Example code for de-clocking your application to reduce power and thermal load as well as how to query the current power level state. |
OVRMonoscopic.cs |
Drop-in component for toggling Monoscopic rendering on and off for Android. |
OVRResetOrientation.cs |
Drop-in component for resetting the camera orientation. |
OVRWaitCursor.cs |
Helper component for auto-rotating a wait cursor. |
See our Oculus Utilities for Unity Reference Manual for a more detailed look at these and other C# scripts. Undocumented scripts may be considered internal, and should generally never be modified.
Oculus Mobile SDK Examples
The SDK Examples project demonstrates useful scenarios and functionality for Gear VR development.
The Examples include sample scenes, scripts that allow you to toggle features including chromatic aberration correction, TimeWarp debug graph, and monoscopic rendering, and samples that illustrate typical implementations of touchpad input, volume control, and more.
To download, select Platform: Game Engines from our Downloads page here:https://developer.oculus.com/downloads/
To import SDKExamples into Unity, begin by creating a new, empty project. Then select Assets>Import Package > Custom Package… and select SDKExamples.unityPackage to import the assets into your project. Alternately, you can locate the SDKExamples.unityPackage and double-click to launch, which will have the same effect.
Once imported, replace your Unity project’s ProjectSettings folder with the ProjectSettings folder included with SDKExamples.
You will find the following sample scenes located in Assets/Scenes:
30Hz_Sample |
An example of how to set the TimeWarp vsync rate to support 30Hz apps, as well as how to enable Chromatic Aberration Correction and Monoscopic Rendering for Android. For more information on 30Hz TimeWarp and Chromatic Aberration Correction for Android, please review the TimeWarp technical note in theMobile SDK documentation. |
Box_Room |
A simple box room for testing. |
Crosshair_Sample |
An example of how to use a 3D cursor in the world with three different modes. |
FirstPerson_Sample |
An example of how to attach avatar geometry to the OVRPlayerController. |
GlobalMenu_Sample |
An example demonstrating Back Key long-press action and the Universal Menu. Additionally demonstrates a gaze cursor with trail. For more information on Interface Guidelines and requirements, please review the following documents: Interface Guidelines andUniversal Menu in the Mobile SDK documentation. |
LayeredCameras |
Illustrates how to render nearby and far-away content with separate cameras. |
Menu_Sample |
An example demonstrating a simple in-game menu activated by Back Key short-press action. The menu also uses the Battery Level API for displaying the current battery level and temperature. |
MoviePlayer_Sample |
An example demonstrating basic in-game video using Android MediaPlayer. |
Multicamera_Sample |
An example of switching cameras in one scene. |
SaveState_Sample |
An example demonstrating saving the state of the game on pause and loading it on resume. Click on the objects in the scene to change their color. When you run the scene again, the objects should be in the color you had selected before exiting. |
Startup_Sample |
An example of a quick, comfortable VR app loading experience utilizing a black splash screen, VR enabled logo scene, and an async main level load. For more information on interface guidelines, please review Interface Guidelines and Universal Menu in the Mobile SDK documentation. |
These example scripts are located in Assets/Scripts/:
Crosshair3D.cs |
Detailed code for how to create judder-free crosshairs tied to the camera view. |
MoviePlayerSample.cs |
Example code and documentation for how to play an in-game video on a textured quad using Android MediaPlayer (mobile) or Unity’s native media rendering (PC). |
Multicamera_Sample.cs |
For use with the sample scene. |
StartupSample.cs |
Example code for loading a minimal-scene on startup while loading the main scene in the background. |
TimeWarp30HzSample.cs |
Example code for setting up TimeWarp to support 30Hz apps as well as toggling Chromatic Aberration Correction and Monoscopic Rendering on and off. |