From 08164a36cda6f747214914eb6ebdeebb29aeb7a8 Mon Sep 17 00:00:00 2001 From: Amy Louise Green Date: Tue, 2 Dec 2025 14:43:55 -0500 Subject: [PATCH 1/3] DOCATT-8754: Updated TrackedDevice class documentation --- .../InputSystem/Devices/TrackedDevice.cs | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs b/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs index 89153d282a..2ab60cca6d 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs @@ -7,17 +7,85 @@ 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](https://docs.unity3d.com/Packages/com.unity.xr.interaction.toolkit@latest/index.html?subfolder=/manual/samples-spatial-keyboard.html) + /// 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 or not. + /// + /// + /// This property can contain a simple bit (1 or 0), but for some Open XR devices, this might + /// contain a float that includes bits that can indicate whether the device's position is actual + /// or inferred from its last-known [pose](xref:openxr-input#pose-data) (OpenXR Plugin package). + /// + /// For more information about how the float represents inferred position vs. actual position in + /// OpenXR devices, refer to [Reference Spaces](https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#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 position. 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.0/html/xrspec.html#semantic-path-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 position. 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.0/html/xrspec.html#semantic-path-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; } From 98caedb67ed8e0ac70c1fb7e9cb7942abee4ec0a Mon Sep 17 00:00:00 2001 From: Amy Louise Green Date: Tue, 2 Dec 2025 15:02:25 -0500 Subject: [PATCH 2/3] DOCATT-8754: Corrected position/pose in deviceRotation/devicePosition --- .../InputSystem/Devices/TrackedDevice.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs b/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs index 2ab60cca6d..fa1f4034b3 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs @@ -54,7 +54,7 @@ public class TrackedDevice : InputDevice /// /// 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 position. For XR controllers, it means the "grip" pose. + /// 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 @@ -73,7 +73,7 @@ public class TrackedDevice : InputDevice /// /// 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 position. For XR controllers, it means the "grip" pose. + /// 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 From fa1e9aba2ad4776f9d3afb93c7969a7a2764f430 Mon Sep 17 00:00:00 2001 From: Amy Louise Green Date: Fri, 5 Dec 2025 17:38:08 -0500 Subject: [PATCH 3/3] DOCATT-8754: Post tech-review updates - Fixed some links, clarified isTracked return in TrackedDevice.cs - Added related XR packages to `xref` list in projectMetadata.json --- .../Documentation~/projectMetadata.json | 6 +++++- .../InputSystem/Devices/TrackedDevice.cs | 16 ++++++---------- 2 files changed, 11 insertions(+), 11 deletions(-) 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 fa1f4034b3..391cbb7371 100644 --- a/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs +++ b/Packages/com.unity.inputsystem/InputSystem/Devices/TrackedDevice.cs @@ -12,7 +12,7 @@ namespace UnityEngine.InputSystem /// [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](https://docs.unity3d.com/Packages/com.unity.xr.interaction.toolkit@latest/index.html?subfolder=/manual/samples-spatial-keyboard.html) + /// 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. /// @@ -37,15 +37,11 @@ public class TrackedDevice : InputDevice public IntegerControl trackingState { get; protected set; } /// - /// Indicates whether the input device is actively tracked or not. + /// Indicates whether the input device is actively tracked (1) or not (0). /// /// - /// This property can contain a simple bit (1 or 0), but for some Open XR devices, this might - /// contain a float that includes bits that can indicate whether the device's position is actual - /// or inferred from its last-known [pose](xref:openxr-input#pose-data) (OpenXR Plugin package). - /// - /// For more information about how the float represents inferred position vs. actual position in - /// OpenXR devices, refer to [Reference Spaces](https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#reference-spaces) + /// 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)] @@ -58,7 +54,7 @@ public class TrackedDevice : InputDevice /// /// /// For more information about how OpenXR represents the grip pose, refer to - /// [Standard pose identifiers](https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#semantic-path-standard-identifiers) + /// [Standard pose identifiers](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#semantic-paths-standard-identifiers) /// (OpenXR Specification). /// /// > [!NOTE] @@ -77,7 +73,7 @@ public class TrackedDevice : InputDevice /// /// /// For more information about how OpenXR represents the grip pose, refer to - /// [Standard pose identifiers](https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#semantic-path-standard-identifiers) + /// [Standard pose identifiers](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#semantic-paths-standard-identifiers) /// (OpenXR Specification). /// /// > [!NOTE]