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.

Implements
Namespace: UnityEngine.InputSystem.Layouts
Assembly: Unity.InputSystem.dll
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, bool) 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 bool empty { get; }
Property Value
Type Description
bool

Whether the matcher contains any matching patterns.
See Also

patterns

The list of patterns to match.

Declaration
public 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 null.
Returns
Type Description
bool

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
bool

True if the two matchers are equivalent.
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.

See Also

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 deviceDescription exactly.
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.

See Also

GetHashCode()

Compute a hash code for the device matcher.

Declaration
public override int GetHashCode()
Returns
Type Description
int

A hash code for the matcher.
Overrides
See Also

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
float

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);
See Also

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
See Also

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. "elements/count".
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 Mathf.Epsilon. Values are converted between types automatically as needed (meaning that a bool can be compared to a string, for example).
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, bool)

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.
bool supportRegex

If true (default), pattern can be a regular expression.
Returns
Type Description
InputDeviceMatcher

The modified device matcher with the added pattern.
See Also

WithInterface(string, bool)

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.
bool supportRegex

If true (default), pattern can be a regular expression.
Returns
Type Description
InputDeviceMatcher

The modified device matcher with the added pattern.
See Also

WithManufacturer(string, bool)

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.
bool supportRegex

If true (default), pattern can be a regular expression.
Returns
Type Description
InputDeviceMatcher

The modified device matcher with the added pattern.
See Also

WithManufacturerContains(string)

Add a pattern (simple string) to patterns to match a manufacturer.

Declaration
public InputDeviceMatcher WithManufacturerContains(string noRegExPattern)
Parameters
Type Name Description
string noRegExPattern

String to match - simple keyword search in a device manufacturer string (eg "SONY").
Returns
Type Description
InputDeviceMatcher

The modified device matcher with the added pattern.
See Also

WithProduct(string, bool)

Add a pattern to patterns to match a product.

Declaration
public InputDeviceMatcher WithProduct(string pattern, bool supportRegex = true)
Parameters
Type Name Description
string pattern

String to match.
bool supportRegex

If true (default), pattern can be a regular expression.
Returns
Type Description
InputDeviceMatcher

The modified device matcher with the added pattern.
See Also

WithVersion(string, bool)

Add a pattern to patterns to match a version.

Declaration
public InputDeviceMatcher WithVersion(string pattern, bool supportRegex = true)
Parameters
Type Name Description
string pattern

String to match.
bool supportRegex

If true (default), pattern can be a regular expression.
Returns
Type Description
InputDeviceMatcher

The modified device matcher with the added pattern.
See Also

Operators

operator ==(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
bool

True if the two matchers are equivalent.
See Also

operator !=(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
bool

True if the two matchers are not equivalent.
See Also

Implements

See Also