Class XRTargetFilter

Target Filter that uses a list of evaluator objects to filter Interactable targets (candidates) returned by the Interactor each frame. You can edit the evaluator list and the evaluators properties in the Inspector.

Inheritance
Object
Object
Component
Behaviour
MonoBehaviour
XRBaseTargetFilter
XRTargetFilter
Inherited Members
Namespace: UnityEngine.XR.Interaction.Toolkit.Filtering
Syntax
[AddComponentMenu("XR/XR Target Filter", 11)]
[HelpURL("https://docs.unity3d.com/Packages/com.unity.xr.interaction.toolkit@2.1/api/UnityEngine.XR.Interaction.Toolkit.Filtering.XRTargetFilter.html")]
public sealed class XRTargetFilter : XRBaseTargetFilter, IXRTargetFilter, IEnumerable<XRTargetEvaluator>, IEnumerable
Remarks

The virtual and abstract methods on the Target Evaluators are designed to be called by this Filter rather than being called directly by the user in order to maintain consistency between all objects involved in the filtering of an interaction.

Properties

canProcess

Whether this Target Filter can process and filter targets. Filters that can process targets receive calls to Process(IXRInteractor, List<IXRInteractable>, List<IXRInteractable>), filters that cannot process do not.

Declaration
public override bool canProcess { get; }
Property Value
Type Description
Boolean
Overrides

evaluatorCount

The number of evaluators this filter has.

Declaration
public int evaluatorCount { get; }
Property Value
Type Description
Int32

Methods

AddEvaluator(Type)

Adds an instance of the given evaluator type to this filter.

Declaration
public XRTargetEvaluator AddEvaluator(Type evaluatorType)
Parameters
Type Name Description
Type evaluatorType

Type of the evaluator to be added.
Returns
Type Description
XRTargetEvaluator

The added evaluator or null if the instance could not be added.
Remarks

If the filter is processing the added evaluator will only participate from the next filtering process.

AddEvaluator<T>()

Adds an instance of the given evaluator type to this filter.

Declaration
public T AddEvaluator<T>()
    where T : XRTargetEvaluator
Returns
Type Description
T

The added evaluator or null if the instance could not be added.
Type Parameters
Name Description
T

Type of the evaluator to be added.
Remarks

If the filter is processing the added evaluator will only participate from the next filtering process.

GetEnabledEvaluators(List<XRTargetEvaluator>)

Returns the enabled evaluators in this filter.

Declaration
public void GetEnabledEvaluators(List<XRTargetEvaluator> results)
Parameters
Type Name Description
List<XRTargetEvaluator> results

List to receive the results.
Remarks

Clears results before adding to it.

Exceptions
Type Condition
ArgumentNullException

results is null.

GetEnumerator()

Returns an enumerator to iterate through the evaluators in this Target Filter.

Declaration
public IEnumerator<XRTargetEvaluator> GetEnumerator()
Returns
Type Description
IEnumerator<XRTargetEvaluator>

Returns an IEnumerator object that can be used to iterate through the evaluators.
Implements

GetEvaluator(Type)

Returns the first Target Evaluator of the specified type if this Target Filter has one.

Declaration
public XRTargetEvaluator GetEvaluator(Type type)
Parameters
Type Name Description
Type type

The Type of the Evaluator to retrieve.
Returns
Type Description
XRTargetEvaluator

Returns the first Evaluator of the specified type. Returns null if this Filter has no Evaluator of the specified Type in it.
Exceptions
Type Condition
ArgumentNullException

type is null.
See Also

GetEvaluator<T>()

Returns the first Target Evaluator of the specified Type if this Target Filter has one.

Declaration
public T GetEvaluator<T>()
Returns
Type Description
T

Returns the first Evaluator of the specified Type. Returns null if this Filter has no Evaluator of the specified Type in it.
Type Parameters
Name Description
T

The Type of the Evaluator to retrieve.
Remarks

Generic version of GetEvaluator(Type).

GetEvaluatorAt(Int32)

Gets the evaluator in the given index.

Declaration
public XRTargetEvaluator GetEvaluatorAt(int index)
Parameters
Type Name Description
Int32 index

Index of the evaluator to return. Must be smaller than evaluatorCount and not negative.
Returns
Type Description
XRTargetEvaluator

The evaluator in the given index.
Remarks

The total number of evaluators can be provided by evaluatorCount.

GetEvaluators(List<XRTargetEvaluator>)

Returns the evaluators in this filter.

Declaration
public void GetEvaluators(List<XRTargetEvaluator> results)
Parameters
Type Name Description
List<XRTargetEvaluator> results

List to receive the results.
Remarks

Clears results before adding to it.

Exceptions
Type Condition
ArgumentNullException

results is null.

GetLinkedInteractors(List<IXRInteractor>)

Returns the Interactors linked to this filter.

Declaration
public void GetLinkedInteractors(List<IXRInteractor> results)
Parameters
Type Name Description
List<IXRInteractor> results

List to receive the results.
Remarks

Clears results before adding to it.

Exceptions
Type Condition
ArgumentNullException

results is null.

Link(IXRInteractor)

Called by Unity when the given Interactor links to this filter. Use this to do any code initialization for the given Interactor.

Declaration
public override void Link(IXRInteractor interactor)
Parameters
Type Name Description
IXRInteractor interactor

The Interactor being linked to this filter.
Overrides

MoveEvaluatorTo(XRTargetEvaluator, Int32)

Moves the given evaluator to the given index.

Declaration
public void MoveEvaluatorTo(XRTargetEvaluator evaluator, int newIndex)
Parameters
Type Name Description
XRTargetEvaluator evaluator

Evaluator to update the index.
Int32 newIndex

New index of the evaluator.

Process(IXRInteractor, List<IXRInteractable>, List<IXRInteractable>)

Called by the linked Interactor to filter the Interactables that it could possibly interact with this frame. Implement your custom logic to filter the Interactable candidates in this method.

Declaration
public override void Process(IXRInteractor interactor, List<IXRInteractable> targets, List<IXRInteractable> results)
Parameters
Type Name Description
IXRInteractor interactor

The linked Interactor whose Interactable candidates (or targets) are being filtered.
List<IXRInteractable> targets

The read only list of candidate Interactables to filter. This list should not be modified.
List<IXRInteractable> results

The results list to populate with the filtered results. This list should be sorted by priority (with highest priority first).
Overrides
Remarks

For each Interactable (in the given targets list), the evaluator list is processed in order.
Each enabled evaluator calculates an interaction score for the supplied Interactable. A 0 or negative score immediately stops the processing for the current Interactable.
These scores are multiplied together to get the final interaction score for the Interactable. A negative final score excludes the Interactable as a candidate for interaction (it won't added to the results list).
This final score is then used to sort (in descending order) the Interactables in the results list.

Exceptions
Type Condition
InvalidOperationException

Throws when this filter is currently processing and filtering Interactables.

RemoveEvaluator(XRTargetEvaluator)

Removes the given evaluator from this filter. The evaluator being removed is disabled and disposed.

Declaration
public void RemoveEvaluator(XRTargetEvaluator evaluator)
Parameters
Type Name Description
XRTargetEvaluator evaluator

Evaluator to be removed.
Remarks

You cannot call this method while the filter is processing.

RemoveEvaluatorAt(Int32)

Removes the evaluator at the given index from this filter. The evaluator being removed is disabled and disposed.

Declaration
public void RemoveEvaluatorAt(int index)
Parameters
Type Name Description
Int32 index

Index of the evaluator to be removed. Must be smaller than evaluatorCount and not negative.
Remarks

The total number of evaluators can be provided by evaluatorCount. You cannot call this method while the filter is processing.

Unlink(IXRInteractor)

Called by Unity when the given Interactor unlinks from this filter. Use this to do any code cleanup for the given Interactor.

Declaration
public override void Unlink(IXRInteractor interactor)
Parameters
Type Name Description
IXRInteractor interactor

The Interactor being unlinked from this filter.
Overrides
Remarks

You cannot call this method while the filter is processing.

Exceptions
Type Condition
InvalidOperationException

Throws when this filter is currently processing and filtering Interactables.

Events

interactorLinked

Calls the methods in this invocation when this filter is linked to an Interactor.

Declaration
public event Action<IXRInteractor> interactorLinked
Event Type
Type Description
Action<IXRInteractor>
See Also

interactorUnlinked

Calls the methods in this invocation when this filter is unlinked from an Interactor.

Declaration
public event Action<IXRInteractor> interactorUnlinked
Event Type
Type Description
Action<IXRInteractor>
See Also

Explicit Interface Implementations

IEnumerable.GetEnumerator()

Returns an enumerator to iterate through the evaluators in this Target Filter.

Declaration
IEnumerator IEnumerable.GetEnumerator()
Returns
Type Description
IEnumerator

Returns an IEnumerator object that can be used to iterate through the evaluators.
Implements

See Also