Struct InputDeviceDescription

Metadata for an input device.

Implements
Namespace: UnityEngine.InputSystem.Layouts
Assembly: Unity.InputSystem.dll
Syntax
[Serializable]
public struct InputDeviceDescription : IEquatable<InputDeviceDescription>
Remarks

Device descriptions are mainly used to determine which InputControlLayout to create an actual InputDevice instance from. Each description is comprised of a set of properties that each are individually optional. However, for a description to be usable, at least some need to be set. Generally, the minimum viable description for a device is one with deviceClass filled out.

// Device description equivalent to a generic gamepad with no
// further information about the device.
new InputDeviceDescription
{
    deviceClass = "Gamepad"
};

Device descriptions will usually be supplied by the Unity runtime but can also be manually fed into the system using AddDevice(InputDeviceDescription). The system will remember each device description it has seen regardless of whether it was able to successfully create a device from the description. To query the list of descriptions that for whatever reason did not result in a device being created, call GetUnsupportedDevices().

Whenever layout registrations in the system are changed (e.g. by calling RegisterLayout<T>(string, InputDeviceMatcher?) or whenever supportedDevices is changed, the system will go through the list of unsupported devices itself and figure out if there are device descriptions that now it can turn into devices. The same also applies in reverse; if, for example, a layout is removed that is currently used a device, the device will be removed and its description (if any) will be placed on the list of unsupported devices.

Properties

capabilities

An optional JSON string listing device-specific capabilities.

Declaration
public string capabilities { get; set; }
Property Value
Type Description
string

Interface-specific listing of device capabilities.
Remarks

The primary use of this field is to allow custom layout factories to create layouts on the fly from in-depth device descriptions delivered by external APIs.

In the case of HID, for example, this field contains a JSON representation of the HID descriptor (see HID.HIDDeviceDescriptor) as reported by the device driver. This descriptor contains information about all I/O elements on the device which can be used to determine the control setup and data format used by the device.

See Also
WithCapability<TValue>(string, TValue)

deviceClass

What the interface thinks the device classifies as.

Declaration
public string deviceClass { get; set; }
Property Value
Type Description
string

Broad classification of device.
Remarks

If there is no layout specifically matching a device description, the device class is used as as fallback. If, for example, this field is set to "Gamepad", the "Gamepad" layout is used as a fallback.

See Also

empty

Whether any of the properties in the description are set.

Declaration
public bool empty { get; }
Property Value
Type Description
bool

True if any of interfaceName, deviceClass, manufacturer, product, serial, version, or capabilities is not null and not empty.
See Also

interfaceName

How we talk to the device; usually name of the underlying backend that feeds state for the device (e.g. "HID" or "XInput").

Declaration
public string interfaceName { get; set; }
Property Value
Type Description
string

Name of interface through which the device is reported.
See Also

manufacturer

Name of the vendor that produced the device.

Declaration
public string manufacturer { get; set; }
Property Value
Type Description
string

Name of manufacturer.
See Also

product

Name of the product assigned by the vendor to the device.

Declaration
public string product { get; set; }
Property Value
Type Description
string

Name of product.
See Also

serial

If available, serial number for the device.

Declaration
public string serial { get; set; }
Property Value
Type Description
string

Serial number of device.
See Also

version

Version string of the device and/or driver.

Declaration
public string version { get; set; }
Property Value
Type Description
string

Version of device and/or driver.
See Also

Methods

Equals(object)

Compare the description to the given object.

Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
object obj

An object.
Returns
Type Description
bool

True if obj is an InputDeviceDescription equivalent to this one.
Overrides
See Also

Equals(InputDeviceDescription)

Compare the description to the given other description.

Declaration
public bool Equals(InputDeviceDescription other)
Parameters
Type Name Description
InputDeviceDescription other

Another device description.
Returns
Type Description
bool

True if the two descriptions are equivalent.
Remarks

Two descriptions are equivalent if all their properties are equal (ignore case).

See Also

FromJson(string)

Read an InputDeviceDescription from its JSON representation.

Declaration
public static InputDeviceDescription FromJson(string json)
Parameters
Type Name Description
string json

String in JSON format.
Returns
Type Description
InputDeviceDescription

The converted
Remarks
InputDeviceDescription.FromJson(@"
    {
        ""interface"" : ""HID"",
        ""product"" : ""SomeDevice""
    }
");
Exceptions
Type Condition
ArgumentNullException

json is null.
ArgumentException

There as a parse error in json.
See Also

GetHashCode()

Compute a hash code for the device description.

Declaration
public override int GetHashCode()
Returns
Type Description
int

A hash code.
Overrides
See Also

ToJson()

Return a JSON representation of the device description.

Declaration
public string ToJson()
Returns
Type Description
string

A JSON representation of the description.
Remarks
The result can be converted back into an InputDeviceDescription using FromJson(string). 
var description = new InputDeviceDescription
{
    interfaceName = "HID",
    product = "SomeDevice",
    capabilities = @"
        {
            ""vendorId"" : 0xABA,
            ""productId"" : 0xEFE
        }
    "
};

Debug.Log(description.ToJson());
// Prints
// {
//     "interface" : "HID",
//     "product" : "SomeDevice",
//     "capabilities" : "{ \"vendorId\" : 0xABA, \"productId\" : 0xEFF }"
// }
See Also

ToString()

Return a string representation of the description useful for debugging.

Declaration
public override string ToString()
Returns
Type Description
string

A script representation of the description.
Overrides
See Also

Operators

operator ==(InputDeviceDescription, InputDeviceDescription)

Compare the two device descriptions.

Declaration
public static bool operator ==(InputDeviceDescription left, InputDeviceDescription right)
Parameters
Type Name Description
InputDeviceDescription left

First device description.
InputDeviceDescription right

Second device description.
Returns
Type Description
bool

True if the two descriptions are equivalent.
See Also

operator !=(InputDeviceDescription, InputDeviceDescription)

Compare the two device descriptions for inequality.

Declaration
public static bool operator !=(InputDeviceDescription left, InputDeviceDescription right)
Parameters
Type Name Description
InputDeviceDescription left

First device description.
InputDeviceDescription right

Second device description.
Returns
Type Description
bool

True if the two descriptions are not equivalent.
See Also

Implements

See Also