Struct InputDeviceMatcher
Specification that can be matched against an InputDeviceDescription. This is used to find which InputControlLayout to create for a device when it is discovered.
Namespace: UnityEngine.InputSystem.Layouts
Syntax
public struct InputDeviceMatcher : IEquatable<InputDeviceMatcher>
Remarks
Each matcher is basically a set of key/value pairs where each value may either be a regular expression or a plain value object. The central method for testing a given matcher against an InputDeviceDescription is MatchPercentage(InputDeviceDescription).
Various helper methods such as WithInterface(String, Boolean) or WithCapability<TValue>(String, TValue) assist with creating matchers.
// A matcher that matches a PS4 controller by name.
new InputDeviceMatcher()
.WithInterface("HID")
.WithManufacturer("Sony.+Entertainment") // Regular expression
.WithProduct("Wireless Controller"));
// A matcher that matches the same controller by PID and VID.
new InputDeviceMatcher()
.WithInterface("HID")
.WithCapability("vendorId", 0x54C) // Sony Entertainment.
.WithCapability("productId", 0x9CC)); // Wireless controller.
For each registered InputControlLayout in the system that represents a device, arbitrary many matchers can be added. A matcher can be supplied either at registration time or at any point after using RegisterLayoutMatcher(String, InputDeviceMatcher).
// Supply a matcher at registration time.
InputSystem.RegisterLayout<DualShock4GamepadHID>(
matches: new InputDeviceMatcher()
.WithInterface("HID")
.WithCapability("vendorId", 0x54C) // Sony Entertainment.
.WithCapability("productId", 0x9CC)); // Wireless controller.
// Supply a matcher for an already registered layout.
// This can be called repeatedly and will add another matcher
// each time.
InputSystem.RegisterLayoutMatcher<DualShock4GamepadHID>(
matches: new InputDeviceMatcher()
.WithInterface("HID")
.WithManufacturer("Sony.+Entertainment")
.WithProduct("Wireless Controller"));
Properties
empty
If true, the matcher has been default-initialized and contains no matching patterns.
Declaration
public readonly bool empty { get; }
Property Value
Type | Description |
---|---|
Boolean | Whether the matcher contains any matching patterns. |
See Also
patterns
The list of patterns to match.
Declaration
public readonly IEnumerable<KeyValuePair<string, object>> patterns { get; }
Property Value
Type | Description |
---|---|
IEnumerable<KeyValuePair<String, Object>> | List of matching patterns. |
Remarks
Each pattern is comprised of a key and a value. The key determines which part of an InputDeviceDescription to match.
The value represents the expected value. This can be either a plain string (matched case-insensitive) or a regular expression.
See Also
Methods
Equals(Object)
Compare this matcher to another.
Declaration
public override bool Equals(object obj)
Parameters
Type | Name | Description |
---|---|---|
Object | obj | A matcher object or |
Returns
Type | Description |
---|---|
Boolean | True if the matcher is equivalent. |
Overrides
See Also
Equals(InputDeviceMatcher)
Test whether this matcher is equivalent to the other
matcher.
Declaration
public bool Equals(InputDeviceMatcher other)
Parameters
Type | Name | Description |
---|---|---|
InputDeviceMatcher | other | Another device matcher. |
Returns
Type | Description |
---|---|
Boolean | True if the two matchers are equivalent. |
Implements
Remarks
Two matchers are equivalent if they contain the same number of patterns and the same pattern occurs in each of the matchers. Order of the patterns does not matter.
FromDeviceDescription(InputDeviceDescription)
Produce a matcher that matches the given device description verbatim.
Declaration
public static InputDeviceMatcher FromDeviceDescription(InputDeviceDescription deviceDescription)
Parameters
Type | Name | Description |
---|---|---|
InputDeviceDescription | deviceDescription | A device description. |
Returns
Type | Description |
---|---|
InputDeviceMatcher | A matcher that matches |
Remarks
This method can be used to produce a matcher for an existing device description, e.g. when writing a layout InputControlLayout.Builder that produces layouts for devices on the fly.
GetHashCode()
Compute a hash code for the device matcher.
Declaration
public override int GetHashCode()
Returns
Type | Description |
---|---|
Int32 | A hash code for the matcher. |
Overrides
MatchPercentage(InputDeviceDescription)
Return the level of matching to the given deviceDescription
.
Declaration
public float MatchPercentage(InputDeviceDescription deviceDescription)
Parameters
Type | Name | Description |
---|---|---|
InputDeviceDescription | deviceDescription | A device description. |
Returns
Type | Description |
---|---|
Single | A score usually in the range between 0 and 1. |
Remarks
The algorithm computes a score of how well the matcher matches the given description.
Essentially, a matcher that matches every single property that is present (as in
not null
and not an empty string) in deviceDescription
receives
a score of 1, a matcher that matches none a score of 0. Matches that match only a subset
receive a score in-between.
An exception to this are capabilities. Every single match of a capability is counted as one property match and added to the score. This means that matchers that match on multiple capabilities may actually achieve a score >1.
var description = new InputDeviceDescription
{
interfaceName = "HID",
product = "MadeUpDevice",
capabilities = new HID.HIDDeviceDescriptor
{
vendorId = 0xABC,
productId = 0xDEF
}.ToJson()
};
// This matcher will achieve a score of 0.666 (2/3) as it
// matches two out of three available properties.
new InputDeviceMatcher()
.WithInterface("HID")
.WithProduct("MadeUpDevice");
// This matcher will achieve a score of 1 despite not matching
// 'product'. The reason is that it matches two keys in
// 'capabilities'.
new InputDeviceMatcher()
.WithInterface("HID")
.WithCapability("vendorId", 0xABC)
.WithCapability("productId", 0xDEF);
ToString()
Return a string representation useful for debugging. Lists the patterns contained in the matcher.
Declaration
public override string ToString()
Returns
Type | Description |
---|---|
String | A string representation of the matcher. |
Overrides
WithCapability<TValue>(String, TValue)
Add a pattern to patterns to match an individual capability in capabilities.
Declaration
public InputDeviceMatcher WithCapability<TValue>(string path, TValue value)
Parameters
Type | Name | Description |
---|---|---|
String | path | Path to the JSON property using '/' as a separator,
e.g. |
TValue | value | Value to match. This can be a string, a regular expression,
a boolean, an integer, or a float. Floating-point numbers are matched with respect
for |
Returns
Type | Description |
---|---|
InputDeviceMatcher | The modified device matcher with the added pattern. |
Type Parameters
Name | Description |
---|---|
TValue | Type of value to match. |
Remarks
Capabilities are stored as JSON strings in capabilities. A matcher has the ability to match specific properties from the JSON object contained in the capabilities string.
// The description for a HID will usually have a HIDDeviceDescriptor in
// JSON format found on its InputDeviceDescription.capabilities. So, a
// real-world device description could look the equivalent of this:
var description = new InputDeviceDescription
{
interfaceName = "HID",
capabilities = new HID.HIDDeviceDescriptor
{
vendorId = 0x54C,
productId = 0x9CC
}.ToJson()
};
// We can create a device matcher that looks for those to properties
// directly in the JSON object.
new InputDeviceMatcher()
.WithCapability("vendorId", 0x54C)
.WithCapability("productId", 0x9CC);
Properties in nested objects can be referenced by separating properties
with /
and properties in arrays can be indexed with [..]
.
See Also
WithDeviceClass(String, Boolean)
Add a pattern to patterns to match a deviceClass.
Declaration
public InputDeviceMatcher WithDeviceClass(string pattern, bool supportRegex = true)
Parameters
Type | Name | Description |
---|---|---|
String | pattern | String to match. |
Boolean | supportRegex | If true (default), |
Returns
Type | Description |
---|---|
InputDeviceMatcher | The modified device matcher with the added pattern. |
See Also
WithInterface(String, Boolean)
Add a pattern to patterns to match an interfaceName.
Declaration
public InputDeviceMatcher WithInterface(string pattern, bool supportRegex = true)
Parameters
Type | Name | Description |
---|---|---|
String | pattern | String to match. |
Boolean | supportRegex | If true (default), |
Returns
Type | Description |
---|---|
InputDeviceMatcher | The modified device matcher with the added pattern. |
See Also
WithManufacturer(String, Boolean)
Add a pattern to patterns to match a manufacturer.
Declaration
public InputDeviceMatcher WithManufacturer(string pattern, bool supportRegex = true)
Parameters
Type | Name | Description |
---|---|---|
String | pattern | String to match. |
Boolean | supportRegex | If true (default), |
Returns
Type | Description |
---|---|
InputDeviceMatcher | The modified device matcher with the added pattern. |
See Also
WithProduct(String, Boolean)
Declaration
public InputDeviceMatcher WithProduct(string pattern, bool supportRegex = true)
Parameters
Type | Name | Description |
---|---|---|
String | pattern | String to match. |
Boolean | supportRegex | If true (default), |
Returns
Type | Description |
---|---|
InputDeviceMatcher | The modified device matcher with the added pattern. |
See Also
WithVersion(String, Boolean)
Declaration
public InputDeviceMatcher WithVersion(string pattern, bool supportRegex = true)
Parameters
Type | Name | Description |
---|---|---|
String | pattern | String to match. |
Boolean | supportRegex | If true (default), |
Returns
Type | Description |
---|---|
InputDeviceMatcher | The modified device matcher with the added pattern. |
See Also
Operators
Equality(InputDeviceMatcher, InputDeviceMatcher)
Compare two matchers for equivalence.
Declaration
public static bool operator ==(InputDeviceMatcher left, InputDeviceMatcher right)
Parameters
Type | Name | Description |
---|---|---|
InputDeviceMatcher | left | First device matcher. |
InputDeviceMatcher | right | Second device matcher. |
Returns
Type | Description |
---|---|
Boolean | True if the two matchers are equivalent. |
See Also
Inequality(InputDeviceMatcher, InputDeviceMatcher)
Compare two matchers for non-equivalence.
Declaration
public static bool operator !=(InputDeviceMatcher left, InputDeviceMatcher right)
Parameters
Type | Name | Description |
---|---|---|
InputDeviceMatcher | left | First device matcher. |
InputDeviceMatcher | right | Second device matcher. |
Returns
Type | Description |
---|---|
Boolean | True if the two matchers are not equivalent. |