Vuforia Engine Lifecycle in Unity

Vuforia Engine provides an API that extends the Unity Editor with Vuforia Engine objects and scripting classes. Most authoring tasks for creating AR experiences with Vuforia Engine can be done with the Vuforia Engine GameObjects directly in the Unity Editor. The scripting API offers extended options and control over your AR application

Introduction

In this guide, we provide a brief introduction and examples on managing the Vuforia Engine lifecycle with VuforiaApplication, configure Vuforia with VuforiaBehaviour, creating Observers, retrieving information on tracked targets, and other common management tasks.

Managing the Vuforia Engine Life Cycle

In Unity, the Vuforia Engine life cycle is managed automatically by default:

  • Vuforia Engine is initialized automatically once when the application is started
  • It is deinitialized when the application is quit
  • Loading a Unity scene with any Vuforia Engine game objects, such as target observers or an ARCamera, will start Vuforia Engine, and unloading the scene will stop it again.

This functionality is coupled to the VuforiaBehaviour component on the main camera. If a scene that uses Vuforia game objects does not contain a VuforiaBehaviour, one will automatically be created and attached to the main camera object, starting Vuforia and taking care of camera control and video background rendering.

There are several ways to override this default behavior:

  • Vuforia Engine initialization can be delayed by checking the Delayed Initialization checkbox in the Vuforia Configuration:

This for instance makes sense if there is a special AR mode in your application that is not used by every end user. Other use cases include initializing Vuforia Engine with a custom driver or a specific Fusion Provider.

In those cases, Vuforia Engine can be initialized manually from scripting API before loading the first scene containing Vuforia Engine functionality: VuforiaApplication.Instance.Initialize();.

  • When loading a scene containing Vuforia Engine game objects, such as Targets or an ARCamera, Vuforia Engine can be prevented from starting by disabling the VuforiaBehaviour component on the ARCamera

It can be enabled at a later time from a script to start Vuforia Engine in this scene.

In some cases, it is necessary to execute code at a certain point during the Vuforia Engine life cycle. Some examples include:

  • Checking for initialization errors after Vuforia Engine attempted to initialize.
  • Creating an Observer at runtime to track a target or accessing the properties of an Observer after Vuforia Engine has started.
  • Setting a specific camera focus mode after Vuforia Engine has started.
  • Deleting app-level resources after Vuforia Engine stopped or deinitialized completely.

The VuforiaApplication instance provides callbacks for all these life cycle events. They can be subscribed to from application level scripts:

Vuforia Engine has initialized

Subscribe to VuforiaApplication.Instance.OnVuforiaInitialized to run code that requires Vuforia Engine to be initialized:

void Awake()
{
    VuforiaApplication.Instance.OnVuforiaInitialized += OnVuforiaInitialized;
}

void OnVuforiaInitialized(VuforiaInitError error)
{
    if(error != VuforiaInitError.NONE)
        // Handle initialization errors
}

Vuforia Engine has started

Subscribe to OnVuforiaStarted to run events after Vuforia was started:

void Start()
{
    VuforiaApplication.Instance.OnVuforiaStarted += OnVuforiaStarted;
}

void OnVuforiaStarted()
{
    // turn device flashlight on
    VuforiaBehaviour.Instance.CameraDevice.SetFlash(true);
}

Vuforia Engine has stopped

Subscribe to OnVuforiaStopped to run events after Vuforia was stopped:

void Start()
{
     VuforiaApplication.Instance.OnVuforiaStopped += OnVuforiaStopped;
}

Vuforia Engine has paused or resumed

Subscribe to OnVuforiaPaused to run events after Vuforia paused or resumed, e.g. in order to set a specific focus mode again after the application as paused:

void Start()
{
     VuforiaApplication.Instance.OnVuforiaPaused += OnVuforiaPaused();
}

void OnVuforiaPaused(bool paused)
{
    if (!paused)
        // set focus to infinity:
        VuforiaBehaviour.Instance.CameraDevice.SetFocusMode(FocusMode.FOCUS_MODE_INFINITY);
}

Vuforia Engine has deinitialized

Subscribe to OnVuforiaDeinitialized with a subscriber method to terminate the VuforiaBehaviour and all tracking operations:

void Start()
{
     VuforiaApplication.Instance. OnVuforiaDeinitialized += OnVuforiaDeinitialized;
}

VuforiaConfiguration

Other Vuforia Configuration options can be found in the VuforiaConfiguration inspector that is available from the ARCamera GameObject or from Window -> Vuforia Configuration in the Unity.

Editor menu:

Some settings, like the App License Key, is used when initializing Vuforia Engine. Others, like the ARCore requirement setting, is a build-time setting that is evaluated when building Unity apps.
Finally, some settings, like tracking the device pose, is evaluated before Vuforia Engine is started in a Unity scene.

These settings can also be accessed at runtime, e.g. to set the License key from some key store or disable device tracking for some scenes:

VuforiaConfiguration.Instance.Vuforia.LicenseKey = myLicenseKey;
VuforiaConfiguration.Instance.DeviceTracker.AutoInitAndStartTracker = false;

Vuforia Engine State in Unity

In Unity, Vuforia Engine will automatically update the currently observed state for all targets and observers every frame. Changes to the Unity scene, like the positions of targets will be applied automatically. There are therefore no specific API calls necessary to manually retrieve updates.

For some operations, it is important to run your application logic after Vuforia Engine has updated the state in a frame. This includes:

  • Calculating the distance between two targets based on their latest positions.
  • Access Illumination data from VuforiaBehaviour.Instance.World.IlluminationData
  • Access the most up-to-date camera image from VuforiaBehaviour.Instance.CameraDevice.GetCameraImage(…)

Use OnStateUpdated for these purposes:

VuforiaBehaviour.Instance.World.OnStateUpdated += OnStateUpdated;

Create an Observer

As an alternative to setting up a target using the Vuforia game objects in the Unity Editor, a target can also be loaded and observed at runtime with the ObserverFactory class. Its member functions each take a varying number of overloads to create a target. For example, creating an Image Target from a device database would look like this:

var mImageTarget = VuforiaBehaviour.Instance.ObserverFactory.CreateImageTarget(
            "Vuforia/VuforiaMars_Images.xml ",
            "Astronaut");

Activate and deactivate a target with

mImageTarget.enabled = true/false;

Retrieve the Target Status and Status Info

By default, augmentations are rendered when a target is tracked. The DefaultObserverEventHandler is a Vuforia provided component that offers an interface for adding actions to On Target Found and On Target Lost.

You can even implement your own custom event handler script and change these events to implement your custom behavior.

Target Status

It is also possible to directly register for an Observer-specific status changed event and evaluate the current status directly:

modelTargetBehaviour.OnTargetStatusChanged += OnTargetStatusChanged;
void OnTargetStatusChanged(TargetStatus status)
{
    if (status.Status == Status.TRACKED && status.StatusInfo == StatusInfo.NORMAL)
    {
       // ...
    }
}

Device Tracking Management

The Device Pose Observer is used track the movement of the device in the environment and provide Extended Tracking for observed targets. Enable the device pose tracking in Vuforia Configuration or control it at runtime with enabled and the Reset() function:

VuforiaBehaviour.Instance.DevicePoseObserver.enabled = true;

The Device Pose Observer provides additional status information that varies depending on the type of device platform (ARKit, ARCore) and device type (Handheld, Eyewear). For details, see Target Poses and Status Info.

VuforiaBehaviour.Instance.DeviceBehaviour.OnTargetStatusChanged += OnDevicePoseStatusChanged;

Attach Content to a Target

With Vuforia Engine started, and a target loaded and observed, content can be added at runtime as a child to the target GameObject. The script below demonstrates a simple method for adding a prefab GameObject to the parent target at runtime on target found by inheriting from the DefaultObserverEventHandler script.

  1. In a Unity project, create a new script named MyPrefabInstantiator.
  2. Copy the code below and save the file.
  3. In the scene, add a Vuforia target GameObject from the menu GameObject -> Vuforia Engine -> <Vuforia Target>.
  4. Remove the existing DefaultObserverEventHandler component from the GameObject
  5. Add MyPrefabInstantiator to the target GameObject.
  6. Create a prefab or use an existing one and submit it to the myModelPrefab field.
  7. Test your target on your device or in Play Mode.
using UnityEngine;
using Vuforia;
 
public class MyPrefabInstantiator : DefaultObserverEventHandler
{
    ImageTargetBehaviour mImageTarget;
    public GameObject myModelPrefab;
 
    protected override void OnTrackingFound()
    {
        InstantiateContent();
    }
 
    void InstantiateContent()
    {
        if (myModelPrefab != null)
        {
            GameObject myModelTrf = Instantiate(myModelPrefab);
            myModelTrf.transform.parent = mImageTarget.transform;
            myModelTrf.transform.localPosition = new Vector3(0f, 0f, 0f);
            myModelTrf.transform.localRotation = Quaternion.identity;
            myModelTrf.transform.localScale = new Vector3(0.1f, 0.1f, 0.1f);
            myModelTrf.transform.gameObject.SetActive(true);
        }
   }
}

Error Handling

Use the VuforiaInitError to ensure Vuforia Engine has initialized properly as demonstrated in the DefaultInitializationHandler script:

void Start()
{
    VuforiaApplication.Instance.OnVuforiaInitialized += OnVuforiaInitialized;
}
void OnVuforiaInitialized(VuforiaInitError error)
{
    if(error != VuforiaInitError.NONE)
        // Error handling code
}