ImmersiON-VRelia SDK User

Guide
For Unity 3D +Android
Alpha Version 1.032a

All trademarks, service marks, trade names, trade dress, product names and logos appearing on
this documentation are the property of their respective owners.
Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

Contents
1.
Overview, 3
1.1. About this SDK, 3
1.2. Features, 3
1.3. Required Software, 3
1.4. Installation, 4
1.5. Basic Usage, 7
1.6. Sample Project, 9
1.7. Differences between Unity Free and Unity Pro, 9
2.
Editor, 10
2.1. Menu, 10
2.2. ImmersiON-VRelia Components, 10
2.3. Folder Structure, 11
2.4. VR Parameters, 12
3. Project Configuration, 14
3.1. Android Setup, 14
3.2. AlterSpace Connectivity, 16
4.

Controls & Input, 19

5.
Performance and Stereoscopic Comfort, 20
5.1. Optical correction, 20
5.2. Image Effects, 20
5.3. Dynamic Convergence, 20
5.4. Tips, 21

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

1. Overview
1.1. About this SDK
ImmersiON-VRelia offers a free Unity 3D SDK to greatly simplify VR
development for our
hardware devices and enable seamless and consistent integration into our VR
ecosystem. This SDK will handle device based calibration, simplify 3D side by
side rendering, and allow users to tweak stereoscopic parameters at run time.
With some of the hard stuff out of the way, developers can focus on creating
the best quality content.
We are going to constantly improve this SDK and add new features making easy
for you to get the best of your work on our devices.

1.2. Features
Easy integration.
Presets for first and third person controllers.
Compatible with a large number of devices - mobile and VR.
Advanced sensor based head tracking.
Standard gamepad compatibility.

1.3. Required Software

Unity 3D 4.6 or newer. Supported on Windows and OSX.
Additional requirements for Android: Android SDK and Java
Development Kit (JDK).

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

1.4. Installation
To start a new Unity VR project using this SDK:
Open or create a new Unity 3D project.
Select File -> Build Settings and set the compilation platform to Android.

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

 Use the import option from Assets -> Import Package -> Custom
Package.

Search and select ImmersiON-VRelia Unity package.

Import the package contents. If you have a Project Settings custom
configuration for your project you can uncheck this option, except the
InputManager.asset.

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

Note: If you see UnityEngine.UI.dll and UnityEditor.UI.dll in the asset import

tree, uncheck them to avoid DLL conflicts. (Only in Unity 4.x, not in 5.x)

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

1.5. Basic Usage

Please follow this steps to quickly use the SDK in one scene:
Create a new Unity scene or open an existing one.
Replace the Unity first person controller or your own person controller
with the
ImmersiON-VRelia_FPS_Player that you will find in the
ImmersiON-VRelia_Menu in your scene.
If you want to use your own controller replace the MainCamera object of your
person controller with ImmersiON-VRelia_Camera.

Check that ImmersiON-VRelia_Main and ImmersiON-VRelia_Menu are

both included in your scene. If not include them from ImmersiONVRelia/ Prefabs menu.

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

 Configure the VR SDK parameters (based on your application needs) in

the Unity inspector by selecting ImmersiON-VRelia_Main in your scene.

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

1.6. Sample Project

We have included a basic demo scene in Assets / ImmersiON-VRelia / Scenes.
For a more complex demo check out Assets / ImmersiON-VRelia / Example
Project / House of Science. This scene is a full architectural project with basic
interactions.
You can also find example scripts that use the ImmersiON-VRelia SDK in
Assets / ImmersiON-VRelia / Example Scripts.

1.7. Differences between Unity Free and Unity Pro:

You can use the SDK with Unity Free and Unity Pro but these features will
require both Unity Pro and Android Pro
Lens distortion correction (Available in Free and Pro in Unity5)

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

2. Editor
2.1. Menu
The SDK creates a new menu in the Unity application menu bar called
ImmersiON-VRelia.
It adds a convenient way to add the most commonly used SDK assets which can
be found in Assets / ImmersiON-VRelia / Prefabs.
ImmersiON-VRelia Main
ImmersiON-VRelia Menu
ImmersiON-VRelia Player Controller
ImmersiON-VRelia Camera Controller

2.2. ImmersiON-VRelia Components

If you prefer setting up your own game objects, you may use our scripted
components
directly. It is generally to start with our prefabs.
Heres a list of the components we provide:
Image Effects:
ImmersiONVRelia Distortion.
This script is used to correct distortion caused by the
physical lenses in your VR hardware.
This script is applied to the virtual cameras. (Unity Pro
Only)
Character:
ImmersiONVRelia Controller.
This script provides a player controller that uses the
character controller included by Unity.
Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

10

Scripts:
ImmersiONVRelia Main.
Controls the real time execution of the SDK. VR parameters
can be configured in the Unity inspector (Please check the
VR parameters section).
Camera:
ImmersiONVRelia MouseLook.
Provides mouse based movement of the camera when no
accelerometer/gyroscope is available. (Like the Editor).
ImmersiONVRelia Tracker.
Provides precise head tracking based on a mobile phones
sensors. It works great with devices like the ImmersiON-VRelia
GO.

2.3. Folder Structure

Most of our assets are imported to Assets / ImmersiONVRelia. Inside this folder,
you will find:

Example Project: Full sample project with all its assets and resources.
Example Scripts: Sample scripts to use with the SDK.
Materials: Materials used by the SDK basic scene.
Prefabs: Basic game objects useful in setting up your VR scenes.
Resources: Resources included in the SDK.
Scenes: Basic sample scene included with the SDK.
Scripts: Script components that the SDK uses.
Textures: Textures that the SDK uses.

You can find the libraries used by the SDK in Assets / Plugins. The Assets /
Plugins /Android folder contains an AndroidManifest.xml file.
Once configured, this manifest file can be used to easily integrate with our
AlterSpace virtual environment. Please check the Android Manifest
Configuration section.

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

11

2.4. VR Parameters
These parameters are included in the ImmersiON-VRelia_Main script. You can
use them to
configure your VR scenes. We provide tooltips in the Unity inspector for each
of these.

These parameters are:

Active Distortion: Activates or deactivates the optical geometric
distortion correction.
Distortion: The amount of correction used when Active Distortion
option is enabled.
FOV: Controls the virtual cameras field of view.
IPD: The amount of separation between eye pupils in centimeters. It
configures the virtual cameras separation in your scene to match a
physical distance between the human eyes pupils in the real world.
Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

12

 Active Dynamic Convergence: Activates the dynamic convergence

feature of the virtual cameras.
Layer: This parameter configures the Unity layer that Dynamic
Convergence will use. It is only available when Dynamic Convergence
option is active.
Debug Ray: It activates a debug mode for Dynamic Convergence. Only
available when Dynamic Convergence option is active.
Z Threshold: Threshold jump distance used to get a progressive or
instant adjustment. When Dynamic Convergence detects values higher
than this threshold the convergence produced is progressive and smooth.
Only available when Dynamic Convergence option is active.
Response Time: This parameter controls the focus speed that
progressive convergence uses. The higher the value the faster the
convergence. Only available when Dynamic Convergence is enabled.
Type: Allows to select between dynamic convergence based on a
specific Point in space or a specific Area in the field of view for the
possible object of interest. Selecting Point requires less resources than
Area but is less precise than the Area option.
Area precission: This parameter sets the level of precision when using
Area type for Dynamic Convergence. A lower X (X2 for instance) requires l
ess resources and provides less precision while X8 is more precise but
requires more resources.
Manual Convergence: This parameter controls the manual convergence
of the virtual cameras.
Near Clip Plane: Controls the virtual cameras near clip plane in meters.
This value represents the minimum distance where the virtual cameras
start to render the scene.
Far Clip Plane: Controls the virtual cameras far clip plane in meters. This
value represents the maximum distance where the scene is rendered.
Player Height: Player height expressed in meters. It represents the point
where the players virtual head will rotate.
Active Menu: Activate or deactivate the ImmersiON-VRelia menu when
the app runs on a device. If this menu is active, it allows users to control a
few parameters like FOV, IPD or Convergence. You will find a save/load
configurations option too. There you can save or load a desired set of
parameters letting the user to get the best configuration possible
according to his/her particular visual requirements and phone used.

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

13

3. Project Configuration
Here are some steps to follow for Android project configuration and AlterSpace
compatibility.

3.1. Android Setup

You must have Android Development Tools installed and their path
configured in the Unity preferences section for External Tools / Android
SDK Location.

You must select Android platform from Unitys Build Settings.

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

14

 In Unitys Player Settings for Resolution and Presentation configure

the orientation parameter to Landscape Left.

For

a stereoscopic Splash Screen, you must select the provided

ImmersiONVRelia splash screen at Assets / ImmersiONVRelia / Textures /
LaunchScreen.png.

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

15

3.2. AlterSpace Connectivity

Fill

in your Company Name and Product Name and in Other Settings the
Bundle Identifier.

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

16

 Next we are going to explain how to change the AndroidManifest.xml.

You have two different options:
Option 1. Modifiy the file with the ImmersiON-VRelia tool:
Opening the menu ImmersiON-VRelia /Tools / Android Scheme Utility.
This option will display a floating menu where you can write your Android
Scheme in the required field. You will modify the AndroidManifest.xml
pushing the button Set scheme.

If you want to use a personalized AndroidManifest with this option, first

you must place it in the folder Assets / Plugins / Android and overwrite
the default file. Now if you use the ImmersiON-VRelia tool it will add the
Android Scheme info to your file.

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

17

Option 2, Modifying the file manually:

Please open the AndroidManifest.xml file located in the folder Assets /
Plugins / Android and fill in the same names that in the previous step to
enable Alterspace communication with your app:
<package="com.your_company.your_product">
<data android:scheme="your.android.scheme" />

Open the ImmersiONVReliaMain.cs located at Assets/ImmersiONVRelia/

Scripts and change the Start function at this line (change this to true):
inputManager.callAlterspace = true;
Once set to true, the input manager will automatically return to the
Alterspace when your app closes.
If your scene uses the Dynamic Convergence feature, the objects in
your scene must have colliders that must to be included in the detection
layer that Dynamic Convergence uses. The detail quality of this colliders
will affect the efficiency detecting objects of the Dynamic Convergence
script.

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

18

4.

Controls & Input

The SDK provides some scene managers which are coordinated through
the ImmersiON-Vrelia Main object:
Input Manager: The SDK uses a personalized Input Manager to
control the proprietary menus and the custom controller.
The following controls are included by default with this SDK, and they are
optimized for use with the ImmersiON-VRelia ViaPlay official gamepad.

Gamepad

Keyboard

SDK

Input manager names

Left Stick

W,A,S,D

Movecontroller

Horizontal, Vertical

Right Stick

9,I,O,P

Rotate player

Horizontal2, Vertical2

D-pad

8,4,6,2(numpad)

Modify menu

HorizontalDPad,
VerticalDPad

--

BtnY

--

BtnX

--

BtnB

--

BtnA

Start

Return

Show/hide menu

Show/hide menu

Select

Backspace

--

Select

Home

--

--

--

Menu

--

--

--

Back

--

--

--

L Shoulder Axis

--

LShoulderAxis

R Shoulder Axis

--

RShoulderAxis

L Shoulder Button

--

LShoulderButton

R Shoulder Button

--

RShoulderButton

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

19

5. Performance and Stereoscopic

Comfort
5.1. Optical correction
Distortion correction use significant amount of resources. They are crucial
to the presentation of a higher quality image on lens based VR hardware.
If your app is not getting high enough frames per second, disable them.
This will especially improve head tracking response and reduce lag at the
expense of comfort.

5.2. Image Effects

Using Unitys image effects on mobile devices can cause a significant
performance drop. However, enabling some post-effects like Antialiasing
As Post Effect can significantly improve the visual quality and comfort
level in VR. If you use this Antialiasing effect please set it to
FXAA3Console. Please avoid the antialiasing provided with Unity Quality
Settings.

5.3. Dynamic Convergence

Dynamic Convergence will provide enhanced visual comfort by
dynamically updating the convergence of the virtual cameras a
simulation of how our eyes focus on objects.
This is especially helpful for greatly enhanced depth effects when you
come very close to
objects inthe scene. This feature has a very low
performance impact. Dynamic Convergence requires additional care and
setup, but it is well worth the effort.
The more detailed your colliders are, the better the surface detection will
be. We recommend approximating objects using the basic colliders
provided by Unity.
When using the Dynamic Convergence feature, the objects in your scene
must have colliders that are contained in the detection layer that
Dynamic Convergence uses. The detail quality of this colliders will affect
the efficiency detecting objects of the Dynamic Convergence script.
If you use Dynamic Convergence with animated objects, such objects
must include a Rigid Body component. All such objects must also be in
the detection layer that Dynamic Convergence uses. (Please check VR
parameters).

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

20

5.4. Tips
We suggest to import the SDK TimeManager.asset and use their
Fixed Timestep and
Maximum Allowed Timestep to get better
performance with Unity physics.
Please setGraphics Level to the value Force Open GL ES 2.0 in
PlayerSettings / Other Settings option.

Copyright 2015 ImmersiON-VRelia Inc. All Rights Reserved.

21