Class XRHandSubsystem
A subsystem for detecting and tracking hands and their corresponding joint pose data.
Inheritance
Implements
Inherited Members
Namespace: UnityEngine .XR.Hands
Assembly: Unity.XR.Hands.dll
Syntax
public class XRHandSubsystem : SubsystemWithProvider<XRHandSubsystem, XRHandSubsystemDescriptor, XRHandSubsystemProvider>, ISubsystem
Remarks
The XRHandSubsystem
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 XRHand
For lowest latency, read the tracking data available from the leftMonoBehaviour.Update
event and once near the UnityBeforeRender
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
Before
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 XRHand
If you are implementing an XR hand data provider, call Create
on the XRHand
Fields
handsUpdated
Obsolete. Use updated
Declaration
[Obsolete("Use updatedHands instead.")]
public Action<XRHandSubsystem.UpdateSuccessFlags, XRHandSubsystem.UpdateType> handsUpdated
Field Value
Type | Description |
---|---|
Action<XRHand |
preprocessJoints
This is called after the subsystem retrieves joint data from the
provider, and before and IXRHand
Declaration
public Action<XRHandSubsystem, XRHandSubsystem.UpdateSuccessFlags, XRHandSubsystem.UpdateType> preprocessJoints
Field Value
Type | Description |
---|---|
Action<XRHand |
trackingAcquired
A callback invoked when the subsystem begins tracking a hand's root pose and joints.
Declaration
public Action<XRHand> trackingAcquired
Field Value
Remarks
This is called before updated
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
Remarks
This is called before updated
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<XRHand |
Remarks
This callback is invoked twice per frame, once near
the MonoBehaviour.Update
event and once near the UnityBeforeRender
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
Before
The delegate assigned to this property must take three parameters, which have the following types and assigned values when the callback is invoked:
- XRHand
Subsystem : contains a reference to this subsystem. - XRHand
Subsystem. : the flags indicating which data could be updated.Update Success Flags - XRHand
Subsystem. : the update timing.Update Type
Properties
jointsInLayout
Indicates which joints in the XRHand
Declaration
public NativeArray<bool> jointsInLayout { get; }
Property Value
Type | Description |
---|---|
Native |
Remarks
Hand data providers might not support tracking every joint in the
XRHand
To get the correct array index for a joint, call
To
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 update
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
Check the update
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 |
---|---|
XRHand |
The flags for the most recent update. Applies to the left |
Remarks
This property updated every time the hand data is updated, which only occurs while this XRHandSubsystem is running.
The update
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
RegisterProcessor<TProcessor>(TProcessor)
Registers a processor for hand joint data.
Declaration
public void RegisterProcessor<TProcessor>(TProcessor processor) where TProcessor : class, IXRHandProcessor
Parameters
Type | Name | Description |
---|---|---|
TProcessor | processor | The processor to register for this XRHand |
Type Parameters
Name | Description |
---|---|
TProcessor | The type of the processor to register. |
TryUpdateHands(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 |
---|---|---|
XRHand |
updateType | Informs the provider which kind of timing the update is being requested under. |
Returns
Type | Description |
---|---|
XRHand |
Returns XRHand |
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 left
The update is performed immediately. If you request an update timing that occurs in the
future, for example, requesting BeforeMonoBehaviour.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.
UnregisterProcessor<TProcessor>(TProcessor)
Unregisters a processor for hand joint data.
Declaration
public void UnregisterProcessor<TProcessor>(TProcessor processor) where TProcessor : class, IXRHandProcessor
Parameters
Type | Name | Description |
---|---|---|
TProcessor | processor | The processor to unregister from this XRHand |
Type Parameters
Name | Description |
---|---|
TProcessor | The type of the processor to register. |