Struct InputDeviceDescription

Metadata for an input device.

Namespace: UnityEngine.InputSystem.Layouts

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, Nullable<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

WithDeviceClass(String, Boolean)

empty

Whether any of the properties in the description are set.

Declaration

public bool empty { get; }

Property Value

Type	Description
Boolean	True if any of interfaceName, deviceClass, manufacturer, product, serial, version, or capabilities is not null and not empty..

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.

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

WithManufacturer(String, Boolean)

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

WithProduct(String, Boolean)

serial

If available, serial number for the device.

Declaration

public string serial { get; set; }

Property Value

Type	Description
String	Serial number of device.

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

WithVersion(String, Boolean)

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
Boolean	True if obj is an InputDeviceDescription equivalent to this one.

Overrides

ValueType.Equals(Object)

See Also

Equals(InputDeviceDescription)

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

Implements

IEquatable<T>.Equals(T)

Remarks

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

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

ToJson()

GetHashCode()

Compute a hash code for the device description.

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32	A hash code.

Overrides

ValueType.GetHashCode()

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

FromJson(String)

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

ValueType.ToString()

Operators

Equality(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
Boolean	True if the two descriptions are equivalent.

See Also

Equals(InputDeviceDescription)

Inequality(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
Boolean	True if the two descriptions are not equivalent.

See Also

Equals(InputDeviceDescription)

See Also

description

InputDeviceMatcher