Skip to content

Usage

Jump to bottom
cdytoby edited this page Nov 11, 2020 · 24 revisions

Last Update: 2020.10.09 Version 1.0

The plugin is released, and it can be use in production. Page is updated after release due to some issues.

How to use this package

  • Just download unitypackage and open it in your project.
  • If you have legacy Google Cardboard related SDKs or files in your project, you should delete them. They'll cause issues in newer development environment.
  • Setup your project, please READ the section "Unity Setup and Setting".
  • Check the prefab section in this page. It explains how to integrate it into your scene
  • The unitypackage contains only the SDK itself. For demo usage, please clone this project and open in Unity.
  • If you cloned this project, be advised that this project is created using Unity 2018. If you intend to clone it for Unity 2019, many things have to change. Details are in this link:

Software Requirement

  • Unity 2018.4 or later. Previous 2018 version should also be supported, but they're not tested.
  • Support both Android and iOS.
  • Graphic API is not relevant. Graphic API Metal on iOS and Vulkan on Andoroid are tested and it just works.
  • Default Rendering Pipeline and Scriptable Rendering Pipeline (URP, HDRP) are supported.

Unity Setup and Setting

  • Disable Unity VR setting, because this package doesn't rely on any Unity VR Settings
    • In Unity 2019 or older, disable "Virtual Reality Supported" in Project Settings -> Player -> XR Settings (or VR Settings).
    • In Unity 2019 or later, disable any loader and disable "initiate at startup" if you use Unity XR Management System.
  • Set Default Orientation to "Landscape Left"
  • Scripting Runtime Version: .NET 4.x Equivalent
  • API Compatibility Level: .NET Standard 2.0
  • Scripting Backend: IL2CPP (Other should also work, but both Android and iOS store release now requires il2cpp for multiple reasons.)
  • If you already uses Google's protocol buffer in your project, you can remove Cardboard/Plugins/GoogleProtoBuf.dll, because a conflict may exist when two same dll exists.

Additional Settings for iOS

  • "Camera Usage Description" in "Settings for iOS" must be set in order to pass iOS requirement. Camera will be used to scan cardboard profile qr code.
  • If you're using Unity 2020 or later, OpenGLES is no longer included in "Default frameworks" in "plugin import settings -> Platform Settings". So, in Unity, project tab, locate the libsdk (libsdk.a) file in "Assets -> Cardboard -> Plugins -> iOS", in Inspector, you should check "OpenGLES" in Framework dependencies. Even the your project uses Metal API, this library still have link to native opengl functions. If "OpenGLES" is not included this will throw exception during ios build in XCode.

Additional Settings for Android

  • Custom gradle files must be created, and following packages must be added to dependencies:
  implementation 'com.android.support:appcompat-v7:28.0.0' 
  implementation 'com.android.support:support-compat:28.0.0' 
  implementation 'com.google.android.gms:play-services-vision:15.0.2' 
  implementation 'com.google.protobuf:protobuf-lite:3.0.0'
  • About these dependencies
    • you can check the file "[projectroot]\Assets\Plugins\Android\mainTemplate.gradle" for more details
    • If you already included compiled aar or jar files in your project, add or remove these lines accordingly. It will have some conflict.
    • If you use any other Packages like Google Firebase, or Facebook SDK, you should double or triple check if these packages are included in your Unity project. You can either remove these lines in the gradle file, or delete these files in your other SDK.

Prefab

After setting up a scene, delete the default camera component or object, and simply drag and drop the following prefabs into the scene.

  • /Assets/Cardboard/Prefabs/CardboardCamera
  • /Assets/Cardboard/Prefabs/CardboardUIOverlay

CardboardCamera

CardboardCamera prefab contains 2 GameObject Groups:

  • VR Camera
  • Normal Camera without VR And it contains 4 different MonoBehaviours, each has individual purpose:
  • CardboardMainCamera handles everything with eye camera and no-vr camera (still in dev).
  • CardboardHeadTransform handles camera orientation on mobile device. This script will be disabled automatically in Editor runtime (in Awake()).
  • SimulateHeadTransform handles camera orientation in Editor. This script will be automatically enabled in Editor runtime (in Awake()).
  • CardboardPostCamera is used to render distorted images on Screen.

You can also create your own camera prefab (or camera rig), just make sure CardboardMainCamera and CardboardPostCamera is attached correctly, and their fields in Unity are correctly set.

CardboardUIOverlay

This prefab is used to for displaying overlay. Unity UI System is used in this prefab, and you need an EventSystem GameObject in the scene to make button click works.

This UI Overlay contains the following UI Elements:

  • QR Scan Button, click it to initiate qr code scanning process, this button is hidden when it's not in vr mode. On iOS, a native dialog pupop will show up and ask user to allow camera usage.
  • Overlay Panel, it's used to notify user, which cardboard (vendor and model) he's using.
  • Continue Button on Overlay Panel. It closes this Overlay Panel.
  • Switch VR View Button, it's used to disable and enable vr view.

Except a QR code scan button, everything else is not necessary, you can do everything on your own.

Pre/Post Builds

Clone this wiki locally