UnrealEngine/Plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add the final draft for docs section: SGHandTrackerComponent

Browse Source
This commit is contained in:
Mamadou Babaei
2026-02-24 10:42:44 +01:00
parent 71199a3d52
commit d6a4cea0d1
8 changed files with 141 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Handbook/src/advanced-topics/openxr/README.md
+24
View File
@@ -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
Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/README.md
+14
View File
@@ -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
Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/blueprint.md
+14
View File
@@ -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).
Handbook/src/advanced-topics/openxr/consuming-fxrhandtrackingstate/cpp.md
+14
View File
@@ -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).
Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/README.md
+67
View File
@@ -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/).
Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/sghandtrackercomponent-get-hand-tracking-state.png
LFS
BIN
View File
Binary file not shown.
Handbook/src/advanced-topics/roll-your-own-hand-manipulation-system/sghandtrackercomponent/sghapticscomponent-debug-hand-visualization-settings.png
LFS
BIN
View File
Binary file not shown.
Handbook/src/appendix/changelog.md
+3
View File
@@ -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.