Class ARTrackableManager<TSubsystem, TSubsystemDescriptor, TProvider, TSessionRelativeData, TTrackable>
A generic manager for components generated by features detected in the physical environment.
Inheritance
Inherited Members
Namespace: UnityEngine.XR.ARFoundation
Syntax
[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 |
| TSubsystemDescriptor | The |
| TProvider | The provider associated with the |
| 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_PendingAddsField Value
| Type | Description |
|---|---|
| Dictionary<TrackableId, TTrackable> |
m_Trackables
A dictionary of all trackables, keyed by TrackableId.
Declaration
protected Dictionary<TrackableId, TTrackable> m_TrackablesField 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 |
|---|---|
| Boolean | Returns |
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 |
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 XROrigin. |
Returns
| Type | Description |
|---|---|
| TTrackable | A new |
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 |
|---|---|
| Boolean |
|
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 |
|---|---|
| UnityEngine.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
OnEnable()
Creates the TSubsystem.
Declaration
protected override void OnEnable()Overrides
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(Boolean)
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 |
|---|---|---|
| Boolean | active | If |
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()