Plugin/Source/SenseGloveSettings/Public/SGSettings/SGWristTrackingSettings.h

/**
 * @file
 *
 * @author  Mamadou Babaei <mamadou@senseglove.com>
 *
 * @section LICENSE
 *
 * (The MIT License)
 *
 * Copyright (c) 2020 - 2025 SenseGlove
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 * @section DESCRIPTION
 *
 *
 */


#pragma once

#include "HAL/Platform.h"
#include "InputCoreTypes.h"
#include "Math/Rotator.h"
#include "Math/Vector.h"
#include "UObject/NameTypes.h"
#include "UObject/ObjectMacros.h"

#include "SGSettings/SGWristTrackingDebuggingSettings.h"
#include "SGTypes/SGCoreTypes.h"
#include "SGTypes/SGTrackingTypes.h"

#include "SGWristTrackingSettings.generated.h"

/**
* Implements the wrist tracking settings.
*
* Provides the tracking settings applicable to wrist-tracking hardware.
*/
USTRUCT(BlueprintType)
struct SENSEGLOVESETTINGS_API FSGWristTrackingSettings
{
    GENERATED_USTRUCT_BODY()

public:
    /**
     * Specifies the type of OpenXR provider to use in order to extract the positional tracking data from the
     * underlying XR system. If set to None, the plugin attempts to set this automatically by considering a combination
     * of approaches including, the current value of `TrackingHardware` specified below, the platform it's targeted at,
     * the available OpenXR plugins, along with HMD auto-detection mechanism to specify a compatible OpenXR tracking
     * provider. Please note that the OpenXR provider depends on the combination of plugins, platform, and the settings
     * you use. For example, it is possible to use a Vive Focus 3 Wrist Tracker on Microsoft Windows along with the
     * Epic `OpenXRViveTracker` plugin and check the option `Emulate VIVE Wrist Tracker as VIVE Tracker` inside the
     * VIVE Business Streaming application's Input settings. In that case, the correct OpenXR positional tracking
     * provider to use would be `OpenXRViveTracker`. However, using the official ViveOpenXR plugin on Android, the
     * correct OpenXR provider would be `OpenXRViveWristTracker`.
     *
     * Caution:
     * HMD auto-detection is currently an experimental feature and may fail because HMD vendors occasionally change the
     * properties utilized by the plugin for HMD detection. If you encounter issues, such as incorrect tracker offsets,
     * it is recommended to explicitly specify the tracking hardware.
     *
     * Caution:
     * Due to highly experimental nature of the HMD auto-detection feature, the HTC VIVE Focus Vision, HTC VIVE XR
     * Elite, and HTC VIVE Focus Vision cannot be distinguished from each other in the current iteration. However,
     * since the tracker devices and offsets for all these headsets are the same, this should not affect the
     * performance or  any functionality. The order in which the HMD is detected can be specified through the
     * HMD-tracker setting `ViveHMDDetectionPriority`.
     *
     * Note:
     * Ultimate Tracker and ViveOpenXRXrTracker are not supported, yet.
     */
    UPROPERTY(Config, EditDefaultsOnly, Category = "Wrist Tracking")
    ESGOpenXRPositionalTrackingProvider OpenXRPositionalTrackingProvider;

    /**
     * Specifies the type of tracking hardware to use. If set to None, the plugin attempts at HMD auto-detection to
     * automatically specify a compatible tracking hardware. If set to `Custom`, any desired location and rotation can
     * be specified.
     *
     * Caution:
     * HMD auto-detection is currently an experimental feature and may fail because HMD vendors occasionally change the
     * properties utilized by the plugin for HMD detection. If you encounter issues, such as incorrect tracker offsets,
     * it is recommended to explicitly specify the tracking hardware.
     *
     * Caution:
     * Due to highly experimental nature of the HMD auto-detection feature, the HTC VIVE Focus Vision, HTC VIVE XR
     * Elite, and HTC VIVE Focus Vision cannot be distinguished from each other in the current iteration. However,
     * since the tracker devices and offsets for all these headsets are the same, this should not affect the
     * performance or  any functionality. The order in which the HMD is detected can be specified through the
     * HMD-tracker setting `ViveHMDDetectionPriority`.
     */
    UPROPERTY(Config, EditDefaultsOnly, Category = "Wrist Tracking")
    ESGPositionalTrackingHardware TrackingHardware;

    /**
     * Sets a custom location offset for left hand's wrist-tracking hardware.
     *
     * Note:
     * This setting is visible and valid only if TrackingHardware is set to Custom.
     */
    UPROPERTY(Config, EditDefaultsOnly, Category = "Wrist Tracking",
        meta=(EditCondition="TrackingHardware == ESGPositionalTrackingHardware::Custom", EditConditionHides))
    FVector TrackingHardwareLocationOffsetLeftHand;

    /**
     * Sets a custom location offset for right hand's wrist-tracking hardware.
     *
     * Note:
     * This setting is visible and valid only if TrackingHardware is set to Custom.
     */
    UPROPERTY(Config, EditDefaultsOnly, Category = "Wrist Tracking",
        meta=(EditCondition="TrackingHardware == ESGPositionalTrackingHardware::Custom", EditConditionHides))
    FVector TrackingHardwareLocationOffsetRightHand;

    /**
     * Sets a custom rotation offset for left hand's wrist-tracking hardware.
     *
     * Note:
     * This setting is visible and valid only if TrackingHardware is set to Custom.
     */
    UPROPERTY(Config, EditDefaultsOnly, Category = "Wrist Tracking",
        meta=(EditCondition="TrackingHardware == ESGPositionalTrackingHardware::Custom", EditConditionHides))
    FRotator TrackingHardwareRotationOffsetLeftHand;

    /**
     * Sets a custom rotation offset for right hand's wrist-tracking hardware.
     *
     * Note:
     * This setting is visible and valid only if TrackingHardware is set to Custom.
     */
    UPROPERTY(Config, EditDefaultsOnly, Category = "Wrist Tracking",
        meta=(EditCondition="TrackingHardware == ESGPositionalTrackingHardware::Custom", EditConditionHides))
    FRotator TrackingHardwareRotationOffsetRightHand;

    /**
     * Determines the motion source for the left hand. For Oculus HMDs, this is usually Left, and for VIVE HMDs, it's
     * typically LeftFoot.
     *
     * Note:
     * For VIVE devices using SteamVR, the motion source hardware for the left hand can be specified by the user
     * through the SteamVR app.
     */
    UPROPERTY(Config, EditDefaultsOnly, Category="Wrist Tracking")
    FName LeftHandMotionSource;

    /**
     * Determines the motion source for the left hand. For Oculus HMDs, this is usually Right, and for VIVE HMDs, it's
     * typically RightFoot.
     *
     * Note:
     * For VIVE devices using SteamVR, the motion source hardware for the right hand can be specified by the user
     * through the SteamVR app.
     */
    UPROPERTY(Config, EditDefaultsOnly, Category="Wrist Tracking")
    FName RightHandMotionSource;

    /**
     * Provides debugging options for visually debugging the wrist tracker.
     */
    UPROPERTY(Config, EditDefaultsOnly, Category = "Wrist Tracking")
    FSGWristTrackingDebuggingSettings DebuggingSettings;

public:
    FSGWristTrackingSettings();

    FSGWristTrackingSettings(
        const ESGOpenXRPositionalTrackingProvider InOpenXRPositionalTrackingProvider,
        ESGPositionalTrackingHardware InTrackingHardware,
        const FVector& InTrackingHardwareLocationOffsetLeftHand,
        const FVector& InTrackingHardwareLocationOffsetRightHand,
        const FRotator& InTrackingHardwareRotationOffsetLeftHand,
        const FRotator& InTrackingHardwareRotationOffsetRightHand,
        FName InLeftHandMotionSource,
        FName InRightHandMotionSource,
        const FSGWristTrackingDebuggingSettings& InDebuggingSettings);
};