Class InputControl
A typed and named source of input values in a hierarchy of controls.
Namespace: UnityEngine .InputSystem
Assembly: Unity.InputSystem.dll
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 Input
Controls can be looked up by their path (see Try
Each control must have a unique name within the children of its parent. Multiple names can be assigned to controls using aliases (see aliases). Name lookup is case-insensitive.
For display purposes, a control may have a separate display
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 Common
Controls do not actually store values. Instead, every control receives an Input
Controls are generally not created directly but are created internally by the input system
from data known as "layouts" (see Input
Each control has a single, fixed value type. The type can be queried at runtime using
value
The following example demonstrates various common operations performed on input controls:
// Look up dpad/up control on current gamepad.
var dpadUpControl = Gamepad.current["dpad/up"];
// Look up the back button on the current gamepad.
var backButton = Gamepad.current["{Back}"];
// Look up all dpad/up controls on all gamepads in the system.
using (var controls = InputSystem.FindControls("<Gamepad>/dpad/up"))
Debug.Log($"Found {controls.Count} controls");
// Display the value of all controls on the current gamepad.
foreach (var control in Gamepad.current.allControls)
Debug.Log(controls.ReadValueAsObject());
// Track the value of the left stick on the current gamepad over time.
var leftStickHistory = new InputStateHistory(Gamepad.current.leftStick);
leftStickHistory.Enable();
Constructors
InputControl()
Declaration
protected InputControl()
See Also
Fields
m_StateBlock
Declaration
protected InputStateBlock m_StateBlock
Field Value
Type | Description |
---|---|
Input |
See Also
Properties
this[string]
Fetch a control from the control's hierarchy by name.
Declaration
public InputControl this[string path] { get; }
Parameters
Type | Name | Description |
---|---|---|
string | path |
Property Value
Type | Description |
---|---|
Input |
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, that is, Gamepad.aButton
Exceptions
Type | Condition |
---|---|
Key |
|
See Also
aliases
Declaration
public ReadOnlyArray<InternedString> aliases { get; }
Property Value
Type | Description |
---|---|
Read |
See Also
children
List of immediate children.
Declaration
public ReadOnlyArray<InputControl> children { get; }
Property Value
Type | Description |
---|---|
Read |
Remarks
Does not allocate.
See Also
currentStatePtr
Declaration
protected void* currentStatePtr { get; }
Property Value
Type | Description |
---|---|
void* |
See Also
defaultStatePtr
Declaration
protected void* defaultStatePtr { get; }
Property Value
Type | Description |
---|---|
void* |
See Also
device
The device that this control is a part of.
Declaration
public InputDevice device { get; }
Property Value
Type | Description |
---|---|
Input |
Remarks
This is the root of the control hierarchy. For the device at the root, this will point to itself.
See Also
displayName
The text to display as the name of the control.
Declaration
public string displayName { get; protected set; }
Property Value
Type | Description |
---|---|
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. Key
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".
See Also
layout
Layout the control is based on.
Declaration
public string layout { get; }
Property Value
Type | Description |
---|---|
string |
Remarks
This is the layout name rather than a reference to an Input
See Also
magnitude
Compute an absolute, normalized magnitude value that indicates the extent to which the control
is actuated. Shortcut for Evaluate
Declaration
public float magnitude { get; }
Property Value
Type | Description |
---|---|
float | Amount of actuation of the control or -1 if it cannot be determined. |
See Also
name
The name of the control, i.e. the final name part in its path.
Declaration
public string name { get; }
Property Value
Type | Description |
---|---|
string |
Remarks
Names of controls must be unique within the context of their parent.
Note that this is the name of the control as assigned internally (like "buttonSouth")
and not necessarily a good display name. Use display
Lookup of names is case-insensitive.
This is set from the name of the control in the layout.
See Also
noiseMaskPtr
Return the memory that holds the noise mask for the control.
Declaration
protected void* noiseMaskPtr { get; }
Property Value
Type | Description |
---|---|
void* | Noise bit mask for the control. |
Remarks
Like with all state blocks, the specific memory block for the control is found at the memory
region specified by state
The noise mask can be overlaid as a bit mask over the state for the control. When doing so, all state that is noise will be masked out whereas all state that isn't will come through unmodified. In other words, any bit that is set in the noise mask indicates that the corresponding bit in the control's state memory is noise.
See Also
noisy
Whether the control is considered noisy.
Declaration
public bool noisy { get; }
Property Value
Type | Description |
---|---|
bool | True if the control produces noisy input. |
Remarks
A control is considered "noisy" if it produces different values without necessarily requiring user interaction. A good example are sensors (see Sensor). For example, the PS4 controller which has a gyroscope sensor built into the device. Whereas sticks and buttons on the device require user interaction to produce non-default values, the gyro will produce varying values even if the device just sits there without user interaction.
The value of this property is determined by the layout (Input
Note that for devices (Input
The primary effect of being noise is on MakeApplication.runInBackground
is true and the device the control belongs to is marked as can
See Also
optimizedControlDataType
For some types of control you can safely read/write state memory directly which is much faster than calling ReadUnprocessedValueFromState/WriteValueIntoState. This method returns a type that you can use for reading/writing the control directly, or it returns InputStateBlock.kFormatInvalid if it's not possible for this type of control.
Declaration
public FourCC optimizedControlDataType { get; }
Property Value
Type | Description |
---|---|
Four |
Remarks
For example, AxisControl might be a "float" in state memory, and if no processing is applied during reading (e.g. no invert/scale/etc), then you could read it as float in memory directly without calling ReadUnprocessedValueFromState, which is faster. Additionally, if you have a Vector3Control which uses 3 AxisControls as consecutive floats in memory, you can cast the Vector3Control state memory directly to Vector3 without calling ReadUnprocessedValueFromState on x/y/z axes.
The value returned for any given control is computed automatically by the Input System, when the control's setup configuration changes. Calculate
See Also
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 |
---|---|
Input |
See Also
path
Full path all the way from the root.
Declaration
public string path { get; }
Property Value
Type | Description |
---|---|
string |
Remarks
This will always be the "effective" path of the control, i.e. it will not contain
elements such as usages ("{Back}"
) and other elements that can be part of
control paths used for matching. Instead, this property will always be a simple
linear ordering of names leading from the device at the top to the control with each
element being separated by a forward slash (/
).
Allocates on first hit. Paths are not created until someone asks for them.
See Also
previousFrameStatePtr
Declaration
protected void* previousFrameStatePtr { get; }
Property Value
Type | Description |
---|---|
void* |
See Also
shortDisplayName
An alternate, abbreviated display
Declaration
public string shortDisplayName { get; protected set; }
Property Value
Type | Description |
---|---|
string |
Remarks
If the control has no abbreviated version, this will be null. Note that this behavior is different
from display
For nested controls, the short display name will include the short display names of all parent controls, that is, 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.
See Also
stateBlock
Declaration
public InputStateBlock stateBlock { get; }
Property Value
Type | Description |
---|---|
Input |
See Also
stateOffsetRelativeToDeviceRoot
The offset of this control's state relative to its device root.
Declaration
protected uint stateOffsetRelativeToDeviceRoot { get; }
Property Value
Type | Description |
---|---|
uint |
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.
See Also
synthetic
Whether the control is considered synthetic.
Declaration
public bool synthetic { get; }
Property Value
Type | Description |
---|---|
bool | True if the control does not represent an actual physical control on the device. |
Remarks
A control is considered "synthetic" if it does not correspond to an actual, physical control on the
device. An example for this is any
The value of this property is determined by the layout (Input
The primary effect of being synthetic is in interactive rebinding (see
Input"<Gamepad>/leftStick/x"
and "<Gamepad>/leftStick/left"
are
suitable picks, "<Gamepad>/leftStick/x"
will be favored as it represents
input from an actual physical control whereas "<Gamepad>/leftStick/left"
represents input from a made-up control. If, however, the "left" button is the only
viable pick, it will be accepted.
See Also
usages
List of usage tags associated with the control.
Declaration
public ReadOnlyArray<InternedString> usages { get; }
Property Value
Type | Description |
---|---|
Read |
Remarks
Usages apply "semantics" to a control. Whereas the name of a control identifies a particular "endpoint" within the control hierarchy, the usages of a control identify particular roles of specific control. A simple example is Back which identifies a control generally used to move backwards in the navigation history of a UI. On a keyboard, it is the escape key that generally fulfills this role whereas on a gamepad, it is generally the "B" / "Circle" button. Some devices may not have a control that generally fulfills this function and thus may not have any control with the "Back" usage.
By looking up controls by usage rather than by name, it is possible to locate the correct control to use for certain standardized situation without having to know the particulars of the device or platform.
// Bind to any control which is tagged with the "Back" usage on any device.
var backAction = new InputAction(binding: "*/{Back}");
Note that usages on devices work slightly differently than usages of controls on devices.
They are also queried through this property but unlike the usages of controls, the set of
usages of a device can be changed dynamically as the role of the device changes. For details,
see Set
See Also
valueSizeInBytes
Size in bytes of values that the control returns.
Declaration
public abstract int valueSizeInBytes { get; }
Property Value
Type | Description |
---|---|
int |
See Also
valueType
Returns the underlying value type of this control.
Declaration
public abstract Type valueType { get; }
Property Value
Type | Description |
---|---|
Type | Type of values produced by the control. |
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.
See Also
variants
Semicolon-separated list of variants of the control layout or "default".
Declaration
public string variants { get; }
Property Value
Type | Description |
---|---|
string |
Examples
"Lefty" when using the "Lefty" gamepad layout.
See Also
Methods
ApplyParameterChanges()
Apply built-in parameters changes (e.g. invert, others), recompute optimized
Declaration
public void ApplyParameterChanges()
See Also
CalculateOptimizedControlDataType()
Calculates and returns a optimized data type that can represent a control's value in memory directly.
The value then is cached in optimized
Declaration
protected virtual FourCC CalculateOptimizedControlDataType()
Returns
Type | Description |
---|---|
Four |
See Also
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 |
---|---|---|
void* | firstStatePtr | Memory containing the control's state |
void* | secondStatePtr | Memory containing the control's state |
Returns
Type | Description |
---|---|
bool | True if the value of the control is equal in both |
Remarks
Unlike Compare
This method will apply epsilons (Epsilon) when comparing floats.
See Also
EvaluateMagnitude()
Compute an absolute, normalized magnitude value that indicates the extent to which the control is actuated.
Declaration
public float EvaluateMagnitude()
Returns
Type | Description |
---|---|
float | 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 Touch
Controls that have no meaningful magnitude will return -1 when calling this method. Any negative return value should be considered an invalid value.
See Also
EvaluateMagnitude(void*)
Compute an absolute, normalized magnitude value that indicates the extent to which the control is actuated in the given state.
Declaration
public virtual float EvaluateMagnitude(void* statePtr)
Parameters
Type | Name | Description |
---|---|---|
void* | statePtr | State containing the control's state |
Returns
Type | Description |
---|---|
float | Amount of actuation of the control or -1 if it cannot be determined. |
See Also
FinishSetup()
Perform final initialization tasks after the control hierarchy has been put into place.
Declaration
protected virtual void FinishSetup()
Remarks
This method can be overridden to perform control- or device-specific setup work. The most common use case is for looking up child controls and storing them in local getters.
public class MyDevice : InputDevice
{
public ButtonControl button { get; private set; }
public AxisControl axis { get; private set; }
protected override void OnFinishSetup()
{
// Cache controls in getters.
button = GetChildControl("button");
axis = GetChildControl("axis");
}
}
See Also
GetChildControl(string)
Declaration
public InputControl GetChildControl(string path)
Parameters
Type | Name | Description |
---|---|---|
string | path |
Returns
Type | Description |
---|---|
Input |
See Also
GetChildControl<TControl>(string)
Declaration
public TControl GetChildControl<TControl>(string path) where TControl : InputControl
Parameters
Type | Name | Description |
---|---|---|
string | path |
Returns
Type | Description |
---|---|
TControl |
Type Parameters
Name | Description |
---|---|
TControl |
See Also
ReadValueFromBufferAsObject(void*, int)
Declaration
public abstract object ReadValueFromBufferAsObject(void* buffer, int bufferSize)
Parameters
Returns
Type | Description |
---|---|
object |
See Also
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 |
---|---|---|
void* | statePtr |
Returns
Type | Description |
---|---|
object | The control's value as stored in |
Remarks
This method allocates GC memory and should not be used during normal gameplay operation.
Exceptions
Type | Condition |
---|---|
Argument |
|
See Also
ReadValueFromStateIntoBuffer(void*, void*, int)
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 |
---|---|---|
void* | statePtr | State to read the value for the control from. |
void* | bufferPtr | Buffer to store the value in. |
int | bufferSize | Size of |
Exceptions
Type | Condition |
---|---|
Argument |
|
Argument |
|
See Also
RefreshConfiguration()
Declaration
protected virtual void RefreshConfiguration()
See Also
RefreshConfigurationIfNeeded()
Call Refresh
Declaration
protected void RefreshConfigurationIfNeeded()
Remarks
This method is only relevant if you are implementing your own devices or new
types of controls which are fetching configuration data from the devices (such
as Key
This method should be called if you are accessing cached data set up by
Refresh
// Let's say your device has an associated orientation which it can be held with
// and you want to surface both as a property and as a usage on the device.
// Whenever your backend code detects a change in orientation, it should send
// a DeviceConfigurationEvent to your device to signal that the configuration
// of the device has changed. You can then implement RefreshConfiguration() to
// read out and update the device orientation on the managed InputDevice instance.
public class MyDevice : InputDevice
{
public enum Orientation
{
Horizontal,
Vertical,
}
private Orientation m_Orientation;
public Orientation orientation
{
get
{
// Call RefreshOrientation if the configuration of the device has been
// invalidated since last time we initialized m_Orientation.
RefreshConfigurationIfNeeded();
return m_Orientation;
}
}
protected override void RefreshConfiguration()
{
// Fetch the current orientation from the backend. How you do this
// depends on your device. Using DeviceCommands is one way.
var fetchOrientationCommand = new FetchOrientationCommand();
ExecuteCommand(ref fetchOrientationCommand);
m_Orientation = fetchOrientation;
// Reflect the orientation on the device.
switch (m_Orientation)
{
case Orientation.Vertical:
InputSystem.RemoveDeviceUsage(this, s_Horizontal);
InputSystem.AddDeviceUsage(this, s_Vertical);
break;
case Orientation.Horizontal:
InputSystem.RemoveDeviceUsage(this, s_Vertical);
InputSystem.AddDeviceUsage(this, s_Horizontal);
break;
}
}
private static InternedString s_Vertical = new InternedString("Vertical");
private static InternedString s_Horizontal = new InternedString("Horizontal");
}
See Also
ToString()
Return a string representation of the control useful for debugging.
Declaration
public override string ToString()
Returns
Type | Description |
---|---|
string | A string representation of the control. |
Overrides
See Also
TryGetChildControl(string)
Try to find a child control matching the given path.
Declaration
public InputControl TryGetChildControl(string path)
Parameters
Type | Name | Description |
---|---|---|
string | path | A control path. See Input |
Returns
Type | Description |
---|---|
Input |
The first direct or indirect child control that matches the given |
Remarks
Note that if the given path matches multiple child controls, only the first control encountered in the search will be returned.
// Returns the leftStick control of the current gamepad.
Gamepad.current.TryGetChildControl("leftStick");
// Returns the X axis control of the leftStick on the current gamepad.
Gamepad.current.TryGetChildControl("leftStick/x");
// Returns the first control ending with "stick" in its name. Note that it
// undetermined whether this is leftStick or rightStick (or even another stick
// added by the given gamepad).
Gamepad.current.TryGetChildControl("*stick");
This method is equivalent to calling Try
Exceptions
Type | Condition |
---|---|
Argument |
|
See Also
TryGetChildControl<TControl>(string)
Declaration
public TControl TryGetChildControl<TControl>(string path) where TControl : InputControl
Parameters
Type | Name | Description |
---|---|---|
string | path |
Returns
Type | Description |
---|---|
TControl |
Type Parameters
Name | Description |
---|---|
TControl |
See Also
WriteValueFromBufferIntoState(void*, int, 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 |
---|---|---|
void* | bufferPtr | Memory containing value. |
int | bufferSize | Size of |
void* | statePtr | State containing the control's state |
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 |
---|---|
Not |
The control does not support writing. This is the case, for example, that compute values (such as the magnitude of a vector). |
See Also
WriteValueFromObjectIntoState(object, void*)
Read a value object and store it as state in the given memory.
Declaration
public virtual void WriteValueFromObjectIntoState(object value, void* statePtr)
Parameters
Type | Name | Description |
---|---|---|
object | value | Value for the control. |
void* | statePtr | State containing the control's state |
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 |
---|---|
Not |
The control does not support writing. This is the case, for example, that compute values (such as the magnitude of a vector). |