Skip to content

Commit 9520ecf

Browse files
jechterjechter
authored
Supported hid usages (#826)
* Replace shouldCreateHID with supportedHIDUsages * docs * changelog * Store usages in backing array * make backing array private
2 parents f60ac4f + 15d0091 commit 9520ecf

File tree

5 files changed

+72
-27
lines changed

5 files changed

+72
-27
lines changed

‎Assets/Tests/InputSystem/Plugins/HIDTests.cs‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ public void Devices_CanCreateGenericHID()
7979

8080
[Test]
8181
[Category("Devices")]
82-
public void Devices_DevicesNotAllowedByShouldCreateHIDAreSkipped()
82+
public void Devices_DevicesNotAllowedBySupportedHIDUsagesAreSkipped()
8383
{
8484
var hidDescriptor = new HID.HIDDeviceDescriptor
8585
{
@@ -107,10 +107,9 @@ public void Devices_DevicesNotAllowedByShouldCreateHIDAreSkipped()
107107
Assert.That(InputSystem.devices, Has.Count.EqualTo(0));
108108
Assert.That(InputSystem.GetDeviceById(deviceId), Is.Null);
109109

110-
HIDSupport.shouldCreateHID += descriptor =>
111-
descriptor.usagePage == (HID.UsagePage) 5678 && descriptor.usage == 1234
112-
? true
113-
: (bool?)null;
110+
HIDSupport.supportedHIDUsages = new ReadOnlyArray<HIDSupport.HIDPageUsage>(
111+
new[] {new HIDSupport.HIDPageUsage((HID.UsagePage) 5678, 1234)}
112+
);
114113

115114
runtime.ReportNewInputDevice(descriptionJson, deviceId);
116115
InputSystem.Update();

‎Packages/com.unity.inputsystem/CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@ however, it has to be formatted properly to pass verification tests.
1919
- Pending timeouts on a device not being removed when device was removed.
2020

2121
### Changed
22+
23+
- Replaced `HIDSupport.shouldCreateHID` event with a new `HIDSupport.supportedHIDUsages` property, which takes an array of supported usages.
24+
2225
### Added
2326

2427
#### Actions

‎Packages/com.unity.inputsystem/Documentation~/HID.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ HIDs are handled in one of two ways:
1515

1616
## Auto-generated layouts
1717

18-
By default, the input system will create layouts and device representations for any HID which reports it's usage as `GenericDesktop/Joystick`, `GenericDesktop/Gamepad` or `GenericDesktop/MultiAxisController` (see the [HID usage table specifications](https://www.usb.org/document-library/hid-usage-tables-112) for more info). You can override that behavior to support any other device by adding a handler to the [`HIDSupport.shouldCreateHID`](../api/UnityEngine.InputSystem.HID.HIDSupport.html#UnityEngine_InputSystem_HID_HIDSupport_shouldCreateHID) event.
18+
By default, the input system will create layouts and device representations for any HID which reports it's usage as `GenericDesktop/Joystick`, `GenericDesktop/Gamepad` or `GenericDesktop/MultiAxisController` (see the [HID usage table specifications](https://www.usb.org/document-library/hid-usage-tables-112) for more info). You can change the list of supported usages by setting [`HIDSupport.supportedHIDUsages`](../api/UnityEngine.InputSystem.HID.HIDSupport.html#UnityEngine_InputSystem_HID_HIDSupport_supportedHIDUsages).
1919

2020
Nor when the input system automatically create a layouts for a HID, these devices are currently always reported as [`Joysticks`](Joystick.md), represented by the [`Joystick` device class]((../api/UnityEngine.InputSystem.Joystick.html). The first elements with a reported HID usage of `GenericDesktop/X` and `GenericDesktop/Y` together form the joystick's [`stick`](../api/UnityEngine.InputSystem.Joystick.html#UnityEngine_InputSystem_Joystick_stick) control. Then controls are added for all further HID axis or button elements, using the control names reported by the HID specification (which tend to be rather generic). The first control with a HID usage of `Button/Button 1` will be assigned to the joystick's [`trigger`](../api/UnityEngine.InputSystem.Joystick.html#UnityEngine_InputSystem_Joystick_trigger) control.
2121

‎Packages/com.unity.inputsystem/InputSystem/Plugins/HID/HID.cs‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -91,10 +91,7 @@ internal static string OnFindLayoutForDevice(int deviceId, ref InputDeviceDescri
9191
// Read HID descriptor.
9292
var hidDeviceDescriptor = ReadHIDDeviceDescriptor(deviceId, ref description, runtime);
9393

94-
// Check callbacks to see whether we should actually create a device for this specific HID.
95-
// If no callback says yes or one says no, we ignore the device.
96-
if (HIDSupport.s_ShouldCreateHID.All(f => f(hidDeviceDescriptor) != true) ||
97-
HIDSupport.s_ShouldCreateHID.Any(f => f(hidDeviceDescriptor) == false))
94+
if (!HIDSupport.supportedHIDUsages.Contains(new HIDSupport.HIDPageUsage(hidDeviceDescriptor.usagePage, hidDeviceDescriptor.usage)))
9895
return null;
9996

10097
// Determine if there's any usable elements on the device.
@@ -1154,6 +1151,7 @@ public enum GenericDesktop
11541151
Keypad = 0x07,
11551152
MultiAxisController = 0x08,
11561153
TabletPCControls = 0x09,
1154+
AssistiveControl = 0x0A,
11571155
X = 0x30,
11581156
Y = 0x31,
11591157
Z = 0x32,

‎Packages/com.unity.inputsystem/InputSystem/Plugins/HID/HIDSupport.cs‎

Lines changed: 62 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -28,27 +28,67 @@ namespace UnityEngine.InputSystem.HID
2828
/// </remarks>
2929
public static class HIDSupport
3030
{
31-
public static event ShouldCreateHIDCallback shouldCreateHID
31+
/// <summary>
32+
/// A pair of HID usage page and HID usage number.
33+
/// </summary>
34+
/// <remarks>
35+
/// Used to describe a HID usage for the <see cref="supportedHIDUsages"/> property.
36+
/// </remarks>
37+
public struct HIDPageUsage
3238
{
33-
add => s_ShouldCreateHID.Append(value);
34-
remove => s_ShouldCreateHID.Remove(value);
35-
}
39+
/// <summary>
40+
/// The usage page.
41+
/// </summary>
42+
public HID.UsagePage page;
3643

37-
internal static InlinedArray<ShouldCreateHIDCallback> s_ShouldCreateHID;
44+
/// <summary>
45+
/// A number specifying the usage on the usage page.
46+
/// </summary>
47+
public int usage;
3848

39-
private static bool? DefaultShouldCreateHIDCallback(HID.HIDDeviceDescriptor descriptor)
40-
{
41-
if (descriptor.usagePage == HID.UsagePage.GenericDesktop)
49+
/// <summary>
50+
/// Create a HIDPageUsage struct by specifying a page and usage.
51+
/// </summary>
52+
public HIDPageUsage(HID.UsagePage page, int usage)
4253
{
43-
switch (descriptor.usage)
44-
{
45-
case (int)HID.GenericDesktop.Joystick:
46-
case (int)HID.GenericDesktop.Gamepad:
47-
case (int)HID.GenericDesktop.MultiAxisController:
48-
return true;
49-
}
54+
this.page = page;
55+
this.usage = usage;
56+
}
57+
58+
/// <summary>
59+
/// Create a HIDPageUsage struct from the GenericDesktop usage page by specifying the usage.
60+
/// </summary>
61+
public HIDPageUsage(HID.GenericDesktop usage)
62+
{
63+
this.page = HID.UsagePage.GenericDesktop;
64+
this.usage = (int)usage;
5065
}
51-
return null;
66+
}
67+
68+
private static HIDPageUsage[] s_SupportedHIDUsages;
69+
70+
/// <summary>
71+
/// An array of HID usages the input is configured to support.
72+
/// </summary>
73+
/// <remarks>
74+
/// The input system will only create <see cref="InputDevice"/>s for HIDs with usages
75+
/// listed in this array. Any other HID will be ignored. This saves the input system from
76+
/// spending resources on creating layouts and devices for HIDs which are not supported or
77+
/// not usable for game input.
78+
///
79+
/// By default, this includes only <see cref="HID.GenericDesktop.Joystick"/>,
80+
/// <see cref="HID.GenericDesktop.Gamepad"/> and <see cref="HID.GenericDesktop.MultiAxisController"/>,
81+
/// but you can set this property to include any other HID usages.
82+
///
83+
/// Note that currently on macOS, the only HID usages which can be enabled are
84+
/// <see cref="HID.GenericDesktop.Joystick"/>, <see cref="HID.GenericDesktop.Gamepad"/>,
85+
/// <see cref="HID.GenericDesktop.MultiAxisController"/>, <see cref="HID.GenericDesktop.TabletPCControls"/>,
86+
/// and <see cref="HID.GenericDesktop.AssistiveControl"/>.
87+
/// </remarks>
88+
public static ReadOnlyArray<HIDPageUsage> supportedHIDUsages
89+
{
90+
get => s_SupportedHIDUsages;
91+
set => s_SupportedHIDUsages = value.ToArray();
5292
}
5393

5494
/// <summary>
@@ -61,7 +101,12 @@ public static event ShouldCreateHIDCallback shouldCreateHID
61101
#endif
62102
static void Initialize()
63103
{
64-
s_ShouldCreateHID.Append(DefaultShouldCreateHIDCallback);
104+
s_SupportedHIDUsages = new[]
105+
{
106+
new HIDPageUsage(HID.GenericDesktop.Joystick),
107+
new HIDPageUsage(HID.GenericDesktop.Gamepad),
108+
new HIDPageUsage(HID.GenericDesktop.MultiAxisController),
109+
};
65110

66111
InputSystem.RegisterLayout<HID>();
67112
InputSystem.onFindLayoutForDevice += HID.OnFindLayoutForDevice;

0 commit comments

Comments
 (0)