Files
Plugin/Source/SenseGloveCoreKismet/Public/SGCoreKismet/SGNova2GloveKismetLibrary.h
T

473 lines
21 KiB
C++

/**
* @file
*
* @author Mamadou Babaei <mamadou@senseglove.com>
*
* @section LICENSE
*
* (The MIT License)
*
* Copyright (c) 2020 - 2026 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
*
* Interface for Nova 2.0 Gloves. A soft glove with detachable force-feedback
* and sensor module, and active contact feedback in the front strap.
* Since the Nova 2.0 is significantly different from the Nova 1 Glove, it gets
* its own separate device interface.
*/
#pragma once
#include "SGKismet/SGBlueprintFunctionLibrary.h"
#include "SGTypes/SGCoreTypes.h"
#include "SGTypes/SGVectorArray.h"
#include "SGNova2GloveKismetLibrary.generated.h"
class USGBasicHandModel;
class USGDevice;
class USGHandPose;
class USGHandProfile;
class USGNova2Glove;
class USGNova2GloveHandProfile;
class USGNova2GloveSensorData;
/**
* Interface for Nova 2.0 Gloves. A soft glove with detachable force-feedback and sensor module, and active contact
* feedback in the front strap.
*/
UCLASS(meta=(ScriptName = "SenseGloveNova2GloveKismetLibrary"))
class SENSEGLOVECOREKISMET_API USGNova2GloveKismetLibrary final : public USGBlueprintFunctionLibrary
{
GENERATED_BODY()
public:
/**
* Deserializes a Nova 2.0 from its ConstantsString. Returns a nullptr if unsuccessful.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove",
meta=(WorldContext="WorldContextObject"))
static USGDevice* Parse(UObject* WorldContextObject, const FString& ConstantsString);
/**
* Retrieve all Nova 2.0's.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove",
meta=(WorldContext="WorldContextObject"))
static TArray<USGNova2Glove*> GetNova2Gloves(UObject* WorldContextObject);
/**
* Retrieve the first connected Nova 2.0 there is.
*/
UFUNCTION(BlueprintCallable, DisplayName="Get Nova2 Glove", Category="SenseGlove | Core | Nova | Nova 2 Glove",
meta=(WorldContext="WorldContextObject"))
static bool GetNova2Glove_OutG(UObject* WorldContextObject, USGNova2Glove*& OutGlove);
/**
* Retrieve the first (connected) right or left handed Nova 2.0.
*/
UFUNCTION(BlueprintCallable, DisplayName="Get Nova2 Glove", Category="SenseGlove | Core | Nova | Nova 2 Glove",
meta=(WorldContext="WorldContextObject"))
static bool GetNova2Glove_bRH_OutG(UObject* WorldContextObject,
bool bRightHanded, USGNova2Glove*& OutGlove);
/**
* Retrieve the location of the glove origin, based on a reference location without requiring an object reference.
*/
UFUNCTION(BlueprintCallable, DisplayName="Calculate Glove Location",
Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void CalculateGloveLocation_RP_FQuat_RR_TH_bRH_HW_OutGP_OutGR(
const FVector& ReferencePosition, const FQuat& ReferenceRotation,
ESGPositionalTrackingHardware TrackingHardware, bool bRightHanded, const FString& HardwareVersion,
FVector& OutGlovePosition, FQuat& OutGloveRotation);
/**
* Retrieve the location of the glove origin, based on a reference location without requiring an object reference.
*/
UFUNCTION(BlueprintCallable, DisplayName="Calculate Glove Location",
Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void CalculateGloveLocation_RP_FRotator_RR_TH_bRH_HW_OutGP_OutGR(
const FVector& ReferencePosition, const FRotator& ReferenceRotation,
ESGPositionalTrackingHardware TrackingHardware, bool bRightHanded, const FString& HardwareVersion,
FVector& OutGlovePosition, FRotator& OutGloveRotation);
/**
* Retrieve the location of the wrist, based on a reference location and default glove-hand offsets, without
* needing an object reference.
*
* @remarks The simplest interface, using default offsets.
*/
UFUNCTION(BlueprintCallable, DisplayName="Calculate Wrist Location",
Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void CalculateWristLocation_RP_FQuat_RR_TH_bRH_HW_OutWP_OutWR(
const FVector& ReferencePosition, const FQuat& ReferenceRotation,
ESGPositionalTrackingHardware TrackingHardware, bool bRightHanded, const FString& HardwareVersion,
FVector& OutWristPosition, FQuat& OutWristRotation);
/**
* Retrieve the location of the wrist, based on a reference location and default glove-hand offsets, without
* needing an object reference.
*
* @remarks The simplest interface, using default offsets.
*/
UFUNCTION(BlueprintCallable, DisplayName="Calculate Wrist Location",
Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void CalculateWristLocation_RP_FRotator_RR_TH_bRH_HW_OutWP_OutWR(
const FVector& ReferencePosition, const FRotator& ReferenceRotation,
ESGPositionalTrackingHardware TrackingHardware, bool bRightHanded, const FString& HardwareVersion,
FVector& OutWristPosition, FRotator& OutWristRotation);
/**
* Special Byte to identify the command as a Streaming Byte.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static FString GetStreamByte();
/**
* Ranges before a Nova 2.0 Sensor is allowed to move.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static TArray<float> GetNova2SensorRanges();
/**
* Converts Nova 2.0 Sensor Data into floating point inputs for normalization.
*/
UFUNCTION(BlueprintCallable, DisplayName="To Normalized Values",
Category="SenseGlove | Core | Nova | Nova 2 Glove")
static TArray<float> ToNormalizedValues_SD(const USGNova2GloveSensorData* SensorData);
/**
* Convert Sensor Data into a series of normalized values.
*/
UFUNCTION(BlueprintCallable, DisplayName="To Normalized Values",
Category="SenseGlove | Core | Nova | Nova 2 Glove", meta=(WorldContext="WorldContextObject"))
static TArray<float> ToNormalizedValues_SD_OutSN(
UObject* WorldContextObject,
const USGNova2GloveSensorData* SensorData, USGSensorNormalization*& OutSensorNormalizer);
/**
* Calculate Hand Angles for a Nova 2.0 Glove, based on normalized input.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static TArray<FSGVectorArray> CalculateHandAngles(
const TArray<float>& NormalizedValues, const USGHandInterpolator* Interpolator, bool bInfluenceIndex);
/**
* Convert normalized inputs (5-6 sensors) to input for an Interpolator.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static TArray<FSGVectorArray> ToNormalizedAngles(
const TArray<float>& NormalizedData, const USGNovaGloveInfo* GloveInfo);
/**
* Return the DeviceType of this Nova.
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static ESGDeviceType GetDeviceType(const USGNova2Glove* Nova2Glove);
/**
* Returns this device's unique identifier.
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static FString GetDeviceId(const USGNova2Glove* Nova2Glove);
/**
* Access this device's hardware designation.
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static FString GetHardwareVersion(const USGNova2Glove* Nova2Glove);
/**
* Access this device's main firmware version. (ex: v3.2 -> 3).
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static int32 GetFirmwareVersion(const USGNova2Glove* Nova2Glove);
/**
* Access this device's sub-firmware version. (ex: v3.2 -> 2).
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static int32 GetSubFirmwareVersion(const USGNova2Glove* Nova2Glove);
/**
* Returns true if this device operates on a battery.
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool HasBattery(const USGNova2Glove* Nova2Glove);
/**
* Returns true if this device is currently charging.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool IsCharging(UPARAM(ref) USGNova2Glove* Nova2Glove);
/**
* Returns the device's battery level, as a value between 0 (empty) and 1 (full).
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool GetBatteryLevel(UPARAM(ref) USGNova2Glove* Nova2Glove, float& OutBatteryLevel);
/**
* Returns true if this glove is meant for right hands.
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool IsRight(const USGNova2Glove* Nova2Glove);
/**
* Retrieve this glove's latest IMU rotation, if one is present.
*/
UFUNCTION(BlueprintCallable, DisplayName="Get Imu Rotation", Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool GetImuRotation_FQuat_OutI(UPARAM(ref) USGNova2Glove* Nova2Glove, FQuat& OutImu);
/**
* Retrieve this glove's latest IMU rotation, if one is present.
*/
UFUNCTION(BlueprintCallable, DisplayName="Get Imu Rotation", Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool GetImuRotation_FRotator_OutI(UPARAM(ref) USGNova2Glove* Nova2Glove, FRotator& OutImu);
/**
* Retrieve a new hand pose using this glove, based on (calibrated) user data.
*/
UFUNCTION(BlueprintCallable, DisplayName="Get Hand Pose", Category="SenseGlove | Core | Nova | Nova 2 Glove",
meta=(WorldContext="WorldContextObject"))
static bool GetHandPose(UObject* WorldContextObject,
UPARAM(ref) USGNova2Glove* Nova2Glove,
const USGBasicHandModel* HandModel,
USGHandPose*& OutHandPose);
/**
* Returns the Hand Angles calculated by this Nova2 Glove. Used for input for HandPoses, but can be used in and of
* itself.
*
* @param OutHandAngles
*/
UFUNCTION(BlueprintPure, DisplayName="Get Hand Angles", Category="SenseGlove | Core | Nova | Nova 2 Glove",
meta=(WorldContext="WorldContextObject"))
static bool GetHandAngles(const USGNova2Glove* Nova2Glove, TArray<FSGVectorArray>& OutHandAngles);
/*
* Retrieve the calibration status of this Nova 2.0 Glove.
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static ESGHapticGloveCalibrationState GetCalibrationState(const USGNova2Glove* Nova2Glove);
/*
* Completes sensor Normalization on the Nova 2.0's end.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void EndCalibration(UPARAM(ref) USGNova2Glove* Nova2Glove);
/*
* Completes sensor Normalization on the Nova 2.0's end.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void ResetCalibration(UPARAM(ref) USGNova2Glove* Nova2Glove);
public:
/*
* Stop all haptic feedback effects playing on this device.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void StopHaptics(UPARAM(ref) USGNova2Glove* Nova2Glove);
/**
* Stop only all vibrotactile feedback.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void StopVibrations(UPARAM(ref) USGNova2Glove* Nova2Glove);
/**
* Flush all streaming haptic effects on the different fingers to the Nova 2.0 Glove.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool SendHaptics(UPARAM(ref) USGNova2Glove* Nova2Glove);
/**
* Returns true if this Glove supports the chosen haptic location.
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool SupportsCustomWaveform(const USGNova2Glove* Nova2Glove, ESGHapticLocation AtLocation);
/**
* Send a custom waveform to the Nova 2.0.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool SendCustomWaveform(UPARAM(ref) USGNova2Glove* Nova2Glove,
USGCustomWaveform* OutWaveform, ESGHapticLocation Location);
/**
* Queue a list of force-feedback levels, between 0.0 and 1.0. Your list should be sorted from thumb to pinky.
*
* @remarks Devices that 'only' have on/off FFB will treat any value > 0.0 as 1.0.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool QueueForceFeedbackLevels(UPARAM(ref) USGNova2Glove* Nova2Glove, const TArray<float>& Levels01);
/**
* Set the Force-Feedback value of a particular finger to a specific level.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool QueueForceFeedbackLevel(UPARAM(ref) USGNova2Glove* Nova2Glove, int32 Finger, float Level01);
/**
* Queue a list of vibration levels, between 0.0 and 1.0. Your list should be sorted from thumb to pinky.
*
* @remarks Devices that 'only' have on/off FFB will treat any value > 0.0 as 1.0.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool QueueVibroLevels(UPARAM(ref) USGNova2Glove* Nova2Glove, const TArray<float>& Amplitudes);
/**
* Queue a command to set the (continuous) vibration level at a specific location to a set amplitude. This is to
* support backwards compatibility for older plugins. Use of Customwaveforms is encouraged.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool QueueVibroLevel(UPARAM(ref) USGNova2Glove* Nova2Glove, ESGHapticLocation Location, float Level01);
/**
* Retrieve the location of the glove origin, based on a reference location.
*/
UFUNCTION(BlueprintPure, DisplayName="Get Glove Location", Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void GetGloveLocation_RP_FQuat_RR_TH_OutGP_FQuat_OutGR(
const USGNova2Glove* Nova2Glove,
const FVector& ReferencePosition, const FQuat& ReferenceRotation,
ESGPositionalTrackingHardware TrackingHardware,
FVector& OutGlovePosition, FQuat& OutGloveRotation);
/**
* Retrieve the location of the glove origin, based on a reference location.
*/
UFUNCTION(BlueprintPure, DisplayName="Get Glove Location", Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void GetGloveLocation_RP_FRotator_RR_TH_OutGP_FRotator_OutGR(
const USGNova2Glove* Nova2Glove,
const FVector& ReferencePosition, const FRotator& ReferenceRotation,
ESGPositionalTrackingHardware TrackingHardware,
FVector& OutGlovePosition, FRotator& OutGloveRotation);
/**
* Retrieve the location of the wrist, based on a reference location and default glove-hand offsets.
*/
UFUNCTION(BlueprintPure, DisplayName="Get Wrist Location", Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void GetWristLocation_RP_FQuat_RR_TH_OutWP_FQuat_OutWR(
const USGNova2Glove* Nova2Glove,
const FVector& ReferencePosition, const FQuat& ReferenceRotation,
ESGPositionalTrackingHardware TrackingHardware,
FVector& OutWristPosition, FQuat& OutWristRotation);
/**
* Retrieve the location of the wrist, based on a reference location and default glove-hand offsets.
*/
UFUNCTION(BlueprintPure, DisplayName="Get Wrist Location", Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void GetWristLocation_RP_FRotator_RR_TH_OutWP_FRotator_OutWR(
const USGNova2Glove* Nova2Glove,
const FVector& ReferencePosition, const FRotator& ReferenceRotation,
ESGPositionalTrackingHardware TrackingHardware,
FVector& OutWristPosition, FRotator& OutWristRotation);
/**
* Access DeviceInfo of this Nova.
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove",
meta=(WorldContext="WorldContextObject"))
static USGNovaGloveInfo* GetGloveInfo(UObject* WorldContextObject, const USGNova2Glove* Nova2Glove);
/**
* If true, the Index Finger sensors will influence the tracking of the other fingers.
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool DoesIndexInfluenceOthers(const USGNova2Glove* Nova2Glove);
/**
*
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void SetIndexInfluencesOthers(UPARAM(ref) USGNova2Glove* Nova2Glove, bool bInfluenceOthers);
/**
* If true, this glove's sensor calibration runs on board the device.
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool SupportsOnBoardNormalization(const USGNova2Glove* Nova2Glove);
/**
* Get the latest Sensor Data from this Glove.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove",
meta=(WorldContext="WorldContextObject"))
static bool GetSensorData(UObject* WorldContextObject,
UPARAM(ref) USGNova2Glove* Nova2Glove, USGNova2GloveSensorData*& OutSensorData);
/**
* Returns the normalized Sensor Data of this Nova2 Glove. If no normalization is running on the glove(s), then
* it's done on the PC side.
*
* @param OutNormalizedValues
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool GetNormalizedInput(const USGNova2Glove* Nova2Glove, TArray<float>& OutNormalizedValues);
/**
* Tell the Nova Glove to send Raw Data instead of normalized data.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool SendRawData(UPARAM(ref) USGNova2Glove* Nova2Glove);
/**
* Tell the Nova Glove to send normalized data.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool SendNormalizedData(UPARAM(ref) USGNova2Glove* Nova2Glove);
/**
* Convert a HapticLocation into a Nova 2.0 Motor location.
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static ESGNova2VibroMotor ToNovaMotor(const USGNova2Glove* Nova2Glove, ESGHapticLocation Location);
/**
* Returns the channel index for a particular motor. Can make this as complex as I want for the Nova2 GLove(s).
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static int32 ChannelIndex(const USGNova2Glove* Nova2Glove, ESGNova2VibroMotor Motor);
/**
* Ensures the waveform that is to be sent to this Nova2 Glove has the appropriate parameters.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static void ValidateWaveform(const USGNova2Glove* Nova2Glove,
USGCustomWaveform* OutWaveform, ESGNova2VibroMotor Motor);
/**
* Directly sends a custom waveform to the Nova 2.0 Glove motors, as opposed to specifying a Haptic Location.
*/
UFUNCTION(BlueprintCallable, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static bool SendCustomWaveform_Nova2(
UPARAM(ref) USGNova2Glove* Nova2Glove,
USGCustomWaveform* OutWaveform, ESGNova2VibroMotor Motor, bool bValidateWaveform = true);
/**
* Create a string representation of this device for reporting purposes.
*/
UFUNCTION(BlueprintPure, Category="SenseGlove | Core | Nova | Nova 2 Glove")
static FString ToString(const USGNova2Glove* Nova2Glove);
};