Class InputState

Low-level APIs for working with input state memory.

Inheritance

object

InputState

Namespace: UnityEngine.InputSystem.LowLevel

Assembly: Unity.InputSystem.dll

Syntax

public static class InputState

Properties

currentTime

Declaration

public static double currentTime { get; }

Property Value

Type	Description
double

currentUpdateType

The type of update that was last run or is currently being run on the input state.

Declaration

public static InputUpdateType currentUpdateType { get; }

Property Value

Type	Description
InputUpdateType

Remarks

This determines which set of buffers are currently active and thus determines which view code that queries input state will receive. For example, during editor updates, this will be Editor and the state buffers for the editor will be active.

updateCount

The number of times the current input state has been updated.

Declaration

public static uint updateCount { get; }

Property Value

Type	Description
uint

Methods

AddChangeMonitor(InputControl, Action<InputControl, double, InputEventPtr, long>, int, Action<InputControl, double, long, int>)

Declaration

public static IInputStateChangeMonitor AddChangeMonitor(InputControl control, Action<InputControl, double, InputEventPtr, long> valueChangeCallback, int monitorIndex = -1, Action<InputControl, double, long, int> timerExpiredCallback = null)

Parameters

Type	Name	Description
InputControl	control
Action<InputControl, double, InputEventPtr, long>	valueChangeCallback
int	monitorIndex
Action<InputControl, double, long, int>	timerExpiredCallback

Returns

Type	Description
IInputStateChangeMonitor

AddChangeMonitor(InputControl, IInputStateChangeMonitor, long, uint)

Add a monitor that gets triggered every time the state of control changes.

Declaration

public static void AddChangeMonitor(InputControl control, IInputStateChangeMonitor monitor, long monitorIndex = -1, uint groupIndex = 0)

Parameters

Type	Name	Description
InputControl	control	A control sitting on an InputDevice that has been added.
IInputStateChangeMonitor	monitor	Instance of the monitor that should be notified when state changes occur.
long	monitorIndex	Numeric index of the monitors. Monitors on a device are ordered by decreasing monitor index and invoked in that order.
uint	groupIndex	Numeric group of the monitor. See remarks.

Remarks

All monitors on an InputDevice are sorted by the complexity specified in their monitorIndex (in decreasing order) and invoked in that order.

Every handler gets an opportunity to set handled to true. When doing so, all remaining pending monitors from the same monitor instance that have the same groupIndex will be silenced and skipped over. This can be used to establish an order of event "consumption" where one change monitor may prevent another change monitor from triggering.

Monitors are invoked after a state change has been written to the device. If, for example, a StateEvent is received that sets leftTrigger to 0.5, the value is first applied to the control and then any state monitors that may be listening to the change are invoked (thus getting 0.5 if calling ReadValue()).

class InputMonitor : IInputStateChangeMonitor
{
    public InputMonitor()
    {
        // Watch the left and right mouse button.
        // By supplying monitor indices here, we not only receive the indices in NotifyControlStateChanged,
        // we also create an ordering between the two monitors. The one on RMB will fire *before* the one
        // on LMB in case there is a single event that changes both buttons.
        InputState.AddChangeMonitor(Mouse.current.leftButton, this, monitorIndex: 1);
        InputState.AddChangeMonitor(Mouse.current.rightButton, this, monitorIndex: 2);
    }
public void NotifyControlStateChanged(InputControl control, double time, InputEventPtr eventPtr, long monitorIndex)
{
    Debug.Log($"{control} changed");

    // We can add a monitor timeout that will trigger in case the state of the
    // given control is not changed within the given time. Let's watch the control
    // for 2 seconds. If nothing happens, we will get a call to NotifyTimerExpired.
    // If, however, there is a state change, the timeout is automatically removed
    // and we will see a call to NotifyControlStateChanged instead.
    InputState.AddChangeMonitorTimeout(control, this, 2);
}

public void NotifyTimerExpired(InputControl control, double time, long monitorIndex, int timerIndex)
{
    Debug.Log($"{control} was not changed within 2 seconds");
}

}

Exceptions

Type	Condition
ArgumentNullException	control is null -or- monitor is null.
ArgumentException	The InputDevice of control has not been added.

AddChangeMonitorTimeout(InputControl, IInputStateChangeMonitor, double, long, int)

Put a timeout on a previously registered state change monitor.

Declaration

public static void AddChangeMonitorTimeout(InputControl control, IInputStateChangeMonitor monitor, double time, long monitorIndex = -1, int timerIndex = -1)

Parameters

Type	Name	Description
InputControl	control
IInputStateChangeMonitor	monitor
double	time
long	monitorIndex
int	timerIndex

Remarks

If by the given time, no state change has been registered on the control monitored by the given monitor, NotifyTimerExpired(InputControl, double, long, int) will be called on monitor. If a state change happens by the given time, the monitor is notified as usual and the timer is automatically removed.

Change(InputDevice, InputEventPtr, InputUpdateType)

Declaration

public static void Change(InputDevice device, InputEventPtr eventPtr, InputUpdateType updateType = InputUpdateType.None)

Parameters

Type	Name	Description
InputDevice	device
InputEventPtr	eventPtr
InputUpdateType	updateType

Change<TState>(InputControl, TState, InputUpdateType, InputEventPtr)

Perform one update of input state.

Declaration

public static void Change<TState>(InputControl control, TState state, InputUpdateType updateType = InputUpdateType.None, InputEventPtr eventPtr = default) where TState : struct

Parameters

Type	Name	Description
InputControl	control
TState	state
InputUpdateType	updateType
InputEventPtr	eventPtr

Type Parameters

Name	Description
TState

Remarks

Incorporates the given state and triggers all state change monitors as needed.

Note that input state changes performed with this method will not be visible on remotes as they will bypass event processing. It is effectively equivalent to directly writing into input state memory except that it also performs related tasks such as checking state change monitors, flipping buffers, or making the respective device current.

Change<TState>(InputControl, ref TState, InputUpdateType, InputEventPtr)

Perform one update of input state.

Declaration

public static void Change<TState>(InputControl control, ref TState state, InputUpdateType updateType = InputUpdateType.None, InputEventPtr eventPtr = default) where TState : struct

Parameters

Type	Name	Description
InputControl	control
TState	state
InputUpdateType	updateType
InputEventPtr	eventPtr

Type Parameters

Name	Description
TState

Remarks

Incorporates the given state and triggers all state change monitors as needed.

Note that input state changes performed with this method will not be visible on remotes as they will bypass event processing. It is effectively equivalent to directly writing into input state memory except that it also performs related tasks such as checking state change monitors, flipping buffers, or making the respective device current.

IsIntegerFormat(FourCC)

Declaration

public static bool IsIntegerFormat(this FourCC format)

Parameters

Type	Name	Description
FourCC	format

Returns

Type	Description
bool

RemoveChangeMonitor(InputControl, IInputStateChangeMonitor, long)

Declaration

public static void RemoveChangeMonitor(InputControl control, IInputStateChangeMonitor monitor, long monitorIndex = -1)

Parameters

Type	Name	Description
InputControl	control
IInputStateChangeMonitor	monitor
long	monitorIndex

RemoveChangeMonitorTimeout(IInputStateChangeMonitor, long, int)

Declaration

public static void RemoveChangeMonitorTimeout(IInputStateChangeMonitor monitor, long monitorIndex = -1, int timerIndex = -1)

Parameters

Type	Name	Description
IInputStateChangeMonitor	monitor
long	monitorIndex
int	timerIndex

Events

onChange

Callback that is triggered when the state of an input device changes.

Declaration

public static event Action<InputDevice, InputEventPtr> onChange

Event Type

Type	Description
Action<InputDevice, InputEventPtr>

Remarks

The first parameter is the device whose state was changed the second parameter is the event that triggered the change in state. Note that the latter may be null in case the change was performed directly through Change(InputDevice, InputEventPtr, InputUpdateType) rather than through an event.