update the documentation on consuming the FXRMotionControllerData struct

2024-10-22 05:30:16 +02:00
parent 1bf32dc10f
commit be1823c16f
4 changed files with 228 additions and 199 deletions
@@ -71,68 +71,88 @@ But, fear not, we've got you covered!

 ### Structure Members of FXRMotionControllerData

-1. **bValid**
+- **bValid**
   - **Description**: A boolean flag indicating whether the data is valid or not.
   - **Usage**: This is used to check if the motion controller data is correctly initialized and can be used for further processing.

-2. **DeviceName**
+- **DeviceName**
   - **Type**: `FName`
   - **Description**: The name of the device.
   - **Usage**: Identifies which motion controller device the data is coming from, useful when multiple devices are in use.

-3. **ApplicationInstanceID**
+- **ApplicationInstanceID**
   - **Type**: `FString`
   - **Description**: A unique identifier for the application instance.
   - **Usage**: Helps in differentiating data from different instances of an application, ensuring the correct instance processes the data.

-4. **TrackingStatus**
+- **DeviceVisualType**
+   - **Type**: `EXRVisualType`
+   - **Description**: Enum specifying the visual type of the device (e.g., controller, hand).
+   - **Usage**: Used to differentiate between various motion controller devices or hand-tracking representations for rendering and interaction purposes.
+
+- **HandIndex**
+   - **Type**: `EControllerHand`
+   - **Description**: Enum indicating which hand is being tracked (left or right).
+   - **Usage**: Helps identify whether the motion data pertains to the left or right hand, essential for hand-specific actions or interactions.
+
+- **TrackingStatus**
   - **Type**: `EXRTrackingStatus`
   - **Description**: Enum indicating the tracking status of the motion controller.
   - **Usage**: Shows whether the controller is being tracked accurately, with possible statuses like `Tracked`, `NotTracked`, etc.

-5. **GripPosition**
+- **GripPosition**
   - **Type**: `FVector`
   - **Description**: The position of the grip in world coordinates.
   - **Usage**: Provides the 3D coordinates of the controller's grip, essential for positioning the virtual representation of the controller.

-6. **GripRotation**
+- **GripRotation**
   - **Type**: `FQuat`
   - **Description**: The rotation of the grip in world coordinates.
   - **Usage**: Provides the orientation of the controller's grip, allowing for accurate rotation and alignment in the virtual space.

-7. **AimPosition**
+- **AimPosition**
   - **Type**: `FVector`
   - **Description**: The position of the aim point in world coordinates.
   - **Usage**: Specifies where the controller is aiming, useful for aiming or pointing actions.

-8. **AimRotation**
+- **AimRotation**
   - **Type**: `FQuat`
   - **Description**: The rotation of the aim point in world coordinates.
   - **Usage**: Determines the orientation of the aim direction, important for actions like shooting or selecting objects in VR.

-9. **HandKeyPositions**
+- **PalmPosition**
+   - **Type**: `FVector`
+   - **Description**: The position of the palm in world coordinates.
+   - **Usage**: Provides the 3D location of the palm, important for determining hand gestures or interactions in VR.
+
+- **PalmRotation**
+   - **Type**: `FQuat`
+   - **Description**: The rotation of the palm in world coordinates.
+   - **Usage**: Defines the orientation of the palm, crucial for hand-based interaction accuracy and realism in VR experiences.
+
+- **HandKeyPositions**
   - **Type**: `TArray<FVector>`
   - **Description**: An array of vectors representing key positions of the hand.
   - **Usage**: Provides detailed positions of key points on the hand, useful for precise hand tracking and interaction.

-10. **HandKeyRotations**
+- **HandKeyRotations**
    - **Type**: `TArray<FQuat>`
    - **Description**: An array of quaternions representing key rotations of the hand.
    - **Usage**: Complements the hand key positions with rotational data, ensuring accurate representation of hand movements.

-11. **HandKeyRadii**
+- **HandKeyRadii**
    - **Type**: `TArray<float>`
    - **Description**: An array of floats representing the radii of key points of the hand.
    - **Usage**: Gives the size of the hand key points, aiding in collision detection and interaction fidelity.

-12. **bIsGrasped**
+- **bIsGrasped**
    - **Type**: `bool`
    - **Description**: A boolean indicating whether the controller is currently grasping an object.
    - **Usage**: Determines if the user is holding something, affecting interactions and animations.

 ### Organization of FXRMotionControllerData

-The structure is organized to encapsulate all relevant data needed for motion controller tracking in a coherent and accessible manner. Boolean flags `bValid` and `bIsGrasped` provide quick checks on the state of the controller data. Identifiers `DeviceName` and `ApplicationInstanceID` ensure the correct association of data. Positional and rotational data `GripPosition`, `GripRotation`, `AimPosition`, and `AimRotation` offer precise tracking of the controller's movement. Arrays `HandKeyPositions`, `HandKeyRotations`, and `HandKeyRadii` allow detailed hand tracking, which is critical for immersive VR experiences. Lastly, the tracking status `TrackingStatus` informs the system of the reliability of the data being processed and whether the motion controller is actively being tracked or it's inactive at the moment.
+The structure is organized to encapsulate all relevant data needed for hand and motion controller tracking in a coherent and accessible manner. Boolean flags `bValid` and `bIsGrasped` provide quick checks on the state of the controller data. Identifiers `DeviceName` and `ApplicationInstanceID` ensure the correct association of data. Positional and rotational data `GripPosition`, `GripRotation`, `AimPosition`, and `AimRotation` offer precise tracking of the controller's movement. Arrays `HandKeyPositions`, `HandKeyRotations`, and `HandKeyRadii` allow detailed hand tracking, which is critical for immersive VR experiences. Lastly, the tracking status `TrackingStatus` informs the system of the reliability of the data being processed and whether the motion controller is actively being tracked or it's inactive at the moment.

 ### Processing the Data for Drawing and Animating a Virtual Hand

@@ -217,7 +237,7 @@ So, getting the any joint's position or rotation is as easy as casting the enum
        return;
    }

-    // Ensure that MotionControllerData.HandKeyPositions has the rotation data
+    // Ensure that MotionControllerData.HandKeyRotations has the rotation data
    // for 26 joints!
    if (!ensureAlwaysMsgf(MotionControllerData.HandKeyRotations.Num()
                          == EHandKeypointCount,
@@ -216,7 +216,7 @@ void ADebugPawn::DrawHand(const EControllerHand Hand) const
        return;
    }

-	// Ensure that MotionControllerData.HandKeyPositions has the rotation data
+    // Ensure that MotionControllerData.HandKeyRotations has the rotation data
    // for 26 joints!
    if (!ensureAlwaysMsgf(MotionControllerData.HandKeyRotations.Num()
                          == EHandKeypointCount,
@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

+## [Unreleased]
+
+This is a bugfix release that delivers some documentation fixes.
+
+### Documentation
+
+- Updated the documentation on consuming the `FXRMotionControllerData` struct.
+- Additional minor documentation fixes and improvements that may not be listed here.
+
 ## [2.1.3] - 2024-10-11

 ### Added