Skip to content

README.md

Latest commit

 

History

History
192 lines (157 loc) · 15.2 KB

README.md

File metadata and controls

192 lines (157 loc) · 15.2 KB
Raw
libvirtualhid icon

libvirtualhid

Cross-platform C++ virtual HID library.

GitHub stars GitHub Workflow Status (CI) Codecov SonarCloud

🎮 Windows Virtual HID Driver License

A license is required to create virtual gamepads with the Windows driver.
This requirement is Windows-only; non-Windows backends do not currently require a license.
Yearly and lifetime options are available.

Buy a Windows license

Overview

ℹ️ About

libvirtualhid provides a platform-neutral C++ API for creating virtual input devices. The primary target is gamepad input for remote streaming hosts and other low-latency applications, with keyboard, mouse, touchscreen, trackpad, and pen tablet support available where the platform backend supports those device types.

Consumers work with portable concepts such as runtimes, device profiles, normalized gamepad state, output callbacks, and device nodes. Platform-specific details such as Linux uhid/uinput or the Windows UMDF/VHF driver package stay behind backend implementations.

🎮 Capabilities

  • Gamepad profiles for generic HID, Xbox 360, Xbox One, Xbox Series, DualShock 4, DualSense, and Nintendo Switch Pro-style controllers.
  • Descriptor-driven PlayStation gamepads through Linux uhid; Generic, Xbox, and Switch Pro gamepads plus keyboard, mouse, touchscreen, trackpad, and pen tablet devices through uinput.
  • Windows gamepads through a user-mode UMDF2 control driver backed by Virtual HID Framework, with keyboard and mouse support through normal Win32 APIs.
  • Output callbacks for profile-specific feedback such as rumble, LEDs, adaptive triggers, and raw HID output reports when available.
  • An optional virtualhid_control native UI tool for creating, removing, controlling, and inspecting test gamepads through the public C++ API.
  • CMake consumption through installed packages, vendored source, add_subdirectory, or FetchContent.

🚀 Quick Start

#include <libvirtualhid/libvirtualhid.hpp>

auto runtime = lvh::Runtime::create();
auto created = runtime->create_gamepad(lvh::profiles::dualsense());
if (!created) {
  return;
}

auto &gamepad = *created.gamepad;
gamepad.set_output_callback([](const lvh::GamepadOutput &output) {
  // Forward rumble, LEDs, adaptive triggers, or raw reports to the client.
});

lvh::GamepadState state;
state.buttons.set(lvh::GamepadButton::a, true);
state.left_stick = {0.25F, -0.5F};
state.right_trigger = 1.0F;

gamepad.submit(state);

More complete examples live in examples/, including the streaming-host-oriented examples/gamepad_adapter.cpp.

📚 Documentation

  • Usage and API: CMake consumption, build options, public API overview, profiles, and examples.
  • Platform support: backend capability model, Windows, Linux, macOS, and Linux permission setup.
  • Windows driver package: UMDF/VHF package build, installation, validation, diagnostics, and signing notes.
  • Streaming-host integration: integration contract.
  • Development: local build/test commands, repository layout, docs generation, and roadmap.
  • TODO: known larger compatibility gaps and proposed solution paths.

🎯 Scope

libvirtualhid owns local virtual device creation and input/output report translation. It does not provide a network protocol, parse client packets, own a consumer application's configuration system, bypass anti-cheat systems, hide devices from the OS, or ship a Windows kernel-mode driver.

📌 Status

Linux and Windows provide virtual-device backends. Linux uses standard user-space kernel interfaces. Windows remains user-mode: the C++ library talks to a UMDF2 control driver, and the driver publishes HID gamepads through VHF. macOS currently provides a limited CoreGraphics synthetic-input backend for keyboard and mouse only. It is not a virtual-HID backend and does not yet support gamepads; native macOS virtual-HID gamepad support is planned.

The library is designed around gamepad use first because remote streaming hosts are the first consumer class. Non-gamepad device types are available through the same API where the backend exposes them.

⚠️ Known Windows Limitations

  • Steam does not expose the Xbox Series Share button from the VHF child through the same Xbox HIDAPI path used by physical controllers. That path requires a non-VHF Xbox HIDAPI/GIP transport.
  • PlayStation and Nintendo rumble parsing is covered by protocol and installed driver tests but has not yet completed broad validation with real client applications.
  • The published Windows driver installer is AMD64-only. Windows ARM64 release packages require a different Microsoft driver-signing path.

🔁 Alternatives

Alternatives exist if libvirtualhid does not meet your needs.

Feature libvirtualhid ViGEmBus HIDMaestro inputtino WinUHid
Windows support ✅ ✅ ✅ ❌ ✅
Linux support ✅ ❌ ❌ ✅ ❌
Windows AMD64 support ✅ ✅ ✅ - ✅
Windows ARM64 support ❌5 ✅ ❌6 - ✅
Windows user-mode driver ✅ ❌ ✅ - ✅
No Windows kernel-mode driver ✅ ❌ ✅ - ✅
Descriptor-defined HID devices ✅ ❌ ✅ ✅1 ✅
Platform-neutral C++ API ✅ ❌2 ❌2 ❌3 ❌2
Keyboard ✅ ❌ ❌ ✅ ✅4
Mouse ✅ ❌ ❌ ✅ ✅4
Touchscreen, trackpad, or pen ✅ ❌ ❌ ✅ ✅4
Generic HID gamepad ✅ ❌ ✅ ❌ ✅4
Xbox 360 gamepad ✅ ✅ ✅ ❌ ✅4
Xbox One gamepad ✅ ❌ ✅ ✅ ✅4
Xbox Series gamepad ✅ ❌ ✅ ❌ ✅4
DualShock 4 gamepad ✅ ✅ ✅ ❌ ✅4
DualSense gamepad ✅ ❌ ✅ ✅ ✅4
Nintendo Switch Pro-style gamepad ✅ ❌ ✅ ✅ ✅4
Rumble or output callbacks ✅ ❌ ✅ ✅ ✅4
Data-driven profiles ❌ ❌ ✅ ❌ ❌
Actively developed ✅ ❌ ✅ ✅ ✅

1 inputtino uses uhid for virtual joypads; its other listed device types use Linux input interfaces rather than generic HID descriptors.

2 Windows-only project, so it does not provide a platform-neutral API surface.

3 Linux-only project, so it does not provide a platform-neutral API surface.

4 WinUHid is a framework-level virtual HID target; support requires a custom HID descriptor and matching report handling rather than a ready-made device profile.

5 libvirtualhid has architecture-aware WiX packaging, but the built Windows driver package target is AMD64 today. Windows ARM64 release driver packages require a Microsoft dashboard signing path, such as WHQL/Hardware Dev Center signing; the current Azure Trusted Signing catalog/MSI flow is not sufficient for ARM64 release driver package installation.

6 HIDMaestro documents a win-x64 test app path and does not currently advertise an ARM64 build.

📄 License

The cross-platform libvirtualhid library is licensed under the MIT License. The Windows UMDF driver, broker, proprietary entitlement/evaluation sources, and generated Windows driver package artifacts, including the driver MSI, are licensed under the LizardByte Source-Available License 1.0 (LB-SAL 1.0). The root license notice points to both complete license texts; see the license map for the authoritative repository path and artifact assignments.