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

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

WithInterface(String, Boolean)

WithCapability<TValue>(String, TValue)

WithProduct(String, Boolean)

WithManufacturer(String, Boolean)

WithVersion(String, Boolean)

WithDeviceClass(String, Boolean)

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
Boolean	True if the matcher is equivalent.

See Also

Equals(InputDeviceMatcher)

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.

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

GetHashCode()

Compute a hash code for the device matcher.

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32	A hash code for the matcher.

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.

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

capabilities

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), pattern can be a regular expression.

Returns

Type	Description
InputDeviceMatcher	The modified device matcher with the added pattern.

See Also

deviceClass

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), pattern can be a regular expression.

Returns

Type	Description
InputDeviceMatcher	The modified device matcher with the added pattern.

See Also

interfaceName

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), pattern can be a regular expression.

Returns

Type	Description
InputDeviceMatcher	The modified device matcher with the added pattern.

See Also

manufacturer

WithProduct(String, Boolean)

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.
Boolean	supportRegex	If true (default), pattern can be a regular expression.

Returns

Type	Description
InputDeviceMatcher	The modified device matcher with the added pattern.

See Also

product

WithVersion(String, Boolean)

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.
Boolean	supportRegex	If true (default), pattern can be a regular expression.

Returns

Type	Description
InputDeviceMatcher	The modified device matcher with the added pattern.

See Also

version

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

Equals(InputDeviceMatcher)

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.

See Also

Equals(InputDeviceMatcher)

See Also

InputDeviceDescription

description

RegisterLayoutMatcher(String, InputDeviceMatcher)