From 1e45b0f647a0af6536dc4b51851eff65c2f1bc27 Mon Sep 17 00:00:00 2001 From: Mamadou Babaei Date: Fri, 20 Feb 2026 18:47:19 +0100 Subject: [PATCH] add the final draft for docs section: SGHandTrackerComponent --- Handbook/src/advanced-topics/openxr/README.md | 24 +++++++ .../consuming-fxrhandtrackingstate/README.md | 14 ++++ .../blueprint.md | 14 ++++ .../consuming-fxrhandtrackingstate/cpp.md | 14 ++++ .../sghandtrackercomponent/README.md | 67 +++++++++++++++++++ ...ackercomponent-get-hand-tracking-state.png | 4 +- ...nent-debug-hand-visualization-settings.png | 3 + Handbook/src/appendix/changelog.md | 3 + 8 files changed, 141 insertions(+), 2 deletions(-) create mode 100644 Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/sghapticscomponent-debug-hand-visualization-settings.png diff --git a/Handbook/src/advanced-topics/openxr/README.md b/Handbook/src/advanced-topics/openxr/README.md index 5c6a2f36..df03cf51 100644 --- a/Handbook/src/advanced-topics/openxr/README.md +++ b/Handbook/src/advanced-topics/openxr/README.md @@ -15,12 +15,14 @@ Since the SenseGlove Unreal Engine Plugin registers itself as an `OpenXRHandTrac > `IXTrackingSystem::GetHandTrackingState()`, which guarantees the OpenXR > hand-tracking data is coming from a SenseGlove device and also takes into > account the SenseGlove's wrist-tracker offsets automatically. +> > This is the recommended approach over Unreal Engine's own > `IXTrackingSystem::GetHandTrackingState()` or you have to ensure the data > received is coming from a SenseGlove device yourself, and also take into > account the SenseGlove's wrist-tracker settings and calculate the wrist > offsets either using one of the `SGHapticGlove::GetWristLocation()` variants, > or manually. +> > In short `IXTrackingSystem::GetHandTrackingState()` does not respect the > offsets from > `Project Settings > SenseGlove > Tracking > Wrist-Tracking Settings` @@ -31,6 +33,7 @@ Since the SenseGlove Unreal Engine Plugin registers itself as an `OpenXRHandTrac > `IXTrackingSystem::GetHandTrackingState()`, which guarantees the OpenXR > hand-tracking data is coming from a SenseGlove device and also takes into > account the SenseGlove's wrist-tracker offsets automatically. +> > This is the recommended approach over Unreal Engine's own > `IXTrackingSystem::GetHandTrackingState()` or you have to ensure the data > received is coming from a SenseGlove device yourself, and also take into @@ -38,10 +41,31 @@ Since the SenseGlove Unreal Engine Plugin registers itself as an `OpenXRHandTrac > offsets either using one of the `GetWristLocation()` variants, e.g., > `SGHandLayer::GetWristLocation()`, `SGHapticGlove::GetWristLocation()`, etc, > or manually. +> > In short `IXTrackingSystem::GetHandTrackingState()` does not respect the > offsets from > `Project Settings > SenseGlove > Tracking Settings > Wrist Tracking Settings`. +> [!TIP] +> Starting with version `v2.8.0`, the SenseGlove Unreal Engine Plugin provides +> a highly convenient, high-level abstraction that eliminates all of the manual +> steps described above. By using +> [`SGHandTrackerComponent`](../roll-your-own-hand-manipulation-system/sghandtrackercomponent/) +> you can simply add the component to your Pawn class (or any actor that +> requires hand-tracking data), configure its properties, and retrieve the +> tracking data with a single function call when needed. +> +> The SenseGlove UE Plugin automatically handles all required settings and +> offset calculations for your positional tracking hardware, whether you are +> using pure hand tracking or a SenseGlove device. It also provides an optional +> debug hand out of the box, allowing you to instantly visualize hand-tracking +> data without writing a single line of code. +> +> Furthermore, version `v2.8.0` ships with a companion component, +> [`SGHapticsComponent`](../roll-your-own-hand-manipulation-system/sghapticscomponent/), +> which makes it easy to add haptic feedback to your own custom or third-party +> hand manipulation systems. + > [!TIP] > Sometimes, using `IXTrackingSystem::GetHandTrackingState()` is unavoidable, > e.g., when using a third-party hand manipulation system such as diff --git a/Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/README.md b/Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/README.md index 3b274468..41e04d9c 100644 --- a/Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/README.md +++ b/Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/README.md @@ -1,5 +1,19 @@ # Consuming FXRHandTrackingState +> [!TIP] +> Starting with version `v2.8.0`, a highly convenient high-level approach for +> retrieving `FXRHandTrackingState` has been introduced. It allows you to obtain +> OpenXR hand-tracking data without worrying about the caveats mentioned in the +> [`main OpenXR section`](../). +> +> [`SGHandTrackerComponent`](../../roll-your-own-hand-manipulation-system/sghandtrackercomponent/) +> abstracts these complexities away and provides correctly adjusted +> hand-tracking data with a single function call. +> +> This version also introduces a companion +> [`SGHapticsComponent`](../../roll-your-own-hand-manipulation-system/sghapticscomponent/) +> is also available for easily integrating haptic feedback. + Taking a closer look at the `FXRHandTrackingState` declaration inside the Unreal Engine's `HeadMountedDisplay` module at [`Engine/Source/Runtime/HeadMountedDisplay/Public/HeadMountedDisplayTypes.h`](https://github.com/EpicGames/UnrealEngine/blob/release/Engine/Source/Runtime/HeadMountedDisplay/Public/HeadMountedDisplayTypes.h), figuring out the data structure might not seem very straightforward: ```cpp diff --git a/Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/blueprint.md b/Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/blueprint.md index 9538af71..77e62c29 100644 --- a/Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/blueprint.md +++ b/Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/blueprint.md @@ -2,6 +2,20 @@ Before continuing this section, please ensure you've studied the [Consuming FXRHandTrackingState](./) section, first. +> [!TIP] +> Starting with version `v2.8.0`, a highly convenient high-level approach for +> retrieving `FXRHandTrackingState` has been introduced. It allows you to obtain +> OpenXR hand-tracking data without worrying about the caveats mentioned in the +> [`main OpenXR section`](../). +> +> [`SGHandTrackerComponent`](../../roll-your-own-hand-manipulation-system/sghandtrackercomponent/) +> abstracts these complexities away and provides correctly adjusted +> hand-tracking data with a single function call. +> +> This version also introduces a companion +> [`SGHapticsComponent`](../../roll-your-own-hand-manipulation-system/sghapticscomponent/) +> is also available for easily integrating haptic feedback. + ## Drawing and Animating Virtual Hands 1. Create a new Virtual Reality project based [the Unreal VR Template](https://dev.epicgames.com/documentation/en-us/unreal-engine/vr-template-in-unreal-engine). diff --git a/Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/cpp.md b/Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/cpp.md index c9566f5f..b63b2ff9 100644 --- a/Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/cpp.md +++ b/Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/cpp.md @@ -2,6 +2,20 @@ Before continuing this section, please ensure you've first studied the [Consuming FXRHandTrackingState](./) section. +> [!TIP] +> Starting with version `v2.8.0`, a highly convenient high-level approach for +> retrieving `FXRHandTrackingState` has been introduced. It allows you to obtain +> OpenXR hand-tracking data without worrying about the caveats mentioned in the +> [`main OpenXR section`](../). +> +> [`SGHandTrackerComponent`](../../roll-your-own-hand-manipulation-system/sghandtrackercomponent/) +> abstracts these complexities away and provides correctly adjusted +> hand-tracking data with a single function call. +> +> This version also introduces a companion +> [`SGHapticsComponent`](../../roll-your-own-hand-manipulation-system/sghapticscomponent/) +> is also available for easily integrating haptic feedback. + ## Drawing and Animating Virtual Hands 1. Create a new Virtual Reality project based [the Unreal VR Template](https://dev.epicgames.com/documentation/en-us/unreal-engine/vr-template-in-unreal-engine). diff --git a/Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/README.md b/Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/README.md index 5f7352d0..27bb1fd5 100644 --- a/Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/README.md +++ b/Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/README.md @@ -1,9 +1,76 @@ # SGHandTrackerComponent +Since [`v2.1.0`](../../../appendix/changelog.html#210---2024-08-16), the first version to introduce OpenXR support, the **SenseGlove Unreal Engine Plugin** has provided a convenient way to retrieve `FXRHandTrackingState` for SenseGlove devices. This eliminated the need to manually calculate and apply [SenseGlove wrist-tracker settings and offsets](../../../plugin-configuration/plugin-settings/tracking/wrist-tracking/), or to fetch the `Project Settings > SenseGlove > Tracking Settings > Wrist Tracking Settings` and pass them to `GetWristLocation()` in an additional step, [as described in the relevant documentation](../openxr). + +`SGHandTrackerComponent` simplifies this process even further by abstracting all of that away entirely in a high-level manner: + +1. Simply add this component to your Pawn class (or any actor that requires hand-tracking data). +2. Configure and adjust its properties. +3. Retrieve the tracking data with a single function call when needed. + +The SenseGlove UE Plugin automatically handles all required settings and offset calculations for your positional tracking hardware, regardless of whether you are using pure hand tracking or a SenseGlove device. It also provides an optional debug hand for free, allowing you to visualize the hand-tracking data instantly, without writing a single line of code. + +## Adding the Component to Your Actors + +Adding `SGHandTrackerComponent` is straightforward. In the `Components` panel, click the `Add` button and locate it under the `SenseGlove` section: + ![SGHandTrackerComponent - Adding component](sghandtrackercomponent-add-component.png "SGHandTrackerComponent - Adding Component") +## Blueprint Properties + +`SGHandTrackerComponent` exposes the following properties through the `Details` panel in Unreal’s Blueprint Editor: + ![SGHandTrackerComponent - Exposed Blueprint properties accessible via the Details panel](sghandtrackercomponent-details-panel-uproperties.png "SGHandTrackerComponent - Exposed Blueprint properties accessible via the Details panel") +- `Right`: If enabled, the component tracks and provides hand-tracking data for the **right** hand. If disabled, it tracks the **left** hand instead. +- `Visualize`: If enabled, the component visualizes the hand-tracking data by rendering a debug hand. The appearance of this debug hand can be further customized, as shown below. + +![SGHandTrackerComponent - Debug hand's visualization settings customization](sghapticscomponent-debug-hand-visualization-settings.png "SGHandTrackerComponent - Debug hand's visualization settings customization") + +![SGHandTrackerComponent - Visualized debug virtual hands](../../openxr/consuming-fxrhandtrackingstate-animated-debug-virtual-hands.gif "SGHandTrackerComponent - Visualized debug virtual hands") + +## C++ and Blueprint Functions + +`SGHandTrackerComponent` provdies the following C++ methods: + +```cpp +public: + FORCEINLINE bool IsLeft() const + { + return !IsRight(); + } + + FORCEINLINE bool IsRight() const + { + return bRight; + } + + void SetRight(const bool bInRight); + + FORCEINLINE bool IsVisualized() const + { + return bVisualize; + } + + FORCEINLINE void SetVisualize(const bool bInVisualize) + { + bVisualize = bInVisualize; + } + +public: + const FXRHandTrackingState& GetHandTrackingState() const; +``` + +The same functions are also exposed to Blueprint: + ![SGHandTrackerComponent - Blueprint functions](sghandtrackercomponent-functions.png "SGHandTrackerComponent - Blueprint functions") +## GetHandTrackingState + +The most important function accessible via `SGHandTrackerComponent` is `GetHandTrackingState()`: + ![SGHandTrackerComponent - GetHandTrackingState Blueprint function](sghandtrackercomponent-get-hand-tracking-state.png "SGHandTrackerComponent - GetHandTrackingState Blueprint function") + +This function returns a snapshot of the OpenXR hand-tracking data as an `FXRHandTrackingState` struct. + +For more details on [what this data contains and how to use it, please refer to the Consuming FXRHandTrackingState section](../../../advanced-topics/openxr/consuming-fxrhandtrackingstate/). diff --git a/Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/sghandtrackercomponent-get-hand-tracking-state.png b/Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/sghandtrackercomponent-get-hand-tracking-state.png index 04c8b95f..cac06d2a 100644 --- a/Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/sghandtrackercomponent-get-hand-tracking-state.png +++ b/Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/sghandtrackercomponent-get-hand-tracking-state.png @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:8b827e3ba37b147997f01ac88677ad0bddeb7343e19021b32f00d06bd0f2ad58 -size 66836 +oid sha256:49a019e3d4b9a528df5663a7f12f87d6301f83499f2ee0b77fc4f525efa8653e +size 109355 diff --git a/Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/sghapticscomponent-debug-hand-visualization-settings.png b/Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/sghapticscomponent-debug-hand-visualization-settings.png new file mode 100644 index 00000000..4aa45c01 --- /dev/null +++ b/Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/sghapticscomponent-debug-hand-visualization-settings.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1f250f9076fd89cfab358bf5720db18997cca0381199f59b4c434fcd639f8925 +size 28691 diff --git a/Handbook/src/appendix/changelog.md b/Handbook/src/appendix/changelog.md index 112eee15..25873afe 100644 --- a/Handbook/src/appendix/changelog.md +++ b/Handbook/src/appendix/changelog.md @@ -45,6 +45,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Updated [Setup the Virtual Hand Meshes](../getting-started/setup-virtual-hand-meshes/) documentation, replacing `FXRMotionControllerData` usage with `FXRHandTrackingState`. - Updated [Plugin Configuration > Plugin Settings > Virtual Hand > Mesh](../plugin-configuration/plugin-settings/virtual-hand/mesh.md) documentation, replacing `FXRMotionControllerData` usage with `FXRHandTrackingState`. - Updated [Advanced Topics > OpenXR](../advanced-topics/openxr/) documentation section with more relevant and plenty of useful information reflecting the recent changes. +- Updated [Advanced Topics > OpenXR > Consuming FXRHandTrackingState](../advanced-topics/openxr/consuming-fxrhandtrackingstate/) documentation section with information reflecting the recent changes. +- Updated [Advanced Topics > OpenXR > Consuming FXRHandTrackingState > Blueprint](../advanced-topics/openxr/consuming-fxrhandtrackingstate/blueprint.html) documentation section with information reflecting the recent changes. +- Updated [Advanced Topics > OpenXR > Consuming FXRHandTrackingState > C++](../advanced-topics/openxr/consuming-fxrhandtrackingstate/cpp.html) documentation section with information reflecting the recent changes. - Removed the **Consuming FXRMotionControllerData** documentation section as it's no longer relevant. - Removed the **Consuming FXRMotionControllerData > Blueprint** documentation section as it's no longer relevant. - Removed the **Consuming FXRMotionControllerData > C++** documentation section as it's no longer relevant.