Class InputControl

A typed and named value in a hierarchy of controls.

Inheritance

System.Object

InputControl

Namespace: UnityEngine.InputSystem

Syntax

public abstract class InputControl

Remarks

Controls can have children which in turn may have children. At the root of the child hierarchy is always an InputDevice (which themselves are InputControls).

Controls can be looked up by their path (see GetControl(InputControl, String) and TryFindControl(InputControl, String, Int32)).

Each control must have a unique name within its parent (see name). Multiple names can be assigned to controls using aliases (see aliases). Name lookup is case-insensitive.

In addition to names, a control may have usages associated with it (see usages). A usage indicates how a control is meant to be used. For example, a button can be assigned the "PrimaryAction" usage to indicate it is the primary action button the device. Within a device, usages have to be unique. See CommonUsages for a list of standardized usages.

Controls do not actually store values. Instead, every control receives an InputStateBlock which, after the control's device has been added to the system, is used to read out values from the device's backing store. This backing store is referred to as "state" in the API as opposed to "values" which represent the data resulting from reading state. The format that each control stores state in is specific to the control. It can vary not only between controls of different types but also between controls of the same type. An AxisControl, for example, can be stored as a float or as a byte or in a number of other formats. stateBlock identifies both where the control stores its state as well as the format it stores it in.

Constructors

InputControl()

Declaration

protected InputControl()

Fields

m_StateBlock

Declaration

protected InputStateBlock m_StateBlock

Field Value

Type	Description
InputStateBlock

Properties

aliases

Declaration

public ReadOnlyArray<InternedString> aliases { get; }

Property Value

Type	Description
ReadOnlyArray<InternedString>

children

List of immediate children.

Declaration

public ReadOnlyArray<InputControl> children { get; }

Property Value

Type	Description
ReadOnlyArray<InputControl>

Remarks

Does not allocate.

currentStatePtr

Declaration

protected void *currentStatePtr { get; }

Property Value

Type	Description
System.Void*

defaultStatePtr

Declaration

protected void *defaultStatePtr { get; }

Property Value

Type	Description
System.Void*

device

The device that this control is a part of.

Declaration

public InputDevice device { get; }

Property Value

Type	Description
InputDevice

Remarks

This is the root of the control hiearchy. For the device at the root, this will point to itself.

displayName

The text to display as the name of the control.

Declaration

public string displayName { get; protected set; }

Property Value

Type	Description
System.String

Remarks

Note that the display name of a control may change over time. For example, when changing from a QWERTY keyboard layout to an AZERTY keyboard layout, the "q" key (which will keep that name) will change its display name from "q" to "a".

By default, a control's display name will come from its layout. If it is not assigned a display name there, the display name will default to name. However, specific controls may override this behavior. KeyControl, for example, will set the display name to the actual key name corresponding to the current keyboard layout.

For nested controls, the display name will include the display names of all parent controls, i.e. the display name will fully identify the control on the device. For example, the display name for the left D-Pad button on a gamepad is "D-Pad Left" and not just "Left".

Item[String]

Fetch a control from the control's hierarchy by name.

Declaration

public InputControl this[string path] { get; }

Parameters

Type	Name	Description
System.String	path

Property Value

Type	Description
InputControl

Remarks

Note that path matching is case-insensitive.

Examples

gamepad["leftStick"] // Returns Gamepad.leftStick
gamepad["leftStick/x"] // Returns Gamepad.leftStick.x
gamepad["{PrimaryAction}"] // Returns the control with PrimaryAction usage, i.e. Gamepad.aButton

Exceptions

Type	Condition
System.Collections.Generic.KeyNotFoundException	`path` cannot be found.

layout

Layout the control is based on.

Declaration

public string layout { get; }

Property Value

Type	Description
System.String

Remarks

This is the layout name rather than a reference to an InputControlLayout as we only create layout instances during device creation and treat them as temporaries in general so as to not waste heap space during normal operation.

name

The name of the control, i.e. the final name part in its path.

Declaration

public string name { get; }

Property Value

Type	Description
System.String

Remarks

Names of controls must be unique within the context of their parent.

Lookup of names is case-insensitive.

noiseMaskPtr

Declaration

protected void *noiseMaskPtr { get; }

Property Value

Type	Description
System.Void*

noisy

Whether the control is considered noisy.

Declaration

public bool noisy { get; }

Property Value

Type	Description
System.Boolean

Remarks

A control is considered "noisy" if it produces different values without necessarily requiring user interaction. Sensors are a good example.

The value of this property is determined by the layout (InputControlLayout) that the control has been built from.

Note that for devices (InputDevice) this property is true if any control on the device is marked as noisy.

parent

The immediate parent of the control or null if the control has no parent (which, once fully constructed) will only be the case for InputDevices).

Declaration

public InputControl parent { get; }

Property Value

Type	Description
InputControl

path

Full path all the way from the root.

Declaration

public string path { get; }

Property Value

Type	Description
System.String

Remarks

Allocates on first hit. Paths are not created until someone asks for them.

Examples

Example: "/gamepad/leftStick/x"

previousFrameStatePtr

Declaration

protected void *previousFrameStatePtr { get; }

Property Value

Type	Description
System.Void*

shortDisplayName

An alternate, abbreviated displayName (for example "LMB" instead of "Left Button").

Declaration

public string shortDisplayName { get; protected set; }

Property Value

Type	Description
System.String

Remarks

If the control has no abbreviated version, this will be null. Note that this behavior is different from displayName which will fall back to name if not display name has been assigned to the control.

For nested controls, the short display name will include the short display names of all parent controls, i.e. the display name will fully identify the control on the device. For example, the display name for the left D-Pad button on a gamepad is "D-Pad \u2190" and not just "\u2190". Note that if a parent control has no short name, its long name will be used instead.

stateBlock

Declaration

public InputStateBlock stateBlock { get; }

Property Value

Type	Description
InputStateBlock

stateOffsetRelativeToDeviceRoot

The offset of this control's state relative to its device root.

Declaration

protected uint stateOffsetRelativeToDeviceRoot { get; }

Property Value

Type	Description
System.UInt32

Remarks

Once a device has been added to the system, its state block will get allocated in the global state buffers and the offset of the device's state block will get baked into all of the controls on the device. This property always returns the "unbaked" offset.

synthetic

Whether the control is considered synthetic.

Declaration

public bool synthetic { get; }

Property Value

Type	Description
System.Boolean

Remarks

A control is considered "synthetic" if it does not correspond to an actual, physical control on the device. An example for this is anyKey or the up/down/left/right buttons added by StickControl.

The value of this property is determined by the layout (InputControlLayout) that the control has been built from.

usages

Declaration

public ReadOnlyArray<InternedString> usages { get; }

Property Value

Type	Description
ReadOnlyArray<InternedString>

valueSizeInBytes

Size in bytes of values that the control returns.

Declaration

public abstract int valueSizeInBytes { get; }

Property Value

Type	Description
System.Int32

Declaration

public abstract Type valueType { get; }

Property Value

Type	Description
System.Type

Remarks

This is the type of values that are returned when reading the current value of a control or when reading a value of a control from an event.

variants

Semicolon-separated list of variants of the control layout or "default".

Declaration

public string variants { get; }

Property Value

Type	Description
System.String

Examples

"Lefty" when using the "Lefty" gamepad layout.

Methods

CompareState(Void, Void, Void*)

Compare the control's stored state in firstStatePtr to secondStatePtr.

Declaration

public bool CompareState(void *firstStatePtr, void *secondStatePtr, void *maskPtr = default(void *))

Parameters

Type	Name	Description
System.Void*	firstStatePtr	Memory containing the control's stateBlock.
System.Void*	secondStatePtr	Memory containing the control's stateBlock
System.Void*	maskPtr	Optional mask. If supplied, it will be used to mask the comparison between `firstStatePtr` and `secondStatePtr` such that any bit not set in the mask will be ignored even if different between the two states. This can be used, for example, to ignore noise in the state (noiseMaskPtr).

Returns

Type	Description
System.Boolean	True if the state is equivalent in both memory buffers.

Remarks

Unlike CompareValue(Void*, Void*), this method only compares raw memory state. If used on a stick, for example, it may mean that this method returns false for two stick values that would compare equal using CompareValue(Void*, Void*) (e.g. if both stick values fall below the deadzone).

CompareValue(Void, Void)

Compare the value of the control as read from firstStatePtr to that read from secondStatePtr and return true if they are equal.

Declaration

public abstract bool CompareValue(void *firstStatePtr, void *secondStatePtr)

Parameters

Type	Name	Description
System.Void*	firstStatePtr	Memory containing the control's stateBlock.
System.Void*	secondStatePtr	Memory containing the control's stateBlock

Returns

Type	Description
System.Boolean	True if the value of the control is equal in both `firstStatePtr` and `secondStatePtr`.

Remarks

Unlike CompareState(Void*, Void*, Void*), this method will have to do more than just compare the memory for the control in the two state buffers. It will have to read out state for the control and run the full processing machinery for the control to turn the state into a final, processed value. CompareValue is thus more costly than CompareState(Void*, Void*, Void*).

This method will apply epsilons () when comparing floats.

EvaluateMagnitude()

Compute an absolute, normalized magnitude value that indicates the extent to which the control is actuated.

Declaration

public float EvaluateMagnitude()

Returns

Type	Description
System.Single	Amount of actuation of the control or -1 if it cannot be determined.

Remarks

Magnitudes do not make sense for all types of controls. For example, for a control that represents an enumeration of values (such as PointerPhaseControl), there is no meaningful linear ordering of values (one could derive a linear ordering through the actual enum values but their assignment may be entirely arbitrary; it is unclear whether a state of Canceled has a higher or lower "magnitude" as a state of Began).

Controls that have no meaningful magnitude will return -1 when calling this method. Any negative return value should be considered an invalid value.

Declaration

public virtual float EvaluateMagnitude(void *statePtr)

Parameters

Type	Name	Description
System.Void*	statePtr	State containing the control's stateBlock.

Returns

Type	Description
System.Single	Amount of actuation of the control or -1 if it cannot be determined.

FinishSetup(InputDeviceBuilder)

Declaration

protected virtual void FinishSetup(InputDeviceBuilder builder)

Parameters

Type	Name	Description
InputDeviceBuilder	builder

ReadValueFromBufferAsObject(Void*, Int32)

Declaration

public abstract object ReadValueFromBufferAsObject(void *buffer, int bufferSize)

Parameters

Type	Name	Description
System.Void*	buffer
System.Int32	bufferSize

Returns

Type	Description
System.Object

ReadValueFromStateAsObject(Void*)

Read the control's final, processed value from the given state and return the value as an object.

Declaration

public abstract object ReadValueFromStateAsObject(void *statePtr)

Parameters

Type	Name	Description
System.Void*	statePtr

Returns

Type	Description
System.Object	The control's value as stored in `statePtr`.

Remarks

This method allocates GC memory and should not be used during normal gameplay operation.

Exceptions

Type	Condition
System.ArgumentNullException	`statePtr` is null.

ReadValueFromStateIntoBuffer(Void, Void, Int32)

Read the control's final, processed value from the given state and store it in the given buffer.

Declaration

public abstract void ReadValueFromStateIntoBuffer(void *statePtr, void *bufferPtr, int bufferSize)

Parameters

Type	Name	Description
System.Void*	statePtr	State to read the value for the control from.
System.Void*	bufferPtr	Buffer to store the value in.
System.Int32	bufferSize	Size of `bufferPtr` in bytes. Must be at least valueSizeInBytes. If it is smaller, System.ArgumentException will be thrown.

Exceptions

Type	Condition
System.ArgumentNullException	`statePtr` is null, or `bufferPtr` is null.
System.ArgumentException	`bufferSize` is smaller than valueSizeInBytes.

RefreshConfiguration()

Declaration

protected virtual void RefreshConfiguration()

RefreshConfigurationIfNeeded()

Declaration

protected void RefreshConfigurationIfNeeded()

ToString()

Declaration

public override string ToString()

Returns

Type	Description
System.String

Overrides

System.Object.ToString()

TryGetChildControl(String)

Declaration

public InputControl TryGetChildControl(string path)

Parameters

Type	Name	Description
System.String	path

Returns

Type	Description
InputControl

WriteValueFromBufferIntoState(Void, Int32, Void)

Read a value from the given memory and store it as state.

Declaration

public virtual void WriteValueFromBufferIntoState(void *bufferPtr, int bufferSize, void *statePtr)

Parameters

Type	Name	Description
System.Void*	bufferPtr	Memory containing value.
System.Int32	bufferSize	Size of `bufferPtr` in bytes. Must be at least valueSizeInBytes.
System.Void*	statePtr	State containing the control's stateBlock. Will receive the state as converted from the given value.

Remarks

Writing values will NOT apply processors to the given value. This can mean that when reading a value from a control after it has been written to its state, the resulting value differs from what was written.

Exceptions

Type	Condition
System.NotSupportedException	The control does not support writing. This is the case, for example, that compute values (such as the magnitude of a vector).

Declaration

public virtual void WriteValueFromObjectIntoState(object value, void *statePtr)

Parameters

Type	Name	Description
System.Object	value	Value for the control.
System.Void*	statePtr	State containing the control's stateBlock. Will receive the state state as converted from the given value.

Remarks

Exceptions

Type	Condition
System.NotSupportedException	The control does not support writing. This is the case, for example, that compute values (such as the magnitude of a vector).