Integrating Cardboard to the AR/VR Sample | Vuforia Library Prod

Integrating Cardboard to the AR/VR Sample

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

Vuforia 5 is compatible with the following: 

• Unity versions 5.3.x, 5.2.x 5.1.3p1, 4.6.7. Unity 5.1.3p1 resolves performance issues experienced with earlier 5.x releases.
• Cardboard Unity SDK versions 0.5.0, 0.5.1, 0.5.2 and 0.6.0 (0.6.0 is recommended)
• Cardboard supports iOS version 8 and Android version 4.3 or higher

Vuforia 5.5 now supports minimum of Unity 5.2.4. Refer to the Vuforia Supported Versions guide and SDK Release Notes for the latest info on software version compatibility.

Technique #1. Using Vuforia 5.5's Built-in Support for Cardboard

Vuforia 5.5 introduces built-in support for Cardboard so that it is no longer necessary to import the Cardboard SDK into your project and perform the lengthy integration steps as described in Technique #2 below. The AR/VR 5.5.9 sample app is already pre-configured with the correct Cardboard settings and ready to build. If you want to enable Cardboard support in your own existing Vuforia 5.5 project, follow these steps:

1. Select the ARCamera and set the following values on the DigitalEyewearBehaviour script:

• Eyewear Type = Video See-Through
• Stereo Camera Config = Vuforia
• Viewer Type = Generic Cardboard (Vuforia) or Cardboard v1 (Google)

2. In the Unity Player Settings, set the Default Orientation = Landscape Left

Technique #2. Integrating Vuforia 5 / 5.5 with the Cardboard SDK

	1. Download the Cardboard SDK for Unity (recommended: 0.6.0) 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 CardboardSDKForUnity.unitypackage 5.Open the Vuforia-3-AR-VR scene
	6. Drag a CardboardMain prefab into the Hierarchy and set the following: Position = [0, 0, -1] Back Button = Off * Tap Is Trigger = unchecked ** NOTE: When importing Cardboard 0.5.2, a Cardboard GameObject might be automatically added to the scene. If so, remove this additional Cardboard object as the scene should only have one Cardboard instance. * Turns off the "Back Arrow" which is otherwise displayed on the screen. (Only applies to Cardboard 0.5.2 and 0.6.0) ** Disable Tap Is Trigger as this may prevent screen touch events from being delivered to UI buttons, unless you explicitly want to use screen touch (tap) events as a Cardboard trigger.
	7. Select the Head GameObject and set the following: Position = [0, 2, 0] (recommended position for AR-VR sample app) Track Position = unchecked
	8. Configure the Main Camera, Main Camera Left, & Main Camera Right with these settings: Clear Flags = Solid Color Background = Black Clipping Planes [Near] = 0.05 * Clipping Planes [Far] = 300 * * Use the same clipping plane values that the ARCamera uses.
	9. For the Main Camera, set the following: Stereo Multiplier = [ 0.1 - 0.2 ] (suggested for AR/VR sample app) * Check Stereo Comfort = unchecked * Adjust the Stereo Multiplier value to a comfortable level. A value of 1 will correspond to a "full" stereo offset of 0.06 meters between the eyes (left and right cameras). A value of 0 will result in no stereo offset. If the stereo offset is too strong, you may want to set the Stereo Multiplier to 0.5 or less. For the AR/VR sample app, the suggested Stereo Multiplier is within the range of 0.1 and 0.2.

Camera Binding

Camera Binding Screenshots

Vuforia 5.0 & 5.5 Camera Binding Steps

Cardboard Binding with Vuforia 5.0 Cardboard Binding with Vuforia 5.5

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 Cardboard) Camera Offset = 0 Skew Frustum = checked Viewer = Cardboard 2. If using Vuforia 5.5, in the Inspector options for DigitalEyewearBehaviour, set the following: Eyewear Type = Video See-Through Stereo Camera Config = Cardboard 3. Drag the following GameObjects in the Hierarchy to the respective fields: to Central Anchor Point Main Camera Left to Left Camera Main Camera Right 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.

Code Changes:

InitErrorHandler.cs

private void OnInitError(VuforiaUnity.InitError error) { if (error != VuforiaUnity.InitError.INIT_SUCCESS) { // BEGIN: Add these lines to disable Cardboard stereo mode before showing the init error message. Cardboard.SDK.VRModeEnabled = false ; Cardboard.SDK.DistortionCorrection = false ; // 0.5.0, 0.5.1 Cardboard.SDK.DistortionCorrection = Cardboard.DistortionCorrectionMethod.None; // 0.5.2, 0.6.0 // END: Added code. // Show error popup dialog ShowErrorMessage(error); } }

CardboardHead.cs

private void UpdateHead() { // ... other method code ... // For Cardboard 0.6.0, add this line before the OnHeadUpdated null check below: Vuforia.VuforiaBehaviour.Instance.UpdateState( false , true ); if (OnHeadUpdated != null ) { onHeadUpdated(gameOjbect); } // For Cardboard 0.5.x add this line at the end of the UpdateHead() method: Vuforia.VuforiaBehaviour.Instance.UpdateState( false , true ); }

CardboardEye.cs

// Line 145: Cardboard 0.5.0, 0.5.1 -- Place in the Setup() method: Vuforia.VuforiaBehaviour.Instance.ApplyCorrectedProjectionMatrix(proj, eye == Cardboard.Eye.Left); // Line 179: Cardboard 0.5.2, 0.6.0 -- Place at end of UpdateStereoValues() method: Vuforia.VuforiaBehaviour.Instance.ApplyCorrectedProjectionMatrix(proj, eye == Cardboard.Eye.Left);

Android: Disabling Native Distortion Correction

BaseCardboardDevice.cs (0.5.1, 0.5.2, 0.6.0)

// For 0.5.1, 0.5.2, 0.6.0: protected bool debugDisableNativeDistortion = true ; //false;

AndroidVRDevice.cs (0.5.0)

// For 0.5.0, comment out the #if UNITY_5 preprocessor conditional: public override void Init() { //#if UNITY_5 debugDisableNativeDistortion = true ; //#endif base .Init(); ConnectToActivity(); }

Android: Permissions

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

< uses-permission android:name = "android.permission.CAMERA" /> < uses-permission android:name = "android.permission.INTERNET" /> < uses-permission android:name = "android.permission.ACCESS_NETWORK_STATE" /> < uses-permission android:name = "android.permission.ACCESS_WIFI_STATE" />

iOS: Cardboard Initialization and Onboarding Dialog Changes

iOSVRDevice.cs (0.5.0) ----or---- CardboardiOSDevice.cs (0.5.1, 0.5.2, 0.6.0)

public override void Init() { isOpenGL = false ; //isOpenGLAPI(); setSyncWithCardboardEnabled(Cardboard.SDK.SyncWithCardboardApp); base .Init(); }

iOSVRDevice.cs (0.5.0) ----or---- CardboardiOSDevice.cs (0.5.1, 0.5.2, 0.6.0)

If you want to prevent Cardboard from launching the Onboarding dialog when the app is initially paused/resumed, comment out the launchOnboardingDialog() function call:

public override void OnFocus( bool focus) { if (focus && (debugOnboarding || !isOnboardingDone())) { debugOnboarding = false ; // comment out this line: // launchOnboardingDialog(); } }

iOS: Cardboard Settings Dialog Changes (0.5.0)

BaseVRDevice.cs

// ... other class code ... public bool triggered; public bool tilted; // ADD THIS LINE: public bool settingsDialogLaunched; // ... other class code ...

VRDevice.cs

In the ProcessEvents() method, set the settingsDialogLaunched flag to true in the kLaunchSettingsDialog case handler:

case kLaunchSettingsDialog: // ADD THIS LINE: settingsDialogLaunched = true ; LaunchSettingsDialog(); break ;

Cardboard.cs

// ... other class code ... public event Action OnTrigger; public event Action OnTilt; // ADD THIS LINE: public event Action OnSettingsDialogLaunched; // ... other class code ... private void DispatchEvents() { // ... other method code ... // Add this code at end of DispatchEvents() method: if (device.settingsDialogLaunched) { device.settingsDialogLaunched = false ; if (OnSettingsDialogLaunched != null ) { OnSettingsDialogLaunched(); } } }

CardboardSettingsHandler.cs

Create CardboardSettingsHandler.cs with the following code and attach it to the CardboardMain GameObject in your scene.

using UnityEngine; using System.Collections; using Vuforia; public class CardboardSettingsHandler : MonoBehaviour { private bool mCardboardSettingsDialogWasLaunched = false ; void Start() { Cardboard.SDK.OnSettingsDialogLaunched += delegate () { mCardboardSettingsDialogWasLaunched = true ; }; } void Update () { if (mCardboardSettingsDialogWasLaunched) { mCardboardSettingsDialogWasLaunched = false ; // Reset Vuforia if (VuforiaBehaviour.Instance.enabled) { VuforiaBehaviour.Instance.enabled = false ; VuforiaBehaviour.Instance.enabled = true ; } } } }

iOS: Cardboard Changes (0.5.1, 0.5.2, and 0.6.0)

BaseCardboardDevice.cs

public override void UpdateScreenData() { // ... other method code ... // Add the following code: Vuforia.VuforiaBehaviour vuforia = Vuforia.VuforiaBehaviour.Instance; if (vuforia != null && vuforia.enabled) { // Reset Vuforia vuforia.enabled = false ; vuforia.enabled = true ; } }

iOS: Unity Build & Xcode Project Changes

VuforiaNativeRendererController.mm

• Delete the source file Plugins/iOS/VuforiaNativeRendererController.mm before building your Unity project.

In the Xcode Build Phases section, add the following frameworks to the linked libraries*:

• libc++.dylib -- (Unity 4 only)
• CoreText.framework -- (Unity 4 and 5)

*For latest up-to-date instructions, see Cardboard's Deploying the Project in Xcode

CardboardAppController.h

// Add this method declaration: - ( void )shouldAttachRenderDelegate;

CardboardAppController.mm

// Add the following import: #import "VuforiaRenderDelegate.h" extern "C" { // Add the following declarations: extern void VuforiaRenderEvent( int eventId); extern void VuforiaSetGraphicsDevice( void * device, int deviceType, int eventType); // ... other code ... } @implementation CardboardAppController // ... other methods ... // Add the following method to the end of the CardboardAppController // implementation just before the "pause:(bool)paused" method: - ( void )shouldAttachRenderDelegate { self.renderDelegate = [[VuforiaRenderDelegate alloc] init]; #if UNITY_VERSION>434 UnityRegisterRenderingPlugin(&VuforiaSetGraphicsDevice, &VuforiaRenderEvent); #endif } - ( void )pause:( bool )paused { // ... other code ... } // ... other methods ... @end

Troubleshooting

Review the Cardboard SDK for Unity Release Notes for latest up-to-date details on known issues, fixes, and Unity version compatibility.