Integrating Gear VR and the AR/VR Sample (Legacy)

The Vuforia AR/VR sample for Unity demonstrates how to develop mixed reality AR/VR experiences for the Gear VR Innovator Edition, and also how to implement gaze detection to trigger transitions between the AR and VR modes of the experience.

The following article details how to integrate Gear VR OVR Unity extension with the Vuforia AR/VR sample for Unity versions prior to 5.3. You can find the AR/VR sample in the Samples section of the developer site.

Note: If you are using Unity 5.3 , you can take advantage of Unity's native VR Support and do not need to implement the steps defined in this document. See: Integrating Gear VR and the AR/VR Sample in Unity 5.3

Vuforia 6 is compatible with the following Unity and Oculus SDK versions:

  • Unity versions 5.3.x, 5.2.x, 5.1.3p1, and 4.6.7. Unity 5.1.3p1 resolves performance issues experienced with earlier 5.x releases.
  • Oculus Mobile SDK versions 0.8.0.0, 0.6.2.0, 0.6.0.1, and 0.5.0.

This article documents the steps for integrating Oculus Mobile SDK version 0.8.0.0, which is the recommended SDK version to use with Vuforia.

Integration Steps

1. Download the Unity 4.x Legacy Integration plugin (recommended: 0.8.0.0 or newer)
2. Create a new Unity project and import the ARVR-x-y-z.unitypackage
3. Rename the Assets/Plugins/Android/AndroidManifest.xml to AndroidManifest-Vuforia.xml
4. Import the OculusIntegration.unitypackage
5. Open the Vuforia-3-AR-VR scene
6. Drag an OVRCameraRig prefab into your Hierarchy and position it at [0, 2, -1]
7. Now configure the LeftEyeAnchor & RightEyeAnchor:
  • Clear Flags = Solid Color
  • Background = Black
  • Clipping Planes [Near] = 0.05 *
  • Clipping Planes [Far] = 300 *

* We recommend Near = 0.05 and Far = 300 for AR/VR scenes, but you can adjust to suit your 3D scene.

Camera Rig Binding Steps

Vuforia can support 3rd party camera rigs by binding them to the ARCamera. The procedure for doing this was updated and simplified with Vuforia 5.5. Choose the binding steps which are appropriate to your Unity VR project:

Camera Binding Screenshots Vuforia 5.0 & 5.5 Camera Binding Steps
Oculus Binding with Vuforia 5.0

1. Select the ARCamera in the Hierarchy
2. If using Vuforia 5.0, in the Inspector options for VuforiaBehaviour, set the following:
  • Bind Alternate Camera = checked
  • Synchronize Pose Updates = checked (enables the synchronization of head pose updates between Vuforia and the Gear VR trackers)
  • Skew Frustum = checked
  • Camera Offset = 0
  • Viewer = Gear VR

2. If using Vuforia 5.5, in the Inspector options for DigitalEyewearBehaviour, set the following:

  • Eyewear Type = Video See-Through
  • Stereo Camera Config = Gear VR (Oculus)

3. Drag the following GameObjects in the Hierarchy to the respective fields:

  • CenterEyeAnchor to Central Anchor Point
  • LeftEyeAnchor to Left Camera
  • RightEyeAnchor to Right Camera

4. Click the Add Vuforia Components button that will appear under the Left Camera and also under Right Camera fields in the Inspector.

DLL Tasks:

Move the following VuforiaWrapper files from Plugins to Plugins/x86 folder:
  • VuforiaWrapper.dll
  • VuforiaWrapper.dll.signature
  • VuforiaWrapper.exp
  • VuforiaWrapper.lib
With Unity 5.0+, make sure that the Oculus desktop plugins don't collide. For each of the following Oculus DLL files in the Plugins/x86 and Plugins/x86_64 folders, uncheck Any Platform and enable the Editor and Standalone options:
DLLs (x86, x86_64) 0.6.0.1 0.6.2.0 0.8.0.0
OculusInitPlugin.dll YES --- ---
OculusPlugin.dll YES YES YES
OVRGamepad.dll --- YES YES
OVRPlugin.dll --- YES YES

Android Manifest:

Check the AndroidManifest.xml located under Assets/Plugins/Android and verify that the following permissions are present:

<uses-feature android:name="android.hardware.camera" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Code Changes:

InitErrorHandler.cs

private void OnInitError(VuforiaUnity.InitError error)
{
    if (error != VuforiaUnity.InitError.INIT_SUCCESS)
    {
        // ADD THIS LINE TO DISABLE STEREO MODE // 
        OVRManager.instance.monoscopic = true; 
        // END OF ADDED CODE //
        
        ShowErrorMessage(error);
    }
}

OVRCameraRig.cs

private void UpdateAnchors()
{
    // ... other method code ...
     
    centerEyeAnchor.localPosition = 0.5f * (hmdLeftEye.position + hmdRightEye.position);
    leftEyeAnchor.localPosition = monoscopic   centerEyeAnchor.localPosition : hmdLeftEye.position;
    rightEyeAnchor.localPosition = monoscopic   centerEyeAnchor.localPosition : hmdRightEye.position;

    // START: OPTIONALLY ADD THIS CODE - If you wish to reduce the stereo offset (distance between eyes) //
    if (!monoscopic)
    {
        float stereoMultiplier = 0.2f; // use value you want between 0 (no stereo) and 1 (strong stereo)
        leftEyeAnchor.localPosition = Vector3.Lerp(centerEyeAnchor.localPosition, hmdLeftEye.position, stereoMultiplier);
        rightEyeAnchor.localPosition = Vector3.Lerp(centerEyeAnchor.localPosition, hmdRightEye.position, stereoMultiplier);
    }
    // END: OPTIONALLY ADDED CODE //

    // START: ADD THIS REQUIRED CODE //
    Vuforia.VuforiaBehaviour.Instance.UpdateState(false, true);
    // END: ADDED REQUIRED CODE //

    if (UpdatedAnchors != null)
    {
        UpdatedAnchors(this);
    }
}

// ... other class code ...

private Camera ConfigureCamera(OVREye eye)
{
    // ... other method code ...
  
    // START: ADD THIS CODE - ONLY REQUIRED FOR AR EXPERIENCES //
    cam.ResetProjectionMatrix();
    Vuforia.VuforiaBehaviour.Instance.ApplyCorrectedProjectionMatrix(cam.projectionMatrix, eye == OVREye.Left);
    // END: ADDED CODE //

    return cam;
}

OVRShimLoader.cs

OVR 0.6.0.1 with Unity 5.2 OVR 0.6.2.0 or 0.8.0.0
Update line 52 to include UNITY_5_2:

#if (UNITY_5_0 || UNITY_5_1 || UNITY_5_2)
Comment out line 30:
 
// PlayerSettings.d3d11ForceExclusiveMode = false;

OVRPlugin.cs - (0.6.2.0, 0.8.0.0)

Revise the preprocessor directive #if !UNITY_5 at line 22 to:

#if (UNITY_4_6 || UNITY_5)
#define OVR_LEGACY
#endif

OVRInput.cs - (0.6.2.0, 0.8.0.0)

Revise the preprocessor directive #if !UNITY_5 at line 22 to:

#if (UNITY_4_6 || UNITY_5)
#define OVR_LEGACY
#endif

Final Steps:

  1. Add a Vuforia License Key
  2. Place Oculus Signature Files (OSIGs) in the following Unity project location:
    • Assets/Plugins/Android/assets/
  3. Include the Vuforia-3-AR-VR scene in Build Settings
  4. Omit the Vuforia-1-AboutPage scene from Build Settings
  5. In the Android Player Settings Set the following:
    • Default Orientation = Landscape Left
    • Multithreaded Rendering = checked