Re: [w3c/gamepad] Mapping of HID Events to the Gamepad API (#56)

@luser: WebHID now exists and exposes USB and Bluetooth HID gamepads: https://wicg.github.io/webhid/

We can create a getGamepads shim that inserts WebHID-backed gamepads to experiment with exposing HID usage info. Unfortunately the necessary usage info isn't exposed on Windows Chrome yet, but on Mac and Linux the HIDDevice.collections member contains all the data parsed from the HID report descriptor, including usage IDs.

> 1. Spec out an algorithm for taking a HID descriptor and producing a mapping from its elements to the buttons/axes arrays in the Gamepad spec.

As a starting point for discussion I'll describe what we do in Chrome. Button indices are assigned in two passes. We start by assigning indices based on usage IDs in the Button usage page (UP:0009). For instance, the first button usage (UP:0009 U:0001) becomes buttons[0], U:0002 becomes buttons[1], etc. I think this makes the most sense for the majority of HID gamepads. Unfortunately there are gamepads that have non-Button buttons. Chrome inserts these "special" buttons in a second pass using any indices that were unused in the first pass, in order of increasing usage page and usage ID.

Axes are assigned by usage ID, only considering usages from the Generic Desktop page with U:0030 or greater. Generic Desktop X (UP:0001 U:0030) becomes axes[0], Generic Desktop Y (UP:0001 U:0031) becomes axes[1], etc. All axes are assigned in one pass.

Some issues that aren't addressed well by Chrome's implementation:

**Hat switches should have special handling.** Generic Desktop Hat Switch (UP:0001 U:0039) is almost always a 4-bit rotational value with logical range 0 to 7. When no direction is pressed (null state), it reports the out-of-bounds value 8. If we naively scale to the logical range we get an axis value that violates the spec (axes should be in the range [-1,+1]). But if we clip the value, applications can't detect the null state. Probably we should have special handling for mapping an 8-direction hat switch axis to buttons.

**Multiple inputs with the same usage ID.** This is uncommon for HID gamepads but the spec allows it. For instance, instead of using X/Y Z/Rz for the left and right thumbstick axes, a device might use X/Y usages for both. A device can also use the same button ID for multiple button inputs, which is more commonly a sign of a misconfigured report descriptor but is also allowed. Chrome only uses the first input it encounters for each usage ID.

**"Special" gamepad buttons are defined in a hard-coded list:**
Generic Desktop System Main Menu (UP:0001 U:0085), used by some Xbox One gamepads on old firmware over BT
Consumer Power (UP:000C U:0030), used by the Nvidia Shield 2015 gamepad
Consumer Search (UP:000C, U:0221), used by the Nvidia Shield 2017 gamepad
Consumer Home (UP:000C, U:0223), "home button" usage on Android-friendly gamepads
Consumer Back (UP:000C, U:0224), "back button" usage on Android-friendly gamepads

On one hand, it would be nice to expand this to include anything that might be a "special" HID button. On the other, if any HID device with at least one button counts as a gamepad then we should be careful about including usages that aren't typical gamepad button usages. Maybe a gamepad should have at least one Button button before allowing "special" buttons.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/gamepad/issues/56#issuecomment-667438340