Skip to content

Linux: support Xbox Impulse Triggers #109

Description

@ReenigneArcher

Environment

  • Host OS: CachyOS Linux
  • Backend: Linux uinput/evdev
  • Virtual profile: Xbox Series
  • Test application: SDL3 testcontroller

Observed behavior

The SDL3 controller tester opens the virtual controller through an evdev node
and reports ordinary rumble support, but not trigger-rumble support:

Opened gamepad Xbox Series X Controller, ... /dev/input/event23
Rumble supported

The tester maps the physical trigger axes to ordinary two-motor rumble and maps
stick movement to SDL_RumbleGamepadTriggers(). Pulling either trigger past
halfway therefore activates ordinary rumble as expected, but moving the sticks
does not activate the independent trigger motors.

This is not primarily a tester bug. SDL's Linux evdev backend implements
ordinary rumble but returns unsupported from its trigger-rumble entry point.
The tester currently does not surface that failed trigger-rumble call to the
user.

libvirtualhid currently routes Xbox One and Xbox Series profiles through its
Linux uinput gamepad implementation. That path advertises standard evdev force
feedback and normalizes it to the public ordinary-rumble callback, but it has no
transport for independent left/right trigger-motor values. The existing Xbox
output-report parser can decode a native four-motor payload, but that parser is
not reached through the uinput/evdev path.

Relevant upstream implementations:

Expected behavior

Xbox One and Xbox Series virtual controllers should support Microsoft Impulse
Triggers on Linux when the consuming application requests separate left and
right trigger-motor vibration. The output callback should receive a
GamepadOutputKind::trigger_rumble event with the requested values.

Proposed direction

  1. Investigate representing Xbox One and Xbox Series through a Linux UHID path
    that SDL recognizes through its Xbox HIDAPI/GIP implementation, including
    the required descriptor, transport identity, initialization, and report
    framing.
  2. If UHID cannot enter the appropriate SDL driver path, investigate another
    user-mode Linux transport capable of carrying four independent motor values.
  3. Keep the public C++ API platform-neutral and report trigger-rumble support as
    unavailable when the selected backend cannot deliver it.
  4. Make trigger-rumble support explicit and backend-aware in the public profile
    capability reporting instead of relying only on the general rumble flag.

Merely advertising another evdev force-feedback effect is not sufficient unless
applications can reliably address the independent trigger motors through a
standard consumer API.

Acceptance criteria

  • SDL3 testcontroller reports Trigger rumble supported for virtual Xbox One
    and Xbox Series controllers on Linux.
  • Moving each stick in testcontroller independently produces the corresponding
    left or right GamepadOutputKind::trigger_rumble value.
  • Pulling the physical triggers in the tester continues to exercise ordinary
    two-motor rumble.
  • Standard buttons, sticks, D-pad, analog triggers, Guide, and ordinary rumble
    continue to work through Steam, SDL, and evdev consumers.
  • Automated tests cover Linux backend capability reporting and the independent
    trigger-motor output path.
  • Documentation distinguishes the Windows and Linux host behavior until the
    Linux implementation is validated.

Non-goals

  • Do not add a custom kernel-mode driver.
  • Do not expose Linux transport details through the public, platform-neutral
    C++ API.

Metadata

Metadata

Labels

No labels
No labels

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions