### JslStartContinuousCalibration

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Starts collecting gyroscope data for continuous calibration.

```APIDOC
## JslStartContinuousCalibration

### Description
Start collecting gyro data, recording the ongoing average and using that to offset gyro output.

### Method
POST

### Endpoint
`/device/{deviceId}/calibration/continuous/start`

### Parameters
#### Path Parameters
* **deviceId** (int) - Required - The ID of the device.
```

--------------------------------

### Complete JoyShockLibrary Integration Example

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

This C++ example shows full initialization, per-frame polling, callbacks, and shutdown for a typical PC game integration. It sets up connection/disconnection callbacks, handles input, manages active controller IDs, and configures gyro settings. The main loop periodically checks for new devices and polls motion states, with proper disconnection and disposal at the end.

```cpp
#include "JoyShockLibrary.h"
#include <vector>
#include <atomic>

std::vector<int> activeHandles;
std::atomic<bool> running(true);

void OnConnect(int id) {
    activeHandles.push_back(id);
    JslSetGyroSpace(id, 2);                  // Player Space gyro
    JslSetAutomaticCalibration(id, true);    // auto-calibrate gyro
    int n = (int)activeHandles.size();
    JslSetPlayerNumber(id, n);               // set player light
    int colours[] = {0xFF0000, 0x0000FF, 0x00FF00, 0xFFFF00};
    JslSetLightColour(id, colours[(n - 1) % 4]);
    printf("Player %d connected (id=%d)\n", n, id);
}

void OnDisconnect(int id, bool timedOut) {
    activeHandles.erase(std::remove(activeHandles.begin(), activeHandles.end(), id),
                        activeHandles.end());
    printf("Controller %d disconnected (%s)\n", id, timedOut ? "timeout" : "unplugged");
}

void OnInput(int id, JOY_SHOCK_STATE cur, JOY_SHOCK_STATE prev,
             IMU_STATE imu, IMU_STATE, float dt)
{
    int pressed = cur.buttons & ~prev.buttons;
    if (pressed & JSMASK_HOME) { running = false; return; }  // quit on Home/PS

    // Gyro aiming (accumulated since last report):
    float gx, gy, gz;
    JslGetAndFlushAccumulatedGyro(id, gx, gy, gz);
    // Apply gx*dt, gy*dt to camera...

    // Rumble feedback on ZR press:
    if (pressed & JSMASK_ZR) JslSetRumble(id, 0, 180);
    if ((~cur.buttons & prev.buttons) & JSMASK_ZR) JslSetRumble(id, 0, 0);
}

int main() {
    JslSetConnectCallback(OnConnect);
    JslSetDisconnectCallback(OnDisconnect);
    JslSetCallback(OnInput);

    int n = JslConnectDevices();
    printf("Found %d controller(s)\n", n);

    // Main game loop (callbacks fire from background threads):
    while (running) {
        // Check for newly plugged-in controllers periodically:
        JslConnectDevices();

        // Or poll state directly:
        for (int id : activeHandles) {
            if (!JslStillConnected(id)) continue;
            MOTION_STATE motion = JslGetMotionState(id);
            // Use motion.quatW/X/Y/Z for 3D controller orientation rendering...
        }

        // sleep ~16ms / yield to OS
    }

    JslDisconnectAndDisposeAll();
    return 0;
}

```

--------------------------------

### Get Controller Info and Settings

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Fetches a snapshot of controller configuration including type, split type, gyro space, LED color, player number, and calibration/connection status in a single call.

```cpp
JSL_SETTINGS settings = JslGetControllerInfoAndSettings(deviceId);

printf("Controller type:    %d\n", settings.controllerType);
// 1=Left Joy-Con, 2=Right Joy-Con, 3=Pro/Full, 4=DS4, 5=DualSense

printf("Split type:         %d\n", settings.splitType);
// 1=Left half, 2=Right half, 3=Full controller

printf("Gyro space:         %d\n", settings.gyroSpace);
// 0=Local, 1=World, 2=Player

printf("LED colour (RGB):   #%06X\n", settings.colour);
printf("Player number:      %d\n",    settings.playerNumber);
printf("Calibrating:        %s\n",    settings.isCalibrating ? "yes" : "no");
printf("Auto-calibration:   %s\n",    settings.autoCalibrationEnabled ? "yes" : "no");
printf("Connected:          %s\n",    settings.isConnected ? "yes" : "no");
```

--------------------------------

### JslGetStickStep

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Gets the smallest step size between two values for the device's analog sticks.

```APIDOC
## JslGetStickStep

### Description
Different devices use different size data types and different ranges on those data types when reporting stick axes. For some calculations, it may be important to know the limits of the current device and work around them in different ways. This gives the smallest step size between two values for the given device's analog sticks.

### Method
GET

### Endpoint
`/device/{deviceId}/stick/step`

### Parameters
#### Path Parameters
* **deviceId** (int) - Required - The ID of the device.

#### Return Value
* **float** - The smallest step size for analog sticks.
```

--------------------------------

### Connect and Enumerate Devices

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Scans for supported controllers, connects to any not already connected, initializes them, and starts polling threads. Safe to call repeatedly. Retrieves device handles and identifies controller types.

```cpp
#include "JoyShockLibrary.h"
#include <vector>

// Initial connect (or reconnect check):
int numDevices = JslConnectDevices();
printf("Connected devices: %d\n", numDevices);

// Retrieve all device handles:
std::vector<int> handles(numDevices);
int found = JslGetConnectedDeviceHandles(handles.data(), numDevices);

for (int i = 0; i < found; i++) {
    int id = handles[i];
    int type = JslGetControllerType(id);
    switch (type) {
        case JS_TYPE_JOYCON_LEFT:    printf("[%d] Left Joy-Con\n",    id); break;
        case JS_TYPE_JOYCON_RIGHT:   printf("[%d] Right Joy-Con\n",   id); break;
        case JS_TYPE_PRO_CONTROLLER: printf("[%d] Pro Controller\n",  id); break;
        case JS_TYPE_DS4:            printf("[%d] DualShock 4\n",     id); break;
        case JS_TYPE_DS:             printf("[%d] DualSense\n",       id); break;
    }
    printf("  Split type: %d  Colour: #%06X\n",
        JslGetControllerSplitType(id),
        JslGetControllerColour(id));
}

// At shutdown:
JslDisconnectAndDisposeAll();

```

--------------------------------

### JslGetControllerColour

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Gets the colour of a controller.

```APIDOC
## JslGetControllerColour — Get controller colour

### Description
Gets the colour of a controller.

### Method
```cpp
int JslGetControllerColour(int deviceId);
```

### Parameters
#### Path Parameters
- `deviceId` (*int*) - The ID of the controller.

### Returns
- `int`: The controller colour as an RGB integer (e.g., `#00FF00`).
```

--------------------------------

### JslGetPollRate

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Gets the expected number of updates per second from the device.

```APIDOC
## JslGetPollRate

### Description
Different devices report back new information at different rates. For the given device, this gives how many times one would usually expect the device to report back per second.

### Method
GET

### Endpoint
`/device/{deviceId}/pollrate`

### Parameters
#### Path Parameters
* **deviceId** (int) - Required - The ID of the device.

#### Return Value
* **float** - The expected poll rate in updates per second.
```

--------------------------------

### JslConnectDevices

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Scans for and connects to supported controllers, initializes them, and starts polling threads. Returns the number of connected devices. This function is safe to call repeatedly.

```APIDOC
## JslConnectDevices — Scan and connect supported controllers

### Description
Enumerates all HID devices, connects any supported controllers not already connected, initialises each (calibration, IMU, LED defaults), and starts per-controller polling threads. Returns the total number of currently connected devices. Safe to call repeatedly to detect new connections without disrupting existing ones.

### Method
```cpp
int JslConnectDevices();
```

### Returns
- `int`: The total number of currently connected devices.
```

--------------------------------

### JslGetTriggerStep

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Gets the smallest step size between two values for the device's analog triggers, or 1.0 if they are binary.

```APIDOC
## JslGetTriggerStep

### Description
Some devices have analog triggers, some don't. For some calculations, it may be important to know the limits of the current device and work around them in different ways. This gives the smallest step size between two values for the given device's triggers, or 1.0 if they're actually just binary inputs.

### Method
GET

### Endpoint
`/device/{deviceId}/trigger/step`

### Parameters
#### Path Parameters
* **deviceId** (int) - Required - The ID of the device.

#### Return Value
* **float** - The smallest step size for analog triggers, or 1.0 for binary triggers.
```

--------------------------------

### Get Controller Information and Settings

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Retrieve a comprehensive set of controller information and settings in a single call, including gyro space, color, and calibration status. Refer to JoyShockLibrary.h for detailed field information.

```c
JSL_SETTINGS JslGetControllerInfoAndSettings(int deviceId)
```

--------------------------------

### Manual Continuous Calibration

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

This section details the process of manual continuous calibration for the controller's gyro. It involves starting, pausing, and resetting the calibration process, as well as inspecting and overriding the calibration offset.

```APIDOC
## Manual Continuous Calibration

### Description
Manual calibration collects gyro samples while the controller is at rest to compute a zero-drift offset. Call `JslStartContinuousCalibration` when showing a "place controller flat and still" prompt, `JslPauseContinuousCalibration` when done, and optionally inspect or override the result.

### Usage
```cpp
printf("Place controller on a flat surface and press A to calibrate...\n");
// Wait for user input, then:
JslResetContinuousCalibration(deviceId);  // clear old calibration
JslStartContinuousCalibration(deviceId);  // begin collecting

// ... wait 3 seconds in your game loop ...

JslPauseContinuousCalibration(deviceId);  // stop collecting, keep data

// Inspect the computed offset:
float ox, oy, oz;
JslGetCalibrationOffset(deviceId, ox, oy, oz);
printf("Gyro offset: (%.4f, %.4f, %.4f) dps\n", ox, oy, oz);

// Override with a known-good offset (e.g., saved from a previous session):
JslSetCalibrationOffset(deviceId, ox, oy, oz);
```
```

--------------------------------

### JslGetTriggerStep

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Gets the resolution of the analog trigger input. This indicates whether the trigger is binary or analog.

```APIDOC
## JslGetTriggerStep

### Description
Utility function for querying device-specific characteristics. Returns the resolution of the analog trigger input.

### Parameters
- **deviceId** (int) - The ID of the device.

### Returns
- **float** - The trigger step resolution (1/256 for analog triggers like PS, 1.0 for binary triggers like Nintendo).

### Usage Example
```cpp
float trigRes = JslGetTriggerStep(deviceId);
printf("Trigger resolution: %.5f\n", trigRes);
if (trigRes == 1.0f) {
    printf("Binary trigger — treat as button only\n");
}
```
```

--------------------------------

### Get Motion State (Orientation, Gravity, Acceleration)

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Retrieves fused sensor data including device orientation, gravity vector, and processed linear acceleration. Note that for mouse-like aiming, gyro values are preferred over quaternions due to potential errors introduced by gravity correction.

```cpp
MOTION_STATE motion = JslGetMotionState(deviceId);

// Quaternion orientation (W, X, Y, Z) — subject to yaw drift
printf("Orientation quat: W=%.3f X=%.3f Y=%.3f Z=%.3f\n",
    motion.quatW, motion.quatX, motion.quatY, motion.quatZ);

// Gravity direction in device-local space (used for roll/pitch correction)
printf("Gravity:          X=%.3f Y=%.3f Z=%.3f\n",
    motion.gravX, motion.gravY, motion.gravZ);

// Linear acceleration with gravity removed
printf("Linear accel:     X=%.3f Y=%.3f Z=%.3f\n",
    motion.accelX, motion.accelY, motion.accelZ);

// NOTE: For mouse-like aiming/cursor control, prefer JslGetIMUState gyro values
// or JslGetAndFlushAccumulatedGyro, not quaternions — gravity correction
// introduces error for flat-plane movement.
```

--------------------------------

### Get Controller Split Type

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Check if a controller is a half-controller or a full controller. Returns an integer indicating if it's a left half, right half, or a full controller.

```c
int JslGetControllerSplitType(int deviceId)
```

--------------------------------

### Get Full Controller State

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Efficiently retrieves the complete button, trigger, and stick state for a controller. Recommended when multiple values are needed. Includes logic for detecting button presses/releases and applying a deadzone to the left stick.

```cpp
JOY_SHOCK_STATE state = JslGetSimpleState(deviceId);

// Detect button press this frame (compare with last frame):
JOY_SHOCK_STATE lastState = /* stored from previous frame */;
int justPressed  = state.buttons & ~lastState.buttons;
int justReleased = ~state.buttons & lastState.buttons;

if (justPressed & JSMASK_S)  printf("South button just pressed\n");
if (justReleased & JSMASK_ZR) printf("ZR/R2 just released\n");

// Apply a radial deadzone to left stick:
float lx = state.stickLX;
float ly = state.stickLY;
float magnitude = sqrtf(lx * lx + ly * ly);
const float deadzone = 0.15f;
if (magnitude < deadzone) { lx = 0.f; ly = 0.f; }
else {
    float scale = (magnitude - deadzone) / (1.f - deadzone) / magnitude;
    lx *= scale;
    ly *= scale;
}
printf("Left stick (deadzoned): (%.3f, %.3f)\n", lx, ly);

```

--------------------------------

### Get Controller State with JOY_SHOCK_STATE

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Retrieve the full state of a connected controller, including digital buttons, analog triggers, and stick positions. Use the JSMASK defines to check individual button states. Analog triggers and sticks are normalized to a -1.0 to 1.0 range.

```cpp
#include "JoyShockLibrary.h"

// After connecting devices:
int deviceId = handles[0];
JOY_SHOCK_STATE state = JslGetSimpleState(deviceId);

// Check face buttons (layout-neutral North/South/East/West naming)
if (state.buttons & JSMASK_S) printf("South face button pressed\n"); // B (Nintendo) / X (PlayStation)
if (state.buttons & JSMASK_E) printf("East face button pressed\n");  // A (Nintendo) / O (PlayStation)
if (state.buttons & JSMASK_W) printf("West face button pressed\n");  // Y (Nintendo) / □ (PlayStation)
if (state.buttons & JSMASK_N) printf("North face button pressed\n"); // X (Nintendo) / △ (PlayStation)

// D-pad
if (state.buttons & JSMASK_UP)    printf("D-pad up\n");
if (state.buttons & JSMASK_DOWN)  printf("D-pad down\n");
if (state.buttons & JSMASK_LEFT)  printf("D-pad left\n");
if (state.buttons & JSMASK_RIGHT) printf("D-pad right\n");

// Shoulder / trigger buttons
if (state.buttons & JSMASK_L)  printf("L/L1 pressed\n");
if (state.buttons & JSMASK_R)  printf("R/R1 pressed\n");
if (state.buttons & JSMASK_ZL) printf("ZL/L2 digital pressed\n");
if (state.buttons & JSMASK_ZR) printf("ZR/R2 digital pressed\n");

// Analog triggers: 0.0 (fully released) to 1.0 (fully pressed)
// Nintendo devices report only 0.0 or 1.0 (binary)
printf("Left trigger:  %.3f\n", state.lTrigger);
printf("Right trigger: %.3f\n", state.rTrigger);

// Analog sticks: -1.0 to 1.0 on each axis
printf("Left  stick: (%.3f, %.3f)\n", state.stickLX, state.stickLY);
printf("Right stick: (%.3f, %.3f)\n", state.stickRX, state.stickRY);

// Menu buttons
if (state.buttons & JSMASK_PLUS)    printf("+ / Options pressed\n");
if (state.buttons & JSMASK_MINUS)   printf("- / Share pressed\n");
if (state.buttons & JSMASK_HOME)    printf("Home / PS pressed\n");
if (state.buttons & JSMASK_CAPTURE) printf("Capture / Touchpad Click / Create pressed\n");

// Joy-Con exclusive
if (state.buttons & JSMASK_SL) printf("SL pressed\n");
if (state.buttons & JSMASK_SR) printf("SR pressed\n");
// DualSense exclusive
if (state.buttons & JSMASK_MIC) printf("Mic button pressed\n");

```

--------------------------------

### Get Touch State (DualShock 4/DualSense Touchpad)

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Retrieves the state of up to two simultaneous touch points on the controller's touchpad. Touch positions are normalized (0.0-1.0). You can also retrieve touchpad dimensions and previous touch states for delta calculations.

```cpp
TOUCH_STATE touch = JslGetTouchState(deviceId);

if (touch.t0Down) {
    printf("Touch 0: id=%d  pos=(%.3f, %.3f)\n",
        touch.t0Id, touch.t0X, touch.t0Y);
}
if (touch.t1Down) {
    printf("Touch 1: id=%d  pos=(%.3f, %.3f)\n",
        touch.t1Id, touch.t1X, touch.t1Y);
}

// Get absolute pixel dimensions of the touchpad (DS4/DS5 = 1920 x 943)
int sizeX = 0, sizeY = 0;
if (JslGetTouchpadDimension(deviceId, sizeX, sizeY)) {
    printf("Touchpad resolution: %d x %d\n", sizeX, sizeY);
    // Convert normalized to pixel coords:
    float pixelX = touch.t0X * sizeX;
    float pixelY = touch.t0Y * sizeY;
    printf("Touch 0 pixel pos: (%.1f, %.1f)\n", pixelX, pixelY);
}

// Retrieve previous frame's touch state (useful for delta computation):
TOUCH_STATE prevTouch = JslGetTouchState(deviceId, /*previous=*/true);
float deltaX = touch.t0X - prevTouch.t0X;
float deltaY = touch.t0Y - prevTouch.t0Y;
```

--------------------------------

### Get IMU State with IMU_STATE

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Retrieve raw gyroscope and accelerometer readings from the controller's IMU. Values are automatically transformed based on the active gyro space setting. Individual axis getters are available but less efficient.

```cpp
IMU_STATE imu = JslGetIMUState(deviceId);

// Gyroscope: angular velocity in degrees/second
printf("Gyro  X=%.2f  Y=%.2f  Z=%.2f dps\n",
    imu.gyroX, imu.gyroY, imu.gyroZ);

// Accelerometer: acceleration in g-force
printf("Accel X=%.2f  Y=%.2f  Z=%.2f g\n",
    imu.accelX, imu.accelY, imu.accelZ);

// Individual axis convenience getters (less efficient than the struct getter):
float gx = JslGetGyroX(deviceId);
float gy = JslGetGyroY(deviceId);
float gz = JslGetGyroZ(deviceId);

float ax = JslGetAccelX(deviceId);
float ay = JslGetAccelY(deviceId);
float az = JslGetAccelZ(deviceId);

```

--------------------------------

### JslGetControllerType

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Gets the type of a controller given its device ID.

```APIDOC
## JslGetControllerType — Get controller type

### Description
Gets the type of a controller given its device ID.

### Method
```cpp
int JslGetControllerType(int deviceId);
```

### Parameters
#### Path Parameters
- `deviceId` (*int*) - The ID of the controller.

### Returns
- `int`: The controller type (e.g., JS_TYPE_JOYCON_LEFT, JS_TYPE_PRO_CONTROLLER, JS_TYPE_DS4, JS_TYPE_DS).
```

--------------------------------

### JSL_SETTINGS — Controller configuration snapshot

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Retrieves a comprehensive snapshot of controller settings including type, gyro space, LED color, player number, and connection status.

```APIDOC
## JslGetControllerInfoAndSettings

### Description
Fetches a bundle of information about the controller's current settings and status.

### Method
```cpp
JSL_SETTINGS JslGetControllerInfoAndSettings(int deviceId)
```

### Parameters
*   **deviceId** (int) - Required - Identifier for the device.

### Response
*   **JSL_SETTINGS** - An object containing controller settings:
    *   **controllerType** (int) - Type of controller (e.g., 1=Left Joy-Con, 4=DS4, 5=DualSense).
    *   **splitType** (int) - Indicates if the controller is part of a split pair (e.g., 1=Left, 2=Right, 3=Full).
    *   **gyroSpace** (int) - The reference space for gyro data (0=Local, 1=World, 2=Player).
    *   **colour** (int) - The RGB color value for the controller's LED.
    *   **playerNumber** (int) - The assigned player number.
    *   **isCalibrating** (bool) - True if the controller is currently undergoing calibration.
    *   **autoCalibrationEnabled** (bool) - True if automatic calibration is active.
    *   **isConnected** (bool) - True if the controller is currently connected.

### Request Example
```cpp
JSL_SETTINGS settings = JslGetControllerInfoAndSettings(deviceId);
```

### Response Example
```cpp
printf("Controller type:    %d\n", settings.controllerType);
printf("Split type:         %d\n", settings.splitType);
printf("Gyro space:         %d\n", settings.gyroSpace);
printf("LED colour (RGB):   #%06X\n", settings.colour);
printf("Player number:      %d\n", settings.playerNumber);
printf("Calibrating:        %s\n", settings.isCalibrating ? "yes" : "no");
printf("Auto-calibration:   %s\n", settings.autoCalibrationEnabled ? "yes" : "no");
printf("Connected:          %s\n", settings.isConnected ? "yes" : "no");
```
```

--------------------------------

### JslGetControllerSplitType

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Gets the split type of a controller (e.g., if a Joy-Con is left or right).

```APIDOC
## JslGetControllerSplitType — Get controller split type

### Description
Gets the split type of a controller (e.g., if a Joy-Con is left or right).

### Method
```cpp
int JslGetControllerSplitType(int deviceId);
```

### Parameters
#### Path Parameters
- `deviceId` (*int*) - The ID of the controller.

### Returns
- `int`: The split type of the controller.
```

--------------------------------

### Set Include Directories

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/JoyShockLibrary/CMakeLists.txt

Configures the include directories for the library, making headers accessible.

```cmake
target_include_directories (
    ${PROJECT_NAME} PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}
)
```

--------------------------------

### Define JoyShockLibrary

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/JoyShockLibrary/CMakeLists.txt

Defines the library target and lists its source and header files.

```cmake
add_library (
    ${PROJECT_NAME}
    JoyShockLibrary.cpp    JoyShockLibrary.h
)
```

--------------------------------

### JslGetTimeSinceLastUpdate

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Gets the time in seconds since the last update was received from the device.

```APIDOC
## JslGetTimeSinceLastUpdate

### Description
Getting the time since the last update was received (in seconds) can be helpful for communicating a poor connection to the user. This can help communicate to wireless players that they need to move closer to the console or in some other way improve the connection.

### Method
GET

### Endpoint
`/device/{deviceId}/time_since_last_update`

### Parameters
#### Path Parameters
* **deviceId** (int) - Required - The ID of the device.

#### Return Value
* **float** - The time in seconds since the last update.
```

--------------------------------

### JslGetControllerInfoAndSettings

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Retrieves comprehensive information and settings for a controller, such as gyro space, color, and calibration status, in a single call.

```APIDOC
## JslGetControllerInfoAndSettings

### Description
Read a bunch of info from the controller in one go instead of requesting each thing one at a time. Gyro space, colour (for LED on PlayStation controllers, for the controller itself for Switch controllers), whether it's calibrating, etc. See JoyShockLibrary.h for more info.

### Parameters
- **deviceId** (int) - Required - The unique identifier for the device.

### Returns
- **JSL_SETTINGS** - An object containing various controller settings and information.
```

--------------------------------

### JslGetTouchId

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Gets the ID of the last touch event on the controller's touchpad. Only supported on DualShock 4 controllers.

```APIDOC
## JslGetTouchId

### Description
Get the last touch's id, which is a value in range of 0-127 that automatically increments whenever a new touch appears, for the controller with the given id. Only DualShock 4s support this. If you want more than just a touch's id, it's more efficient to use JslGetTouchState.

### Method
GET

### Endpoint
`/device/{deviceId}/touch/id`

### Parameters
#### Path Parameters
* **deviceId** (int) - Required - The ID of the device.
#### Query Parameters
* **secondTouch** (bool) - Optional - Defaults to false. Specifies if the second touch is requested.

#### Return Value
* **int** - The ID of the last touch event (0-127).
```

--------------------------------

### Link Platform Dependencies

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/JoyShockLibrary/CMakeLists.txt

Links the library against necessary platform-specific dependencies.

```cmake
target_link_libraries (
    ${PROJECT_NAME} ${JSL_PLATFORM_DEPENDENCY_VISIBILITY}
    JSL_Platform::Dependencies
)
```

--------------------------------

### Get Controller Colour

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Retrieve the color of the controller. This feature is primarily supported by Nintendo devices; other devices will report white.

```c
int JslGetControllerColour(int deviceId)
```

--------------------------------

### Configure Gyro Coordinate System

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Selects the coordinate system for gyro data output. Must be called per device. Options include Local Space (raw), World Space (gravity-corrected), and Player Space (adaptive, recommended).

```cpp
// Set Player Space for all connected devices — best default for cursor/aiming:
for (int id : handles) {
    JslSetGyroSpace(id, 2); // 2 = Player Space
}

// Local space (0): raw gyro, caller picks yaw or roll for horizontal movement
JslSetGyroSpace(deviceId, 0);

// World space (1): maps gravity direction to "up", derives horizontal/vertical axes
// Good when controller tilt should track real-world orientation
JslSetGyroSpace(deviceId, 1);

// Player space (2): similar to World but doesn't depend so strongly on gravity
// calculation accuracy — less error accumulation
JslSetGyroSpace(deviceId, 2);

// Gyro output (X=horizontal, Y=vertical, Z=0 in space modes 1 and 2):
float gx, gy, gz;
JslGetAndFlushAccumulatedGyro(deviceId, gx, gy, gz);
printf("Horizontal: %.2f deg/s  Vertical: %.2f deg/s\n", gx, gy);

```

--------------------------------

### JslGetTimeSinceLastUpdate

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Gets the time in seconds since the last HID report was received from the device. Useful for detecting poor wireless connections.

```APIDOC
## JslGetTimeSinceLastUpdate

### Description
Utility function for querying device-specific characteristics. Returns the time in seconds since the last HID report was received.

### Parameters
- **deviceId** (int) - The ID of the device.

### Returns
- **float** - The time in seconds since the last update.

### Usage Example
```cpp
float stale = JslGetTimeSinceLastUpdate(deviceId);
if (stale > 0.1f) {
    printf("Warning: controller %d signal weak (%.3f s stale)\n", deviceId, stale);
}
```
```

--------------------------------

### JslGetAutoCalibrationStatus

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Gets the status of automatic gyroscope calibration, including whether it's enabled, if the controller is considered still, and the confidence level.

```APIDOC
## JslGetAutoCalibrationStatus

### Description
Get whether auto calibration is enabled, whether we think the controller is currently being held still, and how confident we are in its auto calibration. If you want to prompt the user to manually calibrate their controller, you can use auto calibration, and read these values to show to the user whether the controller is at rest as well as progress for calibration. Then, you can either leave auto calibration enabled (when confidence is high, auto calibration becomes difficult to trigger accidentally), or just disable auto calibration to prevent further changes without the user triggering it manually again.

### Method
GET

### Endpoint
`/device/{deviceId}/calibration/auto/status`

### Parameters
#### Path Parameters
* **deviceId** (int) - Required - The ID of the device.

#### Return Value
* **JSL_AUTO_CALIBRATION** - An object containing the auto calibration status:
  * **enabled** (bool) - Whether auto calibration is enabled.
  * **isStill** (bool) - Whether the controller is currently considered still.
  * **confidence** (float) - The confidence level of the auto calibration.
```

--------------------------------

### Register Callbacks for Device Connection/Disconnection

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Use JslSetConnectCallback and JslSetDisconnectCallback to register functions that will be called when a device connects or disconnects. Ensure callbacks are set before calling JslConnectDevices to capture initial connections.

```cpp
void OnDeviceConnected(int deviceId) {
    printf("New controller connected: id=%d  type=%d\n",
        deviceId, JslGetControllerType(deviceId));
    // Apply default settings on connect:
    JslSetGyroSpace(deviceId, 2);
    JslSetAutomaticCalibration(deviceId, true);
    JslSetLightColour(deviceId, 0x0000FF); // blue for player 1
}

void OnDeviceDisconnected(int deviceId, bool timedOut) {
    printf("Controller %d disconnected (%s)\n",
        deviceId, timedOut ? "timeout" : "explicit");
    // Remove from active handle list, show reconnect prompt, etc.
}

JslSetConnectCallback(OnDeviceConnected);
JslSetDisconnectCallback(OnDeviceDisconnected);

// Call JslConnectDevices AFTER setting callbacks so connect fires for initial devices:
int n = JslConnectDevices();
```

--------------------------------

### MOTION_STATE Struct

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Provides the device's orientation and processed motion data, including quaternions and gravity-compensated acceleration.

```APIDOC
## MOTION_STATE

### Description
The MOTION_STATE reports the orientation of the device as calculated using a sensor fusion solution to combine gyro and accelerometer data.

### Fields
* **float quatW**: Quaternion component W, representing the device's orientation.
* **float quatX**: Quaternion component X, representing the device's orientation.
* **float quatY**: Quaternion component Y, representing the device's orientation.
* **float quatZ**: Quaternion component Z, representing the device's orientation.
* **float accelX**: Local acceleration after accounting for and removing the effect of gravity.
* **float accelY**: Local acceleration after accounting for and removing the effect of gravity.
* **float accelZ**: Local acceleration after accounting for and removing the effect of gravity.
* **float gravX**: Local gravity direction along the X-axis.
* **float gravY**: Local gravity direction along the Y-axis.
* **float gravZ**: Local gravity direction along the Z-axis.
```

--------------------------------

### Get Controller Type

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Determine the type of the connected controller. Returns an integer representing the controller type (e.g., Joy-Con, DualShock 4, DualSense).

```c
int JslGetControllerType(int deviceId)
```

--------------------------------

### JslGetSimpleState

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Retrieves the full button, trigger, and stick state for a controller in a single call. This is the most efficient method when multiple input values are needed.

```APIDOC
## JslGetSimpleState — Get full button/trigger/stick state at once

### Description
The most efficient way to read all button, trigger, and stick data for a controller. Prefer this over the individual getters when you need more than one value.

### Method
```cpp
JOY_SHOCK_STATE JslGetSimpleState(int deviceId);
```

### Parameters
#### Path Parameters
- `deviceId` (*int*) - The ID of the controller.

### Returns
- `JOY_SHOCK_STATE`: A structure containing the current state of buttons, triggers, and sticks.
```

--------------------------------

### Get Automatic Gyro Calibration Status

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Reports the status of automatic gyro calibration, including whether it's enabled, if the controller is currently steady (required for sampling), and the confidence level of the calibration.

```cpp
JSL_AUTO_CALIBRATION cal = JslGetAutoCalibrationStatus(deviceId);

printf("Auto-cal enabled:  %s\n",   cal.autoCalibrationEnabled ? "yes" : "no");
printf("Is steady:         %s\n",   cal.isSteady ? "yes" : "no");
printf("Confidence:        %.2f\n", cal.confidence);

// Use confidence to guide user through manual calibration UI:
if (cal.autoCalibrationEnabled && !cal.isSteady) {
    printf("Hold controller still to calibrate gyro...\n");
} else if (cal.confidence > 0.9f) {
    printf("Gyro calibration complete.\n");
    // Optionally lock in the calibration:
    JslSetAutomaticCalibration(deviceId, false);
}
```

--------------------------------

### MOTION_STATE — Fused orientation, gravity, and processed acceleration

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Provides sensor-fusion output including device orientation, gravity direction, and processed acceleration. This data is computed internally by GamepadMotionHelpers.

```APIDOC
## JslGetMotionState

### Description
Retrieves the fused motion state of the device, including orientation, gravity, and acceleration.

### Method
```cpp
MOTION_STATE JslGetMotionState(int deviceId)
```

### Parameters
*   **deviceId** (int) - Required - Identifier for the device.

### Response
*   **MOTION_STATE** - An object containing motion data:
    *   **quatW, quatX, quatY, quatZ** (float) - Quaternion representing absolute device orientation.
    *   **gravX, gravY, gravZ** (float) - Estimated gravity direction in device-local space.
    *   **accelX, accelY, accelZ** (float) - Processed (gravity-removed) linear acceleration.

### Request Example
```cpp
MOTION_STATE motion = JslGetMotionState(deviceId);
```

### Response Example
```cpp
// Orientation quat (W, X, Y, Z)
printf("Orientation quat: W=%.3f X=%.3f Y=%.3f Z=%.3f\n", motion.quatW, motion.quatX, motion.quatY, motion.quatZ);

// Gravity direction
printf("Gravity:          X=%.3f Y=%.3f Z=%.3f\n", motion.gravX, motion.gravY, motion.gravZ);

// Linear acceleration
printf("Linear accel:     X=%.3f Y=%.3f Z=%.3f\n", motion.accelX, motion.accelY, motion.accelZ);
```
```

--------------------------------

### Set Player Indicator LEDs (Nintendo / DualSense)

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Control the player indicator LEDs. For Nintendo devices, this uses a direct integer to control the 4-LED bar. For DualSense, use DS5_PLAYER_* constants to set the 5-LED player lightbar. This function is a no-op on DualShock 4.

```cpp
// Nintendo: set player numbers 1–4 (direct integer)
JslSetPlayerNumber(nintendoDeviceId, 1); // one LED lit
JslSetPlayerNumber(nintendoDeviceId, 2);
JslSetPlayerNumber(nintendoDeviceId, 3);
JslSetPlayerNumber(nintendoDeviceId, 4);

// DualSense: use DS5_PLAYER_* bitmask constants
// DS5_PLAYER_1 = 4   (--x--)
// DS5_PLAYER_2 = 10  (-x-x-)
// DS5_PLAYER_3 = 21  (x-x-x)
// DS5_PLAYER_4 = 27  (xx-xx)
// DS5_PLAYER_5 = 31  (xxxxx)
JslSetPlayerNumber(dualSenseId, DS5_PLAYER_1);
JslSetPlayerNumber(dualSenseId, DS5_PLAYER_2);
```

--------------------------------

### JslGetSimpleState

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Retrieves the latest state of buttons, triggers, and sticks for a given controller.

```APIDOC
## JslGetSimpleState

### Description
Gets the latest button, trigger, and stick state for the controller with the specified ID.

### Method
JOY_SHOCK_STATE JslGetSimpleState(int deviceId)

### Parameters
#### Path Parameters
- **deviceId** (int) - The ID of the device to query.

### Returns
- JOY_SHOCK_STATE: An object containing the latest state of buttons, triggers, and sticks.
```

--------------------------------

### JslSetGyroSpace

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Selects the coordinate system for gyro data output. This must be called per device.

```APIDOC
## JslSetGyroSpace — Choose coordinate system for gyro output

### Description
Selects how gyro data is transformed before being returned by all gyro getters and callbacks. Must be called per device. Values: `0` = Local Space (raw, no transform), `1` = World Space (gravity-corrected axes, small error), `2` = Player Space (adaptive, robust, recommended default).

### Method
```cpp
void JslSetGyroSpace(int deviceId, int space);
```

### Parameters
#### Path Parameters
- `deviceId` (*int*) - The ID of the controller.
- `space` (*int*) - The desired gyro space: `0` for Local, `1` for World, `2` for Player.
```

--------------------------------

### JslGetConnectedDeviceHandles

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Retrieves handles for all currently connected devices. The number of handles to retrieve should be pre-allocated.

```APIDOC
## JslGetConnectedDeviceHandles — Retrieve all device handles

### Description
Retrieves handles for all currently connected devices. The number of handles to retrieve should be pre-allocated.

### Method
```cpp
int JslGetConnectedDeviceHandles(int* handles, int numHandles);
```

### Parameters
#### Path Parameters
- `handles` (*int*)
- `numHandles` (*int*)

### Returns
- `int`: The number of handles successfully retrieved.
```

--------------------------------

### JslGetConnectedDeviceHandles

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Fills an array with the handles of all connected devices. The size of the array should be sufficient to hold all device handles, as determined by the return value of JslConnectDevices.

```APIDOC
## JslGetConnectedDeviceHandles

### Description
Fills the provided array with the handles for all connected devices, up to the specified size. Use the number returned by JslConnectDevices to ensure all handles are retrieved.

### Method
int JslGetConnectedDeviceHandles(int* deviceHandleArray, int size)

### Parameters
#### Path Parameters
- **deviceHandleArray** (int*) - Output array to be filled with device handles.
- **size** (int) - The maximum number of handles to store in the array.

### Returns
- int: The number of device handles successfully written to the array.
```

--------------------------------

### Set LED Lightbar Colour (DS4 / DualSense)

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Set the RGB color of the lightbar on DS4 and DualSense controllers using a 0xRRGGBB format. This function has no effect on Nintendo devices. The example shows setting specific colors and assigning player colors.

```cpp
// Set to red:
JslSetLightColour(deviceId, 0xFF0000);

// Set to green:
JslSetLightColour(deviceId, 0x00FF00);

// Set to white:
JslSetLightColour(deviceId, 0xFFFFFF);

// Turn off (black):
JslSetLightColour(deviceId, 0x000000);

// Assign player colours for local multiplayer:
int playerColours[] = { 0xFF0000, 0x0000FF, 0x00FF00, 0xFFFF00 };
for (int i = 0; i < numDevices; i++) {
    JslSetLightColour(handles[i], playerColours[i]);
}
```

--------------------------------

### Set Device State Callback

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Register a function to receive updates on device state changes, including button, trigger, stick, and IMU data. The callback receives device ID, current and previous states, and time since last report.

```c
void JslSetCallback(void(*callback)(int, JOY_SHOCK_STATE, JOY_SHOCK_STATE, IMU_STATE, IMU_STATE, float))
```

--------------------------------

### Get Accumulated Gyro Data

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Retrieves the average gyro angular velocity since the last call and resets the accumulator. Essential for polling-based input loops to prevent sample loss when the game's frame rate exceeds the controller's report rate.

```cpp
float gyroX, gyroY, gyroZ;
JslGetAndFlushAccumulatedGyro(deviceId, gyroX, gyroY, gyroZ);

// Use gyro to move a camera (sensitivity in degrees per in-game unit):
const float sensitivity = 0.05f;
cameraYaw   += gyroY * sensitivity;  // horizontal
cameraPitch += gyroX * sensitivity;  // vertical
// gyroZ is always 0 in World/Player space; in Local space it is roll

```

--------------------------------

### Register Per-Frame Input Event Callback

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Register a callback function using `JslSetCallback` to receive input events for every controller on each frame. The callback receives current and previous input states, IMU data, and delta time. Unregister by passing `nullptr`.

```cpp
void OnControllerInput(
    int deviceId,
    JOY_SHOCK_STATE current,
    JOY_SHOCK_STATE previous,
    IMU_STATE currentIMU,
    IMU_STATE previousIMU,
    float deltaTime)
{
    // Detect new presses this report:
    int newButtons = current.buttons & ~previous.buttons;
    if (newButtons & JSMASK_S) printf("[%d] South pressed (dt=%.4fs)\n", deviceId, deltaTime);

    // Gyro-based aiming (use deltaTime for frame-rate independence):
    float aimX = currentIMU.gyroX * deltaTime;  // degrees this report
    float aimY = currentIMU.gyroY * deltaTime;
    // Apply to camera pitch/yaw...
}

// Register (replace nullptr to unregister):
JslSetCallback(OnControllerInput);

// At shutdown (also called by JslDisconnectAndDisposeAll):
JslSetCallback(nullptr);
```

--------------------------------

### Set Rumble Intensity (DS4 / DualSense)

Source: https://context7.com/jibbsmart/joyshocklibrary/llms.txt

Control the high-frequency (smallRumble) and low-frequency (bigRumble) motors on DS4 and DualSense controllers. Values range from 0 to 255. Use 0, 0 to stop rumble. The fade-out pattern example shows how to gradually decrease intensity.

```cpp
// Full rumble burst (both motors max):
JslSetRumble(deviceId, 255, 255);

// Light high-frequency buzz only:
JslSetRumble(deviceId, 180, 0);

// Low thud only:
JslSetRumble(deviceId, 0, 200);

// Stop rumble:
JslSetRumble(deviceId, 0, 0);

// Fade-out pattern in a game loop:
float intensity = 1.0f;
while (intensity > 0.f) {
    int motor = (int)(intensity * 255);
    JslSetRumble(deviceId, motor / 2, motor);
    // sleep/yield here...
    intensity -= 0.05f;
}
JslSetRumble(deviceId, 0, 0);
```

--------------------------------

### JslSetTouchCallback

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Sets a callback function for receiving touchpad state updates. This is primarily for DualShock 4 controllers and provides device ID, current and previous touchpad states, and time since last report.

```APIDOC
## JslSetTouchCallback

### Description
Set a callback function by which JoyShockLibrary can report the current touchpad state for each device. Only DualShock 4s will use this. This callback will be given the *deviceId* for the reporting device, its current and previous touchpad states, and the amount of time since the last report for this device (in seconds).

### Parameters
- **callback** (void(*)(int, TOUCH_STATE, TOUCH_STATE, float)) - Required - The callback function to be registered.
```

--------------------------------

### Set Device Connection Callback

Source: https://github.com/jibbsmart/joyshocklibrary/blob/master/README.md

Register a function to be called when a new device connects. This callback is invoked after JslConnectDevices is called and provides the device ID for the new device, allowing for initial configuration.

```c
void JslSetConnectCallback(void(*callback)(int))
```