docs.unity3d.com
    Show / Hide Table of Contents

    Class XRHandSubsystem

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

    Inheritance
    Object
    SubsystemWithProvider
    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()
    UnityEngine.SubsystemsImplementation.SubsystemWithProvider<UnityEngine.XR.Hands.XRHandSubsystem, UnityEngine.XR.Hands.XRHandSubsystemDescriptor, UnityEngine.XR.Hands.ProviderImplementation.XRHandSubsystemProvider>.OnStart()
    UnityEngine.SubsystemsImplementation.SubsystemWithProvider<UnityEngine.XR.Hands.XRHandSubsystem, UnityEngine.XR.Hands.XRHandSubsystemDescriptor, UnityEngine.XR.Hands.ProviderImplementation.XRHandSubsystemProvider>.OnStop()
    UnityEngine.SubsystemsImplementation.SubsystemWithProvider<UnityEngine.XR.Hands.XRHandSubsystem, UnityEngine.XR.Hands.XRHandSubsystemDescriptor, UnityEngine.XR.Hands.ProviderImplementation.XRHandSubsystemProvider>.OnDestroy()
    UnityEngine.SubsystemsImplementation.SubsystemWithProvider<UnityEngine.XR.Hands.XRHandSubsystem, UnityEngine.XR.Hands.XRHandSubsystemDescriptor, UnityEngine.XR.Hands.ProviderImplementation.XRHandSubsystemProvider>.subsystemDescriptor
    UnityEngine.SubsystemsImplementation.SubsystemWithProvider<UnityEngine.XR.Hands.XRHandSubsystem, UnityEngine.XR.Hands.XRHandSubsystemDescriptor, UnityEngine.XR.Hands.ProviderImplementation.XRHandSubsystemProvider>.provider
    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

    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.

    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
    UnityEngine.SubsystemsImplementation.SubsystemWithProvider<UnityEngine.XR.Hands.XRHandSubsystem, UnityEngine.XR.Hands.XRHandSubsystemDescriptor, UnityEngine.XR.Hands.ProviderImplementation.XRHandSubsystemProvider>.OnCreate()

    OnDestroy()

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

    Declaration
    protected override void OnDestroy()
    Overrides
    UnityEngine.SubsystemsImplementation.SubsystemWithProvider<UnityEngine.XR.Hands.XRHandSubsystem, UnityEngine.XR.Hands.XRHandSubsystemDescriptor, UnityEngine.XR.Hands.ProviderImplementation.XRHandSubsystemProvider>.OnDestroy()

    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.

    Back to top Copyright © 2023 Unity Technologies
    Generated by DocFX
    on Tuesday, March 21, 2023
    Terms of use