diff --git a/Packages/com.unity.inputsystem/Documentation~/projectMetadata.json b/Packages/com.unity.inputsystem/Documentation~/projectMetadata.json index fe955ab06e..4f4159cec3 100644 --- a/Packages/com.unity.inputsystem/Documentation~/projectMetadata.json +++ b/Packages/com.unity.inputsystem/Documentation~/projectMetadata.json @@ -1,3 +1,7 @@ { - "hideGlobalNamespace": true + "hideGlobalNamespace": true, + "xref": [ + "com.unity.xr.openxr", + "com.unity.xr.interaction.toolkit" + ] } \ No newline at end of file diff --git a/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs b/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs index 89153d282a..391cbb7371 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs @@ -7,17 +7,81 @@ namespace UnityEngine.InputSystem /// /// An input device that has its orientation and position in space tracked. /// + /// + /// These values are typically read from input actions and fed into the + /// [Tracked Pose Driver](xref:input-system-tracked-input-devices#tracked-pose-driver) + /// component rather than being read directly from this class. + /// + /// Refer to the [Starter Assets](xref:xri-samples-starter-assets) + /// sample in the XR Interaction Toolkit package for a Demo Scene with an XR rig + /// hierarchy that uses these concepts. + /// /// /// + /// UnityEngine.XR.OpenXR.Input.Pose [InputControlLayout(displayName = "Tracked Device", isGenericTypeOfDevice = true)] public class TrackedDevice : InputDevice { + /// + /// Indicates which of the tracked pose components are valid by using an integer containing a + /// bitwise OR of the [Unity XR module enum values](https://docs.unity3d.com/ScriptReference/XR.InputTrackingState.html), + /// for example `InputTrackingState.Position | InputTrackingState.Rotation`. + /// + /// + /// This property determines whether you can retrieve valid values from the + /// and the properties: + /// - The Position bit must be set for the property to have a valid Vector3 value. + /// - The Rotation bit must be set for the property to have a valid Quaternion. + /// [InputControl(synthetic = true)] public IntegerControl trackingState { get; protected set; } + + /// + /// Indicates whether the input device is actively tracked (1) or not (0). + /// + /// + /// For more information about how OpenXR represents inferred position vs. actual position, refer to + /// [Reference Spaces](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#spaces-reference-spaces) + /// (OpenXR Specification). + /// [InputControl(synthetic = true)] public ButtonControl isTracked { get; protected set; } + + /// + /// Represents the position portion of the input device's primary + /// [pose](xref:input-system-tracked-input-devices#tracked-pose-driver). For an HMD + /// device, this means the "center" eye pose. For XR controllers, it means the "grip" pose. + /// + /// + /// For more information about how OpenXR represents the grip pose, refer to + /// [Standard pose identifiers](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#semantic-paths-standard-identifiers) + /// (OpenXR Specification). + /// + /// > [!NOTE] + /// > The position value is in the tracking space reported by the device, which doesn't match + /// > Unity world space. Using a combination of the XR Origin component with the + /// > [Tracked Pose Driver](xref:input-system-tracked-input-devices#tracked-pose-driver) component + /// > to manage that conversion automatically is more reliable than managing it through scripting. + /// [InputControl(noisy = true, dontReset = true)] public Vector3Control devicePosition { get; protected set; } + + /// + /// Represents the rotation portion of the input device's primary + /// [pose](xref:input-system-tracked-input-devices#tracked-pose-driver). For an HMD + /// device, this means the "center" eye pose. For XR controllers, it means the "grip" pose. + /// + /// + /// For more information about how OpenXR represents the grip pose, refer to + /// [Standard pose identifiers](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#semantic-paths-standard-identifiers) + /// (OpenXR Specification). + /// + /// > [!NOTE] + /// > The rotation value is in the tracking space reported by the device, which doesn't match + /// > Unity world space. Using a combination of the XR Origin component with the + /// > [Tracked Pose Driver](xref:input-system-tracked-input-devices#tracked-pose-driver) component + /// > to manage that conversion automatically is more reliable than managing it through scripting. + /// [InputControl(noisy = true, dontReset = true)] public QuaternionControl deviceRotation { get; protected set; }