[RequireComponent(typeof(XROrigin))]
[DisallowMultipleComponent]
public abstract class ARTrackableManager<TSubsystem, TSubsystemDescriptor, TProvider, TSessionRelativeData, TTrackable> : SubsystemLifecycleManager<TSubsystem, TSubsystemDescriptor, TProvider> where TSubsystem : TrackingSubsystem<TSessionRelativeData, TSubsystem, TSubsystemDescriptor, TProvider>, new() where TSubsystemDescriptor : SubsystemDescriptorWithProvider<TSubsystem, TProvider> where TProvider : SubsystemProvider<TSubsystem> where TSessionRelativeData : struct, ITrackable where TTrackable : ARTrackable<TSessionRelativeData, TTrackable>

Type Parameters

Name	Description
TSubsystem	The `Subsystem` which provides this manager data.
TSubsystemDescriptor	The `SubsystemDescriptor` required to create the Subsystem.
TProvider	The provider associated with the `TSubsystem`.
TSessionRelativeData	A concrete struct used to hold data provided by the Subsystem.
TTrackable	The type of component that this component will manage (that is, create, update, and destroy).

Remarks

When the manager is informed that a trackable has been added, a new GameObject is created with an ARTrackable component on it. If ARTrackableManager<TSubsystem, TSubsystemDescriptor, TProvider, TSessionRelativeData, TTrackable> is not null, then that Prefab will be instantiated.

Fields

m_PendingAdds

A dictionary of trackables added via CreateTrackableImmediate(TSessionRelativeData) but not yet reported as added.

Declaration

protected Dictionary<TrackableId, TTrackable> m_PendingAdds

Field Value

Type	Description
Dictionary<TrackableId, TTrackable>

m_Trackables

A dictionary of all trackables, keyed by TrackableId.

Declaration

protected Dictionary<TrackableId, TTrackable> m_Trackables

Field Value

Type	Description
Dictionary<TrackableId, TTrackable>

Properties

gameObjectName

The name prefix that should be used when instantiating new GameObjects.

Declaration

protected abstract string gameObjectName { get; }

Property Value

Type	Description
string

origin

The XROrigin which will be used to instantiate detected trackables.

Declaration

protected XROrigin origin { get; }

Property Value

Type	Description
XROrigin

sessionOrigin

(Deprecated) The XROrigin which will be used to instantiate detected trackables.

Declaration

[Obsolete("'sessionOrigin' has been obsoleted; use 'origin' instead. (UnityUpgradable) -> origin", false)]
protected XROrigin sessionOrigin { get; }

Property Value

Type	Description
XROrigin

trackables

A collection of all trackables managed by this component.

Declaration

public TrackableCollection<TTrackable> trackables { get; }

Property Value

Type	Description
TrackableCollection<TTrackable>

Methods

Awake()

Invoked by Unity once when this component wakes up.

Declaration

protected virtual void Awake()

CanBeAddedToSubsystem(TTrackable)

Determines whether an existing ARTrackable<TSessionRelativeData, TTrackable> can be added to the underlying subsystem.

Declaration

protected bool CanBeAddedToSubsystem(TTrackable trackable)

Parameters

Type	Name	Description
TTrackable	trackable	An existing ARTrackable<TSessionRelativeData, TTrackable> to add to the underlying subsystem.

Returns

Type	Description
bool	Returns `true` if this manager is enabled, has a valid subsystem, and `trackable` is not already being tracked by this manager. Returns `false` otherwise.

Remarks

If trackable has not been added yet (that is, it is not tracked by this manager) and the manager is either disabled or does not have a valid subsystem, then the trackable's pending state is set to true.

Exceptions

Type	Condition
ArgumentNullException	Thrown if `trackable` is `null`.

CreateTrackableFromExisting(TTrackable, TSessionRelativeData)

Creates the native counterpart for an existing ARTrackable<TSessionRelativeData, TTrackable> added with a call to AddComponent, for example.

Declaration

protected void CreateTrackableFromExisting(TTrackable existingTrackable, TSessionRelativeData sessionRelativeData)

Parameters

Type	Name	Description
TTrackable	existingTrackable	The existing trackable component.
TSessionRelativeData	sessionRelativeData	The AR data associated with the trackable. This usually comes from the trackable's associated subsystem

CreateTrackableImmediate(TSessionRelativeData)

Creates a TTrackable immediately and leaves it in a "pending" state.

Declaration

protected TTrackable CreateTrackableImmediate(TSessionRelativeData sessionRelativeData)

Parameters

Type	Name	Description
TSessionRelativeData	sessionRelativeData	The data associated with the trackable. All spatial data should be relative to the Unity.XR.CoreUtils.XROrigin.

Returns

Type	Description
TTrackable	A new `TTrackable`

Remarks

Trackables are usually created, updated, or destroyed during Update(). This method creates a trackable immediately and marks it as "pending" until it is reported as added by the subsystem. This is useful for subsystems that deal with trackables that can be both detected and manually created.

This method does not invoke OnTrackablesChanged(List<TTrackable>, List<TTrackable>, List<TTrackable>), so no "added" notifications will occur until the next call to Update().

The trackable will appear in the trackables collection immediately.

DestroyPendingTrackable(TrackableId)

If in a "pending" state and destroyOnRemoval is true, this method destroys the trackable's GameObject. Otherwise, this method has no effect.

Declaration

protected bool DestroyPendingTrackable(TrackableId trackableId)

Parameters

Type	Name	Description
TrackableId	trackableId	The id of the trackable to destroy.

Returns

Type	Description
bool	`True` if the trackable is "pending" (that is, not yet reported as "added").

Remarks

Trackables are usually removed only when the subsystem reports they have been removed during Update().

This method will immediately remove a trackable only if it was created by CreateTrackableImmediate(TSessionRelativeData) and has not yet been reported as added by the subsystem.

This can happen if the trackable is created and removed within the same frame, as the subsystem might never have a chance to report its existence. Derived classes should use this if they support the concept of manual addition and removal of trackables, as there might not be a removal event if the trackable is added and removed quickly.

If the trackable is not in a pending state (that is, it has already been reported as "added"), then this method does nothing.

This method does not invoke OnTrackablesChanged(List<TTrackable>, List<TTrackable>, List<TTrackable>), so no "removed" notifications will occur until the next call to Update(). "Removed" notifications will only occur if it was previously reported as "added".

GetPrefab()

The Prefab that should be instantiated when adding a trackable. Can be null.

Declaration

protected virtual GameObject GetPrefab()

Returns

Type	Description
GameObject	The prefab should be instantiated when adding a trackable.

OnAfterSetSessionRelativeData(TTrackable, TSessionRelativeData)

Invoked just after session-relative data has been set on a trackable.

Declaration

protected virtual void OnAfterSetSessionRelativeData(TTrackable trackable, TSessionRelativeData sessionRelativeData)

Parameters

Type	Name	Description
TTrackable	trackable	The trackable that has just been updated.
TSessionRelativeData	sessionRelativeData	The session relative data used to update the trackable.

OnCreateTrackable(TTrackable)

Invoked after creating the trackable. The trackable's sessionRelativeData property will already be set.

Declaration

protected virtual void OnCreateTrackable(TTrackable trackable)

Parameters

Type	Name	Description
TTrackable	trackable	The newly created trackable.

OnDisable()

Stops the TSubsystem.

Declaration

protected override void OnDisable()

Overrides

SubsystemLifecycleManager<TSubsystem, TSubsystemDescriptor, TProvider>.OnDisable()

OnEnable()

Creates the TSubsystem.

Declaration

protected override void OnEnable()

Overrides

SubsystemLifecycleManager<TSubsystem, TSubsystemDescriptor, TProvider>.OnEnable()

OnTrackablesChanged(List<TTrackable>, List<TTrackable>, List<TTrackable>)

Invoked when trackables have change (that is, they were added, updated, or removed). Use this to perform additional logic, or to invoke public events related to your trackables.

Declaration

protected virtual void OnTrackablesChanged(List<TTrackable> added, List<TTrackable> updated, List<TTrackable> removed)

Parameters

Type	Name	Description
List<TTrackable>	added	A list of trackables added this frame.
List<TTrackable>	updated	A list of trackables updated this frame.
List<TTrackable>	removed	A list of trackables removed this frame. The trackable components are not destroyed until after this method returns.

SetTrackablesActive(bool)

Iterates over every instantiated ARTrackable<TSessionRelativeData, TTrackable> and activates or deactivates its GameObject based on the value of active. This calls GameObject.SetActive on each trackable's GameObject.

Declaration

public void SetTrackablesActive(bool active)

Parameters

Type	Name	Description
bool	active	If `true` each trackable's `GameObject` is activated. Otherwise, it is deactivated.

Update()

Update is called once per frame. This component's internal state is first updated, and then an event notifying whether any trackables have been added, removed, or updated is invoked by the derived manager.

Declaration

protected virtual void Update()