SGHapticsComponent docs: document individual haptics functions

2026-02-24 13:16:38 +01:00
parent b84426d3ff
commit b7df9050f1
14 changed files with 328 additions and 4 deletions
@@ -187,3 +187,294 @@ The same set of functions are also exposed to Blueprint:
 ![SGHapticsComponent - Blueprint functions](sghapticscomponent-functions1.png "SGHapticsComponent - Blueprint functions")

 ![SGHapticsComponent - Blueprint functions](sghapticscomponent-functions2.png "SGHapticsComponent - Blueprint functions")
+
+## Quick Blueprint Functions Reference
+
+Here is a brief at-a-glance reference of all `SGHapticsComponent` Blueprint functions related to haptic feedback.
+
+### Stop Haptics
+
+Stops **all active haptic effects** currently playing on the glove.
+
+This includes:
+
+- Vibrations.
+- Force-feedback (FFB).
+- Wrist-squeeze.
+- Any queued but unsent haptic commands.
+
+![SGHapticsComponent - Blueprint function: Stop Haptics](sghapticscomponent-blueprint-function-stop-haptics.png "SGHapticsComponent - Blueprint function: Stop Haptics")
+
+**Typical Use Cases:**
+
+- Resetting the glove at the end of a simulation.
+- Restarting a level.
+- Emergency stop logic.
+- Cleaning up when disabling an actor.
+
+**Returns:**
+
+This Blueprint node does not return a value.
+
+### Stop Vibrations
+
+Stops only **vibration feedback**, without affecting:
+
+- Force-feedback
+- Wrist-squeeze
+
+![SGHapticsComponent - Blueprint function: Stop Vibrations](sghapticscomponent-blueprint-function-stop-vibrations.png "SGHapticsComponent - Blueprint function: Stop Vibrations")
+
+**Typical Use Cases:**
+
+It is useful for example if you want to keep finger resistance active while stopping tactile feedback.
+
+**Returns:**
+
+This Blueprint node does not return a value.
+
+### Send Haptics
+
+Compiles all currently queued haptic commands and sends them to the glove.
+
+![SGHapticsComponent - Blueprint function: Send Haptics](sghapticscomponent-blueprint-function-stop-haptics.png "SGHapticsComponent - Blueprint function: Send Haptics")
+
+The component works using a **queue-based system**:
+
+1. You queue multiple commands (Force-feedback, Vibro, Wrist, etc..)
+2. You call **Send Haptics**.
+3. Everything is compiled into one device message.
+
+**Returns:**
+
+- `true`: Indicates message has been successfully sent to SenseCom.
+- `false`: Failed to send haptics.
+
+### Supports Custom Waveform
+
+Checks whether the glove supports **custom waveform vibration** at a specific location.
+
+![SGHapticsComponent - Blueprint function: Supports Custom Waveform](sghapticscomponent-blueprint-function-supports-custom-waveform.png "SGHapticsComponent - Blueprint function: Supports Custom Waveform")
+
+**Parameters**:
+
+- **AtLocation:** The vibration location to test (e.g., Thumb Tip, Index Tip, Palm Index Side, etc.).
+
+**Returns:**
+
+- `true`: Custom waveform is supported.
+- `false`: Not supported at this location.
+
+You can call this before using `Send Custom Waveform` to see if your glove model at the specified location supports vibration.
+
+### Send Custom Waveform
+
+Sends a **custom vibration waveform** to a specific haptic location.
+
+![SGHapticsComponent - Blueprint function: Send Custom Waveform](sghapticscomponent-blueprint-function-send-custom-waveform.png "SGHapticsComponent - Blueprint function: Send Custom Waveform")
+
+This function has **three overloads** in C++ and is exposed accordingly in Blueprint.
+
+#### 1) Send a Custom Waveform Asset
+
+**Parameters:**
+
+- **OutWaveform:** A predefined waveform asset that allows you to configure additional custom waveform parameters not available in the other two overloads, giving you more fine-grained control over the vibration’s behavior and timing.
+
+| Name                   | Unit      | Range         | Description                                                                 |
+|------------------------|-----------|--------------|-----------------------------------------------------------------------------|
+| Amplitude              |           | 0.0 … 1.0     | Vibration intensity                                                         |
+| Start Frequency        | Hz        | 10 … 500      | Vibration Frequency at the start of the vibration                          |
+| End Frequency          | Hz        | 10 … 500      | Vibration Frequency at the end of the vibration                            |
+| Attack Time            | s         | 0.0 … 1.0     | Time to reach from 0.0 to Amplitude                                        |
+| Sustain Time           | s         | 0.0 … 1.0     | Time for which the signal will stay at Amplitude                           |
+| Decay Time             | s         | 0.0 … 1.0     | Time to reach from Amplitude down to  0.0.                                 |
+| Pause Time             | s         | 0.0 … 1.0     | Time between each vibration, when repeating the waveform.                  |
+| Repeat Amount          |           | 1 .. 100      | How often the waveform is repeated before stopping.                        |
+| Infinite               |           | True / False  | If true, the glove will keep playing this waveform until a new one is played. |
+| Waveform Type          | EWaveType | 0 .. 5        | The shape of the waveform: Sine / Square / SawUp / SawDown / Triangle / Noise. |
+| FrequencySwitchTime*   |           | 0.0 … 1.0     | At this position in the waveform (0.0 being start, 1.0 being the end), we start multiply the Frequency by FrequencySwitchFactor |
+| FrequencySwitchFactor* |           | 1.0 .. 3.0    | How much to multiply the frequency by, after FrequencySwitchTime has passed. |
+
+- **Location:** Where to play the waveform.
+
+**Returns:**
+
+- `true`: If command successfully sent.
+- `false`: If it fails.
+
+#### 2) Send Amplitude + Duration
+
+**Parameters:**
+
+- **Amplitude:** Vibration strength (0.0 – 1.0).
+- **Duration:** Duration in seconds.
+- **Location:** Target haptic location.
+
+**Returns:**
+
+- `true`: If command successfully sent.
+- `false`: If it fails.
+
+#### 3) Send Amplitude + Duration + Frequency
+
+**Parameters:**
+
+- **Amplitude** — Vibration strength (0.0 – 1.0).
+- **Duration** — Duration in seconds.
+- **Frequency** — Vibration frequency in Hz.
+- **Location** — Target haptic location.
+
+**Returns:**
+
+- `true`: If command successfully sent.
+- `false`: If it fails.
+
+### Queue Force Feedback Levels
+
+Queues force-feedback levels for **all fingers** at once.
+
+![SGHapticsComponent - Blueprint function: Queue Force Feedback Levels](sghapticscomponent-blueprint-function-queue-force-feedback-levels.png "SGHapticsComponent - Blueprint function: Queue Force Feedback Levels")
+
+**Parameters:**
+
+- **Levels01:** Array containing the Force-Feedback levels between `0.0` (no FFB) to `1.0` (full FFB); ordered from **Thumb → Index → Middle → Ring → Pinky**.
+
+> [!NOTE]
+> Force-feedback value behavior:
+>
+> - `0.0` = No resistance.
+> - `1.0` = Full resistance.
+> - Values `< 0.0` are ignored.
+> - Devices that only support on/off FFB treat any value > `0.0` as full force.
+
+**Returns:**
+
+- `true`: If queued successfully.
+- `false`: If it fails.
+
+### Queue Force Feedback Level
+
+Queues force-feedback on a **particular finger** to a specific level.
+
+![SGHapticsComponent - Blueprint function: Queue Force Feedback Level](sghapticscomponent-blueprint-function-queue-force-feedback-level.png "SGHapticsComponent - Blueprint function: Queue Force Feedback Level")
+
+**Parameters:**
+
+- **Finger:**  Index of the finger; indexed from **Thumb → Index → Middle → Ring → Pinky**.
+- **Level01:** Value clamped between `0.0` (no FFB) to `1.0` (full FFB).
+
+> [!NOTE]
+> Force-feedback value behavior:
+>
+> - `0.0` = No resistance.
+> - `1.0` = Full resistance.
+> - Values `< 0.0` are ignored.
+> - Devices that only support on/off FFB treat any value > `0.0` as full force.
+
+**Returns:**
+
+- `true`: If queued successfully.
+- `false`: If it fails.
+
+### Queue Vibro Levels
+
+> [!IMPORTANT]
+> **Legacy Function – Use Custom Waveforms Instead**
+>
+> `Queue Vibro Levels` is retained for backward compatibility with older API
+> releases.
+>
+> Internally, it delegates to `Send Custom Waveform`, which is the recommended
+> method for applying vibrotactile feedback.
+>
+> For new projects, prefer `Send Custom Waveform`, as it provides more
+> fine-grained control over amplitude, frequency, timing, and waveform shaping.
+
+Queues continuous vibrotactile levels for **all fingers** at once to a set amplitude.
+
+![SGHapticsComponent - Blueprint function: Queue Vibro Levels](sghapticscomponent-blueprint-function-queue-vibro-levels.png "SGHapticsComponent - Blueprint function: Queue Vibro Levels")
+
+**Parameters:**
+
+- **Levels01:** Array containing the vibro levels between `0.0` (no vibration) to `1.0` (full vibration); ordered from **Thumb → Index → Middle → Ring → Pinky**.
+
+> [!NOTE]
+> Force-feedback value behavior:
+>
+> - `0.0` = No vibration.
+> - `1.0` = Full vibration.
+> - Values `< 0.0` are ignored.
+
+**Returns:**
+
+- `true`: If queued successfully.
+- `false`: If it fails.
+
+### Queue Vibro Level
+
+> [!IMPORTANT]
+> **Legacy Function – Use Custom Waveforms Instead**
+>
+> `Queue Vibro Level` is retained for backward compatibility with older API
+> releases.
+>
+> Internally, it delegates to `Send Custom Waveform`, which is the recommended
+> method for applying vibrotactile feedback.
+>
+> For new projects, prefer `Send Custom Waveform`, as it provides more
+> fine-grained control over amplitude, frequency, timing, and waveform shaping.
+
+Queues continuous vibration at a **specific location** to a set amplitude.
+
+![SGHapticsComponent - Blueprint function: Queue Vibro Level](sghapticscomponent-blueprint-function-queue-vibro-level.png "SGHapticsComponent - Blueprint function: Queue Vibro Level")
+
+**Parameters:**
+
+- **Location:** Target location to apply vibration.
+- **Level01 (float):** Value clamped between `0.0` (no vibration) to `1.0` (full vibration).
+  
+> [!NOTE]
+> Force-feedback value behavior:
+>
+> - `0.0` = No vibration.
+> - `1.0` = Full vibration.
+> - Values `< 0.0` are ignored.
+
+**Returns:**
+
+- `true`: If queued successfully.
+- `false`: If it fails.
+
+### Supports Wrist Squeeze
+
+Checks if the connected glove supports **active wrist-squeeze feedback**.
+
+![SGHapticsComponent - Blueprint function: Supports Wrist Squeeze](sghapticscomponent-blueprint-function-supports-wrist-squeeze.png "SGHapticsComponent - Blueprint function: Supports Wrist Squeeze")
+
+**Returns:**
+
+- `true`: If wrist-squeeze is supported.
+- `false`: If it's not supported.
+
+### Queue Wrist Squeeze
+
+Queues a wrist-squeeze feedback at the desired level, and optionally if chosen, sends it right away.
+
+![SGHapticsComponent - Blueprint function: Queue Wrist Squeeze](sghapticscomponent-blueprint-function-queue-wrist-squeeze.png "SGHapticsComponent - Blueprint function: Queue Wrist Squeeze")
+
+**Parameters:**
+
+- **SqueezeLevel01:** Value clamped between `0.0` (no squeeze) to `1.0` (full squeeze).
+- **bSendImmediate** If set to `true`, immediately sends the command, otherwise only queues until `Send Haptics` function is called.
+
+> [!NOTE]
+> Wrist-squeeze value behavior:
+>
+> - `0.0` = No squeeze.
+> - `1.0` = Full squeeze.
+
+**Returns:**
+
+- `true`: If queued successfully.
+- `false`: If it fails.