docs: add end-user gamepad guide

Adds a new end-user-facing guide covering the streaming input path, controller setup, Sunshine configuration, client-specific compatibility observations, troubleshooting by symptom, and how to report problems. Links the guide from README.md, docs/usage.md, and Doxyfile.

Author: ReenigneArcher

README.md

@@ -87,6 +87,8 @@ More complete examples live in `examples/`, including the streaming-host-oriente
 
 ## 📚 Documentation
 
+- [End-user gamepad guide](docs/end-user-gamepad-guide.md): Sunshine and Moonlight setup, feature caveats,
+  troubleshooting, and controller support references.
 - [Usage and API](docs/usage.md): CMake consumption, build options, public API overview, profiles, and examples.
 - [Platform support](docs/platform-support.md): backend capability model, Windows, Linux, macOS,
   and Linux permission setup.
@@ -119,12 +121,6 @@ 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.
 

docs/Doxyfile

@@ -37,6 +37,7 @@ WARN_IF_UNDOCUMENTED = YES
 # files and directories to process
 USE_MDFILE_AS_MAINPAGE = ../README.md
 INPUT = ../README.md \
+        end-user-gamepad-guide.md \
         usage.md \
         platform-support.md \
         windows-driver.md \

docs/end-user-gamepad-guide.md

@@ -68,19 +68,14 @@ Xbox One uses the native eight-byte PID payload exposed by the Windows Xbox HID
 stack. Xbox Series keeps the `0x045E:0x0B12` identity, release `0x0509`, and the
 `0x045E:0x0B12&IG_00` XInputHID match ID observed from physical Xbox Series USB
 and Xbox Wireless Adapter connections. The VHF device preserves the native
-17-byte GIP-shaped input report, including Share/Misc as button bit 12, and the
-native eight-byte four-motor rumble payload. Steam maps physical Xbox Series
-USB, Bluetooth, and Wireless Adapter transports through its Xbox HIDAPI path
-with Share as `misc1:b11`; the Windows VHF Xbox Series child does not follow that
-same consumer path or guarantee registration as an XInput slot. A Steam-visible
-Xbox Series Share button on Windows requires a non-VHF Xbox HIDAPI/GIP
-transport. The public Xbox Series profile remains `0x045E:0x0B12`; the Windows
-transport applies the captured release at device creation. Xbox One accepts
-native HID rumble writes. The Xbox Series report parser accepts the native
-eight-byte four-motor payload when a consumer delivers it, applies its
-actuator-enable mask and duration field, and reports the body motors as
-normalized low/high-frequency rumble and the independent trigger motors as
-trigger-rumble output.
+17-byte GIP-shaped input report and native eight-byte four-motor rumble payload.
+The public Xbox Series profile remains `0x045E:0x0B12`; the Windows transport
+applies the captured release at device creation. Xbox One accepts native HID
+rumble writes. The Xbox Series report parser accepts the native eight-byte
+four-motor payload when a consumer delivers it, applies its actuator-enable
+mask and duration field, and reports the body motors as normalized
+low/high-frequency rumble and the independent trigger motors as trigger-rumble
+output.
 
 The VHF driver answers the calibration, pairing, and firmware feature reports
 used to initialize DualShock 4 and DualSense HIDAPI output. It also answers the

docs/platform-support.md

@@ -4,47 +4,6 @@ This page tracks known compatibility work that is larger than a small report
 packing fix. Keep entries here until the repo has a validated implementation
 path and consumer tests or manual validation prove the behavior.
 
-## Windows Xbox Series Share Button in Steam
-
-Status: unresolved for the Windows VHF backend.
-
-The Windows Xbox Series profile currently preserves the native 17-byte
-GIP-shaped input report, including Share/Misc as button bit 12, and uses the
-captured `VID_045E&PID_0B12` release `0x0509` identity. Browser HID testers can
-see the virtual HID device, but Steam's controller tester still does not expose
-the Share button.
-
-The blocking issue is Steam's input path selection. Physical Xbox Series USB,
-Bluetooth, and Xbox Wireless Adapter controllers enter Steam's Xbox HIDAPI path
-and map Share as `misc1:b11`. The VHF-created Windows HID child is consumed
-through the Windows XInput path instead. XInput exposes the standard Xbox button
-set only and has no Share/Misc button. SDL's Xbox HIDAPI driver also rejects the
-Windows `\\?\HID#` fake endpoints used for XGIP controllers, so changing only
-the VHF HID descriptor cannot force Steam into the same path used by physical
-Xbox Series transports.
-
-Proposed solution:
-
-1. Add a separate Windows Xbox transport that is not a VHF HID child and can be
-   accepted by Steam's Xbox HIDAPI/GIP path.
-2. Model the transport on captured physical Xbox Series USB, Bluetooth, and
-   Xbox Wireless Adapter device trees, including the parent transport identity,
-   interface class, compatible IDs, report initialization behavior, and output
-   report routing.
-3. Keep the existing VHF Xbox Series path as the user-mode compatibility path
-   until the new transport is implemented and validated.
-4. Validate with Steam controller logs and the Steam controller tester before
-   claiming Share support. Required proof is a Steam mapping containing
-   `misc1:b11` for the virtual device and working normal buttons, triggers,
-   D-pad, Guide, and rumble.
-
-Non-goals for this item:
-
-- Do not add a kernel-mode driver to the normal C++ library.
-- Do not keep trying descriptor-only VHF remaps for Steam Share support.
-- Do not change the public platform-neutral profile API for a Windows-specific
-  transport limitation.
-
 ## Controller Capture Tooling
 
 Status: proposed.

docs/todo.md

@@ -3,6 +3,9 @@
 This page covers how consumers bring `libvirtualhid` into a CMake project and
 which public API concepts they should build around.
 
+If you use Sunshine or another application that already embeds the library,
+see the [end-user gamepad guide](end-user-gamepad-guide.md) instead.
+
 ## CMake Consumption
 
 The library exports `libvirtualhid::libvirtualhid`.

docs/usage.md

@@ -419,14 +419,9 @@ The built-in Xbox One profile uses its XboxGIP-shaped HID descriptor. The public
 Xbox Series profile remains `VID_045E&PID_0B12`; the Windows transport presents
 it with release `0x0509` and the `VID_045E&PID_0B12&IG_00` XInputHID match ID
 observed from physical Xbox Series USB and Xbox Wireless Adapter connections.
-The VHF child preserves the native 17-byte GIP-shaped input report, including
-Share/Misc as button bit 12, and the report parser accepts the native eight-byte
-four-motor Xbox payload when a consumer delivers it. Physical Xbox Series USB,
-Bluetooth, and Xbox Wireless Adapter transports register in Steam through the
-Xbox HIDAPI path with Share mapped as `misc1:b11`; the VHF child does not follow
-that same consumer path or guarantee registration as an XInput slot. A
-Steam-visible Xbox Series Share button on Windows requires a non-VHF Xbox
-HIDAPI/GIP transport. The Xbox 360 profile is rejected by the UMDF/VHF backend
+The VHF child preserves the native 17-byte GIP-shaped input report, and the
+report parser accepts the native eight-byte four-motor Xbox payload when a
+consumer delivers it. The Xbox 360 profile is rejected by the UMDF/VHF backend
 because a real Xbox 360 controller is an XUSB device rather than a VHF HID
 gamepad.
 
@@ -446,12 +441,6 @@ label because VHF does not provide a product/manufacturer string callback.
 
 ### Current Release Limits
 
-- Steam does not expose the Xbox Series Share button from the VHF child through
-  the same Xbox HIDAPI path used by physical controllers. Supporting 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 Microsoft dashboard signing path that is not part of the
   current Azure Trusted Signing workflow.