Skip to content

Engine Library

Jump to bottom
hifihedgehog edited this page May 26, 2026 · 56 revisions

Engine Library

The PadForge.Engine assembly: data types, interfaces, and enums shared by the input pipeline and the WPF UI. No UI dependencies. Targets net10.0-windows.

v3 (2026-04-26): Rewritten for v3. The HIDMaestro SDK surface, OpenXInput shim, thread-pool lifecycle, and bubble-up cascade live on HIDMaestro Deep Dive. If anything here drifts from the live source, the live source wins.

graph TB
    subgraph "Data Models. PadForge.Engine.Data"
        PS[PadSetting<br/>mapping config · deadzones · curves]
        US[UserSetting<br/>device-to-slot linkage]
        UD[UserDevice<br/>physical device record]
        MT[MappingTranslation<br/>cross-layout Copy From]
        VJM[ExtendedMappingEntry<br/>custom axis/button/POV maps]
    end

    subgraph "Output State Types. PadForge.Engine"
        GP[Gamepad<br/>XInput-layout struct]
        VRS[ExtendedRawState<br/>arbitrary axes · 128 buttons · 4 POVs]
        KRS[KbmRawState<br/>256 VK codes · mouse deltas]
        MRS[MidiRawState<br/>128 notes · 128 CCs]
    end

    subgraph "Device Wrappers. PadForge.Engine"
        ISDI[ISdlInputDevice<br/>common interface]
        SDW[SdlDeviceWrapper<br/>joystick/gamepad · rumble · haptic · sensors]
        SKW[SdlKeyboardWrapper<br/>per-device keyboard]
        SMW[SdlMouseWrapper<br/>per-device mouse]
        WCD[WebControllerDevice<br/>browser gamepad]
        TOD[TouchpadOverlayDevice<br/>on-screen touchpad window]
    end

    subgraph "Force Feedback"
        FFS[ForceFeedbackState<br/>per-device FFB tracking]
        VIB[Vibration<br/>left + right motor]
    end

    subgraph "Interfaces"
        IVC[IVirtualController<br/>Create · Submit · Destroy]
    end

    US -->|references| PS
    US -->|references| UD
    PS -->|contains| VJM
    PS -->|uses| MT
    UD -->|runtime: Device| ISDI
    SDW -.->|implements| ISDI
    SKW -.->|implements| ISDI
    SMW -.->|implements| ISDI
    WCD -.->|implements| ISDI
    TOD -.->|implements| ISDI
    IVC -->|accepts| GP
    IVC -->|accepts| VRS
    IVC -->|accepts| KRS
    IVC -->|accepts| MRS
    FFS -->|outputs| VIB

    style GP fill:#e1f5fe
    style PS fill:#e8f5e9
    style SDW fill:#f3e5f5
    style IVC fill:#fff3e0
    style FFS fill:#fce4ec
Loading

Project file: PadForge.Engine/PadForge.Engine.csproj

Namespace Contents
PadForge.Engine Output state types, device wrappers, force-feedback types, common interfaces
PadForge.Engine.Data XML-persisted data models (PadSetting, UserSetting, UserDevice, MappingSet, etc.)
PadForge.Engine.Common InputHookManager (LL hook host), PrecisionTouchpadReader
PadForge.Engine.Common.Mapping (v3.2) Multi-source mapping helpers: CombineHelper, SourceEvaluator, SourceCoercion, SourceKindRuntime, TargetKind, MappingExpression
PadForge.Engine.Touchpad (v3.3) Touchpad gesture pipeline: GestureRecognizer (Tier 1/2/3 detector), ShapeRecognizer (canonical $Q point-cloud matcher), ShapeTemplate, AngularMarginRecognizer, InBoxShapeTemplates, TouchpadCustomGesture, TouchpadGestureContext, TouchpadGestureSettings
SDL3 P/Invoke

Table of Contents

Gamepad

File: PadForge.Engine/Common/GamepadTypes.cs Namespace: PadForge.Engine

Minimal struct matching the XInput XINPUT_GAMEPAD layout. Output of the mapping pipeline (Step 3 → Step 4 → Step 5).

public struct Gamepad
{
    // Fields
    public ushort Buttons;       // Bitmask of button flags
    public ushort LeftTrigger;   // 0-65535
    public ushort RightTrigger;  // 0-65535
    public short ThumbLX;        // -32768 to 32767
    public short ThumbLY;        // -32768 to 32767
    public short ThumbRX;        // -32768 to 32767
    public short ThumbRY;        // -32768 to 32767

    // Methods
    public bool IsButtonPressed(ushort flag);
    public void SetButton(ushort flag, bool pressed);
    public void Clear();
}

Button Flag Constants

Constant Value Description
DPAD_UP 0x0001 D-pad up
DPAD_DOWN 0x0002 D-pad down
DPAD_LEFT 0x0004 D-pad left
DPAD_RIGHT 0x0008 D-pad right
START 0x0010 Start button
BACK 0x0020 Back button
LEFT_THUMB 0x0040 Left stick click
RIGHT_THUMB 0x0080 Right stick click
LEFT_SHOULDER 0x0100 Left bumper
RIGHT_SHOULDER 0x0200 Right bumper
GUIDE 0x0400 Guide/home button
TOUCHPAD 0x0800 Touchpad click. Output-side bitmask in Gamepad.Buttons. Mirrors CustomInputState.Buttons[16] on the input side (= SDL_GAMEPAD_BUTTON_TOUCHPAD).
A 0x1000 A button
B 0x2000 B button
X 0x4000 X button
Y 0x8000 Y button

Methods

Method Signature Description
IsButtonPressed bool IsButtonPressed(ushort flag) true if the button flag bit is set in Buttons
SetButton void SetButton(ushort flag, bool pressed) Sets or clears a button flag bit via bitwise OR/AND
Clear void Clear() Resets all fields to zero

TouchpadState

File: PadForge.Engine/Common/GamepadTypes.cs Namespace: PadForge.Engine

Two-finger touchpad surface state for PlayStation slots. Step 5's HMaestroVirtualController.SubmitGamepadState overload takes a TouchpadState alongside the Gamepad struct so games see touchpad finger positions on the DS4 / DualSense extended report.

public struct TouchpadState
{
    public float X0;             // Finger 0 X (0.0–1.0, left → right)
    public float Y0;             // Finger 0 Y (0.0–1.0, top → bottom)
    public float X1;             // Finger 1 X
    public float Y1;             // Finger 1 Y
    public bool  Down0;          // Finger 0 contact state
    public bool  Down1;          // Finger 1 contact state
    public bool  Click;          // Touchpad click button
    public byte  PacketCounter;  // Increments on each finger down/up edge (DS4_TOUCH encoding)
}

X / Y coordinates are normalized [0, 1] across the active touch surface. PacketCounter increments only on finger-state transitions (not every frame) so the DS4 / DualSense touch encoder can fire its own internal touch-event accounting.

ExtendedRawState

File: PadForge.Engine/Common/GamepadTypes.cs Namespace: PadForge.Engine

Raw output state for Extended-category virtual controllers and custom HID descriptors. Bypasses the fixed Gamepad struct to support arbitrary axis, button, and POV counts. Step 5 forwards this directly to HIDMaestro via HMaestroVirtualController.SubmitExtendedRawState.

public struct ExtendedRawState
{
    public short[] Axes;      // Up to 8 axes (signed short range -32768..32767)
    public uint[] Buttons;    // Button state as 4 x 32-bit words = 128 buttons max
    public int[] Povs;        // Up to 4 POV hat switches (-1=centered, 0-35900=direction)

    public static ExtendedRawState Create(int nAxes, int nButtons, int nPovs);
    public void SetButton(int index, bool pressed);
    public bool IsButtonPressed(int index);
    public void Clear();
}

Methods

Method Signature Description
Create static ExtendedRawState Create(int nAxes, int nButtons, int nPovs) Factory. Clamps axes to 8, buttons to 128 (stored as (N+31)/32 uint words), POVs to 4. All zeroed.
SetButton void SetButton(int index, bool pressed) Sets button by 0-based index (word = index/32, bit = index%32). No-op if out of range.
IsButtonPressed bool IsButtonPressed(int index) true if button at index is set. false if out of range.
Clear void Clear() Resets axes to 0, buttons to 0, POVs to −1 (centered).

Button Storage

Buttons use a 128-bit bitmask stored as uint[4] (32 buttons per word).

POV Values

Hundredths of degrees: 0=N, 4500=NE, 9000=E, 13500=SE, 18000=S, 22500=SW, 27000=W, 31500=NW, 0xFFFFFFFF (−1) = centered.

CustomControllerLayout

File: PadForge.Engine/Common/CustomControllerLayout.cs Namespace: PadForge.Engine

Per-slot HID-descriptor shape for the Extended (custom DirectInput) virtual controller path. Replaces the v2 ExtendedDeviceConfig struct that used to live inside ExtendedVirtualController. The Step 3 → Step 5 pipeline reads these counts to translate per-axis / button / POV mappings into raw HID report indices.

public struct CustomControllerLayout
{
    public int Axes;       // Total axis report fields (sticks*2 + triggers)
    public int Buttons;    // Total button report fields
    public int Povs;       // Total POV (hat) report fields
    public int Sticks;     // Number of thumbsticks (each consumes 2 of Axes)
    public int Triggers;   // Number of triggers (each consumes 1 of Axes)

    public bool IsTriggerSlot(int axisIndex);
}

IsTriggerSlot resolves the interleaved-then-trailing axis layout that ExtendedSlotConfig.ComputeAxisLayout produces. Sticks and triggers need different rest-state and combine rules. Centralizing the index → role formula here keeps Step 3 (mapping), Step 4 (multi-device merge), and the deadzone pipeline in agreement even when the layout edits.

KbmRawState

File: PadForge.Engine/Common/GamepadTypes.cs Namespace: PadForge.Engine

Raw keyboard + mouse output state for KeyboardMouseVirtualController. Key states packed into 4 × 64-bit words covering 256 Windows VK codes. Mouse axes are signed shorts (delta per frame).

public struct KbmRawState
{
    // Key state (256 VK codes packed into 4 ulongs)
    public ulong Keys0;             // VK 0-63
    public ulong Keys1;             // VK 64-127
    public ulong Keys2;             // VK 128-191
    public ulong Keys3;             // VK 192-255

    // Mouse output
    public short MouseDeltaX;       // Mouse X delta (signed, pixels per frame)
    public short MouseDeltaY;       // Mouse Y delta (signed, pixels per frame)
    public short ScrollDelta;       // Mouse scroll delta (positive = up)
    public byte MouseButtons;       // Bit 0=LMB, 1=RMB, 2=MMB, 3=X1, 4=X2

    // Pre-deadzone values (for UI stick/trigger preview)
    public short PreDzMouseDeltaX;  // Mouse X before center offset + deadzone
    public short PreDzMouseDeltaY;  // Mouse Y before center offset + deadzone
    public short PreDzScrollDelta;  // Scroll before deadzone

    // Methods
    public bool GetKey(byte vk);
    public void SetKey(byte vk, bool pressed);
    public bool GetMouseButton(int index);
    public void SetMouseButton(int index, bool pressed);
    public void Clear();
    public static KbmRawState Combine(KbmRawState a, KbmRawState b);
}

Methods

Method Signature Description
GetKey bool GetKey(byte vk) true if VK code bit is set (word = vk/64, bit = vk%64).
SetKey void SetKey(byte vk, bool pressed) Sets or clears a VK code bit.
GetMouseButton bool GetMouseButton(int index) true if mouse button bit is set (0=LMB, 1=RMB, 2=MMB, 3=X1, 4=X2).
SetMouseButton void SetMouseButton(int index, bool pressed) Sets or clears a mouse button bit.
Clear void Clear() Zeros all keys, mouse deltas, scroll, mouse buttons, and pre-deadzone fields.
Combine static KbmRawState Combine(KbmRawState a, KbmRawState b) Merges two KBM states. Keys and mouse buttons OR'd. Deltas and scroll use largest absolute magnitude.

MidiRawState

File: PadForge.Engine/Common/GamepadTypes.cs Namespace: PadForge.Engine

Dynamic-sized MIDI output state for MidiVirtualController. CC values: 0–127 (MIDI range). Notes: boolean (on/off).

public struct MidiRawState
{
    public byte[] CcValues;   // CC values 0-127 per CC slot
    public bool[] Notes;      // Note on/off per note slot

    public static MidiRawState Create(int ccCount, int noteCount);
    public void Clear();
    public static MidiRawState Combine(MidiRawState a, MidiRawState b);
}

Methods

Method Signature Description
Create static MidiRawState Create(int ccCount, int noteCount) Allocates arrays. CC values initialized to 0.
Clear void Clear() Resets CCs to 64 (center), notes to false.
Combine static MidiRawState Combine(MidiRawState a, MidiRawState b) Merges two states. CCs take the value furthest from center (64); notes OR'd.

VirtualControllerType

File: PadForge.Engine/Common/VirtualControllerTypes.cs Namespace: PadForge.Engine

public enum VirtualControllerType
{
    [XmlEnum("Microsoft")] Xbox = 0,
    [XmlEnum("Sony")]      PlayStation = 1,
    Extended = 2,
    Midi = 3,
    KeyboardMouse = 4
}

Numeric values are preserved across the rename so legacy PadForge.xml files keep loading. The [XmlEnum] attributes on Xbox and PlayStation are a back-compat accept-list for older settings files written with the prior identifiers. This is the exception path, not the canonical naming.

IVirtualController

File: PadForge.Engine/Common/VirtualControllerTypes.cs Namespace: PadForge.Engine

Abstraction for virtual controller operations. v3 collapses Xbox / PlayStation / Extended onto a single concrete class backed by HIDMaestro; MIDI and KB+M remain separate.

Class Backend
HMaestroVirtualController HIDMaestro SDK (HMContext, HMProfile, HMController). Handles Xbox, PlayStation, and Extended categories. Profile selected at construction.
MidiVirtualController Windows MIDI Services
KeyboardMouseVirtualController Win32 SendInput

HMaestroVirtualController.Type reports the user-facing category (Xbox / PlayStation / Extended) so per-type counting in InputService keeps working without inspecting profile metadata.

public interface IVirtualController : IDisposable
{
    VirtualControllerType Type { get; }
    bool IsConnected { get; }
    int FeedbackPadIndex { get; set; }

    void Connect();
    void Disconnect();
    void SubmitGamepadState(Gamepad gp);
    void RegisterFeedbackCallback(int padIndex, Vibration[] vibrationStates);
}

Members

Member Type Description
Type VirtualControllerType Virtual controller type
IsConnected bool Whether the VC is connected
FeedbackPadIndex int Slot index for feedback callbacks into VibrationStates[] (updated on SwapSlotData)
Connect() void Creates and plugs in the VC
Disconnect() void Unplugs and destroys the VC
SubmitGamepadState(Gamepad) void Sends gamepad state to the VC
RegisterFeedbackCallback(int, Vibration[]) void Registers a callback writing rumble to VibrationStates[] at the given index

CustomInputState

File: PadForge.Engine/Common/CustomInputState.cs Namespace: PadForge.Engine

API-agnostic snapshot of a device's full input state at one point in time.

public class CustomInputState
{
    // Constants
    public const int MaxAxis = 24;
    public const int MaxSliders = 8;
    public const int MaxPovs = 4;
    public const int MaxButtons = 256;

    // Fields
    public int[] Axis;            // 0-65535, center = 32767
    public int[] Sliders;         // 0-65535
    public int[] Povs;            // centidegrees 0-35900, or -1 for centered
    public bool[] Buttons;        // true = pressed; index 16 = SDL_GAMEPAD_BUTTON_TOUCHPAD
    public float[] Gyro;          // [X, Y, Z] radians per second
    public float[] Accel;         // [X, Y, Z] meters per second squared
    public float[] TouchpadFingers; // 6 floats: [finger*3+0]=x, [finger*3+1]=y, [finger*3+2]=pressure
    public bool[] TouchpadDown;     // [2] contact state per finger
    public int BatteryPercent;      // 0..100 or -1 if unknown. Refreshed periodically, not per-frame.
    public bool BatteryCharging;    // True when the source pad reports charging or fully charged.

    // Constructors
    public CustomInputState();
    public CustomInputState(int[] axes, int[] sliders, int[] povs, bool[] buttons);

    // Methods
    public CustomInputState Clone();
    public static void GetAxisMask(DeviceObjectItem[] items, int numAxes,
        out int axisMask, out int actuatorMask, out int actuatorCount);
}

Constructors

Constructor Description
CustomInputState() Zeroed arrays at default sizes. POVs init to −1 (centered). Gyro/Accel are float[3]. TouchpadFingers float[6], TouchpadDown bool[2]. BatteryPercent defaults to −1 (unknown), BatteryCharging to false.
CustomInputState(int[], int[], int[], bool[]) Copies arrays up to max lengths (snapshot isolation). POVs init to −1 before copy.

Methods

Method Signature Description
Clone CustomInputState Clone() Deep copy of all arrays (Axis, Sliders, Povs, Buttons, Gyro, Accel, TouchpadFingers, TouchpadDown) and the scalar Battery fields.
GetAxisMask static void GetAxisMask(DeviceObjectItem[], int, out int, out int, out int) Scans device objects to build axis and FFB actuator bitmasks. Bit N = axis/actuator N exists.

Value Conventions

Array Range Center Description
Axis 0–65535 32767 0–5 = X, Y, Z, Rx, Ry, Rz; 6–23 = additional
Sliders 0–65535 32767 Overflow or dedicated slider controls
Povs 0–35900 or −1 −1 Centidegrees. −1 = centered
Buttons bool false 256 max (covers full Windows VK range)
Gyro float[3] 0.0 Radians/s. Gyro-capable devices only
Accel float[3] 0.0 m/s². Accelerometer-capable devices only
TouchpadFingers float[6] 0.0 Two-finger position + pressure. Layout [f0.x, f0.y, f0.p, f1.x, f1.y, f1.p]. X/Y are 0.0-1.0 across the pad surface
TouchpadDown bool[2] false Per-finger contact state. true when that finger is currently touching the pad
BatteryPercent int -1 SDL3-reported charge level. 0-100 = percentage; -1 = unknown. Not refreshed every frame.
BatteryCharging bool false true when the source pad reports charging or fully charged. Drives the lightbar Battery mode

ISdlInputDevice

File: PadForge.Engine/Common/ISdlInputDevice.cs Namespace: PadForge.Engine

Common interface for all SDL-based input device wrappers (joystick/gamepad, keyboard, mouse, web controller). Lets the pipeline (Steps 2–5) read state from any device type uniformly.

public interface ISdlInputDevice : IDisposable
{
    // Identity
    uint SdlInstanceId { get; }
    string Name { get; }
    Guid InstanceGuid { get; }
    Guid ProductGuid { get; }
    string DevicePath { get; }
    string SerialNumber { get; }
    ushort VendorId { get; }
    ushort ProductId { get; }

    // Capabilities
    int NumAxes { get; }
    int NumButtons { get; }
    int RawButtonCount { get; }
    int NumHats { get; }
    bool HasRumble { get; }
    bool HasHaptic { get; }
    bool HasGyro { get; }
    bool HasAccel { get; }
    bool IsAttached { get; }

    // Haptic
    HapticEffectStrategy HapticStrategy { get; }
    IntPtr HapticHandle { get; }
    uint HapticFeatures { get; }
    int NumHapticAxes { get; }

    // State reading
    CustomInputState GetCurrentState(bool forceRaw = false);
    DeviceObjectItem[] GetDeviceObjects();
    int GetInputDeviceType();

    // Force feedback
    bool SetRumble(ushort low, ushort high, uint durationMs = uint.MaxValue);
    bool StopRumble();
}

Properties

Property Type Description
SdlInstanceId uint SDL instance ID (unique per connection session; 0 = invalid)
Name string Human-readable device name
InstanceGuid Guid Deterministic GUID for settings matching (from path/serial/VID+PID)
ProductGuid Guid Product GUID from VID/PID for device family identification
DevicePath string Device path (may be empty)
SerialNumber string Serial number, e.g., Bluetooth MAC (may be empty)
VendorId ushort USB Vendor ID
ProductId ushort USB Product ID
NumAxes int Axis count (6 for gamepads)
NumButtons int Button count (11 for gamepads)
RawButtonCount int Raw joystick button count before gamepad remapping. May exceed NumButtons
NumHats int POV hat count (1 for gamepads)
HasRumble bool Supports simple rumble
HasHaptic bool Has an SDL haptic handle open
HasGyro bool Has gyroscope sensor
HasAccel bool Has accelerometer sensor
IsAttached bool Handle still valid and connected
HapticStrategy HapticEffectStrategy Best haptic strategy chosen at open time
HapticHandle IntPtr SDL haptic handle (IntPtr.Zero if none)
HapticFeatures uint Bitmask of SDL_HAPTIC_* flags
NumHapticAxes int Haptic axes (1 = wheel, 2+ = joystick)

Methods

Method Signature Description
GetCurrentState CustomInputState GetCurrentState(bool forceRaw = false) Reads input state. forceRaw=true bypasses gamepad remapping.
GetDeviceObjects DeviceObjectItem[] GetDeviceObjects() Returns metadata for each axis, hat, and button. Button count uses Math.Max(NumButtons, RawButtonCount).
GetInputDeviceType int GetInputDeviceType() Returns an InputDeviceType constant.
SetRumble bool SetRumble(ushort low, ushort high, uint durationMs) Sends rumble. Default duration uint.MaxValue (~49 days).
StopRumble bool StopRumble() Stops all rumble (SetRumble(0, 0, 0)).

SdlDeviceWrapper

File: PadForge.Engine/Common/SdlDeviceWrapper.cs Namespace: PadForge.Engine

Wraps an SDL joystick (and optionally its Gamepad overlay) for unified device access: open/close, state polling, rumble, GUID construction, and object enumeration. Implements ISdlInputDevice.

Properties (beyond ISdlInputDevice)

Property Type Default Description
Joystick IntPtr IntPtr.Zero Raw SDL joystick handle. Always valid when open.
GameController IntPtr IntPtr.Zero SDL Gamepad handle. Zero if not a gamepad.
Haptic IntPtr IntPtr.Zero SDL haptic handle. Non-zero when haptic FFB available.
ProductVersion ushort 0 USB Product Version
JoystickType SDL_JoystickType UNKNOWN SDL joystick type classification
IsGameController bool (computed) true if opened as an SDL Gamepad

Public Methods

Method Signature Description
Open bool Open(uint instanceId) Opens SDL device. Tries Gamepad first, falls back to Joystick. Populates all properties.
GetCurrentState CustomInputState GetCurrentState(bool forceRaw = false) Routes to GetGamepadState() (remapped) or GetJoystickState() (raw) based on device type and forceRaw.
GetDeviceObjects DeviceObjectItem[] GetDeviceObjects() Builds DeviceObjectItem[] for each axis, hat, button. Uses Math.Max(NumButtons, RawButtonCount) for button count so extra raw buttons (beyond gamepad 11) are included with generic "Button N" names. First 6 axes use standard GUIDs; extras use Slider.
GetInputDeviceType int GetInputDeviceType() Maps SDL_JoystickType to InputDeviceType.
SetRumble bool SetRumble(ushort lowFreq, ushort highFreq, uint durationMs) Sends rumble via SDL_RumbleJoystick. false if unsupported.
StopRumble bool StopRumble() SetRumble(0, 0, 0).

Static Methods

Method Signature Description
BuildProductGuid static Guid BuildProductGuid(ushort vid, ushort pid) Synthetic GUID from VID+PID. bytes[0–1]=VID LE, [2–3]=PID LE, [4–15]=0x00.
BuildInstanceGuid static Guid BuildInstanceGuid(string devicePath, ushort vid, ushort pid, uint instanceId, string serial = null) Deterministic GUID via MD5. Priority: VID+PID+Serial (stable), device path (wired), VID+PID+SDL ID (session-only).
HatToCentidegrees static int HatToCentidegrees(byte hat) SDL hat bitmask to centidegrees (−1 for centered).
DpadToCentidegrees static int DpadToCentidegrees(bool up, bool down, bool left, bool right) 4 D-pad booleans to centidegrees (supports 8-way diagonals).

Gamepad State Reading

GetGamepadState() reads through SDL's gamecontrollerdb mapping layer, producing a standardized layout:

Output Indices
Axes [0]=LX, [1]=LY, [2]=LT, [3]=RX, [4]=RY, [5]=RT
Buttons [0]=A, [1]=B, [2]=X, [3]=Y, [4]=LB, [5]=RB, [6]=Back, [7]=Start, [8]=LS, [9]=RS, [10]=Guide
POV[0] Synthesized from gamepad D-pad buttons
Sensors Gyro and Accel populated if available

Guide suppression: When Back+Start+Guide are all pressed, Guide is suppressed (Windows/XInput synthesizes Guide from this combo).

Extra raw buttons: Raw joystick buttons beyond index 10 are appended (e.g., DualSense touchpad click), excluding indices consumed by the gamepad mapping (ParseMappedButtonIndices()).

Joystick State Reading

GetJoystickState() reads raw joystick input (no gamepad remapping):

  • Axes: SDL signed (−32768..32767) converted to unsigned (0..65535) via - short.MinValue. First MaxAxis go to Axis[], overflow to Sliders[].
  • Hats: SDL bitmask to centidegrees via HatToCentidegrees.
  • Buttons: Uses RawButtonCount (not NumButtons) for full raw coverage.

HID Product String Fallback

SDL3 may return a raw VID/PID string (e.g., "0x16c0/0x05e1") for unknown devices. IsRawVidPidName() detects this; TryGetHidProductString() queries the HID product string via CreateFile + HidD_GetProductString P/Invoke.

Haptic Open Strategy

OpenHaptic() opens SDL_OpenHapticFromJoystick and selects the best strategy:

  1. LeftRight. Best for dual-motor
  2. Sine. Periodic fallback
  3. Constant. Last resort

Devices with both simple rumble and LeftRight haptic prefer simple rumble (more reliable for gamepads). Gain set to 100 if SDL_HAPTIC_GAIN is supported.

HapticEffectStrategy

File: PadForge.Engine/Common/SdlDeviceWrapper.cs Namespace: PadForge.Engine

public enum HapticEffectStrategy
{
    None,       // No haptic support
    LeftRight,  // Best: SDL_HAPTIC_LEFTRIGHT (dual-motor)
    Sine,       // Periodic effect (period varies by motor)
    Constant    // Fallback: constant level from dominant motor
}

SdlKeyboardWrapper

File: PadForge.Engine/Common/SdlKeyboardWrapper.cs Namespace: PadForge.Engine

Wraps a keyboard device for unified input via ISdlInputDevice. State read from Raw Input (per-device) via RawInputListener.

Properties

Property Type Value/Description
NumAxes int 0
NumButtons int Up to 256 (min of 256 and MaxButtons)
RawButtonCount int 0
NumHats int 0
HasRumble bool false
HasHaptic bool false
HasGyro bool false
HasAccel bool false
RawInputHandle IntPtr The Raw Input device handle for per-device state reading

Methods

Method Signature Description
Open bool Open(RawInputListener.DeviceInfo deviceInfo) Opens from Raw Input enumeration. Builds GUID from device path. Path hash is used as the pseudo SDL instance ID.
GetCurrentState CustomInputState GetCurrentState(bool forceRaw) Reads from RawInputListener.GetKeyboardState, merges hooked state via InputHookManager.MergeHookedKeyState (suppressed keys bypass Raw Input).
GetDeviceObjects DeviceObjectItem[] 256 button items with ObjectGuid.Key GUIDs. Names from SDL.VirtualKeyName.
GetInputDeviceType int InputDeviceType.Keyboard (19).
SetRumble / StopRumble Always false.

SdlMouseWrapper

File: PadForge.Engine/Common/SdlMouseWrapper.cs Namespace: PadForge.Engine

Wraps a mouse device for unified input via ISdlInputDevice. State read from Raw Input (per-device) via RawInputListener.

Constants

Constant Value Description
MouseButtons 5 Left, Middle, Right, X1, X2
MouseAxes 3 X Motion, Y Motion, Scroll
AxisCenter 32767 Center value for mouse axis output
MotionScale 2048f Multiplier for mouse delta to axis value
ScrollScale 128f Multiplier for scroll delta to axis value

Properties

Property Type Value/Description
NumAxes int 3 (X Motion, Y Motion, Scroll)
NumButtons int 5 (Left, Middle, Right, X1, X2)
RawButtonCount int 0
NumHats int 0
HasRumble bool false
RawInputHandle IntPtr The Raw Input device handle

Methods

Method Signature Description
Open bool Open(RawInputListener.DeviceInfo deviceInfo) Opens from Raw Input enumeration.
GetCurrentState CustomInputState GetCurrentState(bool forceRaw) Reads deltas via ConsumeMouseDelta, scroll via ConsumeMouseScroll, buttons via GetMouseButtons + MergeHookedMouseState. Axes = AxisCenter + (delta * Scale) clamped to 0–65535.
GetDeviceObjects DeviceObjectItem[] 3 RelativeAxis (X, Y, Scroll) + 5 PushButton (L, M, R, X1, X2).
GetInputDeviceType int InputDeviceType.Mouse (18).

WebControllerDevice

File: PadForge.Engine/Common/WebControllerDevice.cs Namespace: PadForge.Engine

Virtual input device for a browser-connected gamepad. Implements ISdlInputDevice for standard pipeline integration. State written by WebSocket thread, read by polling thread via volatile reference swaps.

Constants

Constant Value Description
WebVendorId 0xBEEF Distinctive VID to avoid HIDMaestro filter false positives
WebProductId 0xCA7E Distinctive PID
WebProductGuid {BEBC0000-...} Fixed ProductGuid for all web controller instances

Fixed Capabilities

Property Value
Axes 6 (LX, LY, LT, RX, RY, RT. 0–65535 range)
Buttons 11 (standard Xbox layout: A, B, X, Y, LB, RB, Back, Start, LS, RS, Guide)
POV Hats 1
HasRumble true (via browser Vibration API)
HasHaptic false
HasGyro false
HasAccel false

Constructor

public WebControllerDevice(string clientId, string displayName)

Creates a web controller. clientId is a unique browser localStorage identifier. InstanceGuid derived from client ID via MD5. SdlInstanceId is the client ID hash code. Stick axes init to center (32767), trigger axes to 0.

Events

Event Signature Description
RumbleRequested Action<ushort, ushort> Fired on SetRumble. Parameters: (lowFreq, highFreq), 0–65535.

State Update Methods

Method Signature Description
UpdateAxis void UpdateAxis(int code, int value) Sets axis (0=LX, 1=LY, 2=LT, 3=RX, 4=RY, 5=RT). Thread-safe.
UpdateButton void UpdateButton(int code, bool pressed) Sets button (0=A through 10=Guide). Thread-safe.
UpdatePov void UpdatePov(int value) Sets POV hat (centidegrees or −1). Thread-safe.
SetConnected void SetConnected(bool connected) Sets connection state (volatile write).

TouchpadOverlayDevice

File: PadForge.Engine/Common/TouchpadOverlayDevice.cs Namespace: PadForge.Engine

(v3.2) Virtual input device that backs the on-screen touchpad overlay. Implements ISdlInputDevice so the overlay shows up on the Devices page like any other gamepad and can be assigned to PlayStation slots. The window reads its position / size / monitor / opacity from AppSettingsData.TouchpadOverlay* fields.

Property Value
Name "Touchpad Overlay"
VendorId / ProductId 0xBEEF / 0xCA7F
OverlayInstanceGuid BEBC0001-0000-0000-0000-CAFEFACE0002 (fixed)
OverlayProductGuid BEBC0000-0000-0000-0000-CAFEFACE0002 (fixed)
NumAxes / NumHats 0 / 0
NumButtons / RawButtonCount 17 (touchpad click lives at Buttons[16])
SupportedButtonIndices [16] (sparse, only the touchpad click is populated)
HasTouchpad true
HasRumble / HasGyro / HasAccel all false
DevicePath "overlay://touchpad"

Touch state is fed in by the overlay window through a callback. The device exposes the resulting CustomInputState (TouchpadFingers / TouchpadDown / Buttons[16]) through the standard GetCurrentState interface so Step 2 reads it the same way it reads SDL devices. There is only ever one overlay device per session (SdlInstanceId = 0xFFFFFFFE).

DeviceObjectItem

File: PadForge.Engine/Common/DeviceObjectItem.cs Namespace: PadForge.Engine

Describes a single input object (axis, button, hat, slider) on a device. Used by mapping UI and pipeline.

public class DeviceObjectItem
{
    // Identity
    public string Name { get; set; }                           // Default: ""
    public Guid ObjectTypeGuid { get; set; }                   // Default: Guid.Empty
    public DeviceObjectTypeFlags ObjectType { get; set; }      // Default: All

    // Position
    public int InputIndex { get; set; }                        // Default: 0
    public int Offset { get; set; }                            // Default: 0

    // Aspect
    public ObjectAspect Aspect { get; set; }                   // Default: Position

    // Computed helpers (read-only)
    public bool IsForceActuator { get; }
    public bool IsAxis { get; }
    public bool IsButton { get; }
    public bool IsPov { get; }
    public bool IsSlider { get; }

    public override string ToString();  // "{Name} ({TypeLabel}, Index {InputIndex})"
}

Properties

Property Type Default Description
Name string "" Display name (e.g., "X Axis", "Button 3")
ObjectTypeGuid Guid Guid.Empty Well-known GUID from ObjectGuid
ObjectType DeviceObjectTypeFlags All Classification flags
InputIndex int 0 Zero-based index into CustomInputState arrays
Offset int 0 Byte offset (synthetic for SDL, mapping compatibility)
Aspect ObjectAspect Position Object aspect

Computed Properties

Property Logic
IsForceActuator (ObjectType & ForceFeedbackActuator) != 0
IsAxis (ObjectType & Axis) != 0
IsButton (ObjectType & Button) != 0
IsPov (ObjectType & PointOfViewController) != 0
IsSlider ObjectTypeGuid == ObjectGuid.Slider

InputTypes

File: PadForge.Engine/Common/InputTypes.cs Namespace: PadForge.Engine

DeviceObjectTypeFlags

[Flags]
public enum DeviceObjectTypeFlags : int
{
    All = 0,
    RelativeAxis = 1,
    AbsoluteAxis = 2,
    Axis = 3,                        // RelativeAxis | AbsoluteAxis
    PushButton = 4,
    ToggleButton = 8,
    Button = 12,                     // PushButton | ToggleButton
    PointOfViewController = 16,
    Collection = 64,
    NoData = 128,
    ForceFeedbackActuator = 0x01000000,
    ForceFeedbackEffectTrigger = 0x02000000
}

ObjectAspect

[Flags]
public enum ObjectAspect : int
{
    Position = 0x100
}

EffectParameterFlags

[Flags]
public enum EffectParameterFlags : int
{
    None = 0
}

ObjectGuid

Well-known GUIDs for device object types, matching DirectInput GUID constants.

Field GUID Description
XAxis {A36D02E0-C9F3-11CF-BFC7-444553540000} GUID_XAxis
YAxis {A36D02E1-C9F3-11CF-BFC7-444553540000} GUID_YAxis
ZAxis {A36D02E2-C9F3-11CF-BFC7-444553540000} GUID_ZAxis
RxAxis {A36D02F4-C9F3-11CF-BFC7-444553540000} GUID_RxAxis
RyAxis {A36D02F5-C9F3-11CF-BFC7-444553540000} GUID_RyAxis
RzAxis {A36D02E3-C9F3-11CF-BFC7-444553540000} GUID_RzAxis
Slider {A36D02E4-C9F3-11CF-BFC7-444553540000} GUID_Slider
Button {A36D02F0-C9F3-11CF-BFC7-444553540000} GUID_Button
Key {55728220-D33C-11CF-BFC7-444553540000} GUID_Key
PovController {A36D02F2-C9F3-11CF-BFC7-444553540000} GUID_POV
Unknown Guid.Empty GUID_Unknown

InputDeviceType

Integer constants matching DirectInput device type values. Used in UserDevice.CapType.

Constant Value Description
Device 17 Generic device
Mouse 18 Mouse
Keyboard 19 Keyboard
Joystick 20 Joystick
Gamepad 21 Gamepad
Driving 22 Steering wheel
Flight 23 Flight stick
FirstPerson 24 First-person device
Supplemental 25 Supplemental device (guitar, drum, dance pad)

MapType

public enum MapType : int
{
    None = 0,
    Axis = 1,
    Button = 2,
    Slider = 3,
    POV = 4
}

ForceFeedbackState

File: PadForge.Engine/Common/ForceFeedbackState.cs Namespace: PadForge.Engine

Per-device force feedback (rumble) state with change detection. Only sends to hardware when motor values differ. Uses uint.MaxValue duration (~49 days) to mimic XInput's "set and forget" model.

Public Properties

Property Type Description
LeftMotorSpeed ushort Last sent left (low-freq) motor speed, 0–65535. Read-only.
RightMotorSpeed ushort Last sent right (high-freq) motor speed, 0–65535. Read-only.
IsActive bool Whether FFB is active on the device. Read-only.

Private Fields (Change Detection Cache)

Field Type Description
_cachedLeftMotorSpeed ushort Last sent left motor speed
_cachedRightMotorSpeed ushort Last sent right motor speed
_hapticEffectId int SDL haptic effect ID (-1 = none)
_hapticEffectCreated bool Whether a haptic effect has been created
_cachedEffectType uint Last sent FFB effect type
_cachedSignedMag short Last sent signed magnitude
_cachedDirection ushort Last sent polar direction
_cachedPeriod uint Last sent period
_cachedHasCondition bool Last sent condition data flag
_cachedHasDirectional bool Last sent directional data flag

Public Methods

Method Signature Description
SetDeviceForces void SetDeviceForces(UserDevice ud, ISdlInputDevice device, PadSetting ps, Vibration v) Main entry. Reads gain from PadSetting. Routes to directional haptic when HasDirectionalData or HasConditionData and device supports haptic, or scalar rumble otherwise. Only sends when values change.
StopDeviceForces void StopDeviceForces(ISdlInputDevice device) Stops all rumble/haptic and resets cached state.

Private Methods

Method Description
SetDirectionalHapticForces(device, v, overallGain) Directional constant/periodic force. Single-axis (wheels): projects via sin(angle). Multi-axis: full 2D polar. Falls back to scalar if unsupported.
SetConditionHapticForces(device, v, overallGain) Condition effects (spring/damper/friction/inertia) with per-axis coefficients. Scales HID (−10000..+10000) to SDL (−32767..+32767).
SetHapticForces(device, left, right) Scalar haptic fallback. Translates dual-motor to SDL effect per HapticEffectStrategy.
ApplyHapticEffect(device, ref effect) Creates on first call, updates in-place after. Avoids create/destroy churn.
StopAndDestroyHapticEffect(device) Stops and destroys active haptic effect. Resets effect state.

Scalar Haptic Strategy Mapping

Strategy SDL Effect Large Motor Small Motor
LeftRight SDL_HAPTIC_LEFTRIGHT large_magnitude = left small_magnitude = right
Sine SDL_HAPTIC_SINE magnitude = max/2, period = 120 period = 40
Constant SDL_HAPTIC_CONSTANT level = max/2 N/A

FfbEffectTypes

File: PadForge.Engine/Common/ForceFeedbackState.cs Namespace: PadForge.Engine

FFB effect type constants matching the HID PID effect-type values used in HIDMaestro's PID descriptor path. Defined in Engine so both Engine and App can reference them.

Constant Value Description
None 0 No effect
Const 1 Constant force
Ramp 2 Ramp force
Square 3 Square wave periodic
Sine 4 Sine wave periodic
Triangle 5 Triangle wave periodic
SawUp 6 Sawtooth up periodic
SawDown 7 Sawtooth down periodic
Spring 8 Spring condition
Damper 9 Damper condition
Inertia 10 Inertia condition
Friction 11 Friction condition

Vibration

File: PadForge.Engine/Common/ForceFeedbackState.cs Namespace: PadForge.Engine

Vibration/FFB state for a virtual controller slot. Carries scalar motor speeds (rumble) and directional FFB data (haptic joysticks/wheels).

public class Vibration
{
    // Scalar fields (HIDMaestro XInput / HID rumble callback path)
    public ushort LeftMotorSpeed { get; set; }       // 0-65535, low-frequency heavy rumble
    public ushort RightMotorSpeed { get; set; }      // 0-65535, high-frequency light buzz

    // Directional FFB fields (HIDMaestro PID/FFB callback for haptic devices)
    public bool HasDirectionalData { get; set; }
    public uint EffectType { get; set; }             // FfbEffectTypes constant
    public short SignedMagnitude { get; set; }        // -10000 to +10000
    public ushort Direction { get; set; }             // Polar 0-32767 (0=North)
    public uint Period { get; set; }                  // ms, for periodic effects
    public byte DeviceGain { get; set; } = 255;       // 0-255, device-level gain

    // Condition effect fields (spring/damper/friction/inertia)
    public bool HasConditionData { get; set; }
    public ConditionAxisData[] ConditionAxes { get; set; }
    public int ConditionAxisCount { get; set; }       // 1 for wheels, 2 for joysticks

    // Constructors
    public Vibration();
    public Vibration(ushort leftMotor, ushort rightMotor);
}

Fields

Field Type Default Description
LeftMotorSpeed ushort 0 Left (low-freq) motor speed. Set by HIDMaestro OutputReceived callback.
RightMotorSpeed ushort 0 Right (high-freq) motor speed. Set by HIDMaestro OutputReceived callback.
HasDirectionalData bool false Directional FFB data available (HIDMaestro PID descriptor path)
EffectType uint 0 FfbEffectTypes constant
SignedMagnitude short 0 −10000 to +10000. Negative = opposite direction.
Direction ushort 0 Polar HID units 0–32767 (0=N, ~8192=E, ~16384=S, ~24576=W)
Period uint 0 Period in ms (periodic effects)
DeviceGain byte 255 Device-level gain 0–255, on top of per-effect gain
HasConditionData bool false Per-axis condition data available
ConditionAxes ConditionAxisData[] null Per-axis coefficients (0=X, 1=Y)
ConditionAxisCount int 0 Valid entries (1 = wheel, 2 = joystick)

ConditionAxisData

File: PadForge.Engine/Common/ForceFeedbackState.cs Namespace: PadForge.Engine

Per-axis condition parameters for spring/damper/friction/inertia effects.

public struct ConditionAxisData
{
    public short PositiveCoefficient;    // 0–10000, force when displacement > center
    public short NegativeCoefficient;    // 0–10000, force when displacement < center
    public short Offset;                 // -10000 to +10000, center offset
    public uint DeadBand;                // 0–10000, dead band around center
    public uint PositiveSaturation;      // 0–10000
    public uint NegativeSaturation;      // 0–10000
}

InputHookManager

File: PadForge.Engine/Common/InputHookManager.cs Namespace: PadForge.Engine.Common

Manages WH_KEYBOARD_LL and WH_MOUSE_LL low-level hooks to suppress mapped keyboard/mouse inputs. Only suppresses inputs in the active suppression sets.

public class InputHookManager : IDisposable
{
    void Start();
    void Stop();
    void SetSuppressedKeys(HashSet<int> vkCodes);
    void SetSuppressedMouseButtons(HashSet<int> buttons);
    bool HasAnySuppression { get; }

    static void MergeHookedKeyState(bool[] dest, int count);
    static void MergeHookedMouseState(bool[] dest, int count);
}

Methods

Method Signature Description
Start void Start() Creates background thread with GetMessage loop, installs both hooks. Blocks until installed (5s timeout).
Stop void Stop() Posts WM_QUIT to hook thread, joins (2s timeout), clears state.
SetSuppressedKeys void SetSuppressedKeys(HashSet<int> vkCodes) Updates VK codes to suppress. Clears state for removed keys. Volatile reference swap.
SetSuppressedMouseButtons void SetSuppressedMouseButtons(HashSet<int> buttons) Updates mouse button IDs to suppress (0=L, 1=R, 2=M, 3=X1, 4=X2). Volatile reference swap.
HasAnySuppression bool (property) true if any keys or mouse buttons suppressed.
MergeHookedKeyState static void MergeHookedKeyState(bool[] dest, int count) Merges suppressed-key state into dest (hook state is authoritative). Called by SdlKeyboardWrapper.
MergeHookedMouseState static void MergeHookedMouseState(bool[] dest, int count) Same for mouse buttons. Called by SdlMouseWrapper.

Hook Callbacks

  • Keyboard: Intercepts WM_KEYDOWN/UP, WM_SYSKEYDOWN/UP. Returns (IntPtr)1 to suppress, CallNextHookEx to pass through. Captures state into _hookedKeyState[] before suppressing (LL hook runs before WM_INPUT).
  • Mouse: Intercepts button messages (WM_[LR/M/X]BUTTONDOWN/UP). Converts via MouseMessageToButtonId(). Captures into _hookedMouseState[].

Button ID Mapping

Mouse Message Button ID
WM_LBUTTONDOWN/UP 0 (Left)
WM_RBUTTONDOWN/UP 1 (Right)
WM_MBUTTONDOWN/UP 2 (Middle)
WM_XBUTTONDOWN/UP (XBUTTON1) 3
WM_XBUTTONDOWN/UP (XBUTTON2) 4
Other (move, wheel) -1 (pass through)

P/Invoke

Function DLL Purpose
SetWindowsHookExW user32.dll Install low-level hook
UnhookWindowsHookEx user32.dll Remove hook
CallNextHookEx user32.dll Pass input to next hook
GetModuleHandleW kernel32.dll Get module handle for hook registration
GetMessageW user32.dll Message pump loop
PostThreadMessageW user32.dll Post WM_QUIT to hook thread
GetCurrentThreadId kernel32.dll Get hook thread ID

RawInputListener

File: PadForge.Engine/Common/RawInputListener.cs Namespace: PadForge.Engine

Receives keyboard and mouse input via Windows Raw Input API, even when unfocused (RIDEV_INPUTSINK). Creates a hidden message-only window (HWND_MESSAGE) on a background thread. State tracked per-device via RAWINPUT.header.hDevice for multi-device isolation.

DeviceInfo Struct

public struct DeviceInfo
{
    public IntPtr Handle;       // Raw Input device handle
    public string Name;         // Device display name
    public string DevicePath;   // Device interface path
    public ushort VendorId;     // USB VID
    public ushort ProductId;    // USB PID
}

Static Fields

Field Type Description
AggregateKeyboardHandle IntPtr Sentinel new IntPtr(-99). Aggregates all keyboards.
AggregateMouseHandle IntPtr Sentinel new IntPtr(-98). Aggregates all mice.

Public Methods

Method Signature Description
Start static void Start() Creates message-pump thread, registers Raw Input. Blocks until window created.
Stop static void Stop() Posts WM_QUIT, joins thread.
EnumerateKeyboards static DeviceInfo[] EnumerateKeyboards() All connected keyboards via GetRawInputDeviceList.
EnumerateMice static DeviceInfo[] EnumerateMice() All connected mice.
GetKeyboardState static void GetKeyboardState(IntPtr hDevice, bool[] dest, int count) Copies per-device key states. Aggregate handle for combined output.
ConsumeMouseDelta static void ConsumeMouseDelta(IntPtr hDevice, out int dx, out int dy) Returns and resets accumulated mouse delta.
ConsumeMouseScroll static int ConsumeMouseScroll(IntPtr hDevice) Returns and resets scroll delta.
GetMouseButtons static void GetMouseButtons(IntPtr hDevice, bool[] dest) Copies per-device button states (5: L, M, R, X1, X2).

Input Processing

  • Keyboard (RIM_TYPEKEYBOARD): Reads RAWKEYBOARD.VKey, handles RI_KEY_E0 extended keys (right Ctrl/Alt/Shift, NumLock, Insert, Home, etc.). Per-device state in ConcurrentDictionary<IntPtr, bool[]>.
  • Mouse (RIM_TYPEMOUSE): Accumulates lLastX/lLastY deltas. Tracks buttons via usButtonFlags. Scroll via RI_MOUSE_WHEEL.
  • Scroll: usButtonData is a signed short. Accumulated per-device, consumed by ConsumeMouseScroll.
  • Absolute-mode skip: when RAWMOUSE.usFlags has MOUSE_MOVE_ABSOLUTE (bit 0) set, lLastX/lLastY are absolute coordinates in 0..65535 over the active region, not deltas. RDP virtual mice, Wacom tablets in absolute mode, and some KVMs send these. Treating them as deltas would inject 0..65535-magnitude jumps into the gamepad-mapping aim and scroll paths, so the reader returns early at the top of the mouse-event branch for absolute events. Matches the policy SDL3 and XInput use for the same situation.

PrecisionTouchpadReader

File: PadForge.Engine/Common/PrecisionTouchpadReader.cs Namespace: PadForge.Engine

Reads Windows Precision Touchpad (PTP) devices via Raw Input. Each enumerated PTP device shows up as a UserDevice with CapType = Touchpad and Device == null (data flows through this reader rather than an ISdlInputDevice wrapper). The reader runs its own hidden message-only window on a background thread, registers for digitizer top-level collection 0x0D / 0x05 with RIDEV_INPUTSINK, and uses the HidP_* API family to parse contacts from each report.

Constants

Constant Value Purpose
PtpMaxFingers 5 Per-device contact ceiling. Matches the PTP-spec maximum and the canonical Windows-certified hardware bound.
StaleThresholdTicks 100 ms If no WM_INPUT arrives within this window, all contacts and the in-progress frame are cleared on the next ReadInto.

PtpDeviceState

Per-device state, keyed by Raw Input hDevice:

Field Type Purpose
X, Y, Down float[5] / bool[5] Per-slot contact position and touching flag. The gesture engine reads these via TouchpadInputState.
LastFrameDown, CurrentContactId bool[5] / int[5] Persistent per-slot rising-edge tracking so the engine sees one continuous contact ID across the lifetime of a finger touching the slot.
SlotToHidId int[5] HID contact ID currently occupying each engine slot, or -1 for free. Carries across frames — see "Stable slot assignment" below.
FrameExpected, FrameSeen int Multi-report frame-assembly bookkeeping.
FrameBufX, FrameBufY, FrameBufId parallel arrays Per-fragment scratch buffer for the contacts seen so far in the in-progress frame.
Name, DevicePath, VendorId, ProductId, LastReportTicks various Device identity + staleness timestamp.

Spec-mandatory behaviors

These four behaviors are required by the Microsoft Precision Touchpad spec and are the difference between a reader that works at 2 fingers and one that works through 5.

Tip-switch (digitizer usage 0x42)

The PTP spec sends one final report for each contact with tip-switch = 0 at lift, then drops the contact slot from subsequent reports. Without checking the bit, a lifted contact reads as still touching, inflates the apparent contact count, and corrupts the engine-side path the gesture recognizer builds.

ReadTipSwitch calls HidP_GetUsages on each per-finger link collection and scans the returned usage list for HID_USAGE_DIGITIZER_TIP_SWITCH. Touching iff the usage is present. HID-call failure falls back to "treat as touching" so non-conformant devices that don't expose the usage retain the legacy behavior.

Multi-report frame assembly

Most certified PTP hardware caps each HID report at 2 contacts; a 5-finger frame arrives as three reports (2 + 2 + 1). The PTP spec carries the total contact count on the first report's contact-count usage; continuation reports carry zero.

The reader accumulates contacts into FrameBuf* across reports and only commits ds.Down when the buffer reaches FrameExpected. Out-of-spec devices that never set contact-count (FrameExpected stays 0) fall back to per-report commit. Each fragment's contact append is bounded by FrameExpected - FrameSeen so that a descriptor with more contact link-collections than the frame actually carries (empty slots parse as zero-X/Y "contacts" with stale IDs) doesn't inflate the buffer past the spec-declared total.

Stable slot assignment by HID contact ID

Each contact in the assembled frame buffer carries the HID contact ID parsed from the report. Commit-time slot assignment runs in two passes:

  1. Pass 1 — existing IDs keep their slots. For each buffered contact, scan SlotToHidId for a matching ID; if found, that contact stays in its existing slot.
  2. Pass 2 — new IDs claim free slots. For each unassigned contact, scan SlotToHidId for -1; the first free slot is claimed for this contact's HID ID.

Unclaimed slots get released (SlotToHidId[s] = -1) and the ReadDeviceState synth-cid pass turns the cleared Down[s] into a wasDown→!isDown transition that terminates the path cleanly.

Without slot stability, when a low-slot finger lifts, the remaining contacts shift down in buffer-arrival order on the next frame. Engine slot 0's continuous-touch path gets extended with a different physical finger's coordinates, the resulting position jump looks like a swipe, and the tap fails to fire.

Staleness clear

If no WM_INPUT report arrives for the device within StaleThresholdTicks, the next ReadInto clears ds.Down, resets SlotToHidId to -1, and zeros the in-progress frame state. Prevents an orphaned partial frame from bleeding into the next touch session.

Public API

Method Signature Description
Start void Start() Spawns the message-pump thread and registers for digitizer Raw Input.
Stop void Stop() Posts WM_QUIT, joins thread.
IsAvailable bool { get; } True once at least one PTP device has produced a report.
GetDevices (IntPtr, string, string, ushort, ushort)[] GetDevices() Snapshots known devices. Called from Step 1 enumeration.
ReadInto void ReadInto(IntPtr hDevice, CustomInputState state) Per-device read. Allocates state.Touchpads[0] if absent.
ReadInto void ReadInto(CustomInputState state) Aggregate read for the "All Touchpads (Merged)" pseudo-device — first device's state.

Interaction with InputManager

Step 2 (UpdateInputStates) reads PTP devices via the path:

if (ud.IsTouchpad && ud.Device == null && _ptpReader != null && _ptpReader.IsAvailable)
{
    newState = new CustomInputState();
    if (ud.InstanceGuid == PtpMergedGuid)
        _ptpReader.ReadInto(newState);
    else
    {
        IntPtr ptpHandle = FindPtpHandle(ud.InstanceGuid);
        if (ptpHandle != IntPtr.Zero)
            _ptpReader.ReadInto(ptpHandle, newState);
    }
}

The picker fallback in MappingDisplayResolver.AddTouchpadGestureChoices defaults MaxFingers to PtpMaxFingers when ud.IsTouchpad && ud.Device == null so 3/4/5-finger gestures surface in the dropdown even when no live state is available at picker-build time.

PadSetting

File: PadForge.Engine/Data/PadSetting.cs Namespace: PadForge.Engine.Data

Complete mapping configuration for a device-to-slot assignment. All mapping properties are string descriptors: "Button N", "Axis N", "IHAxis N", "POV N Dir", "Slider N", or "" (unmapped). Declared partial.

Stored separately from UserSettings, linked via PadSettingChecksum. Multiple UserSettings can share one PadSetting. Numeric settings stored as strings for XML consistency.

Identity

Property Type Serialization Default Description
PadSettingChecksum string [XmlElement] "" Checksum from all mapping/setting properties. Links to UserSettings.

Button Mappings

Property Type Serialization Default
ButtonA string [XmlElement] ""
ButtonB string [XmlElement] ""
ButtonX string [XmlElement] ""
ButtonY string [XmlElement] ""
LeftShoulder string [XmlElement] ""
RightShoulder string [XmlElement] ""
ButtonBack string [XmlElement] ""
ButtonStart string [XmlElement] ""
ButtonGuide string [XmlElement] ""
LeftThumbButton string [XmlElement] ""
RightThumbButton string [XmlElement] ""

D-Pad Mappings

Property Type Serialization Default Description
DPad string [XmlElement] "" Combined D-Pad mapping. POV descriptor auto-extracts all 4 directions. Individual overrides take priority.
DPadUp string [XmlElement] ""
DPadDown string [XmlElement] ""
DPadLeft string [XmlElement] ""
DPadRight string [XmlElement] ""

Trigger Mappings and Settings

Property Type Serialization Default Description
LeftTrigger string [XmlElement] "" Mapping descriptor
RightTrigger string [XmlElement] "" Mapping descriptor
LeftTriggerDeadZone string [XmlElement] "0" 0–100%
RightTriggerDeadZone string [XmlElement] "0" 0–100%
LeftTriggerAntiDeadZone string [XmlElement] "0" 0–100%
RightTriggerAntiDeadZone string [XmlElement] "0" 0–100%
LeftTriggerMaxRange string [XmlElement] "100" 1–100%
RightTriggerMaxRange string [XmlElement] "100" 1–100%
LeftTriggerSensitivityCurve string [XmlElement] "0" −100 to 100 (0=linear, +100=exp, −100=log)
RightTriggerSensitivityCurve string [XmlElement] "0" −100 to 100

Thumbstick Axis Mappings

Property Type Serialization Default Description
LeftThumbAxisX string [XmlElement] ""
LeftThumbAxisY string [XmlElement] ""
RightThumbAxisX string [XmlElement] ""
RightThumbAxisY string [XmlElement] ""
LeftThumbAxisXNeg string [XmlElement] "" Negative direction (buttons mapped to bidirectional axes)
LeftThumbAxisYNeg string [XmlElement] ""
RightThumbAxisXNeg string [XmlElement] ""
RightThumbAxisYNeg string [XmlElement] ""

Deadzone Settings

Property Type Serialization Default Description
LeftThumbDeadZoneX string [XmlElement] "0" Left stick deadzone X (0–100%)
LeftThumbDeadZoneY string [XmlElement] "0" Left stick deadzone Y
RightThumbDeadZoneX string [XmlElement] "0" Right stick deadzone X
RightThumbDeadZoneY string [XmlElement] "0" Right stick deadzone Y
LeftThumbDeadZoneShape string [XmlElement] "2" DeadZoneShape enum value. 2 = ScaledRadial.
RightThumbDeadZoneShape string [XmlElement] "2" DeadZoneShape enum value
LeftThumbAntiDeadZone string [XmlElement] "0" Legacy unified (0–100%). Prefer per-axis X/Y.
RightThumbAntiDeadZone string [XmlElement] "0" Legacy unified
LeftThumbAntiDeadZoneX string [XmlElement] "0" Left stick anti-deadzone X (0–100%)
LeftThumbAntiDeadZoneY string [XmlElement] "0" Left stick anti-deadzone Y
RightThumbAntiDeadZoneX string [XmlElement] "0" Right stick anti-deadzone X
RightThumbAntiDeadZoneY string [XmlElement] "0" Right stick anti-deadzone Y
LeftThumbLinear string [XmlElement] "0" Response curve (0–100%). 0=default, 100=fully linear.
RightThumbLinear string [XmlElement] "0"

Sensitivity Curve Settings

Property Type Serialization Default Description
LeftThumbSensitivityCurveX string [XmlElement] "0" −100 to 100 (0=linear, +100=exp, −100=log)
LeftThumbSensitivityCurveY string [XmlElement] "0"
RightThumbSensitivityCurveX string [XmlElement] "0"
RightThumbSensitivityCurveY string [XmlElement] "0"

Max Range Settings

Property Type Serialization Default Description
LeftThumbMaxRangeX string [XmlElement] "100" Left stick X max range (1–100%). Symmetric/positive direction.
LeftThumbMaxRangeY string [XmlElement] "100"
RightThumbMaxRangeX string [XmlElement] "100"
RightThumbMaxRangeY string [XmlElement] "100"
LeftThumbMaxRangeXNeg string [XmlElement] null Left stick X negative (left). Null = inherit symmetric.
LeftThumbMaxRangeYNeg string [XmlElement] null Left stick Y negative (down) direction
RightThumbMaxRangeXNeg string [XmlElement] null
RightThumbMaxRangeYNeg string [XmlElement] null

Stick Center Offset Calibration

Property Type Serialization Default Description
LeftThumbCenterOffsetX string [XmlElement] "0" −100 to 100%. Corrects stick drift before deadzone.
LeftThumbCenterOffsetY string [XmlElement] "0"
RightThumbCenterOffsetX string [XmlElement] "0"
RightThumbCenterOffsetY string [XmlElement] "0"

Force Feedback Settings

Property Type Serialization Default Description
ForceType string [XmlElement] "1" 0=Off, 1=SDL Rumble
ForceOverall string [XmlElement] "100" Overall strength 0–100%. Multiplier for both motors.
ForceSwapMotor string [XmlElement] "0" "0"=no swap, "1"=swap left/right motors
LeftMotorStrength string [XmlElement] "100" Left (low-freq) motor strength 0–100%
RightMotorStrength string [XmlElement] "100" Right (high-freq) motor strength 0–100%

Audio Rumble Settings

Property Type Serialization Default Description
AudioRumbleEnabled string [XmlElement] "0" Enable audio bass rumble. "0"=off, "1"=on.
AudioRumbleSensitivity string [XmlElement] "4" Bass detection sensitivity (1–20)
AudioRumbleCutoffHz string [XmlElement] "80" Low-pass cutoff Hz (40–200)
AudioRumbleLeftMotor string [XmlElement] "100" Left motor strength for audio rumble (0–100%)
AudioRumbleRightMotor string [XmlElement] "100" Right motor strength for audio rumble (0–100%)

Axis Configuration

Property Type Serialization Default Description
AxisToButtonThreshold string [XmlElement] "50" Threshold 0–100% for axis-as-button
MappingDeadZoneEntries ExtendedMappingEntry[] [XmlArray("MappingDeadZones")] [XmlArrayItem("Map")] null Per-mapping axis-to-button thresholds. Keys = target names, values = 0–100%.
LeftThumbAxisXInvert string [XmlElement] "0" Invert left stick X. "0" or "1".
LeftThumbAxisYInvert string [XmlElement] "0"
RightThumbAxisXInvert string [XmlElement] "0"
RightThumbAxisYInvert string [XmlElement] "0"

Extended Custom Mappings (Dictionary-based)

For Extended slots with custom HID descriptors (arbitrary axis/button/POV counts). Keys: "ExtendedAxis0", "ExtendedAxis0Neg", "ExtendedBtn0", "ExtendedPov0Up". Values: mapping descriptors.

Property Type Serialization Description
ExtendedMappingEntries ExtendedMappingEntry[] [XmlArray("ExtendedMappings")] [XmlArrayItem("Map")] Serializable array for XML persistence
Method Signature Description
GetExtendedMapping string GetExtendedMapping(string key) Gets an Extended mapping value by key. Returns "" if not found.
SetExtendedMapping void SetExtendedMapping(string key, string value) Sets an Extended mapping value. Empty/null removes the key.
FlushExtendedMappings void FlushExtendedMappings() Flushes in-memory dictionary back to serializable array.

MIDI Custom Mappings (Dictionary-based)

Same pattern as Extended. Keys: "MidiCC0", "MidiCC0Neg", "MidiNote0", etc.

Property Type Serialization Description
MidiMappingEntries ExtendedMappingEntry[] [XmlArray("MidiMappings")] [XmlArrayItem("Map")] Serializable array
Method Signature Description
GetMidiMapping string GetMidiMapping(string key) Gets a MIDI mapping value.
SetMidiMapping void SetMidiMapping(string key, string value) Sets a MIDI mapping value.
FlushMidiMappings void FlushMidiMappings() Flushes dictionary to array.

KBM Custom Mappings (Dictionary-based)

Keys: "KbmKey41" (VK_A), "KbmMouseX", "KbmMouseXNeg", "KbmMBtn0", "KbmScroll", etc.

Property Type Serialization Description
KbmMappingEntries ExtendedMappingEntry[] [XmlArray("KbmMappings")] [XmlArrayItem("Map")] Serializable array
Method Signature Description
GetKbmMapping string GetKbmMapping(string key) Gets a KBM mapping value.
SetKbmMapping void SetKbmMapping(string key, string value) Sets a KBM mapping value.
FlushKbmMappings void FlushKbmMappings() Flushes dictionary to array.

Per-Mapping Deadzones (Dictionary-based)

Same pattern as Extended/MIDI/KBM mappings. Keys = target mapping names (e.g. "LeftThumbAxisX"), values = 0–100% threshold for axis-to-button activation. Default removal values: "0" or "50".

Method Signature Description
GetMappingDeadZone string GetMappingDeadZone(string key) Gets deadzone for a target. Returns "" if not found.
SetMappingDeadZone void SetMappingDeadZone(string key, string value) Sets or removes a deadzone entry. Removes at "0" or "50".
FlushMappingDeadZones void FlushMappingDeadZones() Syncs in-memory dictionary to MappingDeadZoneEntries array for serialization.

Computed Properties

Property Type Serialization Description
HasAnyMapping bool [XmlIgnore] true if any mapping property has a non-empty descriptor.

Methods

Method Signature Description
MigrateAntiDeadZones void MigrateAntiDeadZones() Migrates legacy unified anti-deadzone to per-axis X/Y. Call after deserialization.
MigrateMaxRangeDirections void MigrateMaxRangeDirections() Copies symmetric max range to null/empty negative-direction properties.
ComputeChecksum string ComputeChecksum() 8-char hex checksum (first 4 bytes of MD5) from all properties. Keys sorted for determinism.
UpdateChecksum void UpdateChecksum() Computes and stores checksum in PadSettingChecksum.
ClearMappingDescriptors void ClearMappingDescriptors() Clears all mapping descriptors. Preserves deadzone and FFB settings.
GetAllMappingDescriptors List<string> GetAllMappingDescriptors() All non-empty mapping descriptor strings.
ToJson string ToJson(VirtualControllerType outputType, bool isExtended) JSON for clipboard. Embeds __OutputType / __IsExtended layout metadata, the mapping dicts (__ExtendedMappings, __MidiMappings, __KbmMappings, __MappingDeadZones), the typed touchpad sub-tree (__TouchpadSettings), and the clipboard-only per-slot payloads when set on the source (__SlotPerDeviceSettings, __SlotPlayStationConfigs, __SlotExtendedConfig, __SlotMidiConfig, __SlotMultiSourceRows, __DeviceScopedMultiSourceRows).
FromJson static PadSetting FromJson(string json) Deserializes JSON. Returns null on invalid input.
FromJson static PadSetting FromJson(string json, out VirtualControllerType, out bool) Same, also returns the source layout metadata so cross-layout paste can translate. Reattaches the typed TouchpadSettings and the clipboard-only payloads listed above when present.
CopyFrom void CopyFrom(PadSetting source) Reflection copy of every CopyablePropertyNames entry. Deep-copies mapping arrays and the TouchpadSettings typed sub-tree. Invalidates cached dicts.
CopyFromTranslated void CopyFromTranslated(PadSetting source, VirtualControllerType srcType, bool srcIsExtended, VirtualControllerType tgtType, bool tgtIsExtended) Cross-layout copy via MappingTranslation. Translates mapping properties by canonical position.
CloneDeep PadSetting CloneDeep() Deep copy including checksum.

ExtendedMappingEntry

File: PadForge.Engine/Data/PadSetting.cs Namespace: PadForge.Engine.Data

Key-value entry for Extended/MIDI/KBM mapping and per-mapping deadzone XML persistence. Shared by all four dictionary-based systems.

public class ExtendedMappingEntry
{
    [XmlAttribute] public string Key { get; set; } = "";
    [XmlAttribute] public string Value { get; set; } = "";
}

UserSetting

File: PadForge.Engine/Data/UserSetting.cs Namespace: PadForge.Engine.Data

Links a physical device to a virtual controller slot and mapping. One per device-to-slot assignment. Implements INotifyPropertyChanged.

Serialized Properties

Property Type Serialization Default Description
InstanceGuid Guid [XmlElement] Physical device instance GUID
InstanceName string [XmlElement] "" Instance name (for offline display)
ProductGuid Guid [XmlElement] Product GUID for matching across sessions
ProductName string [XmlElement] "" Product name
MapTo int [XmlElement] -1 VC slot index (0–15). −1 = unmapped. Raises PropertyChanged.
PadSettingChecksum string [XmlElement] "" Links to a PadSetting
IsEnabled bool [XmlElement] true Whether this mapping is enabled. Disabled = skipped in pipeline.
DateCreated DateTime [XmlElement] DateTime.Now Creation timestamp
DateUpdated DateTime [XmlElement] DateTime.Now Last modification timestamp

Runtime-Only Fields (Not Serialized)

Property Type Serialization Description
OutputState Gamepad [XmlIgnore] Mapped output from Step 3. Written by background thread.
RawMappedState Gamepad [XmlIgnore] Pre-processing state (axis-selected, Y-negated, before DZ/ADZ/linear/range). For UI preview.
ExtendedRawOutputState ExtendedRawState [XmlIgnore] Mapped raw output for Extended slots. Forwarded to HIDMaestro via HMaestroVirtualController.SubmitExtendedRawState.
MidiRawOutputState MidiRawState [XmlIgnore] Mapped MIDI raw output for MIDI slots.
KbmRawOutputState KbmRawState [XmlIgnore] Mapped KBM raw output for KeyboardMouse slots.
_cachedPadSetting PadSetting [XmlIgnore] (internal) Cached PadSetting reference set by SettingsManager.

Methods

Method Signature Description
GetPadSetting PadSetting GetPadSetting() Returns cached PadSetting.
SetPadSetting void SetPadSetting(PadSetting ps) Sets cached PadSetting. Called by SettingsManager on load/sync.

UserDevice

File: PadForge.Engine/Data/UserDevice.cs Namespace: PadForge.Engine.Data

Data model for a physical input device. Serializable properties (settings-persisted) and runtime-only fields (pipeline). Partial class. Implements INotifyPropertyChanged.

Serialized Identity Properties

Property Type Serialization Default Description
InstanceGuid Guid [XmlElement] Deterministic GUID from device path
InstanceName string [XmlElement] "" Instance name (e.g., "Xbox Controller")
ProductGuid Guid [XmlElement] Product GUID (PIDVID format)
ProductName string [XmlElement] "" Product name
VendorId ushort [XmlElement] 0 USB Vendor ID
ProdId ushort [XmlElement] 0 USB Product ID
DevRevision ushort [XmlElement] 0 USB Product Version / Revision
DevicePath string [XmlElement] "" Device file system path
SerialNumber string [XmlElement] "" Device serial number (e.g., Bluetooth MAC)

Serialized Capability Properties

Property Type Serialization Default Description
CapAxeCount int [XmlElement] 0 Number of axes
CapButtonCount int [XmlElement] 0 Button count (gamepad-mapped for gamepads)
RawButtonCount int [XmlElement] 0 Raw button count before gamepad remapping
CapPovCount int [XmlElement] 0 Number of POV hat switches
CapType int [XmlElement] 0 InputDeviceType constant
HasGyro bool [XmlElement] false Gyroscope support
HasAccel bool [XmlElement] false Accelerometer support

Serialized Metadata

Property Type Serialization Default Description
DateCreated DateTime [XmlElement] DateTime.Now First creation timestamp. Vestigial. Serialized but never read by any consumer.
DateUpdated DateTime [XmlElement] DateTime.Now Last update timestamp. Vestigial. Serialized but never read by any consumer.
IsEnabled bool [XmlElement] true Whether device is enabled for mapping
IsHidden bool [XmlElement] false Whether device is hidden from UI
DisplayName string [XmlElement] "" User-assigned name (overrides InstanceName)
HidHideEnabled bool [XmlElement] false Hide device from games via HidHide when assigned
ConsumeInputEnabled bool [XmlElement] false Suppress mapped KB/mouse inputs via hooks
ForceRawJoystickMode bool [XmlElement] false Bypass SDL gamepad remapping
HidHideInstanceIds List<string> [XmlArray] [XmlArrayItem("Id")] new() Cached HID instance IDs for HidHide (persisted for offline devices)
DeviceObjects DeviceObjectItem[] [XmlElement] null Axis, hat, and button metadata. Populated in Step 1. Serialized for offline dropdown persistence so mapping UI can show source descriptors when the device is disconnected.

Runtime-Only Fields (Not Serialized)

Property Type Serialization Description
Device ISdlInputDevice [XmlIgnore] Live device handle. Set in Step 1.
IsOnline bool [XmlIgnore] Connected and opened.
InputState CustomInputState [XmlIgnore] Current state snapshot (Step 2, atomic ref).
InputStateTime DateTime [XmlIgnore] Timestamp of InputState.
OldInputState CustomInputState [XmlIgnore] Previous state for change detection.
OldInputStateTime DateTime [XmlIgnore] Timestamp of OldInputState.
ActuatorCount int [XmlIgnore] FFB actuator axis count.
ForceFeedbackState ForceFeedbackState [XmlIgnore] Per-device FFB state.

Computed Convenience Properties

Property Type Serialization Description
IsMouse bool [XmlIgnore] CapType == InputDeviceType.Mouse
IsKeyboard bool [XmlIgnore] CapType == InputDeviceType.Keyboard
HasForceFeedback bool [XmlIgnore] `ActuatorCount > 0
ResolvedName string [XmlIgnore] DisplayName if set, then InstanceName, then ProductName, then "(Unknown Device)"
StatusText string [XmlIgnore] "Disabled", "Online", or "Offline"

Methods

Method Signature Description
LoadInstance void LoadInstance(...) Sets identity properties.
LoadCapabilities void LoadCapabilities(...) Sets capability properties.
LoadFromSdlDevice void LoadFromSdlDevice(SdlDeviceWrapper) Loads from SDL wrapper + DevRevision.
LoadFromKeyboardDevice void LoadFromKeyboardDevice(SdlKeyboardWrapper) Loads from keyboard wrapper.
LoadFromMouseDevice void LoadFromMouseDevice(SdlMouseWrapper) Loads from mouse wrapper.
LoadFromWebDevice void LoadFromWebDevice(WebControllerDevice) Loads from web controller.
ClearRuntimeState void ClearRuntimeState() Clears runtime fields. Preserves serialized properties.
NotifyStateChanged void NotifyStateChanged() Raises PropertyChanged for IsOnline, StatusText, InputState.
ToString string Returns "{ResolvedName} [{InstanceGuid:N}]".

DeadZoneShape

File: PadForge.Engine/Data/DeadZoneShape.cs Namespace: PadForge.Engine.Data

Deadzone algorithm for thumbstick axes.

public enum DeadZoneShape
{
    Axial = 0,              // Independent per-axis (square/cross shape). Legacy behavior.
    Radial = 1,             // Circular/elliptical magnitude check, no output rescaling.
    ScaledRadial = 2,       // Circular/elliptical with output rescaling (industry standard). DEFAULT.
    SlopedAxial = 3,        // Axis-dependent thresholds: DZ grows as other axis increases.
    SlopedScaledAxial = 4,  // Sloped axis-dependent with output rescaling.
    Hybrid = 5,             // Scaled Radial followed by Sloped Scaled Axial (best hybrid).
}

MappingTranslation

File: PadForge.Engine/Data/MappingTranslation.cs Namespace: PadForge.Engine.Data

Translates mapping property names between virtual controller layouts using positional equivalence.

Key Types

public enum ControlCategory { Button, Axis, AxisNeg, DPad }
public record MappingSlot(ControlCategory Category, int Position);

MappingSlot represents a canonical position (e.g., "3rd button", "1st axis negative"). Translation converts source property name to MappingSlot, then to the target layout's property name.

Public Methods

Method Signature Description
GetPosition static MappingSlot GetPosition(string propertyName, VirtualControllerType type, bool isExtended) Property name to canonical MappingSlot
GetPropertyName static string GetPropertyName(MappingSlot slot, VirtualControllerType type, bool isExtended) Canonical MappingSlot to property name
IsSameLayout static bool IsSameLayout(VirtualControllerType srcType, bool srcIsExtended, VirtualControllerType tgtType, bool tgtIsExtended) true if source and target share property names
GetLayoutLabel static string GetLayoutLabel(VirtualControllerType type, bool isExtended) Display label (e.g., "Xbox", "Extended", "MIDI", "KB+M")

Supported Layouts

Layout Property Name Examples Notes
Gamepad (Xbox / PlayStation / Extended gamepad preset) ButtonA, LeftThumbAxisX, DPadUp Xbox and PlayStation share property names. Buttons: A=0..Guide=10. Axes: LX=0..RT=5.
Extended Custom ExtendedBtn0, ExtendedAxis2, ExtendedAxis2Neg, ExtendedPov0Up Indexed by position. POV 0 only maps to D-Pad.
MIDI MidiNote0, MidiCC3, MidiCC3Neg No D-Pad support (returns null).
KB+M KbmMBtn0, KbmMouseX, KbmMouseXNeg, KbmKey20, KbmScroll Mouse buttons 0–4, VK codes, 3 mouse axes. D-Pad mapped to arrow keys.

Internal Layout Kinds

private enum LayoutKind { Gamepad, Extended, Midi, Kbm }
  • Xbox, PlayStation, and Extended gamepad preset all resolve to LayoutKind.Gamepad.
  • Extended with isExtended=true (custom HID descriptor) resolves to LayoutKind.Extended.
  • IsSameLayout compares resolved LayoutKind values.

SDL3 P/Invoke

File: PadForge.Engine/Common/SDL3Minimal.cs Namespace: SDL3

Minimal SDL3 P/Invoke declarations for joystick, gamepad, keyboard, mouse, and haptic. Only functions used by PadForge are declared. Native library: "SDL3".

Init Flags

Constant Value Description
SDL_INIT_VIDEO 0x00000020 Required for keyboard/mouse
SDL_INIT_JOYSTICK 0x00000200 Joystick subsystem
SDL_INIT_HAPTIC 0x00001000 Haptic subsystem
SDL_INIT_GAMEPAD 0x00002000 Gamepad subsystem (was SDL_INIT_GAMECONTROLLER)

Hat Constants

Constant Value
SDL_HAT_CENTERED 0x00
SDL_HAT_UP 0x01
SDL_HAT_RIGHT 0x02
SDL_HAT_DOWN 0x04
SDL_HAT_LEFT 0x08
SDL_HAT_RIGHTUP 0x03
SDL_HAT_RIGHTDOWN 0x06
SDL_HAT_LEFTUP 0x09
SDL_HAT_LEFTDOWN 0x0C

Hint Strings

Constant Value Description
SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" Allow events when app not focused
SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" Do NOT set (conflicts with XInput enumeration)
SDL_HINT_JOYSTICK_XINPUT "SDL_JOYSTICK_XINPUT" Enables Xbox controller enumeration
SDL_HINT_JOYSTICK_HIDAPI_SWITCH2 "SDL_JOYSTICK_HIDAPI_SWITCH2" Switch 2 controller support
SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" Allow screensaver

Enums

SDL_JoystickType:

Value Name
0 SDL_JOYSTICK_TYPE_UNKNOWN
1 SDL_JOYSTICK_TYPE_GAMEPAD
2 SDL_JOYSTICK_TYPE_WHEEL
3 SDL_JOYSTICK_TYPE_ARCADE_STICK
4 SDL_JOYSTICK_TYPE_FLIGHT_STICK
5 SDL_JOYSTICK_TYPE_DANCE_PAD
6 SDL_JOYSTICK_TYPE_GUITAR
7 SDL_JOYSTICK_TYPE_DRUM_KIT
8 SDL_JOYSTICK_TYPE_ARCADE_PAD
9 SDL_JOYSTICK_TYPE_THROTTLE
10 SDL_JOYSTICK_TYPE_COUNT

SDL_PowerState:

Value Name
-1 SDL_POWERSTATE_ERROR
0 SDL_POWERSTATE_UNKNOWN
1 SDL_POWERSTATE_ON_BATTERY
2 SDL_POWERSTATE_NO_BATTERY
3 SDL_POWERSTATE_CHARGING
4 SDL_POWERSTATE_CHARGED

Structs

SDL_GUID (16 bytes): data0 through data15. Methods: ToGuid() (converts to .NET Guid), ToByteArray().

SDL_HapticDirection (16 bytes): type (byte), dir0, dir1, dir2 (int).

SDL_HapticLeftRight (12 bytes): type, length, large_magnitude, small_magnitude.

SDL_HapticConstant (40 bytes): type, direction, length, delay, button, interval, level, attack_length, attack_level, fade_length, fade_level.

SDL_HapticPeriodic (44 bytes): type, direction, length, delay, button, interval, period, magnitude, offset, phase, attack_length, attack_level, fade_length, fade_level.

SDL_HapticCondition (68 bytes): type, direction, length, delay, button, interval, per-axis arrays (3 axes): right_sat[0-2], left_sat[0-2], right_coeff[0-2], left_coeff[0-2], deadband[0-2], center[0-2].

SDL_HapticRamp (44 bytes): type, direction, length, delay, button, interval, start, end, attack_length, attack_level, fade_length, fade_level.

SDL_HapticEffect (72 bytes, explicit layout): Union overlaying type, leftright, constant, periodic, condition, ramp all at FieldOffset(0).

Haptic Constants

Constant Value Description
SDL_HAPTIC_CONSTANT 1 << 0 Constant force
SDL_HAPTIC_SINE 1 << 1 Sine wave
SDL_HAPTIC_SQUARE 1 << 2 Square wave
SDL_HAPTIC_TRIANGLE 1 << 3 Triangle wave
SDL_HAPTIC_SAWTOOTHUP 1 << 4 Sawtooth up
SDL_HAPTIC_SAWTOOTHDOWN 1 << 5 Sawtooth down
SDL_HAPTIC_RAMP 1 << 6 Ramp
SDL_HAPTIC_SPRING 1 << 7 Spring condition
SDL_HAPTIC_DAMPER 1 << 8 Damper condition
SDL_HAPTIC_INERTIA 1 << 9 Inertia condition
SDL_HAPTIC_FRICTION 1 << 10 Friction condition
SDL_HAPTIC_LEFTRIGHT 1 << 11 Left/right dual-motor
SDL_HAPTIC_CUSTOM 1 << 15 Custom effect
SDL_HAPTIC_GAIN 1 << 16 Gain control supported
SDL_HAPTIC_AUTOCENTER 1 << 17 Auto-center supported
SDL_HAPTIC_INFINITY 0xFFFFFFFF Infinite duration
SDL_HAPTIC_POLAR 0 (byte) Polar direction type
SDL_HAPTIC_CARTESIAN 1 (byte) Cartesian direction type
SDL_HAPTIC_SPHERICAL 2 (byte) Spherical direction type
SDL_HAPTIC_STEERING_AXIS 3 (byte) Steering axis direction type

Gamepad Axis Constants

Constant Value Description
SDL_GAMEPAD_AXIS_LEFTX 0 Left stick X
SDL_GAMEPAD_AXIS_LEFTY 1 Left stick Y
SDL_GAMEPAD_AXIS_RIGHTX 2 Right stick X
SDL_GAMEPAD_AXIS_RIGHTY 3 Right stick Y
SDL_GAMEPAD_AXIS_LEFT_TRIGGER 4 Left trigger
SDL_GAMEPAD_AXIS_RIGHT_TRIGGER 5 Right trigger
SDL_GAMEPAD_AXIS_COUNT 6 Total axis count

Gamepad Button Constants

Constant Value Description
SDL_GAMEPAD_BUTTON_SOUTH 0 A
SDL_GAMEPAD_BUTTON_EAST 1 B
SDL_GAMEPAD_BUTTON_WEST 2 X
SDL_GAMEPAD_BUTTON_NORTH 3 Y
SDL_GAMEPAD_BUTTON_BACK 4 Back/Select
SDL_GAMEPAD_BUTTON_GUIDE 5 Guide/Home
SDL_GAMEPAD_BUTTON_START 6 Start
SDL_GAMEPAD_BUTTON_LEFT_STICK 7 Left stick click
SDL_GAMEPAD_BUTTON_RIGHT_STICK 8 Right stick click
SDL_GAMEPAD_BUTTON_LEFT_SHOULDER 9 Left bumper
SDL_GAMEPAD_BUTTON_RIGHT_SHOULDER 10 Right bumper
SDL_GAMEPAD_BUTTON_DPAD_UP 11 D-pad up
SDL_GAMEPAD_BUTTON_DPAD_DOWN 12 D-pad down
SDL_GAMEPAD_BUTTON_DPAD_LEFT 13 D-pad left
SDL_GAMEPAD_BUTTON_DPAD_RIGHT 14 D-pad right
SDL_GAMEPAD_BUTTON_MISC1 15 Share / Capture / extra button (Xbox Series Share, Switch Capture, PS5 Mic)
SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 16 Elite / DualSense Edge paddle (upper right)
SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 17 Elite / Edge paddle (upper left)
SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2 18 Elite / Edge paddle (lower right)
SDL_GAMEPAD_BUTTON_LEFT_PADDLE2 19 Elite / Edge paddle (lower left)
SDL_GAMEPAD_BUTTON_TOUCHPAD 20 Touchpad click (DS4 / DualSense / Steam Controller)
SDL_GAMEPAD_BUTTON_MISC2 21 Additional device-specific button
SDL_GAMEPAD_BUTTON_MISC3 22 Additional device-specific button
SDL_GAMEPAD_BUTTON_MISC4 23 Additional device-specific button
SDL_GAMEPAD_BUTTON_MISC5 24 Additional device-specific button
SDL_GAMEPAD_BUTTON_MISC6 25 Additional device-specific button
SDL_GAMEPAD_BUTTON_COUNT 26 Total button count

Sensor Type Constants

Constant Value Description
SDL_SENSOR_ACCEL 1 Accelerometer
SDL_SENSOR_GYRO 2 Gyroscope
SDL_SENSOR_ACCEL_L 3 Left accelerometer
SDL_SENSOR_GYRO_L 4 Left gyroscope
SDL_SENSOR_ACCEL_R 5 Right accelerometer
SDL_SENSOR_GYRO_R 6 Right gyroscope

Mouse Button Masks

Constant Value Description
SDL_BUTTON_LMASK 1 << 0 Left button
SDL_BUTTON_MMASK 1 << 1 Middle button
SDL_BUTTON_RMASK 1 << 2 Right button
SDL_BUTTON_X1MASK 1 << 3 X1 button
SDL_BUTTON_X2MASK 1 << 4 X2 button

VirtualKeyName Array

string[256] array of human-readable Windows VK code names. Built by BuildVirtualKeyNames(). Covers standard keys, modifiers, F1–F24, numpad, OEM keys. Used by SdlKeyboardWrapper.GetDeviceObjects() for button naming.

Core Function Categories

Lifecycle: SDL_Init, SDL_Quit, SDL_EnableScreenSaver, SDL_GetError, SDL_SetHint, SDL_free

Joystick Enumeration: SDL_GetJoysticks, SDL_GetJoystickGUIDForID, SDL_GetJoystickVendorForID, SDL_GetJoystickProductForID, SDL_GetJoystickProductVersionForID, SDL_GetJoystickTypeForID, SDL_GetJoystickNameForID, SDL_GetJoystickPathForID, SDL_IsGamepad

Gamepad Mappings: SDL_AddGamepadMappingsFromFile, SDL_AddGamepadMapping, GetGamepadMapping

Joystick Instance: SDL_OpenJoystick, SDL_CloseJoystick, SDL_GetJoystickID, SDL_JoystickConnected

Gamepad Instance: SDL_OpenGamepad, SDL_CloseGamepad, SDL_GetGamepadJoystick

Gamepad State: SDL_GetGamepadAxis, SDL_GetGamepadButton

Joystick State: SDL_UpdateJoysticks, SDL_PumpEvents, SDL_GetJoystickAxis, SDL_GetJoystickButton, SDL_GetJoystickHat, SDL_GetNumJoystickAxes, SDL_GetNumJoystickButtons, SDL_GetNumJoystickHats

Joystick Properties: SDL_GetJoystickName, SDL_GetJoystickVendor, SDL_GetJoystickProduct, SDL_GetJoystickProductVersion, SDL_GetJoystickType, SDL_GetJoystickPath, SDL_GetJoystickSerial, SDL_GetJoystickGUID, SDL_GetJoystickProperties, SDL_GetBooleanProperty, SDL_GetGamepadPowerInfo

Sensors: SDL_GamepadHasSensor, SDL_SetGamepadSensorEnabled, SDL_GetGamepadSensorData

Rumble: SDL_RumbleJoystick

Haptic: SDL_OpenHapticFromJoystick, SDL_CloseHaptic, SDL_GetHapticFeatures, SDL_CreateHapticEffect, SDL_UpdateHapticEffect, SDL_RunHapticEffect, SDL_StopHapticEffect, SDL_DestroyHapticEffect, SDL_SetHapticGain, SDL_GetNumHapticAxes

Keyboard: SDL_GetKeyboards, SDL_GetKeyboardNameForID, SDL_GetKeyboardState

Mouse: SDL_GetMice, SDL_GetMouseNameForID, SDL_GetMouseState, SDL_GetRelativeMouseState

Version: SDL_GetVersion, SDL_Linked_Version (returns (major, minor, patch) tuple)

GestureRecognizer

File: PadForge.Engine/Touchpad/GestureRecognizer.cs Namespace: PadForge.Engine.Touchpad

The per-tick touchpad recognizer. Reads one device's current TouchpadInputState against that pad's TouchpadGestureSettings and a persistent TouchpadGestureContext, then populates the context's FiredGesturesThisFrame set with gesture-descriptor names. Static class with one entry point.

Entry point

public static void Update(
    int padIdx,
    TouchpadGestureContext ctx,
    TouchpadInputState pad,
    TouchpadGestureSettings settings,
    long nowMs,
    IReadOnlyList<ShapeTemplate> shapeTemplates = null)

Walks the state machine Idle → Accumulating → Recognizing → Cooldown → Idle. Path tracking runs whenever either gesture recognition or joystick output is enabled; both off skips the tick. Suspended state freezes detection (used by the global gesture-suspend hotkey).

Three tiers

Tier When it runs What it fires
1: direction-based Every tick while a finger is down 4-way / 8-way swipes (end-of-gesture), radial-zone fires (mid-gesture, one-finger), tap / double-tap / triple-tap (end-of-gesture), long-press (mid-gesture, one-finger, recent-stillness gate)
2: multi-finger continuous Every tick while ≥2 fingers are down Pinch / spread (one-shot threshold), rotate (one-shot threshold), continuous PinchAxis and RotateAxis, two-finger end-of-gesture swipe + tap
3: shape templates End-of-gesture only ShapeRecognizer (point-cloud) + AngularMarginRecognizer (per-segment angle) run in parallel on single-finger templates and keep the higher-confidence match. Multi-finger templates use ShapeRecognizer alone.

Long-press metric

DetectLongPress uses a recent-stillness window rather than max-from-touchdown. The bounding-box span of the last 25% of the path must stay below LongPressMaxMotion. Without this, users settling a finger into position (a common DualSense pattern where the contact patch shifts the reported position by a few percent during the first hundred ms) failed the max-distance check even when the finger was now perfectly stable.

LongPress / RadialZones coexistence

DetectLongPress does NOT clear the path after firing. DetectRadialZones reads path[0] each tick to compute the angle from touchdown, and a cleared path collapses start ≈ end so the next radial tick sees dist < RadialCenterDeadzone and releases the held zone. End-of-gesture detection checks for the LongPress entry in FiredGesturesThisFrame and skips swipe / tap / shape recognition instead.

Per-slot fan-out

The same physical pad in multiple slots ticks through Update once per slot with that slot's own TouchpadGestureContext and TouchpadGestureSettings. The InputManager wiring is keyed by (slot, deviceGuid, padIdx). Fires from slot 0 don't bleed into slot 1's mapping rows.

ShapeRecognizer

File: PadForge.Engine/Touchpad/ShapeRecognizer.cs Namespace: PadForge.Engine.Touchpad

C# re-derivation of the canonical $Q point-cloud recognizer (Vatavu / Anthony / Wobbrock, MobileHCI 2018), BSD 3-Clause. Faithful port of the reference JavaScript implementation. Used by GestureRecognizer Tier 3 at the Accumulating → Recognizing transition.

Constants

Constant Value Purpose
DefaultResampleCount 32 Resampled points per template / candidate.
DefaultLookupTableSize 64 LUT grid resolution.
MaxIntCoord 1024 Lookup-table integer-coordinate ceiling.

Public API

public static string Match(
    Vector2[] candidate,
    IReadOnlyList<ShapeTemplate> templates,
    int fingerCount,
    float threshold,
    out float bestScore)

Returns the matched template name, or null when no template scores below the threshold. Templates whose FingerCount doesn't match fingerCount are skipped. The bestScore out-param is the actual best distance (regardless of threshold).

public static ShapeTemplate Build(string name, Vector2[] points, int fingerCount)

Preprocesses a candidate path or template into a ready-to-match ShapeTemplate: resample → scale-to-unit → translate-to-origin → build LUT.

Algorithm

Match builds the candidate's preprocessed cloud + LUT once per call, then iterates templates. For each template:

  1. ComputeLowerBound(template, candidate) — closed-form SAT-based lower bound on CloudDistance. If the lower bound exceeds the current best score, skip this template entirely.
  2. CloudMatch(template, candidate) — runs CloudDistance in both directions (template→candidate and candidate→template), floor(sqrt(n)) starting indices each way, takes the minimum. Matches the canonical implementation.
  3. CloudDistance(c1, c2, startIdx) — greedy nearest-unmatched matching with a matched[] exclusion array. Weight starts at n and decrements per step, biasing the score toward the earliest correspondences. Early-abandons when the running sum exceeds the current best.

The matched[] tracking is mandatory; an earlier PadForge revision dropped it on the assumption that the LUT replaced it, and an M-shape custom gesture matched a horizontal swipe.

Threshold semantics

Lower threshold = stricter match (fewer false positives). Default GestureMatchThreshold is 3.0, preserved across the $P → $Q migration so user-tuned values transfer.

AngularMarginRecognizer

File: PadForge.Engine/Touchpad/AngularMarginRecognizer.cs Namespace: PadForge.Engine.Touchpad

Per-segment angle-direction matcher adapted from GestureSign's PointPatternAnalyzer, BSD 3-Clause. Runs alongside ShapeRecognizer on single-finger templates; the higher-confidence match wins.

Circular-variance gate

Templates whose path has circular variance (1 - R) below LineLikeVarianceGate = 0.1 (line-like) are matched only against other line-like candidates. Templates with variance above 0.2 (corner-rich) are matched only against other corner-rich candidates. The gate stops a horizontal swipe (line-like) from scoring well against a corner-rich M-template.

R is the mean resultant length of the per-segment unit direction vectors.

Closed-path detection

Templates flagged AngularIsClosed get a special endpoint-match scoring path so a re-traced closed shape doesn't get penalized for ending near where it started.

Direction agnosticism

Templates flagged AngularIsDirectionAgnostic score the candidate against both forward and reversed traversals and keep the better. Used for shapes where the user's drawing direction shouldn't matter (e.g. a horizontal Z that traces left-to-right or right-to-left).

ShapeTemplate

File: PadForge.Engine/Touchpad/ShapeTemplate.cs Namespace: PadForge.Engine.Touchpad

Preprocessed template ready for matching by ShapeRecognizer and AngularMarginRecognizer. Constructed once from a path of Vector2 points; the heavy work (resample / scale / translate / LUT-build / angular-signature precompute) runs at construction time so the per-tick Match path stays cheap.

Field Type Purpose
Name string Descriptor suffix (e.g. Circle, CircleCCW, custom name)
FingerCount int Number of simultaneous fingers expected (1 for in-box, 1..5 for custom)
PointCloud Vector2[] Resampled to DefaultResampleCount, normalized to unit box, centered
LookupTable ushort[] Closest-point integer-grid LUT for $Q lower-bound short-circuit
LookupTableSize int LUT grid resolution (typically DefaultLookupTableSize)
ThresholdOverride float? Per-template threshold override, null = use slot's GestureMatchThreshold
Enabled bool Per-gesture enable toggle (only meaningful for custom templates)
IsCustom bool True for user-recorded gestures, false for in-box shapes
AngularSignature float[] Per-segment direction angles for AngularMarginRecognizer
AngularIsClosed bool Path starts ≈ ends; angular scoring uses closed-path rules
AngularIsDirectionAgnostic bool Match both forward and reversed candidate traversals

InBoxShapeTemplates

File: PadForge.Engine/Touchpad/InBoxShapeTemplates.cs Namespace: PadForge.Engine.Touchpad

Procedural builders for the in-box shapes shipped with every profile. Six templates total: Circle (clockwise), CircleCCW, Square, Triangle, Z, Checkmark. The picker exposes Circle as two separate descriptors so the two directions can drive different mappings.

Add(...) builds each template inline: generates the canonical Vector2 path, preprocesses it through ShapeRecognizer.Build, attaches the LUT, sets the angular flags appropriate to the shape, and appends to the catalog. Static once-per-app initialization; no XML.

Names is a static string[] the picker walks to surface in-box shape descriptors.

TouchpadCustomGesture

File: PadForge.Engine/Touchpad/TouchpadCustomGesture.cs Namespace: PadForge.Engine.Touchpad

XML-serializable representation of a user-recorded custom gesture. Stored in the profile's gesture library; compiled to a ShapeTemplate at profile load.

Field Type Serialization Purpose
Name string [XmlAttribute] Suffix on the Touchpad N Custom_<name> descriptor
FingerCount int [XmlAttribute] 1..5
DeviceClass string [XmlAttribute] Optional filter ("DualSense", "PTP", "Overlay", "WebController", or empty = any)
TouchpadIndex int [XmlAttribute] Filter to a specific pad index on multi-pad devices
Enabled bool [XmlAttribute] Per-gesture disable toggle
Paths List<List<Vector2>> [XmlElement] Per-finger recorded paths
ThresholdOverride float? [XmlElement] Per-gesture override of the slot-wide threshold

ToTemplate() constructs the ShapeTemplate by concatenating per-finger paths in a deterministic order, running it through ShapeRecognizer.Build, and copying threshold-override + finger-count + name.

TouchpadGestureContext

File: PadForge.Engine/Touchpad/TouchpadGestureContext.cs Namespace: PadForge.Engine.Touchpad

Per-(slot, deviceGuid, padIdx) runtime context for the gesture recognizer. Held by InputManager.GestureContexts and lazily allocated on first tick.

Lifecycle state

State Meaning
Idle No fingers in contact. Waiting for a finger-down.
Accumulating ≥1 finger in contact. Path is growing. Tier 1 / Tier 2 mid-gesture detectors may fire.
Recognizing All fingers just lifted. Ran end-of-gesture recognition. Transitions immediately to Cooldown.
Cooldown Post-gesture quiet period (CooldownMs). Prevents bounce-fire.
Suspended Global suspend hotkey active. No detection runs on any pad.

Per-finger path storage

FingerPaths is List<List<Vector2>>, indexed by the order fingers touched down (not by hardware slot index). A finger lifting and a new one landing in the same slot opens a fresh path so the gesture engine doesn't stitch unrelated contacts together. Cleared at the end of every gesture when the cooldown expires.

FingerStartTimestampsMs / FingerContactIds / FingerSlotIndices parallel FingerPaths so each entry's touchdown time, originating HID contact ID, and hardware slot index are recoverable.

Per-frame fire set

FiredGesturesThisFrame is a HashSet<string> of gesture-descriptor names fired this tick. The name is historical — fires actually latch across the cooldown window so downstream readers (mapping evaluator → button output → macro trigger) see a stable fire long enough to pick up the rising edge at any reasonable polling rate. Cleared on cooldown expiry, not on every tick.

Continuous-axis state

CurrentPinchAxis and CurrentRotateAxis hold the live bipolar -1..+1 values for the PinchAxis / RotateAxis mapping sources. Captured baselines (TwoFingerInitialDistance, TwoFingerInitialAngle) anchor pinch and rotate to the session's opening geometry. FiredPinchThisSession / FiredSpreadThisSession / FiredRotateCWThisSession / FiredRotateCCWThisSession are one-shot-per-session latches.

Radial-zone state

CurrentRadialZone is the most-recently-fired zone index (-1 = none held). Re-entering the same zone doesn't re-fire; crossing to a different zone releases the old fire and presses the new one.

TouchpadGestureSettings

File: PadForge.Engine/Touchpad/TouchpadGestureSettings.cs Namespace: PadForge.Engine.Touchpad

Per-(slot, deviceGuid, padIdx) toggles and thresholds. Stored as a nested XML element on the slot's PadSetting keyed by (deviceGuid, padIdx) so the same pad on two slots can carry two independent configurations.

Master toggles

Property Default Purpose
Enabled false Master gesture-engine switch. Off skips the recognizer entirely.
Mode "Both" "InBoxOnly", "CustomOnly", or "Both". Filters which template catalog runs.
CooldownMs 100 Minimum time between consecutive fires from this pad.

Per-feature toggles (all default false)

EnableFourWaySwipes, EnableEightWaySwipes, EnableRadialZones, EnableTaps, EnableLongPress, EnableTwoFingerSwipes, EnablePinchSpread, EnableRotate, EnableThreeFingerGestures, EnableFourFingerGestures, EnableFiveFingerGestures, EnableShapeGestures, EnableJoystickOutput.

Numeric thresholds

Property Default Unit
SwipeDistanceThreshold 0.15 0..1 of pad span
SwipeTimeWindowMs 500 ms from touchdown
RadialZoneCount 8 4 / 6 / 8 / 12 (UI restricts)
RadialCenterDeadzone 0.30 0..1
TapTimeWindowMs 350 ms total gesture duration
TapMaxMotion 0.04 0..1 per-finger max delta
MultiTapGapMs 300 ms between taps for double / triple counting
LongPressTimeWindowMs 500 ms hold
LongPressMaxMotion 0.05 0..1, applied to the bounding-box span of the last 25% of the path
TwoFingerSwipeAngularTolerance 25 degrees
PinchThreshold 0.25 relative distance change
RotateThresholdDegrees 20 absolute rotation
GestureMatchThreshold 3.0 $Q distance, lower = stricter

Joystick / D-pad output

EnableJoystickOutput, JoystickMaxRadius, JoystickInnerDeadzone, JoystickDPadMode ("Off" / "FourWay" / "EightWay"), JoystickDPadActivationThreshold. Independent of the gesture-engine master toggle so users who want only stick / D-pad output can leave gestures disabled.

Mouse output

MouseSensitivityX, MouseSensitivityY, MouseInvertX, MouseInvertY. Per-axis sensitivity (0.05..10) and per-axis invert. Applied when a touchpad-finger source is bound to a KBM virtual controller mouse axis.

See Also

  • Architecture Overview: Solution structure, how Engine and App assemblies relate
  • Input Pipeline: 6-step pipeline consuming CustomInputState, Gamepad, PadSetting
  • SDL3 Integration: SDL3 P/Invoke details, SdlDeviceWrapper usage, haptic strategies
  • Virtual Controllers: IVirtualController implementations consuming Gamepad, ExtendedRawState, KbmRawState, MidiRawState
  • Settings and Serialization: PadSetting XML persistence, UserDevice/UserSetting serialization, v3.2 MappingSet / MappingRow / MappingSource / ShiftActivator / MappingSetMigrator DTOs
  • HIDMaestro Deep Dive: HMaestroVirtualController lifecycle, FFB through HM PID descriptors, OpenXInput shim

Clone this wiki locally