Oculus Legacy 4.x Unity Integration Developer Guide
Oglas
Oglas
Unity 4.x Legacy Integration
Developer Guide
Version 1.3.0
2 | Introduction | Unity
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 their respective owners. Certain materials included in this publication are reprinted with the permission of the copyright holder.
2 | |
Unity | Contents | 3
Contents
Introduction
5
Getting Started
....................................................................................................
9
A Detailed Look at the Unity Integration
..........................................................
11
OVRInput
18
Configuring for Build
.........................................................................................
26
Sample Unity Application Demos
......................................................................
34
Troubleshooting and Known Issues
...................................................................
36
Debugging and Performance Analysis in Unity
.................................................
37
4 | Contents | Unity
Best Practices: Mobile
.......................................................................................
45
Tutorial: Build a Simple VR Unity Game
............................................................
49
Getting Started FAQ
..........................................................................................
53
Unity-SDK Version Compatibility
.......................................................................
55
Release Notes
....................................................................................................
57
Unity | Introduction | 5
Introduction
This guide covers developing Unity 4 games and applications for the Oculus Rift and Samsung Gear VR.
The legacy integration provides VR support for development with
Unity 4.x Professional and Free editions. It also includes Unity prefabs, C# scripts, sample scenes, and more to assist with development.
Projects using
Unity 5.1 and later should use the Oculus Utilities for Unity package instead of this integration.
Developers beginning new projects should use Unity 5.1+.
For information on recommended and supported Unity versions, see
Compatibility and Requirements
This guide covers:
• Getting started
• Downloading and installing the Oculus Unity Integration
• Package contents
• Input Mapping
• How to use the provided samples, assets, and sample applications
• Configuring Unity VR projects for build to various targets
• Getting Started Frequently Asked Questions
• Debugging and Performance Analysis
• Getting Started Tutorial (build a simple VR game)
Most information in this guide applies to the use of the Utilities package for either Rift or Mobile development.
Any exceptions are clearly indicated where they occur.
For a complete API reference, see our
Unity Developer Reference
.
When developing for both Rift and mobile platforms, keep in mind that the requirements for PC and mobile
VR applications differ substantially. If you would like to generate builds for both PC and mobile from a single project, it is important to follow the more stringent mobile development best practices.
Compatibility and Requirements
System and Hardware Requirements
To verify that you are using supported hardware, please review the relevant PC or mobile setup documentation:
• PC SDK:
Getting Started with the SDK
• Mobile SDK:
System and Hardware Requirements
Recommended Unity Versions
All Unity versions 5.1 and later ship with a bundled version of the Oculus OVRPlugin that provides built-in Rift and Gear VR support.
Beginning with Utilities for Unity 1.14, the Utilities package also includes the latest version of OVRPlugin. When you import Utilities for Unity into a Unity project, if the OVRPlugin version included with the Utilities is later than the version built into your editor, a pop-up dialog will give you the option to update it. We always recommend using the latest available OVRPlugin version.
6 | Introduction | Unity
For more information, see
OVRPlugin
.
Legacy support is available for Unity 4 - see our
Unity 4.x Legacy Integration Developer Guide
for more information.
Unity 5.1 or later provide built-in support for Rift and Gear VR development. The optional Oculus Utilities for
Unity package offers additional developer resources.
Unity Version
Unity 5.4
Recommended Release
Unity 5.4.5p1 and later
Unity 5.5
Unity 5.6
Unity 4
Unity 5.5.3p2 and later
Unity 5.6.0p3 and later
Unity 4.7.0f1 (legacy support only)
For complete details Oculus SDK or Integration version compatibility with Unity, see
Unity-SDK Version
Compatibility
.
OS Compatibility
•
Windows: Windows 7, 8, 10
•
Mac: OS X Yosemite, El Capitan, Sierra
OS X development requires the Oculus Rift Runtime for OS X, available from our
Downloads page
. Note that runtime support for OS X is legacy only. It does not support consumer versions of Rift.
Unity Personal and Professional Licenses
The Unity Personal and Professional licenses both provide built-in Rift support. Mobile developers using the
Unity Free license receive basic Android support automatically. Mobile developers using a Professional license require an Android Pro Unity license.
For more information, see
License Comparisons
in Unity’s documentation.
Controllers
You may wish to have a controller for development or to use with the supplied demo applications. Available controllers include the Oculus Touch or Xbox 360 controller for Rift, and the Gear VR Controller for mobile development.
Downloading the Legacy Integration
All Oculus Unity development materials are available for download at our Developer site:
https:// developer.oculus.com/downloads/
Legacy Integration Contents
• Oculus Integration package
• Project Settings assets
Unity | Introduction | 7
Included with Mobile SDK
• SDKExamples (source)
• BlockSplosion sample application (source and pre-built apk, for Mobile SDK)
• Shadowgun sample application (pre-built-apk, for Mobile SDK)
SDK Examples is a resource for mobile developers that includes Unity example scenes illustrating the use
of common resources such as menus, crosshairs, and more. See
for more information.
Also Available
Additional development resources are available separately from our
Downloads page
.
• Legacy Oculus Spatializer for Unity (included with Oculus Audio SDK Plugins; the Native OSP is for use with
Unity 5)
• OVRMonitor (includes the VrCapture library and Oculus Remote Monitor client for mobile performance analysis and debugging; see our
OVRMonitor documentation
for more information).
Preparing for Development: Rift
We recommend Rift developers begin by reviewing the
PC Developer Guide
. Mobile developers should review
Mobile VR Application Development
.
Recommended Configuration
• On Windows, enable Direct3D 11 - it exposes the most advanced VR rendering capabilities. Direct3D 9 and
Windows OpenGL are not supported. D3D 12 is currently available as an experimental feature.
• Use the Linear Color Space. Linear lighting is not only more correct for shading, it also causes Unity to perform sRGB read/write to the eye textures. This helps reduce aliasing during VR distortion rendering, where the eye textures are interpolated with slightly greater dynamic range.
• Never clone displays. When the Rift is cloned with another display, the application may not vsync properly.
This leads to visible tearing or judder (stuttering or vibrating motion).
Preparing for Development: Mobile
This guide describes setup requirements for Oculus mobile VR development with Unity.
Android SDK Setup and Oculus Mobile SDK
The Android SDK is required for mobile development with Unity. However, most Unity developers do not need to install Android Studio or NDK. Unity developers should follow the instructions in our
Device Setup guide
, and install the Java Development Kit (JDK) and Android SDK before beginning development. See Unity’s
Getting Started with Android Development
for more information.
OVRMonitor is available to Unity 4 developers as a separate download. However, Unity 4 developers must download the Oculus Mobile SDK for the SDK Examples.
When developing for mobile, please be sure to fully review all of the relevant performance and design
. Mobile apps are subject to more stringent
limitations and requirements and computational limitations which should be taken into consideration from the ground up.
8 | Introduction | Unity
Application Signing
Mobile applications require two different signatures at different stages of development. Be sure to read the
Application Signing
section of the Mobile SDK documentation for more information.
Application Entitlement Checking
Entitlement checking, used to protect apps from unauthorized distribution, is disabled by default in Unity. For more information and instructions, see
Getting Started with the SDK
in our Platform guide.
Unity | Getting Started | 9
Getting Started
This section describes how to begin working in Unity.
Importing the Unity Integration
The Oculus Integration asset package is the heart of the supplied development resources. Importing it will install the minimum set of required files necessary for VR integration into Unity. We have also included various assets, scripts, and sample scenes to assist with development.
Create or Open 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 Unity integration is fully self-contained.
5. Click the Create button. Unity will reopen with the new project loaded.
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/
Assets/Plugins/x86/
Assets/Plugins/ x86_64/
*Oculus*
AndroidManifest.xml
*vrapi*
*vrlib*
*vrplatlib*
Oculus.*
OVR.*
Oculus.*
OVR.*
10 | Getting Started | Unity
Import Integration Package
To import the integration into Unity, select Assets > Custom Package... and select the Unity
Integration .unityPackage to import the assets into your new project. Alternately, you can simply find 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.
Copy Project Settings (Mobile)
The mobile Unity Integration includes a Project Settings folder which provides default settings for a VR mobile application. You may manually copy these files to your [Project]/Assets/ProjectSettings folder. Be sure to keep a copy in your Mobile SDK folder to copy later for use with additional projects.
To Import BlockSplosion Sample Application (Mobile)
Note: The Room sample scene included in the integration package may be used for Rift development.
To import the SDKExamples into Unity, select Assets > Custom Package... and select
BlockSplosion.unityPackage to import the assets into your new project. Alternately, you can simply find 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.
Each sample application project includes a ProjectSettings folder, which provides default settings for the VR mobile application. Copy these files to your [Project]/Assets/ProjectSettings folder.
Adding VR to an Existing Unity Project
Note: This process is covered in greater detail in our Tutorial
.
The Unity Integration package may be used to integrate Oculus VR into an existing project. This may be useful as a way of getting oriented to VR development, but dropping a VR camera into a Unity game that wasn't designed with VR best practices in mind is unlikely to produce a great experience.
1. Import package.
2. Instantiate OVRCameraRig if you already have locomotion figured out or instantiate OVRPlayerController to walk around.
3. Copy any scripts from the non-VR camera to the OVRCameraRig. Any image effect should go to both the
Left/RightEyeAnchor GameObjects. These are children of a TrackingSpace GameObject, which is itself a child of OVRCameraRig. The TrackingSpace GameObject allows clients to change the frame of reference used by tracking, e.g., for use with a game avatar.
4. Disable your old non-VR camera.
5. Build your project and run normally.
Note: This is one simple method for adding VR to an existing application, but is by no means the only way. For example, you may not always wish to use OVRPlayerController.
Unity | A Detailed Look at the Unity Integration | 11
A Detailed Look at the Unity Integration
This section examines the Unity integration, including the directory structure of the integration, the Unity prefabs are described, and several key C# scripts.
Contents
OVR
The contents of the OVR folder in OculusUnityIntegration.unitypackage are uniquely named and should be safe to import into an existing project.
The OVR directory contains the following subdirectories:
Editor
Materials
Moonlight
Prefabs
Resources
Scenes
Scripts
Shaders
Textures
Contains scripts that add functionality to the Unity Editor, and enhance several C# component scripts.
Contains materials that are used for graphical components within the integration, such as the main GUI display.
Contains classes designed for mobile Gear VR development. Holds sub-folders with mobile equivalents of all top-level folders (Editor, Materials, Prefabs, et cetera).
Contains the main Unity prefabs that are used to provide the VR support for a Unity scene: OVRCameraRig and OVRPlayerController.
Contains prefabs and other objects that are required and instantiated by some OVR scripts, such as the main GUI.
Contains sample scenes.
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.
Contains various Cg shaders required by some of the OVR components.
Contains image assets that are required by some of the script components.
Note: We strongly recommend that developers not directly modify the included OVR scripts.
Plugins
The Plugins folder contains vrapi.so and the OculusPlugin.dll, which enables the VR framework to communicate with Unity on Windows (both 32 and 64-bit versions).
This folder also contains the plugins for other platforms: OculusPlugin.bundle for MacOS; and Android/ libOculusPlugin.so, vrlib.jar, and AndroidManifest.xml for Android.
12 | A Detailed Look at the Unity Integration | Unity
Prefabs
The current integration for adding VR support into Unity applications is based on two prefabs that may be added into a scene:
• OVRCameraRig
• OVRPlayerController
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.
Note: Make sure to turn off any other Camera in the scene to ensure that OVRCameraRig is the only one being used.
Figure 1: Prefabs: OVRCameraRig, expanded in the inspector
OVRCameraRig contains two Unity cameras, one for each eye. It is meant to be attached to a moving object
(such as a character walking around, a car, a gun turret, etc.) 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.
Note: Make sure that collision detection is active in the environment.
Two scripts (components) are attached to the OVRPlayerController prefab:
• OVRPlayerController.cs
• OVRGamepadController.cs
Figure 2: Prefabs: OVRPlayerController, expanded in the inspector
Unity | A Detailed Look at the Unity Integration | 13
Unity Components
This section gives a general overview of the Components provided by the legacy integration.
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. This 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.
14 | A Detailed Look at the Unity Integration | Unity
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 there are public members that allow for changing certain values in the
Unity inspector.
OVRManager.cs contains the following public members:
Table 1: Mobile and PC 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.
Eye Texture Format
Eye Texture Depth
Sets the format of the eye RenderTextures. Normally you should use Default or
DefaultHDR for high-dynamic range rendering.
Sets the depth precision of the eye RenderTextures. May fix z-fighting artifacts at the expense of performance.
Eye Texture Antialiasing Sets the level of antialiasing for the eye RenderTextures.
Table 2: PC-Only Public Members
Native Texture Scale Each camera in the camera controller creates a RenderTexture that is the ideal size for obtaining the sharpest pixel density (a 1-to-1 pixel size in the center of the screen post lens distortion). This field can be used to permanently scale the cameras' render targets to any multiple ideal pixel fidelity, which gives you control over the trade-off between performance and quality.
Virtual Texture Scale
Use Position Tracking
This field can be used to dynamically scale the cameras render target to values lower then the ideal pixel fidelity, which can help reduce GPU usage at run-time if necessary.
Disables the IR tracker and causes head position to be inferred from the current rotation using the head model. To fully ignore tracking or otherwise modify tracking behavior, see OVRCameraRig.UpdatedAnchors above
Unity | A Detailed Look at the Unity Integration | 15
Mirror to Display
Time Warp (desktop only) Time warp is a technique that adjusts the on-screen position of rendered images based on the latest tracking pose at the time the user will see it. Enabling this will force vertical-sync and make other timing adjustments to minimize latency.
Freeze Time Warp
(desktop only)
Reset Tracker On Load
When enabled, the undistorted rendered output appears on your desktop in addition to the Rift. If disabled, you may add your own scripts next to OVRCameraRig and set that
GameObject's Camera component to render whatever you like. Disabling may slightly improve performance.
If enabled, this illustrates the effect of time warp by temporarily freezing the rendered eye pose.
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.
Helper Classes
In addition to the above components, your scripts can always access the HMD state via static members of
OVRManager.
OVRDisplay
OVRTracker
Provides the pose and rendering state of the HMD.
Provides the pose, frustum, and tracking status of the infrared tracking sensor.
OVRCommon
OVRCommon OVRCommon is a collection of reusable static functions.
Utilities
The following classes are optional. We provide them to help you make the most of virtual reality, depending on the needs of your application.
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
16 | A Detailed Look at the Unity Integration | Unity
OVRGamepadController OVRGamepadController is an interface class to a gamepad controller.
On Windows systems, the gamepad must be XInput-compliant.
Note: currently native XInput-compliant gamepads are not supported on Mac OS.
Please use the conventional Unity input methods for gamepad input.
OVRCrosshair direction on. This GameObject should also house the body geometry which will be seen by the player.
OVRGUI
OVRCrosshair is a helper class that renders and controls an on-screen cross-hair. It is currently used by the OVRMainMenu component.
OVRGUI is a helper class that encapsulates basic rendering of text in either 2D or 3D.
The 2D version of the code will be deprecated in favor of rendering to a 3D element
(currently used in OVRMainMenu).
OVRGridCube
OVRTrackerBounds
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.
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 more information on OVRInput, see
on page 18.
Oculus Mobile SDKExamples
The Mobile SDK includes sample applications to illustrate implementation of common functionality such as a first-person scene and crosshairs.
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.
Note: If you don't replace the ProjectSettings folder, imported scenes will show console errors.
You will find the following sample scenes located in Assets/Scenes:
Unity | A Detailed Look at the Unity Integration | 17
Cubes
Multicamera
Room
A 3D array of cubes and an OVRCameraRig.
An example of switching cameras in one scene.
A cubic room formed from six cubes enclosing an OVRPlayerController.
The example scripts are located in Assets/OVR/Moonlight/:
OVRChromaticAberration.csDrop-in component for toggling chromatic aberration correction on and off for Android.
OVRCrosshair.cs
A component that adds a stereoscopic crosshair to a scene.
OVRDebugGraph.cs
Drop-in component for toggling the TimeWarp debug graph, which is no longer available.
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.
Cross-platform wrapper for Unity Input.
OVRInputControl.cs
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
OVROverlay.cs
Drop-in component for toggling Monoscopic rendering on and off for Android.
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
.
OVRResetOrientation.cs
Drop-in component for resetting the camera orientation.
OVRTimeWarpUtils.cs
Demonstrates the interface calls for setting important configs, including min vsyncs, enable tw debug graph, and enable cac.
OVRTouchpad.cs
OVRVolumeControl.cs
OVRWaitCursor.cs
Interface class to a touchpad.
An on-screen display that shows the current system audio volume.
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.
18 | OVRInput | Unity
OVRInput
OVRInput exposes a unified input API for multiple controller types. It may be used to query virtual or raw controller state, such as buttons, thumbsticks, triggers, and capacitive touch data. It currently supports the Oculus Touch, Microsoft Xbox controllers, and the Oculus remote on desktop platforms. For mobile development, it supports the Gear VR Controller as well as the touchpad and back button on the Gear VR headset. Gear VR gamepads must be Android compatible and support Bluetooth 3.0.
For keyboard and mouse control, we recommend using the UnityEngine.Input scripting API (see Unity’s
Input scripting reference
for more information).
Mobile input bindings are automatically added to InputManager.asset if they do not already exist.
For more information, see OVRInput in the
Unity Scripting Reference
. For more information on Unity’s input system and Input Manager, documented here:
http://docs.unity3d.com/Manual/Input.html
and
http:// docs.unity3d.com/ScriptReference/Input.html
.
SetControllerVibration() support for Oculus Touch is now deprecated; please use
OVRHaptics for
Oculus Touch
instead.
Oculus Touch Tracking
OVRInput provides Touch position and orientation data through
GetLocalControllerPosition() and
GetLocalControllerRotation(), which return a Vector3 and Quaternion, respectively.
Controller poses are returned by the constellation tracking system and are predicted simultaneously with the headset. These poses are reported in the same coordinate frame as the headset, relative to the initial center eye pose, and may be used for rendering hands or objects in the 3D world. They are also reset by
OVRManager.display.RecenterPose(), similar to the head and eye poses.
Gear VR Controller
Gear VR Controller provides orientation data through
GetLocalControllerRotation(), which returns a quaternion.
Gear VR positions the controller relative to the user by using a body model to estimate the controller’s position.
Whether the controller is visualized on the left or right side of the body is determined by left-handedness versus right-handedness, which is specified by users during controller pairing.
To query handedness of a paired controller, use
IsControllerConnected() or GetActiveController() to query for
RTrackedRemote or LTrackedRemote.
For example:
// returns true if right-handed controller connected
OVRInput.IsControllerConnected(OVRInput.Controller.RTrackedRemote);
Use
OVRInput.Get() to query controller touchpad input. You may query the input position with Axis2D:
OVRInput.Get(OVRInput.Axis2D.PrimaryTouchpad, OVRInput.Controller.RTrackedRemote);
A touchpad touch occurs when the user’s finger makes contact with the touchpad without actively clicking it. Touches may be queried with
OVRInput.Get(OVRInput.Touch.PrimaryTouchpad).
Touchpad clicks are alias to virtual button One clicks, and may be queried with
OVRInput.Get(OVRInput.Button.PrimaryTouchpad).
To recenter a Gear VR Controller, use
OVRInput.RecenterController().
Unity | OVRInput | 19
The volume and home buttons are reserved.
OVRInput Usage
The primary usage of OVRInput is to access controller input state through
Get(), GetDown(), and GetUp().
•
Get() queries the current state of a control.
•
GetDown() queries if a control was pressed this frame.
•
GetUp() queries if a control was released this frame.
Gear VR Controller Swiping Gestures
For Gear VR Controllers, the user interface of your VR experience should follow these natural scrolling and swiping gestures:
• Swipe up: Pull content upward. Equivalent to scrolling down.
• Swipe down: Pull content downward. Equivalent to scrolling up.
• Swipe left: Pull content left or go to the next item or page.
• Swipe right: Pull content right or go to the previous item or page.
Control Input Enumerations
There are multiple variations of
Get() that provide access to different sets of controls. These sets of controls are exposed through enumerations defined by OVRInput as follows:
Control Enumerates
OVRInput.Button
Traditional buttons found on gamepads, Touch controllers, the
Gear VR Controller touchpad and back button, and the Gear VR headset touchpad and back button.
OVRInput.Touch
Capacitive-sensitive control surfaces found on the Oculus Touch and Gear VR Controller.
OVRInput.NearTouch
Proximity-sensitive control surfaces found on the Oculus Touch controllers.
OVRInput.Axis1D
One-dimensional controls such as triggers that report a floating point state.
OVRInput.Axis2D
Two-dimensional controls including thumbsticks and the Gear VR
Controller touchpad. Report a Vector2 state.
A secondary set of enumerations mirror the first, defined as follows:
OVRInput.RawButton
OVRInput.RawTouch
20 | OVRInput | Unity
OVRInput.RawNearTouch
OVRInput.RawAxis1D
OVRInput.RawAxis2D
The first set of enumerations provides a virtualized input mapping that is intended to assist developers with creating control schemes that work across different types of controllers. The second set of enumerations provides raw unmodified access to the underlying state of the controllers. We recommend using the first set of enumerations, since the virtual mapping provides useful functionality, as demonstrated below.
Button, Touch, and NearTouch
In addition to traditional gamepad buttons, the Oculus Touch controllers feature capacitive-sensitive control surfaces which detect when the user's fingers or thumbs make physical contact (a “touch”), as well as when they are in close proximity (a “near touch”). This allows for detecting several distinct states of a user’s interaction with a specific control surface. For example, if a user’s index finger is fully removed from a control surface, the
NearTouch for that control will report false. As the user’s finger approaches the control and gets within close proximity to it, the NearTouch will report true prior to the user making physical contact. When the user makes physical contact, the Touch for that control will report true. When the user pushes the index trigger down, the Button for that control will report true. These distinct states can be used to accurately detect the user’s interaction with the controller and enable a variety of control schemes.
The Gear VR Controller touchpad may be queried for both touch status and click status, where “touch” refers to the user’s finger making contact with the touchpad without actively clicking it.
Example Usage
// returns true if the primary button (typically “A”) is currently pressed.
OVRInput.Get(OVRInput.Button.One);
// returns true if the primary button (typically “A”) was pressed this frame.
OVRInput.GetDown(OVRInput.Button.One);
// returns true if the “X” button was released this frame.
OVRInput.GetUp(OVRInput.RawButton.X);
// returns a Vector2 of the primary (typically the Left) thumbstick’s current state.
// (X/Y range of -1.0f to 1.0f)
OVRInput.Get(OVRInput.Axis2D.PrimaryThumbstick);
// returns true if the primary thumbstick is currently pressed (clicked as a button)
OVRInput.Get(OVRInput.Button.PrimaryThumbstick);
// returns true if the primary thumbstick has been moved upwards more than halfway.
// (Up/Down/Left/Right - Interpret the thumbstick as a D-pad).
OVRInput.Get(OVRInput.Button.PrimaryThumbstickUp);
// returns a float of the secondary (typically the Right) index finger trigger’s current state.
// (range of 0.0f to 1.0f)
OVRInput.Get(OVRInput.Axis1D.SecondaryIndexTrigger);
// returns a float of the left index finger trigger’s current state.
// (range of 0.0f to 1.0f)
OVRInput.Get(OVRInput.RawAxis1D.LIndexTrigger);
// returns true if the left index finger trigger has been pressed more than halfway.
// (Interpret the trigger as a button).
OVRInput.Get(OVRInput.RawButton.LIndexTrigger);
// returns true if the secondary gamepad button, typically “B”, is currently touched by the user.
OVRInput.Get(OVRInput.Touch.Two);
// returns true after a Gear VR touchpad tap
OVRInput.GetDown(OVRInput.Button.One);
Unity | OVRInput | 21
// returns true on the frame when a user’s finger pulled off Gear VR touchpad controller on a swipe
down
OVRInput.GetDown(OVRInput.Button.DpadDown);
// returns true the frame AFTER user’s finger pulled off Gear VR touchpad controller on a swipe right
OVRInput.GetUp(OVRInput.RawButton.DpadRight);
// returns true if the Gear VR back button is pressed
OVRInput.Get(OVRInput.Button.Two);
// Returns true if the the Gear VR Controller trigger is pressed down
OVRInput.Get(OVRInput.Button.PrimaryIndexTrigger);
// Queries active Gear VR Controller touchpad click position
// (normalized to a -1.0, 1.0 range, where -1.0, -1.0 is the lower-left corner)
OVRInput.Get(OVRInput.Axis2D.PrimaryTouchpad, OVRInput.Controller.RTrackedRemote);
// If no controller is specified, queries the touchpad position of the active Gear VR Controller
OVRInput.Get(OVRInput.Axis2D.PrimaryTouchpad);
// returns true if the Gear VR Controller back button is pressed
OVRInput.Get(OVRInput.Button.Back);
// recenters the active Gear VR Controller. Has no effect for other controller types.
OVRInput.RecenterController();
// recenters right Gear VR Controller (even if it is not active)
OVRInput.RecenterController(Controller.RTrackedRemote);
// returns true on the frame when a user’s finger pulled off Gear VR Controller back button
OVRInput.GetDown(OVRInput.Button.Back);
In addition to specifying a control,
Get() also takes an optional controller parameter. The list of supported controllers is defined by the OVRInput.Controller enumeration (for details, refer to OVRInput in the
Unity
Scripting Reference
.
Specifying a controller can be used if a particular control scheme is intended only for a certain controller type.
If no controller parameter is provided to
Get(), the default is to use the Active controller, which corresponds to the controller that most recently reported user input. For example, a user may use a pair of Oculus Touch controllers, set them down, and pick up an Xbox controller, in which case the Active controller will switch to the Xbox controller once the user provides input with it. The current Active controller can be queried with
OVRInput.GetActiveController() and a bitmask of all the connected Controllers can be queried with
OVRInput.GetConnectedControllers().
Example Usage:
// returns true if the Xbox controller’s D-pad is pressed up.
OVRInput.Get(OVRInput.Button.DpadUp, OVRInput.Controller.Gamepad);
// returns a float of the Hand Trigger’s current state on the Left Oculus Touch controller.
OVRInput.Get(OVRInput.Axis1D.PrimaryHandTrigger, OVRInput.Controller.Touch);
// returns a float of the Hand Trigger’s current state on the Right Oculus Touch controller.
OVRInput.Get(OVRInput.Axis1D.SecondaryHandTrigger, OVRInput.Controller.Touch);
Querying the controller type can also be useful for distinguishing between equivalent buttons on different controllers. For example, if you want code to execute on input from a gamepad or Touch controller, but not on a Gear VR Touchpad, you could implement it as follows: if (OVRInput.GetActiveController() != OVRInput.Controller.Touchpad) { /* do input handling */ }
Note that the Oculus Touch controllers may be specified either as the combined pair (with
OVRInput.Controller.Touch), or individually (with OVRInput.Controller.LTouch and RTouch). This is significant because specifying LTouch or RTouch uses a different set of virtual input mappings that allow more convenient development of hand-agnostic input code. See the virtual mapping diagrams in
Touch Input
Mapping
for an illustration.
22 | OVRInput | Unity
Example Usage:
// returns a float of the Hand Trigger’s current state on the Left Oculus Touch controller.
OVRInput.Get(OVRInput.Axis1D.PrimaryHandTrigger, OVRInput.Controller.LTouch);
// returns a float of the Hand Trigger’s current state on the Right Oculus Touch controller.
OVRInput.Get(OVRInput.Axis1D.PrimaryHandTrigger, OVRInput.Controller.RTouch);
This can be taken a step further to allow the same code to be used for either hand by specifying the controller in a variable that is set externally, such as on a public variable in the Unity Editor.
Example Usage:
// public variable that can be set to LTouch or RTouch in the Unity Inspector public Controller controller;
…
// returns a float of the Hand Trigger’s current state on the Oculus Touch controller
// specified by the controller variable.
OVRInput.Get(OVRInput.Axis1D.PrimaryHandTrigger, controller);
// returns true if the primary button (“A” or “X”) is pressed on the Oculus Touch controller
// specified by the controller variable.
OVRInput.Get(OVRInput.Button.One, controller);
This is convenient since it avoids the common pattern of if/else checks for Left/Right hand input mappings.
Touch Input Mapping
The following diagrams illustrate common input mappings for Oculus Touch controllers. For more information on additional mappings that are available, refer to OVRInput in the
Unity Scripting Reference
.
Virtual Mapping (Accessed as a Combined Controller)
When accessing the Touch controllers as a combined pair with OVRInput.Controller.Touch, the virtual mapping closely matches the layout of a typical gamepad split across the Left and Right hands.
Unity | OVRInput | 23
Virtual Mapping (Accessed as Individual Controllers)
When accessing the Left or Right Touch controllers individually with OVRInput.Controller.LTouch or
OVRInput.Controller.RTouch, the virtual mapping changes to allow for hand-agnostic input bindings. For example, the same script can dynamically query the Left or Right Touch controller depending on which hand it is attached to, and Button.One will be mapped appropriately to either the A or X button.
Raw Mapping
The raw mapping directly exposes the Touch controllers. The layout of the Touch controllers closely matches the layout of a typical gamepad split across the Left and Right hands.
24 | OVRInput | Unity
Rift Remote Input Mapping
Virtual Mapping
Raw Mapping
Xbox Input Handling
Virtual Mapping
This diagram shows a common implementation of Xbox controller input bindings using
OVRInput.Controller.Gamepad.
Raw Mapping
The raw mapping directly exposes the Xbox controller.
Unity | OVRInput | 25
26 | Configuring for Build | Unity
Configuring for Build
This section describes building your project to PC and mobile targets.
PC Build Target: Microsoft Windows and Mac OS X
This section describes targeting Unity project builds to Microsoft Windows and Mac OS X.
Build Settings and Player Settings
To build the demo as a standalone full screen application, you will need to change a few project settings to maximize the fidelity of the demo.
Click on File > Build Settings... and select one of the following:
For Windows, set Target Platform to Windows and set Architecture to either x86 or x86 64.
Figure 3: Build Settings: PC
For Mac, set Target Platform to Mac OS X.
Figure 4: Build Settings: Mac
Unity | Configuring for Build | 27
Within the Build Settings pop-up, click Player Settings. Under Resolution and Presentation, set the values to the following:
Figure 5: Player Settings
In the Build Settings pop-up, select Build. If prompted, specify a name and location for the build.
28 | Configuring for Build | Unity
If you are building in the same OS, the demo should start to run in full screen mode as a standalone application.
Quality Settings
You may notice that the graphical fidelity is not as high as the pre-built demo. You will need to change some additional project settings to get a better looking scene.
Navigate to Edit > Project Settings > Quality. Set the values in this menu to the following:
Figure 6: Quality settings for Oculus demo
The most important value to modify is Anti aliasing - it must be increased to compensate for the stereo rendering, which reduces the effective horizontal resolution by 50%. An anti-aliasing value of 2X is ideal - 4x may be used if you have performance to spare, and 8x usually isn't worth it.
Note: A quality setting called Fastest has been added to address a potential performance issue with Unity 4.5 and OS X 10.9. This setting turns off effects and features that may cause the drop in performance.
Now rebuild the project again, and the quality should be at the same level as the pre-built demo.
Running the Build
Now that the project is properly configured for VR, it’s time to install and run the application.
PC builds create a single executable file that may be used in either Direct Display or Extended Display modes.
Unity | Configuring for Build | 29
Mobile Build Target: Android
This section describes targeting Unity project builds to Android.
Build Settings
1. From the File menu, select Build Settings…. From the Build Settings… menu, select Android as the platform. Set Texture Compression to ETC2 (GLES 3.0).
2. Add any scenes you wish to include in your build to Scenes In Build..
Player Settings
1. Click the Player Settings… button and select the Android tab. Set Default Orientation to Landscape Left in
Settings for Android (may be collapsed).
Note: The Use 24-bit Depth Buffer option appears to be ignored for Android. A 24-bit window depth buffer always appears to be created.
2. As a minor optimization, 16 bit buffers, color and/or depth may be used. Most VR scenes should be built to work with 16 bit depth buffer resolution and 2x MSAA. If your world is mostly pre-lit to compressed textures, there will be little difference between 16 and 32 bit color buffers.
3. Select the Splash Image section. For Mobile Splash image, choose a solid black texture.
30 | Configuring for Build | Unity
Note: Custom Splash Screen support is not available with Unity Free. A head-tracked Unity logo screen is provided instead.
4. While still in Player Settings, select Other Settings and verify that Rendering Path* is set to Forward,
Multithreaded Rendering* is selected, and Install Location is set to Force Internal, as shown below:
5. Set the Stripping Level to the maximum level your app allows. It will reduce the size of the installed .apk file.
Note: This feature is not available for Unity Free.
Checking Optimize Mesh Data may improve rendering performance if there are unused components in your mesh data.
Quality Settings
1. Go to the Edit menu and choose Project Settings, then Quality. In the Inspector, set Vsync Count to Don’t
Sync. The TimeWarp rendering performed by the Oculus Mobile SDK already synchronizes with the display refresh.
Unity | Configuring for Build | 31
Note: Anti Aliasing should not be enabled for the main framebuffer.
2. Anti Aliasing should be set to Disabled. You may change the camera render texture antiAliasing by modifying the
Eye Texture Antialiasing parameter on OVRManager. The current default is 2x MSAA.
Be mindful of the performance implications. 2x MSAA runs at full speed on chip, but may still increase the number of tiles for mobile GPUs which use variable bin sizes, so there is some performance cost. 4x MSAA runs at half speed, and is generally not fast enough unless the scene is very undemanding.
3. Pixel Light Count is another attribute which may significantly impact rendering performance. A model is rerendered for each pixel light that affects it. For best performance, set Pixel Light Count to zero. In this case, vertex lighting will be used for all models depending on the shader(s) used.
Time Settings
Note: The following Time Settings advice is for applications which hold a solid 60 FPS, updating all game and/or application logic with each frame. The following Time Settings recommendations may be detrimental for apps that don’t hold 60FPS.
Go to the Edit -> Project Settings -> Time and change both Fixed Timestep and Maximum Allowed
Timestep to “0.0166666” (i.e., 60 frames per second).
Fixed Timestep is the frame-rate-independent interval at which the physics simulation calculations are performed. In script, it is the interval at which
FixedUpdate() is called. The Maximum Allowed Timestep sets an upper bound on how long physics calculations may run.
32 | Configuring for Build | Unity
Android Manifest File
Note: These manifest requirements are intended for development and differ from our submission requirements. Before submitting your application, please be sure to follow the manifest requirements described by our
Application Submission Guidelines
.
Open the AndroidManifest.xml file located under Assets/Plugins/Android/. You will need to configure your manifest with the necessary VR settings, as shown in the following manifest segment:
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="<packagename>" android:versionCode="1" android:versionName="1.0" android:installLocation="internalOnly">
<application android:theme="@android:style/Theme.Black.NoTitleBar.Fullscreen" >
<meta-data android:name="com.samsung.android.vr.application.mode" android:value="vr_only"/>
<activity android:screenOrientation="landscape" android:launchMode="singleTask" android:configChanges="screenSize|orientation|keyboardHidden|keyboard">
</activity>
</application>
<uses-sdk android:minSdkVersion="19" android:targetSdkVersion="19" />
<uses-feature android:glEsVersion="0x00030000" />
• Replace
<packagename> in the first line with your actual package name, such as "com.oculus.cinema".
• Unity will overwrite the required setting android:installLocation="internalOnly" if the Player
Setting Install Location is not set to Force Internal.
• The Android theme should be set to the solid black theme for comfort during application transitioning:
Theme.Black.NoTitleBar.Fullscreen
• The vr_only meta data tag should be added for VR mode detection.
• The required screen orientation is landscape: android:screenOrientation="landscape"
• We recommended setting your configChanges as follows: android:configChanges="screenSize| orientation|keyboardHidden|keyboard"
• The minSdkVersion and targetSdkVersion are set to the API level supported by the device. For the current set of devices, the API level is 19.
•
Do not add the noHistory attribute to your manifest.
Running the Build
Now that the project is properly configured for VR, it’s time to install and run the application on the Android device.
Applications written for development are not launched through the Oculus Home menu system. Instead, build the application directly to your phone, and you will be prompted to insert your phone into the Gear VR headset to launch the application automatically.
To run the application in the future, remove your phone from the Gear VR headset, launch the application directly from the phone desktop or Apps folder, and insert the device into the Gear VR when prompted to do so.
Unity | Configuring for Build | 33
1. Copy an Oculus Signature File specific to your mobile device to the folder Project/Assets/Plugins/Android/ assets/ or the application will not run. See the
Application Signing
section of the Mobile SDK documentation for more information.
2. Be sure the project settings from the steps above are saved with File > Save Project.
3. If you are not already connected to your phone via USB, connect now. Unlock the phone lock screen.
4. From the File menu, select Build Settings…. While in the Build Settings menu, add the Main.scene to Scenes
in Build. Next, verify that Android is selected as your Target Platform and select Build and Run. If asked, specify a name and location for the .apk.
The .apk will be installed and launched on your Android device.
34 | Sample Unity Application Demos | Unity
Sample Unity Application Demos
This section describes the sample Unity applications provided by Oculus as a reference for development.
Running Pre-Built demos: PC
To run the pre-built demos, download the appropriate demo zip file for the platform you need.
• For Windows, download the *demo win.zip file.
• For Mac, download the *demo mac.zip file.
Run the OculusUnityDemoScene.exe (Windows) or OculusUnityDemoScene.app (Mac) pre-built demo. If prompted with a display resolution dialog, hit the Play button. The demo will launch in full-screen mode.
Note: If you using Direct Display mode, you will be able to see the stereo image on your 2D display as well.
Running Pre-Built demos: Mobile
To run the pre-built demos, you must first install the demo packages (.apk) and sample media to your Android device.
Connect to the device via USB and open a command prompt. Run the installToPhone.bat script included with the SDK. This script will copy and install both the Unity and Native sample applications as well as any sample media to your Android device. You should now see application icons for the newly-installed apps on the
Android Home screen.
For more information about these sample apps please review the Initial SDK Setup section in Device and
Environment Setup Guide.
To test a sample application, perform the following steps:
• From the Android Home screen, press the icon of the VR app you wish to run.
• A toast notification will appear with a dialog like the following: “Insert Device: To open this application, insert your device into your Gear VR”
• Insert your device into the supported Gear VR hardware.
The app should now launch.
Pre-Built Demo Controls
BlockSplosion (mobile only)
In BlockSplosion, the camera position does not change, but the user's head orientation will be tracked, allowing them to aim before launching a block.
Unity | Sample Unity Application Demos | 35
• 1-dot Button or Samsung gamepad tap launches a block in the facing direction.
• 2-dot Button resets the current level.
• Left Shoulder Button (L) skips to the next level.
Tuscany (PC only)
Gamepad Control
• If you have a compliant gamepad controller for your platform, you can control the movement of the player controller with it.
• The left analog stick moves the player around as if you were using the W,A,S,D keys.
• The right analog stick rotates the player left and right as if you were using the Q and E keys.
• The left trigger allows you move faster, or run through the scene.
• The Start button toggles the scene selection. Pressing D-Pad Up and D-Pad Down scrolls through available scenes. Pressing the A button starts the currently selected scene.
• If the scene selection is not turned on, Pressing the D-Pad Down resets the orientation of the tracker.
Mouse Control
Using the mouse will rotate the player left and right. If the cursor is enabled, the mouse will track the cursor and not rotate the player until the cursor is off screen.
Shadowgun
In Shadowgun, locomotion allows the camera position to change.
• Left Analog Stick will move the player forward, back, left, and right.
• Right Analog Stick will rotate the player view left, right, up, and down. However, you will likely want to rotate your view just by looking with the VR headset.
36 | Troubleshooting and Known Issues | Unity
Troubleshooting and Known Issues
This section outlines some currently known issues with the Oculus Unity Integration and the Oculus Utilities for
Unity.
Rift
The app does not launch as a VR app.
Verify that you have installed the Oculus App and completed setup as described in
Preparing for Rift
Development
.
Verify that you have selected Virtual Reality Supported in Player Settings.
are using a compatible runtime - see
Compatibility and Requirements
for more details.
Verify that the HMD is plugged in and working normally.
Verify that you have not selected D3D 9 or Windows GL as the renderer (Legacy Integration only).
Mobile
The app does not launch as a VR app.
Verify that you selected Virtual Reality Supported in Player Settings before building your APK.
Applications fail to launch on Gear VR with error message "thread priority security exception make sure the apk is signed”.
You must sign your application with an Oculus Signature File (osig). See "Sign your App with an Oculus
Signature File" in
Preparing for Mobile Development
for instructions.
General Issues
Unity 5 hangs while importing assets from SDKExamples.
Unity 5 is known to import ETC2-compressed assets very slowly.
Receiving OVRPlugin console errors after importing a new version of Utilities.
Be sure to delete any previously-imported Utilities packages from your Unity project before importing a new version. If you are receiving errors and have not done so, delete the relevant folders in your project and reimport Utilities. For more information, please see
Importing the Oculus Utilities Package
.
Contact Information
Questions?
Visit our developer support forums at
https://developer.oculus.com
.
Our Support Center can be accessed at
https://support.oculus.com
.
Unity | Debugging and Performance Analysis in Unity | 37
In this guide, we’ll review baseline targets, recommendations, tools, resources, and common workflows for performance analysis and bug squashing for Unity VR applications.
General Tips
VR application debugging is a matter of getting insight into how the application is structured and executed, gathering data to evaluate actual performance, evaluating it against expectation, then methodically isolating and eliminating problems.
When analyzing or debugging, it is crucial to proceed in a controlled way so that you know specifically what change results in a different outcome. Focus on bottlenecks first. Only compare apples to apples, and change one thing at a time (e.g., resolution, hardware, quality, configuration).
Always be sure to profile, as systems are full of surprises. We recommend starting with simple code, and optimizing as you go - don’t try to optimize too early.
We recommend creating a 2D, non-VR version of your camera rig so you can swap between VR and non-VR perspectives. This allows you to spot check your scenes, and it may be useful if you want to do profiling with third-party tools (e.g., Adreno Profiler).
It can be useful to disable Multithreaded Rendering in Player Settings during performance debugging. This will slow down the renderer, but also give you a clearer view of where your frame time is going. Be sure to turn it back on when you’re done!
Performance Targets
Before debugging performance problems, establish clear targets to use as a baseline for calibrating your performance.
These targets can give you a sense of where to aim, and what to look at if you’re not making frame rate or are having performance problems.
Below you will find some general guidelines for establishing your baselines, given as approximate ranges unless otherwise noted.
Mobile
• 60 FPS (required by Oculus)
• 50-100 draw calls per frame
• 50,000-100,000 triangles or vertices per frame
PC
• 90 FPS (required by Oculus)
• 500-1,000 draw calls per frame
• 1-2 million triangles or vertices per frame
For more information, see:
•
PC SDK Developer Guide
38 | Debugging and Performance Analysis in Unity | Unity
•
Mobile VR Application Development
Unity Profiling Tools
This section details tools provided by Unity to help you diagnose application problems and bottlenecks.
Unity Profiler
Unity comes with a built-in profiler (see Unity’s
Profiler manual
). The Unity Profiler provides per-frame performance metrics, which can be used to help identify bottlenecks.
Unity Pro comes with a built-in profiler. The profiler provides per-frame performance metrics, which can be used to help identify bottlenecks.
PC Setup
To use Unity Profiler with a Rift application, select Development Build and Autoconnect Profiler in Build
Settings and build your application. When you launch your application, the Profiler will automatically open.
Mobile Setup
You may profile your application as it is running on your Android device using adb or Wi-Fi. For steps on how to set up remote profiling for your device, please refer to the Android section of the following Unity documentation:
https://docs.unity3d.com/Documentation/Manual/Profiler.html
.
The Unity Profiler displays CPU utilization for the following categories: Rendering, Scripts, Physics,
GarbageCollector, and Vsync. It also provides detailed information regarding Rendering Statistics, Memory
Usage (including a breakdown of per-object type memory usage), Audio and Physics Simulation statistics.
GPU Usage data for Android is not available at this time.
The Unity profiler only displays performance metrics for your application. If your app isn’t performing as expected, you may need to gather information on what the entire system is doing.
Show Rendering Statistics
Unity provides an option to display real-time rendering statistics, such as FPS, Draw Calls, Tri and Vert Counts,
VRAM usage. While in the Game View, pressing the Stats button above the Game View will display an overlay
Unity | Debugging and Performance Analysis in Unity | 39
showing realtime render statistics.Viewing stats in the Editor can help analyze and improve batching for your scene by indicating how many draw calls are being issued and how many are being saved by batching (the
OverDraw render mode is helpful for this as well).
Show GPU Overdraw
Unity provides a specific render mode for viewing overdraw in a scene. From the Scene View Control Bar, select
OverDraw in the drop-down Render Mode selection box.
In this mode, translucent colors will accumulate providing an overdraw “heat map” where more saturated colors represent areas with the most overdraw.
Unity Built-in Profiler
Unity Built-in Profiler (not to be confused with Unity Profiler) provides frame rate statistics through logcat, including the number of draw calls, min/max frametime, number of tris and verts, et cetera.
40 | Debugging and Performance Analysis in Unity | Unity
To use this profiler, connect to your device over Wi-Fi using ADB over TCPIP as described in the
Wireless usage
section of Android’s adb documentation. Then run adb logcat while the device is docked in the headset.
See
Unity’s Measuring Performance with the Built-in Profiler
for more information. For more on using adb and logcat, see
Android Debugging
in the Mobile SDK documentation.
Oculus Performance Heads-Up Display (HUD) for the
Rift
Oculus Performance Head-Up Display (HUD)
The Oculus Performance Head-Up Display (HUD) is an important, easy-to-use tool for viewing timings for render, latency, and performance headroom in real-time as you run an application in the Oculus Rift. The
HUD is easily accessible through the Oculus Debug Tool provided with the PC SDK. For more details, see the
Performance Head-Up Display
and
Oculus Debug Tool
sections of the Oculus Rift Developers Guide.
Compositor Mirror
The compositor mirror is an experimental tool for viewing exactly what appears in the headset, with
Asynchronous TimeWarp and distortion applied.
The compositor mirror is useful for development and troubleshooting without having to wear the headset.
Everything that appears in the headset will appear, including Oculus Home, Guardian boundaries, ingame notifications, and transition fades. The compositor mirror is compatible with any game or experience, regardless of whether it was developed using the native PC SDK or a game engine.
For more details, see the
Compositor Mirror
section of the PC SDK Guide.
Oculus Remote Monitor for Gear VR
Oculus Remote Monitor is a client for Windows and Mac OS X that connects to VR applications running on remote devices to capture, store, and display the streamed-in data. It provides visibility into Android VR and
GLES activity, and includes low-res rendered image snapshots for a visual reference to its timeline-based display. Remote Monitor is available for download from our Downloads page.
Unity | Debugging and Performance Analysis in Unity | 41
The Remote Monitor client uses VrCapture, a low-overhead remote monitoring library. VrCapture is designed to help debug behavior and performance issues in mobile VR applications. VrCapture is included automatically in any project built with Unity 5, or compiled with the Legacy Integration.
For more information on setup, configuration, and usage, please see
VrCapture and Oculus Remote Monitor
.
Additional Third-Party Tools
ETW + GPUView
Event Tracing for Windows
(ETW) is a trace utility provided by Windows for performance analysis.
GPUView
view provides a window into both GPU and CPU performance with DirectX applications. It is precise, has low overhead, and covers the whole Windows system. Custom event manifests.
ETW profiles the whole system, not just the GPU. For a sample debug workflow using ETW to investigate queuing and system-level contention, see Example Workflow: PC below.
Windows 10 replaces ETW with
Tracelogging
.
Systrace
Reports complete Android system utilization. Available here:
http://developer.android.com/tools/help/ systrace.html
NVIDIA NSight
NSight is a CPU/GPU debug tool for NVIDIA users, available in a
Visual Studio version
and an
Eclipse version
.
Mac OpenGL Monitor
42 | Debugging and Performance Analysis in Unity | Unity
An OpenGL debugging and optimizing tool for OS X. Available here:
https://developer.apple.com/library/mac/ technotes/tn2178/_index.html#//apple_ref/doc/uid/DTS40007990
APITrace
https://apitrace.github.io/
Analyzing Slowdown
In this guide, we take a look at three of the areas commonly involved with slow application performance: pixel fill, draw call overhead, and slow script execution.
Pixel Fill
Pixel fill is a function of overdraw and of fragment shader complexity. Unity shaders are often implemented as multiple passes (draw diffuse part, draw specular part, and so forth). This can cause the same pixel to be touched multiple times. Transparency does this as well. Your goal is to touch almost all pixels on the screen only one time per frame.
Unity's Frame Debugger (described in
Unity Profiling Tools
) is very useful for getting a sense of how your scene is drawn. Watch out for large sections of the screen that are drawn and then covered, or for objects that are drawn multiple times (e.g., because they are touched by multiple lights).
Z-testing is faster than drawing a pixel. Unity does culling and opaque sorting via bounding box. Therefore, large background objects (like your Skybox or ground plane) may end up being drawn first (because the bounding box is large) and filling a lot of pixels that will not be visible. If you see this happen, you can move those objects to the end of the queue manually. See
Material.renderQueue
in Unity's Scripting API Reference for more information.
Frame Debugger will clearly show you shadows, offscreen render targets, et cetera.
Draw Calls
Modern PC hardware can push a lot of draw calls at 90 fps, but the overhead of each call is still high enough that you should try to reduce them. On mobile, draw call optimization is your primary scene optimization.
Draw call optimization is usually about batching multiple meshes together into a single VBO with the same material. This is key in Unity because the state change related to selecting a new VBO is relatively slow. If you select a single VBO and then draw different meshes out of it with multiple draw calls, only the first draw call is slow.
Unity batches well when given properly formatted source data. Generally:
• Batching is only possible for objects that share the same material pointer.
• Batching doesn't work on objects that have multiple materials.
• Implicit state changes (e.g. lightmap index) can cause batching to end early.
Here is a quick checklist for maximizing batching:
• Use as few textures in the scene as possible. Fewer textures require fewer unique materials, so they are easier to batch. Use texture atlases.
• Bake lightmaps at the largest atlas size possible. Fewer lightmaps require fewer material state changes. Gear
VR can push 4096 lightmaps without too much trouble, but watch your memory footprint.
• Be careful not to accidentally instance materials. Note that accessing
Renderer.material automatically creates an instance (!) and opts that object of batching. Use
Renderer.sharedMaterial instead whenever possible.
Unity | Debugging and Performance Analysis in Unity | 43
• Watch out for multi-pass shaders. Add noforwardadd to your shaders whenever you can to prevent more than one directional from applying. Multiple directionals generally break batching.
• Mark all mesh that never moves as
Static in the editor. Note that this will cause the mesh to be combined into a mega mesh at build time, which can increase load time and app size on disk, though usually not in a material way. You can also create a static batch at runtime (e.g., after generating a procedural level out of static parts) using StaticBatchingUtility.
• Watch your static and dynamic batch count vs the total draw call count using the Profiler, internal profiler log, or stats gizmo.
Script Performance
Unity's C# implementation is fast, and slowdown from script is usually the result of a mistake and/or an inadvertent block on slow external operations such as memory allocation. The Unity Profiler can help you find and fix these scripts.
Try to avoid foreach, lamda, and LINQ structures as these allocate memory needlessly at runtime. Use a for loop instead. Also, be wary of loops that concatenate strings.
Game Object creation and destruction takes time. If you have a lot of objects to create and destroy (say, several hundred in a frame), we recommend pooling them.
Don't move colliders unless they have a rigidbody on them. Creating a rigidbody and setting isKinematic will stop physics from doing anything but will make that collider cheap to move. This is because Unity maintains two collider structures, a static tree and a dynamic tree, and the static tree has to be completely rebuilt every time any static object moves.
Note that coroutines execute in the main thread, and you can have multiple instances of the same coroutine running on the same script.
We recommend targeting around 1-2 ms maximum for all Mono execution time.
PC Debug Workflow
In this guide, we’ll use the example of a hypothetical stuttering app scene and walk through basic steps debugging steps.
Where to Start
Begin by running the scene with the
Oculus Performance HUD
.
If the scene drops more than one frame every five seconds, check the render time. If it’s more than 8 ms, have a look at GPU utilization. Otherwise, look at optimizing CPU utilization. If observed latency is greater than 30 ms, have a look at queuing.
CPU Profiling (Unity Profiler)
Look for the tallest bars in the CPU Usage graph in the Unity Profiler. Sort hierarchy by Total CPU time, and expand to see which objects and calls take the most time.
If you find garbage collection spikes, don’t allocate memory each frame.
GPU Profiling (Unity Profiler)
Are your rendering stats too high? (For reference baselines, see
Performance Targets
.
44 | Debugging and Performance Analysis in Unity | Unity
Check for hogs in your hierarchy or timeline view, such as any single object that takes 8 ms to render. The GPU may also wait for long stalls on CPU. Other potential problem areas are mesh rendering, shadows, vsync, and subsystems.
Unity | Best Practices: Mobile | 45
Best Practices: Mobile
This section provides simple guidelines to help your Unity app perform well with Samsung Gear VR.
Good performance is critical for all VR applications, but the limitations inherent to mobile development warrant special consideration.
We recommend that you also review Design Guidelines and Mobile VR Design and Performance Guidelines in the
Mobile SDK documentation
.
Design Considerations
Startup Sequence
For good VR experiences, all graphics should be rendered such that the user is always viewing a proper threedimensional stereoscopic image. Additionally, head-tracking must be maintained at all times.
An example of how to do this during application startup is demonstrated in the SDKExamples Startup_Sample scene:
• Solid black splash image is shown for the minimum time possible.
• A small test scene with 3D logo and 3D rotating widget or progress meter is immediately loaded.
• While the small startup scene is active, the main scene is loaded in the background.
• Once the main scene is fully loaded, the start scene transitions to the main scene using a fade.
Universal Menu Handling
Applications must handle the Back Key long-press action which launches the Universal Menu as well as the Back
Key short-press action which launches the “Confirm-Quit to Home” Menu and exits the current application, returning to the Oculus Home application.
An example of demonstrating this functionality is in the SDKExamples GlobalMenu_Sample scene. For more information about application menu options and access, see
Universal Menu
in the Mobile SDK documentation.
Best Practices
• Be
Batch Friendly. Share materials and use a texture atlas when possible.
• Prefer lightmapped, static geometry.
•
Prefer lightprobes instead of dynamic lighting for characters and moving objects.
•
Bake as much detail into the textures as possible. E.g., specular reflections, ambient occlusion.
•
Only render one view per eye. No shadow buffers, reflections, multi-camera setups, et cetera.
•
Keep the number of rendering passes to a minimum. No dynamic lighting, no post effects, don't resolve buffers, don’t use grabpass in a shader, et cetera.
•
Avoid alpha tested / pixel discard transparency. Alpha-testing incurs a high performance overhead.
Replace with alpha-blended if possible.
• Keep alpha blended transparency to a minimum.
•
Use Texture Compression. Favor ETC2.
46 | Best Practices: Mobile | Unity
•
MSAA may be enabled on the Eye Render Textures.
General CPU Optimizations
To create a VR application or game that performs well, careful consideration must be given to how features are implemented. It must run at 60 FPS. Avoid any hitching or laggy performance during any point that the player is in your game.
Recommendations
• Be mindful of the total number of GameObjects and components your scenes use.
• Model your game data and objects efficiently. You will generally have plenty of memory.
• Minimize the number of objects that actually perform calculations in
Update() or FixedUpdate().
• Reduce or eliminate physics simulations when they are not actually needed.
• Use object pools to respawn frequently-used effects or objects instead of allocating new ones at runtime.
• Use pooled AudioSources versus PlayOneShot sounds, as the latter allocate a GameObject and destroy it when the sound is done playing.
• Avoid expensive mathematical operations whenever possible.
• Cache frequently-used components and transforms to avoid lookups each frame.
• Use the Unity Profiler to:
• Identify expensive code and optimize as needed.
• Identify and eliminate Garbage Collection allocations that occur each frame.
• Identify and eliminate any spikes in performance during normal play.
• Do not use Unity’s
OnGUI() calls.
• Do not enable gyro or the accelerometer. In current versions of Unity, these features trigger calls to expensive display calls.
• All best practices for mobile app and game development generally apply.
Rendering Optimization
Be conservative on performance from the start.
• Keep draw calls down.
• Be mindful of texture usage and bandwidth.
• Keep geometric complexity to a minimum.
• Be mindful of fillrate.
Reducing Draw Calls
Keep the total number of draw calls to a minimum. A conservative target would be less than
100 draw calls per frame.
Unity provides several built-in features to help reduce draw calls such as batching and culling.
Unity | Best Practices: Mobile | 47
Draw Call Batching
Unity attempts to combine objects at runtime and draw them in a single draw call. This helps reduce overhead on the CPU. There are two types of draw call batching: Static and Dynamic.
Static batching is used for objects that will not move, rotate or scale, and must be set explicitly per object. To mark an object static, select the Static checkbox in the object Inspector.
Note: Static batching is not available for Unity Free.
Dynamic batching is used for moving objects and is applied automatically when objects meet certain criteria, such as sharing the same material, not using real-time shadows, or not using multipass shaders. More information on dynamic batching criteria may be found here:
https://docs.unity3d.com/Documentation/Manual/
DrawCallBatching.html
Culling
Unity offers the ability to set manual per-layer culling distances on the camera via Per-Layer Cull Distance.
This may be useful for culling small objects that do not contribute to the scene when viewed from a given distance. More information about how to set up culling distances may be found here:
https://docs.unity3d.com/
Documentation/ScriptReference/Camera-layerCullDistances.html
.
Unity also has an integrated Occlusion Culling system. The advice to early VR titles is to favor modest “scenes” instead of “open worlds,” and Occlusion Culling may be overkill for modest scenes. More information about the Occlusion Culling system can be found here:
http://blogs.unity3d.com/2013/12/02/occlusion-culling-inunity-integration-4-3-the-basics/
.
Reducing Memory Bandwidth
•
Texture Compression: Texture compression offers a significant performance benefit. Favor ETC2 compressed texture formats.
•
Texture Mipmaps: Always use mipmaps for in-game textures. Fortunately, Unity automatically generates mipmaps for textures on import. To see the available mipmapping options, switch Texture Type to
Advanced in the texture inspector.
•
Texture Filtering: Trilinear filtering is often a good idea for VR. It does have a performance cost, but it is worth it. Anisotropic filtering may be used as well, but keep it to a single anisotropic texture lookup per fragment.
•
Texture Sizes: Favor texture detail over geometric detail, e.g., use high-resolution textures over more triangles. We have a lot of texture memory, and it is pretty much free from a performance standpoint. That said, textures from the Asset Store often come at resolutions which are wasteful for mobile. You can often reduce the size of these textures with no appreciable difference.
•
Framebuffer Format: Most scenes should be built to work with a 16 bit depth buffer resolution.
Additionally, if your world is mostly pre-lit to compressed textures, a 16 bit color buffer may be used.
•
Screen Resolution: Setting Screen.Resolution to a lower resolution may provide a sizeable speedup for most Unity apps.
Reduce Geometric Complexity
Keep geometric complexity to a minimum. 50,000 static triangles per-eye per-view is a conservative target.
Verify model vert counts are mobile-friendly. Typically, assets from the Asset Store are high-fidelity and will need tuning for mobile.
48 | Best Practices: Mobile | Unity
Unity Pro provides a built-in
Level of Detail System (not available in Unity Free), allowing lower-resolution meshes to be displayed when an object is viewed from a certain distance. For more information on how to set up a LODGroup for a model, see the following:
https://docs.unity3d.com/Documentation/Manual/
LevelOfDetail.html
Verify your vertex shaders are mobile friendly. And, when using built-in shaders, favor the Mobile or Unlit version of the shader.
Bake as much detail into the textures as possible to reduce the computation per vertex, for example, baked bumpmapping as demonstrated in the Shadowgun project:
https://docs.unity3d.com/430/Documentation/
Manual/iphone-PracticalRenderingOptimizations.html
Be mindful of GameObject counts when constructing your scenes. The more GameObjects and Renderers in the scene, the more memory consumed and the longer it will take Unity to cull and render your scene.
Reduce Pixel Complexity and Overdraw
Pixel Complexity: Reduce per-pixel calculations by baking as much detail into the textures as possible. For example, bake specular highlights into the texture to avoid having to compute the highlight in the fragment shader.
Verify your fragment shaders are mobile friendly. And, when using built-in shaders, favor the Mobile or Unlit version of the shader.
Overdraw: Objects in the Unity opaque queue are rendered in front to back order using depth-testing to minimize overdraw. However, objects in the transparent queue are rendered in a back to front order without depth testing and are subject to overdraw.
Avoid overlapping alpha-blended geometry (e.g., dense particle effects) and full-screen post processing effects.
Unity | Tutorial: Build a Simple VR Unity Game | 49
Tutorial: Build a Simple VR Unity Game
This section describes the steps necessary to build, load, and run a simple Unity 3D application on the Oculus
Rift or Samsung Gear VR.
It is intended to serve as a basic introduction for developers who are new to VR development and to Unity.
Once the necessary tools are set up, this process should take a few hours to complete. By the end, you will have a working mobile application that you can play and demonstrate on your Oculus Rift or Gear VR device, to the amazement of your friends and loved ones.
We will build and modify the Unity game Roll-a-ball to add VR capability. The game is controllable by keyboard or by the Samsung EI-GP20 gamepad.
Requirements
• Oculus Rift or Gear VR with compatible Samsung phone
• Samsung EI-GP20 gamepad (required for Mobile; optional for Desktop)
• PC running Windows 7, 8 or 10, or a Mac running OS X 10
• Unity 4 (for version compatibility, see
Compatibility and Requirements
You will also need to refer to the relevant Oculus SDK documentation, available for download here:
https:// developer.oculus.com/documentation/
Installation and Preparation
1. Install the appropriate Oculus SDK and prepare for development.
Desktop: Download and install the Oculus PC SDK and Unity Integration from
Oculus PC SDK Downloads
.
Prepare for development as described in the Oculus Rift Getting Started Guide. By the time you have completed this process, you should be able to run the Demo Scene as described in that guide.
Mobile: Download and install the Oculus Mobile SDK from
Oculus Mobile SDK Downloads
. Prepare for development as described by the Device and Environment Setup Guide. By the time you have completed this process, you should be able to communicate with your Samsung phone via USB. To verify this, retrieve the device ID from your phone by connecting via USB and sending the command adb devices from a command prompt. If you are communicating successfully, the phone will return its device ID. You may wish to make a note of it - you will need it later to request a Oculus Signature File (see step four in
for more information).
2. Install Unity.
Check which version of the Unity editor you should download an install in our
Compatibility and Version
Requirements
, then download the appropriate version here:
http://docs.unity3d.com/Manual/index.html
.
Unity provides extensive documentation to introduce users to the environment. You may wish to begin by reviewing their documentation to gain a basic familiarity with core concepts such as the Editor,
GameObjects, prefabs, projects, and scenes.
3. Build the Unity Roll-a-ball application.
Unity provides a number of video tutorials that walk you through the process of creating a simple game. The first in the series provides instructions for creating the Roll-a-ball application, in which you use the keyboard or gamepad to control a ball that rolls around a game board and picks up floating token counters:
http:// unity3d.com/learn/tutorials/projects/roll-a-ball
50 | Tutorial: Build a Simple VR Unity Game | Unity
The development process is covered in eight short video tutorials which run from around five to fifteen minutes in length. Allow for a few hours to complete the procedure.
The final video in the series, "107. Publishing the game," describes building the Roll-a-ball game for play in a web browser. You may skip this lesson if you wish for the purposes of this exercise, as we will follow a different procedure for building a playable application (PC/Mac) or APK (Android).
Note: We refer to the assets, folders, and so forth by the names used in the Unity tutorial, so it is helpful to follow the names they use in their example.
4. Duplicate your Roll-a-ball project (optional).
Once you have completed building Roll-a-ball, you may wish to create a duplicate Roll-a-ball project specifically for VR development. It can be useful to retain a backup of the original unmodified Roll-a-ball project in case you make mistakes or wish to work with it later without the VR assets.
To duplicate the Roll-a-ball project, simply navigate in your OS to the Unity project folder containing your
Roll-a-ball project, copy the folder and all of its contents, and rename it. For this tutorial, we will use the project folder name Roll-a-ball-VR.
5. Launch the new project and prepare the game scene.
1. Launch Unity and select File > Open Project... and select the project folder location for Roll-a-ball-VR in order to launch the project.
2. In your Project tab, open Assets > _Scenes and select "MiniGame."
3. Press F2 and rename the scene "VRMiniGame."
4. Open the scene "VRMiniGame."
Modify Roll-a-ball for VR
1. Import the Oculus Unity Integration Package.
In Unity, select Assets > Import Package > Custom Package.... Navigate to the folder where you have installed the Oculus SDK.
PC SDK: open the OculusUnityIntegration folder, select OculusUnityIntegration.unitypackage, and click
Open.
Mobile SDK: open the UnityIntegration folder in VrUnity, select UnityIntegration.unityPackage, and click
Open.
This will open Unity's Import Package dialog box, which lists the assets included in the package. Leave all boxes checked and select Import.
For more information on the contents of the integration package, see
2. Replace Main Camera with OVRCameraRig.
We will replace the Roll-a-ball Main Camera with OVRCameraRig, an Oculus prefab VR camera included with our Unity Integration. OVRCameraRig renders two stereoscopic images of the game scene with the appropriate distortion.
Main Camera tracks the player ball, but we will modify our camera to overlook the game board from a fixed position, so the player may look around at whatever angle they choose.
Rather than deleting the Main Camera, simply deselect it to make it inactive in the scene. Select Main
Camera in your Hierarchy view and uncheck the check box at the top left of the Inspector view.
Unity | Tutorial: Build a Simple VR Unity Game | 51
Note: Only one camera may be active in a Unity scene at any given time.
In the Project view, open the OVR folder and select the Prefabs folder. Select OVRCameraRig and drag it into the Hierarchy view to instantiate it.
3. Elevate OVRCameraRig above the game board.
Select OVRCameraRig in the Hierarchy view and set the Position fields of the OVRCameraRig Transform to the following values: X = 0; Y = 10; Z = -15.
4. Rotate OVRCameraRig forward for a better view.
Set the Rotation field of the OVRCameraRig Transform to the following value: X = 35; Y = 0; Z = 0.
Enter Play mode by pressing the play button, and note that the Game view now shows the image rendered in two distorted and stereoscopic views as illustrated below. If you are using the PC SDK, you will see the
Health and Safety Warning appear over the game; press any key to continue past it.
Figure 7: Roll-a-ball VR in Unity Scene and Game Views
5. Save your scene and project before building your application.
6. Sign your application (Mobile Only).
To access your Samsung phone's VR capabilities, you will need to sign your application with an Oculus
Signature File (osig). If you recorded your device ID earlier, you may use it now to request your osig file.
Note that you need only one osig per mobile device.
52 | Tutorial: Build a Simple VR Unity Game | Unity
You may obtain an osig from our self-service portal here:
https://dashboard.oculus.com/tools/osiggenerator/
. Once you have received an osig, copy it to your Unity project folder in /Roll-a-ball-VR/Assets/
Plugins/Android/assets/.
More information may be found on application signing in
Application Signing
in our Mobile guide.
Build and Play
Build and Launch
If you are developing for desktop, you will build an executable file that you may launch with your PC or Mac. If you are developing for mobile, you will build an APK and load it onto your phone, and then insert the phone into the Gear VR to launch your game. Follow the build instructions as described by the section
section.
Play
Go ahead and try it out! You may use your keyboard or a paired Samsung gamepad to control your ball and collect the game pickup objects.
Note: Because the GUIText display we built in the Roll-a-ball tutorial will not work with OVRCameraRig without substantial modification, you will not see the score counter or "You win!" message when all the pieces have been collected.
Launching the Game on Gear VR
If you select Apps from the Samsung home screen, you will see Roll-a-ball-VR listed with the other apps. You may launch the application directly, and when instructed, put the phone in the Gear VR. It will not be visible from Oculus Home.
Unity | Getting Started FAQ | 53
Getting Started FAQ
If you’re new to Oculus development with Unity, this FAQ can answer the most common beginner questions.
Question: What’s the best way to get started if you’re a beginner?
Answer: Browse through this FAQ, and check out our
Getting Started Guide
. Read through Unity’s excellent
documentation
and try out some of their introductory
tutorials
to get acquainted with Unity development.
When you're ready to get into the trenches, find out what the version of Unity 5 we recommend at our
Compatibility and Requirements
page, then download and install it. Next, build your own simple VR game by following the instructions in our
Tutorial: Build Your First VR App
.
You can also browse around on our
Unity Developer Forum
.
Question: What are the system requirements for Unity development for Oculus? What operating systems are supported for Unity development?
Answer: For the most up-to-date information, see
Unity Compatibility and Requirements
. We currently support
Windows and OS X for development. The Oculus Rift requires Windows 7, 8 or 10.
Question: What version of Unity should I use?
Answer: Our latest version recommendations may be found in our
Unity Compatibility and Requirements
document. Be sure to check back regularly, as we update it frequently as new SDKs and Unity versions are released. You can find an archive of information in our
Unity-SDK Version Compatibility
list.
Question: What other tools and resources do you provide to Unity developers?
Answer: To find the latest tools we provide, check out our
Other Oculus Resources for Unity Developers
.
Question: What do I need to run Rift applications that I build with Unity?
Answer: You will need a compatible Windows PC, a Rift, and the Oculus software. For more details, see
Preparing for Rift Development
Question: I want to focus on mobile development for the Samsung Gear VR. What do I need to do to get started? Do I need to download the Oculus Mobile SDK?
Answer: The Android SDK is required for mobile development with Unity. However, most Unity developers do not need to download the Oculus Mobile SDK, or to install Android Studio or NDK. For more details, see
Preparing for Mobile Development
.
Question: Can I develop a single application for both Samsung Gear VR and the Oculus Rift?
Answer: Yes, but when developing for both Rift and mobile platforms, keep in mind that the requirements for
PC and mobile VR applications differ substantially. If you would like to generate builds for both PC and mobile from a single project, it is important to follow the more stringent mobile development best practices, as well as meeting the required 90 fps required by the Rift.
Question: What is the difference between the Oculus Unity 4 Legacy Integration and the Oculus Utilities for
Unity 5? How do the differences between Unity 4 and 5 affect development?
Answer: All developers should use Unity 5 and the optional Oculus Utilities package. The Unity 4 Integration is maintained for legacy purposes only.
In Unity 4, you must import our Legacy Integration for Unity 4 unitypackage and add the supplied VR camera and player controller to your application to add Rift or Gear VR support.
Question: Where can I ask questions or get help?
54 | Getting Started FAQ | Unity
Answer: Visit our developer support forums at
https://developer.oculus.com
. Our Support Center can be accessed at
https://support.oculus.com
.
Unity | Unity-SDK Version Compatibility | 55
Unity-SDK Version Compatibility
This reference describes the relationship between Unity versions, Oculus PC and Mobile SDKs, and Oculus
Unity Integration and Utilities packages.
Utilities for Unity 5.x Versions
We are currently supporting the 5.4, 5.5, and 5.6 branches of the Unity editor, which are all under active development. Our Utilities for Unity 5 package no longer supports Unity versions prior to 5.3.4p5.
The following table lists recommended Unity versions and Oculus support they provide with their bundled version of OVRPlugin. Any Unity version may be updated to a later version of Oculus support by importing the
Utilities package. For more information, see
OVRPlugin
.
11/28/2016
11/28/2016
11/28/2016
11/1/2016
11/1/2016
9/15/2016
9/15/2016
8/18/2016
8/18/2016
7/28/2016
7/28/2016
6/30/2016
6/30/2016
Release Date
4/8/2017
4/25/2017
4/27/2017
3/30/2017
3/30/2017
3/30/2017
3/10/2017
3/10/2017
3/10/2017
2/1/2017
2/8/2017
2/1/2017
OVRPlugin / Utilities PC SDK
1.13.0
1.13.0
1.12.0
1.13.0
1.13.0
1.13.0
1.12.0
1.12.0
1.12.0
1.13.1
1.13.1
1.12.0
1.12.0
1.12.0
1.12.0
1.12.0
1.12.0
1.12.0
1.11.0
1.11.0
1.11.0
1.10.0
1.10.0
1.10.0
1.9.0
1.9.0
1.8.0
1.8.0
1.7.0
1.7.0
1.6.0
1.6.0
1.5.0
1.5.0
1.11.0
1.11.0
1.11.0
1.10.0
1.10.0
1.10.0
1.9.0
1.9.0
1.8.0
1.8.0
1.7.0
1.7.0
1.5.0
1.6.0
1.5.0
1.5.0
Mobile SDK
1.5.0
1.5.0
1.0.4.5
1.0.4.5
1.0.4.5
1.0.4.5
1.0.4.5
1.0.4.5
1.0.4.5
1.0.4.5
1.0.4.5
1.0.4.5
1.0.4
1.0.4
1.0.4
1.0.4
1.0.4
1.0.3
1.0.3
1.0.3
1.0.3
1.0.3
1.0.3
1.0.3
1.0.3
Unity
5.6.0p3 or later
5.5.3p2 or later
5.4.5p1 or later
5.6.0f3 or later
5.5.2p3 or later
5.4.5f1 or later
5.5.2p3 or later
5.4.5f1 or later
5.3.8f1 or later
(deprecated)
5.5.1p2 or later
5.4.4p3 or later
5.3.7p4 or later
(deprecated)
5.5.0p1 or later
5.4.3p3 or later
5.3.7p2 or later
5.4.2p2 or later
5.3.6p8 or later
5.4.1p1 or later
5.3.6p5 or later
5.4.0p3 or later
5.3.6p3 or later
5.4.0b16 or later
5.3.6p1 or later
5.4.0b16 and later
5.3.4p5 and later
56 | Unity-SDK Version Compatibility | Unity
Release Date
4/20/2016
4/20/2016
3/28/2016
10/30/2015
10/1/2015
7/6/2015
OVRPlugin / Utilities PC SDK
1.3.2
1.3.2
1.3.2
1.3.0
1.3.2
1.3.0
0.1.3.0 Beta
0.1.2.0 Beta
0.1.0.0 Beta
0.8.0.0
0.7.0.0
0.6.0.1
Unity 4.x Integration Versions
Release Date Integration
3/28/2016
10/30/2015
9/08/2015
8/14/2015
8/7/2015
6/25/2015
6/12/2015
5/15/2015
3/31/2015
3/26/2015
3/20/2015
2/27/2015
1/23/2015
1/7/2015
12/4/2014
11/12/2014
11/10/2014
10/24/2014
9/4/2014
8/11/2014
7/24/2014
5/22/2014
4/14/2014
10/10/2013
D 0.4.3.1
D 0.4.3
D 0.4.2
D 0.4.1
D 0.4.0
D 0.3.2
D 0.3.1
D 0.2.5
1.3.0
0.8.0.0
0.6.2.0
0.6.1.0
0.6.0.2
D 0.6.0.1
M 0.6.0.1
D 0.6.0.0
M 0.5.0
D 0.5.0.1
M 0.4.3.1
M 0.4.3
M 0.4.2
M 0.4.1
D 0.4.4
M 0.4.0
PC SDK
0.5.0.1
0.5.0.1
0.4.4
0.4.4
0.3.2
0.3.2
0.4.4
0.3.2
1.3.0
0.8.0.0
0.7.0.0
0.6.0.1
0.6.0.1
0.5.0.1
0.5.0.1
0.5.0.1
0.4.3.1
0.4.3
0.4.2
0.4.1
0.4.0
0.3.2
0.3.1
0.2.5
Mobile SDK
1.0.0.1
1.0.0.1
1.0.0.1
0.6.2.0
0.6.2.0
0.5.0
Mobile SDK
0.5.0
0.5.0
0.4.3.1
0.4.3
0.4.2
0.4.1
0.4.0
0.4.0
1.0.0.1
1.0.0
0.6.2.0
0.6.1.0
0.6.0.1
0.6.0.1
0.6.0.1
0.5.0
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
Unity
4.5
4.4
4.6
4.4
4.6
4.6
4.5
4.5
4.7.0f1
4.6.9p1
4.6.7+
4.6.7+
4.6.7
4.6
4.6
4.6
4.4
4.3
4.3
4.3
4.5
4.5
4.5
4.4
Unity
5.4.0b11 and later
5.3.3p3 and later
5.3.4p1
5.2.2p2
5.2.1p2
5.1.1
Unity | Release Notes | 57
Release Notes
This section describes changes for each version release.
1.3 Unity 4 Legacy Integration Release Notes
Unity 4.x Legacy Integration 1.3.0
This document provides an overview of new features, improvements, and fixes included in the latest version of the Unity 4.x Legacy Integration. For information on first-party changes to Unity VR support for Oculus, see the
Unity Release Notes for the appropriate version. You will find an updated scripting reference for the included
C# scripts in our
Unity Developer Reference
.
Note: For detailed information about Unity version compatibility, please see
This public release incorporates all changes from private releases 0.9.0 through 1.3.0. It adds support for PC
SDK 1.3, including support for Rift consumer version hardware.
Users may now close applications when switching to Home. When they do this, Unity receives a call from the runtime to close the application.
OnApplicationQuit() callback behaviors still work as before. Keep this in mind if you have previously written a custom shutdown procedure.
VR Focus
When VR Focus is lost in Unity 4 applications, all cameras are disabled and
Time.timeScale is set to 0.
Applications should check
Time.timeScale and pause gameplay and audio if it is 0.
Note that Rift and Samsung Gear VR applications will pause rendering when not in focus in VR. Recentering requests initiated from the Universal Menu are now implemented and will be handled automatically by the
Unity Integration.
New Features
• Added support for PC SDK 1.3, including support for Rift consumer version hardware.
• Added support for Asynchronous TimeWarp and Phase Sync.
• Added Rift Remote controller support.
• Added application lifecycle management, including VR-initiated backgrounding and exit.
• Exposed proximity sensor.
• Added support for multiple trackers.
• Exposed velocity and acceleration for all tracked nodes.
• Added VR Focus support. When VR Focus is lost,
Time.timeScale is set to 0.
• Added support for recentering from within the Home Universal Menu.
• Audio output now automatically uses the Rift headphones, if enabled in the Oculus app.
• Rift’s inter-axial distance slider now affects the distance between Unity’s eye poses.
• Exposed controller visibility so apps can respond to occlusion, et cetera.
58 | Release Notes | Unity
API Changes
•
OVRManager.isUserPresent is true when the proximity sensor detects the user.
•
OVRInput.GetControllerLocal[Angular]Velocity/Accelerations exposes the linear and angular velocity and rotation of each Touch controller.
• Added
OVRInput.GetControllerPosition|OrientationTracked(..) for controller visibility.
Bug Fixes
• Removed redundant axial deadzone handling from Xbox gamepad input.
• Increased deadzone on OVRInput stick input to prevent drift.
• Fixed issue where frustum/occlusion culling was less effective on Gear VR.
• Fixed several errors and race conditions due to hazards in start-up ordering.
Known Issues
• The Rift’s microphone is not the default when calling
Microphone.Start(null,..). Please find the entry in
Microphone.devices that contains the word Rift and use it.
• When you stop playing in the Unity editor, the last frame from the previous play remains frozen on the Rift.
• If an application's simulation time is paused, OVRInput will not update.
• Volume control will be missing on mobile applications until the release of Mobile SDK 1.0.2.
OVRVolumeControl has been removed, but it may still be accessed by using previous versions of the Oculus
Unity 4 Integration.
• If a VR app is running while a Rift is unplugged from a PC and plugged back in without restarting the application, then the Rift display will appear black. To fix this, add the following lines to OVRPlugin.cs and disable your OVRCameraRig and OVRManager if
OVRPlugin.shouldRecreateDistortionWindow is true. You will have to quit and re-start the app before it can use VR again.
private enum Status
{
Debug = 0,
…
}
…
ShouldRecenter,
+ ShouldRecreateDistortionWindow, public static bool shouldRecenter { get { return GetStatus(Status.ShouldRecenter); } }
+ public static bool shouldRecreateDistortionWindow { get { return
GetStatus(Status.ShouldRecreateDistortionWindow); }
0.8 Unity Legacy Integration Release Notes
This document provides an overview of new features, improvements, and fixes included in the Oculus Unity
Integration version 0.8.
Unity 4.x Legacy Integration 0.8.0.0
Overview of Major Changes
This document provides an overview of new features, improvements, and fixes included in the latest version of the Unity 4.x Legacy Integration. For information on first-party changes to Unity VR support for Oculus, see the
Unity Release Notes for the appropriate version.
Unity | Release Notes | 59
Unity 4.x Legacy Integration 0.8.0.0 extends OVRInput support to mobile. OVRInputControl and
OVRGamepadController are now deprecated and will be removed in a future release.
Mobile input bindings are now automatically added to InputManager.asset if they do not already exist - it is no longer required to replace InputManager.asset with Oculus’ version. However, this asset is still provided for now to maintain legacy support for the deprecated OVRGamepadController and OVRInputControl scripts.
Mobile Unity Development
Mobile SDK 1.0.0 includes major changes to VrApi - please see the
Mobile SDK 1.0.0 Release Notes
for more information.
New Features
• Default mobile input bindings are now programmatically generated when projects are imported if they do not already exist.
• Replacing InputManager.asset is no longer required to enable gamepad support on mobile.
API Changes
• Added mobile support OVRInput.
• Deprecated OVRInputControl and OVRGamepadController.
Bug Fixes
• Fixed mobile gamepad thumbstick deadzone/drift handling and axis scaling.
• Fixed mobile gamepad support when multiple gamepads are paired.
• Fixed mobile gamepad bindings for triggers, D-pad, thumbstick presses, etc.
Known Issues
• Some PC configurations may encounter instability when targeting the Windows platform with this release of the Unity 4.x Legacy integration. Please report any issues on our
Developer Forums
.
0.6 Unity Legacy Integration Release Notes
This document provides an overview of new features, improvements, and fixes included in the Oculus Unity
Integration version 0.6.
Unity 4.x Legacy Integration 0.6.2.0
Overview of Major Changes
0.6.2.0 pulls in the 0.7.0 Desktop plugins.
The source for the Unity SDKExample MediaSurface Plugin is now provided. The Media Surface Plugin provides a native library which is used with the Android MediaPlayer for hardware decoding of a single video to a texture. Note that the SDKExample MediaSurface Plugin is not intended to be production quality, and is provided for reference purposes. We have made the source available in case you would like to modify it for your use. The source and build files are located at the following SDK path: VrAppSupport/MediaSurfacePlugin.
This version adds an alpha release of OVRInput, which provides a unified input API for accessing Oculus Touch and Microsoft Xbox controllers.
60 | Release Notes | Unity
New Features
• Added alpha OVRInput script to expose API for Oculus Touch and XInput-based controllers.
• Now dynamically loads OpenGL ES symbols instead of hard-linking to libGLESv3.so. (Mobile)
API Changes
• Now requires the new Android Plugin Java library OculusUtilities.jar (found in Assets/Plugins/Android).
Bug Fixes
• Fixed Editor error message in Unity Free due to unsigned OVRPlugin.dll.
• Fixed thread affinity failing to be set for the TimeWarp and DeviceManager threads. (Mobile)
• Fixed device reset when repeatedly plugging and unplugging the Travel Adapter on the Galaxy SAMSUNG
S6. (Mobile)
• Fixed app crash occurring when using Oculus Runtime for OS X earlier than 0.5.0.1.
Unity 4.x Legacy Integration 0.6.1.0
Overview of Major Changes
Legacy Integration 0.6.1.0 expands upon the changes in Unity 4.x PC Integration 0.6.0.2. It is fully compatible with both our Mobile and PC SDKs.
For more information on important changes and updates relevant to this version, see the Release Notes for
Integration 0.6.0.2 below.
PC Developers
This release of the Unity Legacy Integration is compatible with the Oculus Runtime 0.6 and 0.7.
All Unity projects built with Unity 4 must update to this release, or they will not work on PCs using Runtime 0.7.
OS X Developers
Mac developers using Legacy Integration 0.6.1.0 must update to the Oculus Runtime for OS X 0.5.0.1. Before updating your runtime, be sure to run uninstall.app (found in /Applications/Oculus/) to remove your previous installation.
Mobile Developers
The MediaSurface functionality has been split from the main Unity Integration and provided as a separate plugin, libOculusMediaSurface.so included with the Unity integration package.
New Features
• SDKExamples
• MoviePlayer_Sample now looks for media files in the folder Streaming Assets instead of following a hardcoded path on the internal SD card (default mp4 provided).
• MoviePlayer_Sample defaults to using Unity MovieTexture functionality on the PC (media file expected as
Ogg Theora).
API Changes
• No longer required to issue ResetVrModeParms to dynamically adjust CPU and GPU clock levels.
Unity | Release Notes | 61
Bug Fixes
• Added back one frame of latency to Unity apps to avoid object motion judder by giving Unity apps one frame of additional GPU time (0.5.1 performance parity).
Unity 4.x PC Integration 0.6.0.2
Overview of Major Changes
Note: This release is intended for PC development only. Mobile developers should wait for Legacy
Integration version 0.6.1.0, which will ship very soon.
This release of the Unity Legacy Integration is compatible with the Oculus Runtime 0.6 and 0.7.
All Unity projects built with Unity 4 must update to this release, or they will not work on PCs using Runtime 0.7.
In most cases, migrating to this version of the legacy integration will be easy - simply open your project in
Unity, import the custom Integration unityPackage, and rebuild.
If you have previously used our C API wrappers in OvrCapi.cs, note that they have been removed and you will need to write your own native plugins or replacement wrappers to access functionality from LibOVRRT. This change is also required to use CAPI with our Unity 5 Utilities, so writing your own plugins or wrappers now will help prepare for your migration to Unity 5.
A single executable file is now produced for PC builds, which will work in both Extended and Direct Display modes.
This version removes support for D3D 9 and Windows GL.
Mac developers using Legacy Integration 0.6.0.2 must update to the Oculus Runtime for OS X 0.5.0.1. Before updating your runtime, be sure to run uninstall.app (found in /Applications/Oculus/) to remove your previous installation.
New Features
• Compatible with Oculus Runtime versions 0.6 and 0.7.
• PC builds now produce a single executable file for use in both Extended and Direct Display modes.
• Oculus runtime log messages now visible in the Unity console.
• Unity Editor Game View displays undistorted monoscopic preview.
• No longer necessary to rotate Mac monitor for DK2 in System Preferences->Displays.
API Changes
• Removed all C API wrappers from OvrCapi.cs.
• Removed D3D9, Windows GL, and Linux support.
Bug Fixes
• Fixed C# script problem that caused D3D11 Exclusive Mode errors.
• Fixed several Editor Game View issues:
• Now works for all aspect ratio settings.
• Fixed bug that blacked out Game Views when more than one were created.
• Fixed Game View positioning bug.
62 | Release Notes | Unity
Known Issues
• Mac tearing: Editor Game View and standalone players do not vsync properly, resulting in a vertical tear and/or judder on DK2. Android players are unaffected, even if built on a Mac.
• No VR support for in-editor preview on Windows until Unity 4.6.7p4.
• Slight increase in latency for trivial scenes (i.e., scenes that take < 3 ms to render).
Mobile Unity Integration 0.6.0.1
New Features
• Allow Unity MediaSurface dimensions to be modified via plugin interface.
Bug Fixes
• Fixed not being able to enable chromatic aberration correction in the Unity plugin.
• Fixed adjusting clock levels from Unity during load.
Mobile Unity Integration 0.6.0
Overview of Major Changes
• Oculus Runtime is no longer required for mobile development.
• Synced with the Oculus PC SDK 0.6.0.0 beta.
• Allows clients to re-map plugin event IDs.
For both the PC and Mobile SDKs we recommend the following Unity versions or higher: Unity Pro 4.6.3, Unity
Professional 5.0.2.p2, Unity Free 4.6, or Unity Personal 5.0.2.p2. For mobile development, compatibility issues are known to exist with Unity 5 and OpenGL ES 3.0 – please check back for updates. Earlier versions of Unity 5 should not be used with the Mobile SDK.
New Features
• VrAPI: improved frame prediction, in particular for Unity.
Bug Fixes
• Fixed prediction glitch every 64 frames.
• Use correct prediction for OVR_GetCameraPositionOrientation.
• Fixed location of the PlatformMenu Gaze Cursor Timer
PC Unity Integration 0.6.0.0
New Features
• Disabled eye texture anti-aliasing when using deferred rendering. This fixes the black screen issue.
• Eliminated the need for the DirectToRift.exe in Unity 4.6.3p2 and later.
• Removed the hard dependency from the Oculus runtime. Apps now render in mono without tracking when
VR isn't present.
Unity | Release Notes | 63
0.5 Mobile Unity Integration Release Notes
This document provides an overview of new features, improvements, and fixes included in the Oculus Unity
Integration that shipped with version 0.5 of the Oculus Mobile SDK.
Mobile Unity Integration 0.5.1
Overview of Major Changes
The most significant change in 0.5.1 is to System Activities event handling in Unity. The 0.5.0 code for handling
System Activities events in Unity was doing heap allocations each frame. Though this was not a leak, it would cause garbage collection to trigger much more frequently. Even in simple applications, garbage collection routinely takes 1 to 2 milliseconds. In applications that were already close to dropping below 60 Hz, the increased garbage collection frequency could cause notable performance drops. The event handling now uses a single buffer allocated at start up.
As with Mobile SDK v 0.5.0, Unity developers using this SDK version must install the Oculus Runtime for
Windows or OS X. This requirement will be addressed in a future release of the SDK.
Bug Fixes
• Rework System Activities Event handling to prevent any per-frame allocations that could trigger Garbage
Collector.
Known Issues
• For use with the Mobile SDK, we recommend Unity versions 4.6.3. The Mobile SDK is compatible with Unity
5.0.1p2, which addresses a problem with OpenGL ES 3.0, but there is still a known Android ION memory leak. Please check back for updates.
Mobile Unity Integration 0.5.0
Overview of Major Changes
The Mobile Unity Integration is now synced with the Oculus PC SDK 0.5.0.1 Beta. Please ensure you have installed the corresponding 0.5.0.1 Oculus runtime; it can be found at the following location:
https:// developer.oculus.com/downloads/
VrPlatform entitlement checking is now disabled by default in Unity; handling for native development is unchanged. If your application requires this feature, please refer to the Mobile SDK Documentation for information on how to enable entitlement checking.
New Features w
• Synced with the Oculus PC SDK 0.5.0.1 Beta.
• VrPlatform entitlement checking is now disabled by default.
Bug Fixes
• Health and Safety Warning no longer displays in editor Play Mode if a DK2 is not attached.
64 | Release Notes | Unity
Known Issues
• For use with the Mobile SDK, we recommend Unity versions 4.6.3, which includes Android 5.0 - Lollipop support as well as important Android bug fixes. While the Mobile SDK is compatible with Unity 5.0.0p2
and higher, several issues are still known to exist, including an Android ION memory leak and compatibility issues with OpenGL ES 3.0. Please check back for updates.
Mobile Unity Integration 0.5.0
Overview of Major Changes
The Mobile Unity Integration is now synced with the Oculus PC SDK 0.5.0.1 Beta. Please ensure you have installed the corresponding 0.5.0.1 Oculus runtime; it can be found at the following location:
https:// developer.oculus.com/downloads/
VrPlatform entitlement checking is now disabled by default in Unity; handling for native development is unchanged. If your application requires this feature, please refer to the Mobile SDK Documentation for information on how to enable entitlement checking.
New Features
• Synced with the Oculus PC SDK 0.5.0.1 Beta.
• VrPlatform entitlement checking is now disabled by default.
Bug Fixes
• Health and Safety Warning no longer displays in editor Play Mode if a DK2 is not attached.
Known Issues
• For use with the Mobile SDK, we recommend Unity versions 4.6.3, which includes Android 5.0 - Lollipop support as well as important Android bug fixes. While the Mobile SDK is compatible with Unity 5.0.0p2
and higher, several issues are still known to exist, including an Android ION memory leak and compatibility issues with OpenGL ES 3.0. Please check back for updates.
0.4 Mobile Unity Integration Release Notes
This document provides an overview of new features, improvements, and fixes included in the Oculus Unity
Integration that shipped with version 0.4 of the Oculus Mobile SDK.
Mobile Unity Integration 0.4.3
New Features
• New Mobile Unity Integration Based on Oculus PC SDK 0.4.4
Mobile Unity Integration 0.4.2
Overview of Major Changes
If you are developing with Unity, we recommend updating to Unity 4.6.1, which contains Android 5.0 – Lollipop support.
Unity | Release Notes | 65
We would like to highlight the inclusion of the new Mobile Unity Integration with full DK2 support based on the Oculus PC SDK 0.4.4. As this is a significant API refactor, please refer to the Unity Development Guide:
Migrating From Earlier Versions section for information on how to upgrade projects built with previous versions of the Mobile Unity Integration.
API Changes
• Fix for camera height discrepancies between the Editor and Gear VR device.
• Moonlight Debug Util class names now prefixed with OVR to prevent namespace pollution.
• Provide callback for configuring VR Mode Parms on OVRCameraController; see OVRModeParms.cs for an example.
Mobile Unity Integration 0.4.1
Overview of Major Changes
Added support for Android 5.0 (Lollipop) and Unity Free.
New Features
• Added Unity Free support for Gear VR developers.
Mobile Unity Integration 0.4.0
Overview of Major Changes
First public release of the Oculus Mobile SDK.
Bug Fixes
• Unity vignette rendering updated to match native (slightly increases effective FOV).
• Unity volume pop-up distance to match native.
Migrating From Earlier Versions
The 0.4.3+ Unity Integration’s API is significantly different from prior versions. This section will help you upgrade.
API Changes
The following are changes to Unity components:
Table 3: Unity Components
OVRDevice
→ OVRManager
OVRCameraController
→ OVRCameraRig
OVRCamera
The following are changes to helper classes:
Table 4: Helper Classes
OVRDisplay
OVRTracker
Unity foundation singleton.
Performs tracking and stereo rendering.
Removed. Use eye anchor Transforms instead.
HMD pose and rendering status.
Infrared tracking camera pose and status.
66 | Release Notes | Unity
OVR.Hmd
→ Ovr.Hmd
The following are changes to events:
Table 5: Events
HMD added/removed
Pure C# wrapper for LibOVR.
Tracking acquired/lost
HSWDismissed
Get/Set*(ref *) methods
Fired from OVRCameraRig.Update() on HMD connect and disconnect.
Fired from OVRCameraRig.Update() when entering and exiting camera view.
Fired from OVRCameraRig.Update() when the Health and Safety Warning is no longer visible.
Replaced by properties.
Behavior Changes
• OVRCameraRig’s position is always the initial center eye position.
• Eye anchor Transforms are tracked in OVRCameraRig’s local space.
• OVRPlayerController’s position is always at the user’s feet.
• IPD and FOV are fully determined by profile (PC only).
• Layered rendering: multiple OVRCameraRigs are fully supported (not advised for mobile).
• OVRCameraRig.*EyeAnchor Transforms give the relevant poses.
Upgrade Procedure
To upgrade, follow these steps:
1. Ensure you didn’t modify the structure of the OVRCameraController prefab. If your eye cameras are on
Game Objects named “CameraLeft” and “CameraRight” which are children of the OVRCameraController
Game Object (the default), then the prefab should cleanly upgrade to OVRCameraRig and continue to work properly with the new integration.
2. Write down or take a screenshot of your settings from the inspectors for OVRCameraController,
OVRPlayerController, and OVRDevice. You will have to re-apply them later.
3. Remove the old integration by deleting the following from your project:
• OVR folder
• OVR Internal folder (if applicable)
• Any file in the Plugins folder with “Oculus” or “OVR” in the name
• Android-specific assets in the Plugins/Android folder, including: vrlib.jar, libOculusPlugin.so, res/raw and res/values folders
4. Import the new integration.
5. Click Assets -> Import Package -> Custom Package…
6. Open OculusUnityIntegration.unitypackage
7. Click Import All.
8. Fix any compiler errors in your scripts. Refer to the API changes described above. Note that the substitution of prefabs does not take place until after all script compile errors have been fixed.
9. Re-apply your previous settings to OVRCameraRig, OVRPlayerController, and OVRManager. Note that the runtime camera positions have been adjusted to better match the camera positions set in the Unity editor. If this is undesired, you can get back to the previous positions by adding a small offset to your camera: a.
Adjust the camera's y-position.
Unity | Release Notes | 67
a. If you previously used an OVRCameraController without an OVRPlayerController, add 0.15 to the camera y-position.
b. If you previously used an OVRPlayerController with Use Player Eye Height checked on its
OVRCameraContoller, then you have two options. You may either (1) rely on the new default player eye-height (which has changed from 1.85 to 1.675); or (2) uncheck Use Profile Data on the converted
OVRPlayerController and then manually set the height of the OVRCameraRig to 1.85 by setting its yposition. Note that if you decide to go with (1), then this height should be expected to change when profile customization is added with a later release.
c. If you previously used an OVRPlayerController with Use Player Eye Height unchecked on its
OVRCameraContoller, then be sure uncheck Use Profile Data on your converted OVRPlayerController.
Then, add 0.15 to the y-position of the converted OVRCameraController.
b.
Adjust the camera's x/z-position. If you previously used an OVRCameraController without an
OVRPlayerController, add 0.09 to the camera z-position relative to its y rotation (i.e. +0.09 to z if it has
0 y-rotation, -0.09 to z if it has 180 y-rotation, +0.09 to x if it has 90 y-rotation, -0.09 to x if it has 270 yrotation). If you previously used an OVRPlayerController, no action is needed.
10.Re-start Unity
Common Script Conversions
OVRCameraController -> OVRCameraRig
cameraController.GetCameraPosition() -> cameraRig.rightEyeAnchor.position
cameraController.GetCameraOrientation() -> cameraRig.rightEyeAnchor.rotation
cameraController.NearClipPlane -> cameraRig.rightEyeCamera.nearClipPlane
cameraController.FarClipPlane -> cameraRig.rightEyeCamera.farClipPlane
cameraController.GetCamera() -> cameraRig.rightEyeCamera
----------------------------------------------------------------------
if ( cameraController.GetCameraForward( ref cameraForward ) &&
cameraController.GetCameraPosition( ref cameraPosition ) )
{
...
to
if (OVRManager.display.isPresent)
{
// get the camera forward vector and position
Vector3 cameraPosition = cameraController.centerEyeAnchor.position;
Vector3 cameraForward = cameraController.centerEyeAnchor.forward;
...
----------------------------------------------------------------------
OVRDevice.ResetOrientation();
to
OVRManager.display.RecenterPose();
----------------------------------------------------------------------
cameraController.ReturnToLauncher();
to
OVRManager.instance.ReturnToLauncher();
----------------------------------------------------------------------
OVRDevice.GetBatteryTemperature();
OVRDevice.GetBatteryLevel();
68 | Release Notes | Unity
to
OVRManager.batteryTemperature
OVRManager.batteryLevel
----------------------------------------------------------------------
OrientationOffset
Set rotation on the TrackingSpace game object instead.
----------------------------------------------------------------------
FollowOrientation
----------------------------------------------------------------------
FollowOrientation is no longer necessary since OVRCameraRig applies tracking
in local space. You are free to script the rig’s pose or make it a child of
another Game Object.
Prenesi
Javna povezava posodobljena
Javna povezava do vašega klepeta je bila posodobljena. You may view and manage your chat links after registration here.
Javna povezava do dokumenta
Oglas
