Class XRHandSubsystem

A subsystem for detecting and tracking hands and their corresponding joint pose data.

Inheritance

UnityEngine.SubsystemsImplementation.SubsystemWithProvider<XRHandSubsystem, XRHandSubsystemDescriptor, XRHandSubsystemProvider>

XRHandSubsystem

Inherited Members

UnityEngine.SubsystemsImplementation.SubsystemWithProvider<UnityEngine.XR.Hands.XRHandSubsystem, UnityEngine.XR.Hands.XRHandSubsystemDescriptor, UnityEngine.XR.Hands.ProviderImplementation.XRHandSubsystemProvider>.OnCreate()

SubsystemWithProvider.Start()

UnityEngine.SubsystemsImplementation.SubsystemWithProvider.OnStart()

SubsystemWithProvider.Stop()

UnityEngine.SubsystemsImplementation.SubsystemWithProvider.OnStop()

SubsystemWithProvider.Destroy()

SubsystemWithProvider.running

Namespace: UnityEngine.XR.Hands

Syntax

public class XRHandSubsystem : SubsystemWithProvider<XRHandSubsystem, XRHandSubsystemDescriptor, XRHandSubsystemProvider>, ISubsystem

Remarks

The XRHandSystem class is the main entry point for accessing hand tracking data provided by an XR device. A provider implementation that reads tracking data from the user's device and provides updates to this subsystem must also be available. The XR Hands package includes a provider implementation for OpenXR.

Get an instance for this XRHandSubsystem from the active XR loader, as described in Get the XRHandSubsystem instance.

For lowest latency, read the tracking data available from the leftHand and rightHand properties in a delegate function assigned to the updatedHands callback. This callback is invoked twice per frame, once near the MonoBehaviour.Update event and once near the UnityEngine.Application.onBeforeRender event. The BeforeRender update provides the lowest latency between hand motion and rendering, but occurs too late to affect physics. In addition, trying to perform too much work during the BeforeRender callback can negatively impact framerate. For best results, update game logic affected by hand tracking in a Dynamic update and perform a final update of hand visuals in a BeforeRender update.

Refer to Hand tracking data for more information.

Constructors

XRHandSubsystem()

Constructs a subsystem. Do not invoke directly.

Declaration

public XRHandSubsystem()

Remarks

Do not call this constructor if you are an application developer consuming hand tracking data. Instead, get an instance for this XRHandTrackingSubsystem from the active XR loader, as described in Get the XRHandSubsystem instance.

If you are implementing an XR hand data provider, call Create on the XRHandSubsystemDescriptor or call UnityEngine.XR.Management.XRLoaderHelper.CreateSubsystem``2(System.Collections.Generic.List{``0},System.String) instead of invoking this constructor.

Fields

handsUpdated

Obsolete. Use updatedHands instead.

Declaration

[Obsolete("Use updatedHands instead.")]
public Action<XRHandSubsystem.UpdateSuccessFlags, XRHandSubsystem.UpdateType> handsUpdated

Field Value

Type	Description
Action<XRHandSubsystem.UpdateSuccessFlags, XRHandSubsystem.UpdateType>

trackingAcquired

A callback invoked when the subsystem begins tracking a hand's root pose and joints.

Declaration

public Action<XRHand> trackingAcquired

Field Value

Type	Description
Action<XRHand>

Remarks

This is called before updatedHands.

The delegate assigned to this property must take one parameter of type XRHand, which is assigned a reference to the hand whose tracking was acquired.

trackingLost

A callback invoked when the subsystem stops tracking a hand's root pose and joints.

Declaration

public Action<XRHand> trackingLost

Field Value

Type	Description
Action<XRHand>

Remarks

This is called before updatedHands.

The delegate assigned to this property must take one parameter of type XRHand, which is assigned a reference to the hand whose tracking was lost.

updatedHands

A callback invoked for each hand update.

Declaration

public Action<XRHandSubsystem, XRHandSubsystem.UpdateSuccessFlags, XRHandSubsystem.UpdateType> updatedHands

Field Value

Type	Description
Action<XRHandSubsystem, XRHandSubsystem.UpdateSuccessFlags, XRHandSubsystem.UpdateType>

Remarks

This callback is invoked twice per frame, once near the MonoBehaviour.Update event and once near the UnityEngine.Application.onBeforeRender event. The BeforeRender update provides the lowest latency between hand motion and rendering, but occurs too late to affect physics. In addition, trying to perform too much work during the BeforeRender callback can negatively impact framerate. For best results, update game logic affected by hand tracking in a Dynamic update and update hand visuals in a BeforeRender update.

The delegate assigned to this property must take three parameters, which have the following types and assigned values when the callback is invoked:

XRHandSubsystem: contains a reference to this subsystem.
XRHandSubsystem.UpdateSuccessFlags: the flags indicating which data could be updated.
XRHandSubsystem.UpdateType: the update timing.

Properties

jointsInLayout

Indicates which joints in the XRHandJointID list are supported by the current hand data provider.

Declaration

public NativeArray<bool> jointsInLayout { get; }

Property Value

Type	Description
NativeArray<Boolean>

Remarks

Hand data providers might not support tracking every joint in the XRHandJointID list. This array contains an element for each possible joint. A value of true indicates the the current provider supports tracking the associated joint.

To get the correct array index for a joint, call ToIndex(XRHandJointID) on the XRHandJointID in question.

Refer to Get supported joints array for additional information.

This array will already be valid as soon as you have a reference to a subsystem (in other words, it's filled out before the subsystem is returned by a call to XRHandSubsystemDescriptor.Create).

leftHand

Gets the left XRHand that is being tracked by this subsystem.

Declaration

public XRHand leftHand { get; }

Property Value

Type	Description
XRHand

Remarks

Check the updateSuccessFlags property to determine what data associated with this hand was successfully updated in the last update, if any. The updateSuccessFlags value is also passed to the callback function assigned to updatedHands.

Refer to Hand data model for a description of the available hand tracking data.

rightHand

Gets the right XRHand that is being tracked by this subsystem.

Declaration

public XRHand rightHand { get; }

Property Value

Type	Description
XRHand

Remarks

Refer to Hand data model for a description of the available hand tracking data.

updateSuccessFlags

Describes what data on either hand was updated during the most recent hand update.

Declaration

public XRHandSubsystem.UpdateSuccessFlags updateSuccessFlags { get; protected set; }

Property Value

Type	Description
XRHandSubsystem.UpdateSuccessFlags	The flags for the most recent update. Applies to the leftHand and rightHand properties.

Remarks

This property updated every time the hand data is updated, which only occurs while this XRHandSubsystem is running.

The updateSuccessFlags value is also passed to the callback function assigned to updatedHands.

Methods

OnCreate()

Called by Unity before the subsystem is returned from a call to XRHandSubsystemDescriptor.Create.

Declaration

protected override void OnCreate()

Overrides

OnDestroy()

Called by Unity before the subsystem is fully destroyed during a call to XRHandSubsystem.Destroy.

Declaration

protected override void OnDestroy()

Overrides

TryUpdateHands(XRHandSubsystem.UpdateType)

Request an update from the hand data provider. Application developers consuming hand tracking data should not call this function.

Declaration

public virtual XRHandSubsystem.UpdateSuccessFlags TryUpdateHands(XRHandSubsystem.UpdateType updateType)

Parameters

Type	Name	Description
XRHandSubsystem.UpdateType	updateType	Informs the provider which kind of timing the update is being requested under.

Returns

Type	Description
XRHandSubsystem.UpdateSuccessFlags	Returns XRHandSubsystem.UpdateSuccessFlags to describe what data was updated successfully.

Remarks

This function must be called by the subsystem implementation to request an update from the hand data provider.

When an update is complete, the updated data is available from the leftHand and rightHand properties. The updatedHands callback is invoked.

The update is performed immediately. If you request an update timing that occurs in the future, for example, requesting BeforeRender from a MonoBehaviour.Update function, then the provider predicts what the hand data will be at the requested time.

If overriding this method in a derived type, it is expected that you call base.TryUpdateHands(updateType) and return what it returns.