Documentation

Getting Started

This section describes steps taken to begin working in Unity.

Unity VR Support

Unity 5.1 and later offer first-party virtual reality support, enabled with the Virtual Reality Supported checkbox in the Other Settings > Configuration tab of Player Settings.

When Unity virtual reality support is enabled, any camera with no render texture is automatically rendered in stereo to your device. Positional and head tracking are automatically applied to your camera, overriding your camera’s transform.

Unity applies head tracking to the VR camera within the reference frame of the camera's local pose when the application starts. If you are using OVRCameraRig, that reference frame is defined by the TrackingSpace GameObject, which is the parent of the CenterEyeAnchor GameObject that has the Camera component.

The Unity Game View does not apply lens distortion. The image corresponds to the left eye buffer and uses simple pan-and-scan logic to correct the aspect ratio.

For more information and instructions for using Unity’s VR support, see the Virtual Reality section of the Unity Manual.

Importing the Oculus Utilities Package

The Oculus Utilities Unity Package includes assets, scripts, and sample scenes to assist with development.

Delete Previously-Imported Assets

If you have previously imported a Unity integration package, delete all Oculus Integration content before importing the new Unity package. Be sure to close the Unity Editor, then navigate to your Unity project folder and delete the following:

Folder Content to Delete

Assets/Plugins

Oculus.*

OVR.*

Assets/Plugins/Android/

*Oculus*

AndroidManifest.xml

*vrapi*

*vrlib*

*vrplatlib*

Assets/Plugins/x86/

Oculus.*

OVR.*

Assets/Plugins/x86_64/

Oculus.*

OVR.*

Unity Project

If you are already working in a Unity project, save your work before beginning.

Otherwise, create a new project into which you will import the Oculus assets:

  1. From the Unity menu, select File > New Project.
  2. Click the Browse button and select the folder where the Unity project will be located.
  3. Make sure that the Setup defaults for: field is set to 3D.
  4. You do not need to import any standard or pro Unity asset packages, as the Oculus Utilities package is fully self-contained.
  5. Click the Create button. Unity will reopen with the new project loaded.

Utilities Package

To import the package into Unity, select Assets > Custom Package... and select the Utilities for Unity .unityPackage to import the assets into your new project. Alternately, you can locate the .unityPackage file in your file system and double-click to launch.

When the Importing package dialog box opens, leave all of the boxes checked and select Import. The import process may take a few minutes to complete.

Migrating to Utilities from the Integration Package

Moving to Unity 5.1 is a substantial upgrade for VR development, and we recommend carefully choosing your time frame for making the update. You may encounter problems related to VR performance or otherwise.

Please let us know about any issues you encounter in the Oculus Unity Forum, and keep your eye out for updates.

Delete Previously-Imported Assets

If you have previously imported a Unity integration package, delete all Oculus Integration content before importing the new Unity package. For detailed instructions, see Importing the Oculus Utilities Package.

Upgrade Procedure

  1. Replace any usage of OVRManager.instance.virtualTextureScale or OVRManager.instance.nativeTextureScale with UnityEngine.VR.VRSettings.renderScale. The value of renderScale is equal to nativeTextureScale * virtualTextureScale. If you set renderScale to a value that is less than or equal to any value it has had since the application started, then virtual texture scaling will be used. If you increase it higher, to a new maximum value, then the native scale is increased and the virtual scale is set to 1.
  2. Replace any usage of OVRManager.instance.eyeTextureAntiAliasing with UnityEngine.QualitySettings.antiAliasing. Instead of multisampling the back-buffer when VR is enabled, Unity multisamples the eye buffers.
  3. Remove any usage of OVRManager.instance.timeWarp and OVRManager.instance.freezeTimeWarp. TimeWarp is always on and cannot be frozen.
  4. Do not assume there are Cameras on OVRCameraRig.leftEyeAnchor or rightEyeAnchor. Instead of calling GetComponent<Camera>(), use Camera.main or, for backward compatibility, use OVRCameraRig.leftEyeCamera or rightEyeCamera.
  5. Move any scripts, image effects, tags, or references from the Cameras on OVRCameraRig.leftEyeAnchor and rightEyeAnchor to the one on centerEyeAnchor.
  6. Remove any usage of OvrCapi.cs. The CAPI C# binding is no longer available. If you need to access CAPI, use UnityEngine.VR.VRDevice.GetNativePtr() to get an ovrHmd pointer and then pass it to a native plugin that uses the Oculus SDK corresponding to your Unity version. For more on which Unity versions correspond to which SDKs, see "Integration Versions" in Compatibility and Requirements.

Importing Utilities Package into Legacy Projects

The legacy Oculus Unity Integration used a separate Camera component on each eye anchor. Oculus Utilities for Unity uses single camera on the center eye anchor. If the Oculus Utilities package is imported into an old project built with the legacy Unity integration, editor scripts will patch up old OVRCameraRig GameObjects and enable PlayerSettings.virtualRealitySupported, so the project should work without further action.

Loading…