Using ARDK Feature Managers

The Manager components provide simple Unity-friendly ways to access ARDK features.

Overview

The core interface of ARDK is designed for expressivity and flexibility, and so mostly lives as C# code not directly tied into Unity. This means that there is a lot of C# code required to integrate features into a game; i.e, managing object lifetimes, configuring AR sessions, and passing data to game components.

Managers provide a more streamlined interface for the ARDK features each component covers. For example, for most AR features there is a Manager component that handles enabling that feature for an AR session, configuring it, and surfacing data and events in Unity friendly formats.

How Managers Configure Features

The general pattern is that if a Manager component is enabled, it will enable its features in the active ARSession ‘s ARConfiguration. Values that need configuration (like whether to detect horizontal or vertical planes) will be exposed as properties on the Manager, and the Manager will handle setting the requires values in the ARConfiguration appropriately.

Enabling/disabling the Manager or changing its configuration values will automatically re-run the ARSession with an updated ARConfiguration at the start of the next Unity Update loop. This means that within a Unity Update frame, multiple changes can be made through Managers without inefficiently triggering multiple ARSession re-runs. If no ARSession is constructed or running, then enabling/disabling a Manager will have no perceivable effect until the next time an ARSession is run.

Destroying a Manager includes Disabling it, and so will disable any configuration values controlled by it.

Running the ARSession Manually

The config changes provided by each Manager are automatically collected whenever the ARSession is run, whether it is run automatically due to a change in one of the Managers or manually by user code. This means that it is safe to call Run on the ARSession object yourself. You might want to do this to apply your own configuration values, for example.

Adding Custom Configuration values to a Scene With Managers

If you do manually run the ARSession, the ARConfiguration that is passed in is stored and all the Managers will apply their configuration changes on top of it.

For example, say an ARSession was manually run with an ARConfiguration that had its PlaneDetection value set to PlaneDetection.Horizontal.

// Completely compatible code with all feature managers in your scene,
// excluding the ARPlaneManager.
public void RunSession()
{
   var arSession = ARSessionFactory.Create();
   var config = ARWorldTrackingConfigurationFactory.Create();
   config.PlaneDetection = PlaneDetection.Horizontal;
   arSession.Run(config);
}

If there was an ARMeshManager in the scene the IsMeshingEnabled value on the ARConfiguration would be overridden but the PlaneDetection value would be left alone. Even if the ARMeshManager was later disabled, when the ARSession is re-run the PlaneDetection value would still be PlaneDetection.Horizontal. However, if an ARPlaneManager was added to the scene it would begin overriding the PlaneDetection value, even if it was disabled.

Taking Manual Control Over The Lifecycle

By default any Managers created through the Inspector will have their behavior controlled based on the lifecycle of the Unity component. They will do any initialization logic during Awake, enable their features during OnEnable, disable their features during OnDisable, and release any resources held during OnDestroy. If, for whatever reason, you need to take manual control over the lifecycle of a Manager this is possible by setting its Manage Using Unity Lifecycle property to false in the inspector. The public methods Initialize, EnableFeatures, DisableFeatures, and Deinitialize can then be called to control the Manager. Once a Manager has been deinitialized it is no longer able to be re-initialized, if you want to re-enable it at that point you’ll need to destroy and recreate the component.

Any Managers created programatically, such as through GameObject.AddComponent, will not have their lifecycle managed by Unity. If you need to instantiate a Manager at runtime that is controlled by Unity, it is recommended to create and instantiate a prefab instead.

Managers And What They Do

This is a comprehensive list of all the managers and what features/functionality they control/provide.

Name

Functionality

Details

ARSessionManager

AR session lifecycle

Creates, runs, and provides a reference to an ARSession instance.

NetworkSessionManager

Multiplayer networking session lifecycle

Creates, runs, and provides a reference to a MultipeerNetworking instance.

ARNetworkingManager

Multiplayer AR

Creates, runs, and provides a reference to an ARNetworking instance that uses ARSession and MultipeerNetworking instances provided by an ARSessionManager and an NetworkSessionManager.

CapabilityChecker

Device AR capability

Determines whether a device is AR-capable and provides events so that other code can depend on a device being capable.

ARPlaneManager

Plane finding

Enables plane detection, and optionally maintains a set of GameObjects that are positioned and scaled to match detected planes.

ARImageDetectionManager

Image detection

Enables detection of specified images.

ARDepthManager

Depth

Enables depth features, and optionally processes depth data before surfacing it to listeners.

ARSemanticSegmentationManager

Semantic segmentation

Enables semantic segmentation, and optionally processes semantic data before surfacing it to listeners.

DepthMeshOcclusionManager

Depth-based occlusions

Uses depth data to add real world occlusion to all rendered objects. This manager is being deprecated in favor of setting ARDepthManager.OcclusionMode to ScreenSpaceMesh.

ARMeshManager

Environmental meshing

Maintains a set of GameObjects with Meshes that approximate surfaces in the real world.

FeaturePreloadManager

Environmental meshing

Maintains a set of GameObjects with Meshes that approximate surfaces in the real world.