Cardboard Unity SDK Reference
Each instance can pick out a different region of the GUI texture to show (see
Rect below). Use the object's transform to position
and orient this region in space relative to the parent
CardboardGUI object. The mesh is automatically scaled to account for the aspect ratio of the overall
For each frame,
StereoController decides whether to render via the camera it is attached to (the mono camera)
or the stereo eyes that it controls (see
CardboardEye). You control this decision for all cameras at once by setting the value of
Multiple invocations per frame are OK: Subsequent calls merely yield the cached results of the first call. To minimize latency, it should be first called later in the frame (for example, in
Captures Unity's OnGUI pass in a texture which can then be rendered onto a mesh, such as a quad, in the scene (see
GazeInputModule emits the following events: Enter, Exit, Down, Up, Click, Select, Deselect,
and UpdateSelected. Scroll, drag and drop, move, and submit/cancel events are not emitted.
This section covers the specific purpose of the individual scripts and how they work together, whether within the provided prefabs or if you add them to the scene yourself.
This script provides an implemention of Unity's
BaseInputModule class, so that Canvas-based UI elements (uGUI)
can be selected by looking at them and pulling the trigger or touching the screen. See the Guide for
details concerning use.
Provides access to the underlying VR device, implemented in native code. There should only be one of these in a scene. An instance will be generated at runtime if needed, or you can add one via the Editor if you wish to customize its starting properties.
It is permissible for a
StereoController to contain another StereoController as a child. In this case, a
controlled by its closest
Some minor changes must be made to any script that uses OnGUI() in order to work with CardboardGUI. These are non-invasive and do not alter the behavior of the script when the app is not in VR Mode. The changes are as follows:
It is possible to add more such children to the CardboardGUI object. Just duplicate the
GUIScreen child in the Editor as needed,
adjust each child's Rect to pick out a different region of the OnGUI layer, and set its Transform to place that region in the scene. In this way you can completely rearrange the GUI layout when in VR Mode without
OnGUI() functions' code or behavior.
This prefab is for when you wish to keep your existing Camera object, usually because it is heavily wired with game logic and already moves exactly as needed for non-VR game play. Place this prefab as a child of the camera, and
then executeUpdate Stereo Cameras (or manually attach
StereoController to the camera) to complete the rig.
Draws all or part of the GUI texture captured by
CardboardGUI. It must be attached on a child gameobject of the
accompanied by a
The mesh will be used to draw the texture, and the collider used to check for intersections with the user's gaze for mouse positioning. The material used for rendering the texture is created and maintained internally by this script.
For technical reasons, the mono camera remains enabled for the initial portion of the frame. It is disabled only when rendering begins in
and is reenabled again at the end of the frame. This allows 3rd party scripts that use
Camera.main, for example, to refer the the mono camera even when VR
Mode is enabled.
Encapsulates a rotation and a translation. This is a convenience class that allows construction and value access either by Matrix4x4 or Quaternion+Vector3 types.
Note that matching by moving the eyes requires that the centerOfInterest object be non-null, or there will be no effect.
This value determines how much to match the mono camera's field of view. This is a fraction: 0 means no matching, 1 means full matching, and values in between are compromises. Reasons for not matching 100% would include preserving some VR-ness, and that due to the lens distortion the edges of the view are not as easily seen as when the phone is not in VR-mode.
To use it, add the script to a Lens Flare and clear the flare's Directional flag so that the flare is actually positional. This script keeps the flare at a distance well away from the mono camera along the flare's own forward vector, thus recreating the directional behavior, but with proper stereo parallax. The flare is repositioned relative to each camera that renders it.
By using multiple
CardboardGUIWindow children of the
you can build a VR Mode GUI layout that is arranged in space around the user. This layout is independent of the normal OnGUI layout when the app is not in VR Mode. The
on individual CardboardGUIWindows can be used to turn on or off the separate regions of the GUI.
This script should be attached to the Camera which represents the primary viewpoint of the player (such as Main Camera). At runtime it builds a mesh that will be textured with the camera's skybox material. The mesh is scaled up to just fit inside the far clipping plane, and kept centered on the camera's position.
Implements the same barrel distortion that is performed by the native code. It is used to show the effect of distortion correction when playing the scene in the Editor, and as the fall back when the native code distortion is not available or disabled.
The Inspector panel for this script includes a button Update Stereo Cameras. This performs the same action as described above for startup, but in the Editor. Use this to generate the rig if you intend to
customize it. This action is also available via Component -> Cardboard -> Update Stereo Cameras in the Editor’s main menu, and in the context menu for the
This prefab is intended to be a drop-in replacement for a normal Unity camera, such as Main Camera, primarily when the camera is simple, i.e. not already festooned with scripts. A brand new Unity project is a good time to use it. To apply it in the Editor, delete the camera in question and replace it with an instance of this prefab.
Attach this script to any game object that should match the user's head motion. By default, it continuously updates the local transform to the
Cardboard object. A target object may be specified to provide an alternate reference frame for the motion.
Each prefab is provided as a starting point for customization. It is a framework on which to attach additional scripts for your own needs. Elements under a Head node will maintain a fixed position on screen, thus acting like a Heads-up Display (HUD). Elements that are siblings of Head will maintain a fixed position and orientation relative to the overall point of view, thus acting more like a cockpit instrument panel.
This section describes the prefabs that are provided by the package.
This script must be added to any camera that should render stereo when the app is in VR Mode. This includes picture-in-picture windows, whether their contents are in stereo or not: the window itself must be twinned for stereo, regardless.
The FOV adjustment is done by moving the eyes toward or away from the COI so that it appears to have the same size on screen as it would in the mono camera. This is disabled if the COI is null.
The property is typically auto-initialized by Cardboard, but if you wish to customize the texture, you may assign to it in your code.
The following scripts customize the Inspector panels for some Cardboard components.
At startup the script ensures it has a full stereo rig, which consists of two child cameras with
CardboardEye scripts attached,
CardboardHead script somewhere in the hierarchy of parents and children for head tracking. The rig is created if necessary, the
attached to the controller itself. The child camera settings are then cloned or updated from the mono camera.
This script will typically be attached to directly to a Camera object, or to its parent if you need to offset the camera from the origin. Alternatively it can be inserted as a child of the Camera and parent of the
Do this if you already have steering logic driving the mono Camera and wish to have the user's head motion be relative to that. Note that in the latter setup, head tracking is visible only when VR Mode is enabled.
Another use for this variable is to preserve scene composition against differences in the optical FOV of various Cardboard models. In all cases, this value simply lets the mono camera have some control over the scene in VR mode, like it does in non-VR mode.
Features intended for supporting existing projects in older versions of Unity.
This prefab captures the OnGUI pass of a frame into a texture. It draws the texture on a quad in the scene, along with cursor image for the mouse pointer, if you specify one. It can move the mouse by tracking the user's gaze and it can read the trigger to "click" UI elements.
It is not recommended to use simple zooming for typical scene composition, as it conflicts with the VR need to match the user's head motion with the corresponding scene motion. This should be reserved for special effects such as when the player views the scene through a telescope or other magnifier (and thus the player knows that VR is going to be affected), or similar situations.
To use it, add an instance of the prefab to the scene. It should not be placed under a
CardboardHead if you want the user's
gaze to control the mouse, but can be if you use an alternative input device. The prefab contains one child called GUIScreen, which by default draws the entire screen's OnGUI layer on a single quad.
This can cause an annoying jitter because Unity, during this
LateUpdate() phase, will update the head object first on some
frames but second on others. If this is the case for your game, try switching the head to use
This prefab is a replacement for other cameras in the scene that also need head-tracking. It has a top-level object calledHead with a
Under that is the Camera child which has the
StereoController script, and then the Left and Right stereo eye cameras. Unlike CardboardMain,
the camera in this prefab is not tagged MainCamera.
Unity 4's built-in lens flares do not work correctly for stereo rendering when in Directional mode, for similar reasons as the skybox mentioned previously. This script can be attached to a Lens Flare to make it stereo-aware directional.
The Unity plugin package contains the following:
The prefab contains a top-level object called CardboardMain, which has a Cardboard script attached to it for controlling VR Mode settings. Under this is the Head object, which has a CardboardHead attached
for tracking the user's head motion. That in turn has a Main Camera child object, with the
StereoController script attached. This camera
is tagged as a MainCamera so that the Unity property
Camera.main will find it. Finally there are the Left and Right stereo eye cameras
at the bottom of the hierarchy.
Unity 4's built-in skybox backgrounds do not work correctly for stereo rendering. Since the same exact image is rendered to each eye, the background has zero parallax. Given the optics of Cardboard, this yields an effective stereo depth that is likely right in the middle, or worse, front of the scene. The results in a visually painful parallax clash with other objects in the scene.
Attach this script to the same object as
CardboardGUI itself. It can draw a cursor image into the GUI texture to show the
location of the mouse pointer. It supports moving the mouse with the user's gaze, and clicking on the UI with the trigger, but other mouse-controlling devices, such as gamepads, will work as well.
This section describes scripts provided for legacy purposes.
Rendering of the
CardboardEye Camera is controlled by the StereoController and not by the normal Unity render pipeline. As
CardboardEye Camera will generally have
In each frame, all camera settings (for example, culling mask, field of view, near/far clipping distances, etc) are copied from the parent mono camera before rendering. Therefore it is meaningless to set the properties on the
Camera attached to the
Unlike the other prefabs, this setup places the head-tracked node below the Main Camera. Therefore, only the stereo cameras are affected by the user's head motion.
Renders the same view as the parent StereoController's mono camera, but for a specific stereo eye. The view and projection matrices are continuously updated from the
of the Cardboard object. The render output is directed to Cardboard's
StereoScreen render texture, either to the left half or right half depending on the
A custom editor for properties on the
Cardboard script. This appears in the Inspector window of a Cardboard object. Its purpose
is to allow changing the
Cardboard.SDK object's properties from their default values. In particular, the
value can be set while playing in the Editor in order to fake the phone being inserted into or removed from a Cardboard.
In some cases you may need two instances of CardboardHead, referring to two different targets (one of which may be the parent), in order to split where the rotation is applied from where the positional offset is applied. Use
trackPosition properties in this
CardboardGUI and its Window children have visibility controls that you can use to convert a non-transient (i.e. always
on) UI to a transient (popup) UI when in VR Mode. Non-transient UI is usually placed along the edges of the screen, which in HMD stereo systems are extremely hard to see. For VR Mode, you will likely need to rearrange the UI to appear front-and-center, perhaps
depending on which way the user looks. This obscures the scene itself, unless the UI can be hidden when not needed.
A custom editor for the
StereoController script. It exists to add the Update Stereo Cameras button to
StereoController's Inspector window, and to the corresponding main menu entry and Camera context menu command. The usage of the these actions is described
StereoController.cs section above.
Position the GUI mesh in 3D space using the gameobject's transform. Note: do not place the object as a child of the CardboardHead, or the user will not be able to look at different parts of the UI because it will move with them. It is better to place it as a sibling of the Head object.
This section describes the prefabs that are provided by the package for legacy purposes.