Class InputControl

A typed and named source of input values in a hierarchy of controls.

Inheritance

object

InputControl

InputControl<TValue>

InputDevice

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 InputDevice (which themselves are InputControls).

Controls can be looked up by their path (see TryFindControl(InputControl, string, int)).

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 displayName. This name will usually correspond to what the control is caused on the actual underlying hardware. For example, on an Xbox gamepad, the control with the name "buttonSouth" will have a display name of "A". Controls that have very long display names may also have a shortDisplayName. This is the case for the "Left Button" on the Mouse, for example, which is commonly abbreviated "LMB".

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.

Controls are generally not created directly but are created internally by the input system from data known as "layouts" (see InputControlLayout). Each such layout describes the setup of a specific hierarchy of controls. The system internally maintains a registry of layouts and produces devices and controls from them as needed. The layout that a control has been created from can be queried using layout. For most purposes, the intricacies of the control layout mechanisms can be ignored and it is sufficient to know the names of a small set of common device layouts such as "Keyboard", "Mouse", "Gamepad", and "Touchscreen".

Each control has a single, fixed value type. The type can be queried at runtime using valueType. Most types of controls are derived from InputControl<TValue> which has APIs specific to the type of value of the control (e.g. ReadValue().

The following example demonstrates various common operations performed on input controls:

Examples

// 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()

Constructor for the InputControl

Declaration

protected InputControl()

Remarks

Constructor for the InputControl

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

Fields

m_StateBlock

Information about a memory region storing input state.

Declaration

protected InputStateBlock m_StateBlock

Field Value

Type	Description
InputStateBlock

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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	A control path. See InputControlPath.

Property Value

Type	Description
InputControl

Remarks

Note that path matching is case-insensitive. (see InputControlPath). An alternative method is TryGetChildControl(string).

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
KeyNotFoundException	path cannot be found.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

aliases

List of alternate names for the control.

Declaration

public ReadOnlyArray<InternedString> aliases { get; }

Property Value

Type	Description
ReadOnlyArray<InternedString>	List of aliased alternate names for the control. An example of an alias would be 'North' for the 'Triangle' button on a Playstation pad (or 'Y' button on Xbox pad).

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

children

List of immediate child controls below this.

Declaration

public ReadOnlyArray<InputControl> children { get; }

Property Value

Type	Description
ReadOnlyArray<InputControl>

Remarks

Does not allocate. See the related parent field.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

currentStatePtr

The state data buffer for the device.

Declaration

protected void* currentStatePtr { get; }

Property Value

Type	Description
void*	The state data buffer for the device.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

defaultStatePtr

The default state data buffer

Declaration

protected void* defaultStatePtr { get; }

Property Value

Type	Description
void*	Buffer that has state for each device initialized with default values.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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 hierarchy. For the device at the root, this will point to itself (See allControls).

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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

There is a short name version, see shortDisplayName.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

layout

Layout name for the control it 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 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.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

magnitude

Compute an absolute, normalized magnitude value that indicates the extent to which the control is actuated. Shortcut for EvaluateMagnitude().

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

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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 displayName for getting more readable names for display purposes (where available).

Lookup of names is case-insensitive.

This is set from the name of the control in the layout. See path, aliases, name and name.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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

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.

A control can be marked as noisy.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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

The primary effect of being noise is on MakeCurrent() and on interactive rebinding (see InputActionRebindingExtensions.RebindingOperation). However, being noisy also affects automatic resetting of controls that happens when the application loses focus. While other controls are reset to their default value (except if Application.runInBackground is true and the device the control belongs to is marked as canRunInBackground), noisy controls will not be reset but rather remain at their current value. This is based on the assumption that noisy controls most often represent sensor values and snapping the last sampling value back to default will usually have undesirable effects on an application's simulation logic.

See Also

isNoisy

noisy

optimizedControlDataType

The type of the state memory associated with the control.

Declaration

public FourCC optimizedControlDataType { get; }

Property Value

Type	Description
FourCC

Remarks

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 FormatInvalid if it's not possible for this type of control.

For example, AxisControl valueType 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. CalculateOptimizedControlDataType() There are some parameter changes which don't trigger a configuration change (such as the clamp, invert, normalize, and scale parameters on AxisControl), so if you modify these, the optimized data type is not automatically updated. In this situation, you should manually update it by calling ApplyParameterChanges().

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

parent

The immediate parent of the control.

Declaration

public InputControl parent { get; }

Property Value

Type	Description
InputControl	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). See the related children field.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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 ("") 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.

For more details on the path see InputControlPath.

Examples

Example: "/gamepad/leftStick/x"

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

previousFrameStatePtr

The state data buffer for the device from the previous frame.

Declaration

protected void* previousFrameStatePtr { get; }

Property Value

Type	Description
void*	The state data buffer for the device from the previous frame.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

shortDisplayName

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

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 displayName which will fall back to name if no 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, 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 displayName.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

stateBlock

Information about where the control stores its state, such as format, offset and size.

Declaration

public InputStateBlock stateBlock { get; }

Property Value

Type	Description
InputStateBlock

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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 the controls on the device. This property always returns the "unbaked" offset.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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

The primary effect of being synthetic is in interactive rebinding (see InputActionRebindingExtensions.RebindingOperation) where non-synthetic controls will be favored over synthetic ones. This means, for example, that if both "<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.

A control layout will specify if it is synthetic using isSynthetic. See synthetic.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

usages

List of usage tags associated with the control.

Declaration

public ReadOnlyArray<InternedString> usages { get; }

Property Value

Type	Description
ReadOnlyArray<InternedString>

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.

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 SetDeviceUsage(InputDevice, string). Controls, on the other hand, can currently only be assigned usages through layouts (usage or usages).

AddDeviceUsage(InputDevice, string) can be used to add a device. RemoveDeviceUsage(InputDevice, string) can be used to remove a device.

Examples

// Bind to any control which is tagged with the "Back" usage on any device.
var backAction = new InputAction(binding: "*/{Back}");

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

valueSizeInBytes

Size in bytes of values that the control returns.

Declaration

public abstract int valueSizeInBytes { get; }

Property Value

Type	Description
int

Remarks

The type can be determined with valueType.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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 with ReadValueFromStateAsObject(void*). The size can be determined with valueSizeInBytes.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

Methods

ApplyParameterChanges()

Apply built-in parameters changes.

Declaration

public void ApplyParameterChanges()

Remarks

Apply built-in parameters changes (e.g. invert, others). Recompute optimizedControlDataType for impacted controls and clear cached value

Examples

Gamepad.all[0].leftTrigger.WriteValueIntoState(0.5f, Gamepad.all[0].currentStatePtr);
Gamepad.all[0].ApplyParameterChanges();

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

CalculateOptimizedControlDataType()

Calculates and returns an optimized data type that can represent a control's value in memory directly.

Declaration

protected virtual FourCC CalculateOptimizedControlDataType()

Returns

Type	Description
FourCC	An optimized data type that can represent a control's value in memory directly. InputStateBlock

Remarks

The value then is cached in optimizedControlDataType. This method is for internal use only, you should not call this from your own code.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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 stateBlock.
void*	secondStatePtr	Memory containing the control's stateBlock

Returns

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

Remarks

Unlike CompareValue(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 CompareValue(void*, void*).

This method will apply epsilons (Epsilon) when comparing floats.

See Also

CompareValue(void*, void*)

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 TouchPhaseControl), 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.

See Also

EvaluateMagnitude(void*)

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

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 TouchPhaseControl), 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.

See Also

EvaluateMagnitude()

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.

Examples

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

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

GetChildControl(string)

Find a child control matching the given path.

Declaration

public InputControl GetChildControl(string path)

Parameters

Type	Name	Description
string	path	A control path. See InputControlPath.

Returns

Type	Description
InputControl	The first direct or indirect child control that matches the given path or null if no control was found to match.

Remarks

Note that if the given path matches multiple child controls, only the first control encountered in the search will be returned.

Exceptions

Type	Condition
ArgumentNullException	path is null or empty.
InvalidOperationException	No control found with the specified type.
ArgumentException	The control cannot be found.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

GetChildControl<TControl>(string)

Find a child control matching the given path.

Declaration

public TControl GetChildControl<TControl>(string path) where TControl : InputControl

Parameters

Type	Name	Description
string	path	A control path. See InputControlPath.

Returns

Type	Description
TControl	The first direct or indirect child control that matches the given path or null if no control was found to match.

Type Parameters

Name	Description
TControl	The type of control to locate.

Remarks

Note that if the given path matches multiple child controls, only the first control encountered in the search will be returned.

Exceptions

Type	Condition
ArgumentNullException	path is null or empty.
InvalidOperationException	No control found with the specified type.
ArgumentException	The control cannot be found.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

ReadValueFromBufferAsObject(void*, int)

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

Declaration

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

Parameters

Type	Name	Description
void*	buffer	Buffer to read the value from.
int	bufferSize	Size of buffer in bytes, which must be large enough to store the value.

Returns

Type	Description
object	The control's value as stored in buffer.

Remarks

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

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

Exceptions

Type	Condition
ArgumentNullException	buffer is null.
ArgumentException	bufferSize is smaller than the size of the value to be read.

See Also

ReadValueFromStateAsObject(void*)

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	State to read the value for the control from.

Returns

Type	Description
object	The control's value as stored in statePtr.

Remarks

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

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

Exceptions

Type	Condition
ArgumentNullException	statePtr is null.

See Also

ReadValueFromStateIntoBuffer(void*, void*, int)

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 bufferPtr in bytes. Must be at least valueSizeInBytes. If it is smaller, ArgumentException will be thrown.

Exceptions

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

See Also

ReadValueFromStateAsObject(void*)

WriteValueFromBufferIntoState(void*, int, void*)

RefreshConfiguration()

Refresh the configuration of the control. This is used to update the control's state (e.g. Keyboard Layout or display Name of Keys).

Declaration

protected virtual void RefreshConfiguration()

Remarks

The system will call this method automatically whenever a change is made to one of the control's configuration properties. 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 KeyControl which is fetching display names for individual keys from the underlying platform). See RefreshConfigurationIfNeeded().

Examples

using UnityEngine.InputSystem;
using UnityEngine.InputSystem.Utilities;

public class MyDevice : InputDevice
{
    public enum Orientation
    {
        Horizontal,
        Vertical,
    }
    private Orientation m_Orientation;
    private static InternedString s_Vertical = new InternedString("Vertical");
    private static InternedString s_Horizontal = new InternedString("Horizontal");

    public Orientation orientation
    {
        get
        {
            // Call RefreshOrientation if the configuration of the device has been
            // invalidated since last time we initialized m_Orientation.
            // Calling RefreshConfigurationIfNeeded() is sufficient in most cases, RefreshConfiguration() forces the refresh.
            RefreshConfiguration();
            return m_Orientation;
        }
    }
    protected override void RefreshConfiguration()
    {
        // Set Orientation back to horizontal. Alternatively fetch from device.
        m_Orientation = Orientation.Horizontal;
        // 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;
        }
    }
}

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

RefreshConfigurationIfNeeded()

Call RefreshConfiguration() if the configuration has in the interim been invalidated by a DeviceConfigurationEvent.

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 KeyControl which is fetching display names for individual keys from the underlying platform).

This method should be called if you are accessing cached data set up by RefreshConfiguration().

Examples

using UnityEngine.InputSystem;
using UnityEngine.InputSystem.Utilities;

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

RefreshConfiguration()

ToString()

Return a string representation of the control.

Declaration

public override string ToString()

Returns

Type	Description
string	A string representation of the control.

Overrides

object.ToString()

Remarks

Return a string representation of the control. Useful for debugging.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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

Returns

Type	Description
InputControl	The first direct or indirect child control that matches the given path or null if no control was found to match.

Remarks

Note that if the given path matches multiple child controls, only the first control encountered in the search will be returned.

This method is equivalent to calling TryFindChild(InputControl, string, int).

Examples

// 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");

Exceptions

Type	Condition
ArgumentNullException	path is null or empty.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

TryGetChildControl<TControl>(string)

Try to find a child control matching the given path.

Declaration

public TControl TryGetChildControl<TControl>(string path) where TControl : InputControl

Parameters

Type	Name	Description
string	path	A control path. See InputControlPath.

Returns

Type	Description
TControl	The first direct or indirect child control that matches the given path or null if no control was found to match.

Type Parameters

Name	Description
TControl	The type of control to locate.

Remarks

Note that if the given path matches multiple child controls, only the first control encountered in the search will be returned.

Exceptions

Type	Condition
ArgumentNullException	path is null or empty.
InvalidOperationException	No control found with the specified type.

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock

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, to store into the state.
int	bufferSize	Size of bufferPtr in bytes. Must be at least valueSizeInBytes.
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
NotSupportedException	The control does not support writing. This is the case, for example, that compute values (such as the magnitude of a vector).

See Also

ReadValueFromStateIntoBuffer(void*, void*, int)

WriteValueFromObjectIntoState(object, void*)

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 to store in the state.
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
NotSupportedException	The control does not support writing. This is the case, for example, that compute values (such as the magnitude of a vector).

See Also

WriteValueFromBufferIntoState(void*, int, void*)

Extension Methods

InputControlExtensions.CheckStateIsAtDefault(InputControl)

InputControlExtensions.CheckStateIsAtDefault(InputControl, void*, void*)

InputControlExtensions.CheckStateIsAtDefaultIgnoringNoise(InputControl)

InputControlExtensions.CheckStateIsAtDefaultIgnoringNoise(InputControl, void*)

InputControlExtensions.CompareState(InputControl, void*, void*)

InputControlExtensions.CompareState(InputControl, void*, void*, void*)

InputControlExtensions.CompareStateIgnoringNoise(InputControl, void*)

InputControlExtensions.FindControlsRecursive<TControl>(InputControl, IList<TControl>, Func<TControl, bool>)

InputControlExtensions.FindInParentChain<TControl>(InputControl)

InputControlExtensions.GetStatePtrFromStateEvent(InputControl, InputEventPtr)

InputControlExtensions.HasValueChangeInEvent(InputControl, InputEventPtr)

InputControlExtensions.HasValueChangeInState(InputControl, void*)

InputControlExtensions.IsActuated(InputControl, float)

InputControlExtensions.IsPressed(InputControl, float)

InputControlExtensions.ReadDefaultValueAsObject(InputControl)

InputControlExtensions.ReadValueAsObject(InputControl)

InputControlExtensions.ReadValueFromEventAsObject(InputControl, InputEventPtr)

InputControlExtensions.ReadValueIntoBuffer(InputControl, void*, int)

InputControlExtensions.ResetToDefaultStateInEvent(InputControl, InputEventPtr)

InputControlExtensions.WriteValueFromObjectIntoEvent(InputControl, InputEventPtr, object)

InputControlExtensions.WriteValueIntoEvent<TValue>(InputControl, TValue, InputEventPtr)

InputControlExtensions.WriteValueIntoState(InputControl, void*)

InputControlExtensions.WriteValueIntoState<TValue>(InputControl, TValue, void*)

See Also

InputControl<TValue>

InputDevice

InputControlPath

InputStateBlock