Skip to content

streaming-host-integration.md

Latest commit

 

History

History
60 lines (48 loc) · 2.69 KB

streaming-host-integration.md

File metadata and controls

60 lines (48 loc) · 2.69 KB
Raw

Streaming-Host Integration

Remote streaming hosts are the first consumer class for libvirtualhid. Integration should preserve a host application's existing network protocol, client input parsing, configuration, feedback queue, and device lifecycle while moving local virtual device creation behind the libvirtualhid API.

Integration Contract

A streaming host should be able to:

  • Create stable per-client gamepad handles with both client-relative and global indexes.
  • Submit incremental button, axis, trigger, touchpad, motion, and battery updates without recreating a device.
  • Receive output callbacks for rumble, LEDs, adaptive triggers, trigger rumble, and raw output reports where the selected profile supports them.
  • Query profile and backend capabilities before warning users about unsupported client features.
  • Read device nodes and platform paths when a downstream consumer or diagnostic needs to inspect SDL, HIDAPI, libinput, hidraw, or system device state.
  • Use keyboard and mouse APIs for relative mouse, absolute mouse, buttons, wheel, horizontal wheel, key events, and Unicode text input.

libvirtualhid should not own the host application's network transport, packet schema, configuration model, controller assignment policy, or status API.

Adapter Pattern

The examples/gamepad_adapter.cpp example demonstrates the intended shape:

  • Choose a built-in DeviceProfile from a host-facing profile name.
  • Fill CreateGamepadOptions with stable controller metadata.
  • Create a GamepadStateAdapter from a Runtime.
  • Cache state inside the adapter as separate input events arrive.
  • Submit an initial neutral report so operating-system consumers can enumerate the virtual controller before the first client input packet.
  • Forward output callbacks back to the physical client controller or feedback queue.

This keeps one public code path for Linux, Windows, and future platforms while still letting each backend report real capability limits.

Current Readiness

The core API and adapter shape cover the major streaming-host requirements:

  • Multiple controller lifecycles.
  • Built-in profiles for common controller classes.
  • Rich controller metadata.
  • Gamepad output callbacks.
  • Keyboard and mouse input paths.
  • Linux PlayStation gamepads through uhid, Generic/Xbox/Switch Pro gamepads through uinput, and uinput keyboard/pointer devices.
  • Linux DualSense and DualShock 4 USB/Bluetooth report handling.
  • Linux touchscreen, trackpad, and pen tablet device types.
  • FreeBSD uinput gamepads and pointer devices, with basic PlayStation input and rumble but without Linux UHID-only PlayStation features.
  • Windows UMDF/VHF gamepad creation through an installed driver package.