Class InputControlExtensions

Various extension methods for InputControl. Mostly low-level routines.

Inheritance
System.Object
InputControlExtensions
Namespace: UnityEngine.InputSystem
Syntax
public static class InputControlExtensions

Methods

CheckStateIsAtDefault(InputControl)

Declaration
public static bool CheckStateIsAtDefault(this InputControl control)
Parameters
Type Name Description
InputControl control
Returns
Type Description
System.Boolean

CheckStateIsAtDefault(InputControl, Void*, Void*)

Check if the given state corresponds to the default state of the control.

Declaration
public static bool CheckStateIsAtDefault(this InputControl control, void *statePtr, void *maskPtr = default(void *))
Parameters
Type Name Description
InputControl control
System.Void* statePtr

Pointer to a state buffer containing the stateBlock for control.
System.Void* maskPtr

If not null, only bits set to true in the buffer will be taken into account. This can be used to mask out noise.
Returns
Type Description
System.Boolean

True if the control/device is in its default state.
Remarks

Note that default does not equate all zeroes. Stick axes, for example, that are stored as unsigned byte values will have their resting position at 127 and not at 0. This is why we explicitly store default state in a memory buffer instead of assuming zeroes.

See Also
UnityEngine.InputSystem.LowLevel.InputStateBuffers.defaultStateBuffer

CheckStateIsAtDefaultIgnoringNoise(InputControl)

Declaration
public static bool CheckStateIsAtDefaultIgnoringNoise(this InputControl control)
Parameters
Type Name Description
InputControl control
Returns
Type Description
System.Boolean

CheckStateIsAtDefaultIgnoringNoise(InputControl, Void*)

Declaration
public static bool CheckStateIsAtDefaultIgnoringNoise(this InputControl control, void *statePtr)
Parameters
Type Name Description
InputControl control
System.Void* statePtr
Returns
Type Description
System.Boolean

CompareState(InputControl, Void*, Void*)

Declaration
public static bool CompareState(this InputControl control, void *statePtr, void *maskPtr = default(void *))
Parameters
Type Name Description
InputControl control
System.Void* statePtr
System.Void* maskPtr
Returns
Type Description
System.Boolean

CompareState(InputControl, Void*, Void*, Void*)

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

Declaration
public static bool CompareState(this InputControl control, void *firstStatePtr, void *secondStatePtr, void *maskPtr = default(void *))
Parameters
Type Name Description
InputControl control
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 (e.g. if both stick values fall below the deadzone).

See Also
CompareValue(System.Void*, System.Void*)

CompareStateIgnoringNoise(InputControl, Void*)

Compare the control's current state to the state stored in statePtr.

Declaration
public static bool CompareStateIgnoringNoise(this InputControl control, void *statePtr)
Parameters
Type Name Description
InputControl control
System.Void* statePtr

State memory containing the control's .
Returns
Type Description
System.Boolean

True if

Remarks

This method ignores noise

This method will not actually read values but will instead compare state directly as it is stored in memory. ReadValue() is not invoked and thus processors will not be run.

FindControlsRecursive<TControl>(InputControl, IList<TControl>, Func<TControl, Boolean>)

Declaration
public static void FindControlsRecursive<TControl>(this InputControl parent, IList<TControl> controls, Func<TControl, bool> predicate)
    where TControl : InputControl
Parameters
Type Name Description
InputControl parent
System.Collections.Generic.IList<TControl> controls
System.Func<TControl, System.Boolean> predicate
Type Parameters
Name Description
TControl

GetStatePtrFromStateEvent(InputControl, InputEventPtr)

Declaration
public static void *GetStatePtrFromStateEvent(this InputControl control, InputEventPtr eventPtr)
Parameters
Type Name Description
InputControl control
InputEventPtr eventPtr
Returns
Type Description
System.Void*

HasValueChangeInEvent(InputControl, InputEventPtr)

Declaration
public static bool HasValueChangeInEvent(this InputControl control, InputEventPtr eventPtr)
Parameters
Type Name Description
InputControl control
InputEventPtr eventPtr
Returns
Type Description
System.Boolean

HasValueChangeInState(InputControl, Void*)

Return true if the actual value

Declaration
public static bool HasValueChangeInState(this InputControl control, void *statePtr)
Parameters
Type Name Description
InputControl control
System.Void* statePtr
Returns
Type Description
System.Boolean

IsActuated(InputControl, Single)

Return true if the given control is actuated.

Declaration
public static bool IsActuated(this InputControl control, float threshold = 0F)
Parameters
Type Name Description
InputControl control
System.Single threshold

Magnitude threshold that the control must match or exceed to be considered actuated. An exception to this is the default value of zero. If threshold is zero, the control must have a magnitude greater than zero.
Returns
Type Description
System.Boolean
Remarks

Actuation is defined as a control having a magnitude (EvaluateMagnitude() greater than zero or, if the control does not support magnitudes, has been moved from its default state.

In practice, this means that when actuated, a control will produce a value other than its default value.

QueueValueChange<TValue>(InputControl<TValue>, TValue, Double)

Queue a value change on the given control which will be processed and take effect in the next input update.

Declaration
public static void QueueValueChange<TValue>(this InputControl<TValue> control, TValue value, double time = -1)
    where TValue : struct
Parameters
Type Name Description
InputControl<TValue> control

Control to change the value of.
TValue value

New value for the control.
System.Double time

Optional time at which the value change should take effect. If set, this will become the time of the queued event. If the time is in the future, the event will not be processed until it falls within the time of an input update slice (except if is false, in which case the event will invariably be consumed in the next update).
Type Parameters
Name Description
TValue

Type of value.
Exceptions
Type Condition
System.ArgumentNullException

control is null.

ReadDefaultValueAsObject(InputControl)

Read the control's default value and return it as an object.

Declaration
public static object ReadDefaultValueAsObject(this InputControl control)
Parameters
Type Name Description
InputControl control

Control to read default value from.
Returns
Type Description
System.Object
Remarks

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

Exceptions
Type Condition
System.ArgumentNullException

control is null.
See Also
UnityEngine.InputSystem.InputControl.hasDefaultValue

ReadUnprocessedValueFromEvent<TValue>(InputControl<TValue>, InputEventPtr)

Declaration
public static TValue ReadUnprocessedValueFromEvent<TValue>(this InputControl<TValue> control, InputEventPtr eventPtr)
    where TValue : struct
Parameters
Type Name Description
InputControl<TValue> control
InputEventPtr eventPtr
Returns
Type Description
TValue
Type Parameters
Name Description
TValue

ReadUnprocessedValueFromEvent<TValue>(InputControl<TValue>, InputEventPtr, out TValue)

Declaration
public static bool ReadUnprocessedValueFromEvent<TValue>(this InputControl<TValue> control, InputEventPtr inputEvent, out TValue value)
    where TValue : struct
Parameters
Type Name Description
InputControl<TValue> control
InputEventPtr inputEvent
TValue value
Returns
Type Description
System.Boolean
Type Parameters
Name Description
TValue

ReadValueAsObject(InputControl)

Read the current value of the control and return it as an object.

Declaration
public static object ReadValueAsObject(this InputControl control)
Parameters
Type Name Description
InputControl control
Returns
Type Description
System.Object
Remarks

This method allocates GC memory and thus may cause garbage collection when used during gameplay.

Use ReadValueIntoBuffer(InputControl, Void*, Int32) to read values generically without having to know the specific value type of a control.

See Also

ReadValueFromEvent<TValue>(InputControl<TValue>, InputEventPtr, out TValue)

Read the value of the given control from an event.

Declaration
public static bool ReadValueFromEvent<TValue>(this InputControl<TValue> control, InputEventPtr inputEvent, out TValue value)
    where TValue : struct
Parameters
Type Name Description
InputControl<TValue> control
InputEventPtr inputEvent

Input event. This must be a StateEvent or DeltaStateEvent. Note that in the case of a DeltaStateEvent, the control may not actually be part of the event. In this case, the method returns false and stores default(TValue) in value.
TValue value

Variable that receives the control value.
Returns
Type Description
System.Boolean

True if the value has been successfully read from the event, false otherwise.
Type Parameters
Name Description
TValue
Exceptions
Type Condition
System.ArgumentNullException

control is null.
See Also

ReadValueIntoBuffer(InputControl, Void*, Int32)

Read the current, processed value of the control and store it into the given memory buffer.

Declaration
public static void ReadValueIntoBuffer(this InputControl control, void *buffer, int bufferSize)
Parameters
Type Name Description
InputControl control
System.Void* buffer

Buffer to store value in. Note that the value is not stored with the offset found in byteOffset of the control's stateBlock. It will be stored directly at the given address.
System.Int32 bufferSize

Size of the memory available at buffer in bytes. Has to be at least valueSizeInBytes. If the size is smaller, nothing will be written to the buffer.
See Also
ReadValueFromStateIntoBuffer(System.Void*, System.Void*, System.Int32)

WriteValueFromObjectIntoEvent(InputControl, InputEventPtr, Object)

Declaration
public static void WriteValueFromObjectIntoEvent(this InputControl control, InputEventPtr eventPtr, object value)
Parameters
Type Name Description
InputControl control
InputEventPtr eventPtr
System.Object value

WriteValueIntoEvent<TValue>(InputControl, TValue, InputEventPtr)

Declaration
public static void WriteValueIntoEvent<TValue>(this InputControl control, TValue value, InputEventPtr eventPtr)
    where TValue : struct
Parameters
Type Name Description
InputControl control
TValue value
InputEventPtr eventPtr
Type Parameters
Name Description
TValue

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

Declaration
public static void WriteValueIntoEvent<TValue>(this InputControl<TValue> control, TValue value, InputEventPtr eventPtr)
    where TValue : struct
Parameters
Type Name Description
InputControl<TValue> control
TValue value
InputEventPtr eventPtr
Type Parameters
Name Description
TValue

WriteValueIntoState(InputControl, Void*)

Write the control's current value into statePtr.

Declaration
public static void WriteValueIntoState(this InputControl control, void *statePtr)
Parameters
Type Name Description
InputControl control

Control to read the current value from and to store state for in statePtr.
System.Void* statePtr

State to receive the control's value in its respective stateBlock.
Remarks

This method is equivalent to WriteValueIntoState(TValue, Void*) except that one does not have to know the value type of the given control.

Exceptions
Type Condition
System.ArgumentNullException

control is null or statePtr is null.
System.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
WriteValueIntoState(TValue, System.Void*)

WriteValueIntoState<TValue>(InputControl, TValue, Void*)

Declaration
public static void WriteValueIntoState<TValue>(this InputControl control, TValue value, void *statePtr)
    where TValue : struct
Parameters
Type Name Description
InputControl control
TValue value
System.Void* statePtr
Type Parameters
Name Description
TValue

WriteValueIntoState<TValue>(InputControl<TValue>, TValue, Void*)

Declaration
public static void WriteValueIntoState<TValue>(this InputControl<TValue> control, TValue value, void *statePtr)
    where TValue : struct
Parameters
Type Name Description
InputControl<TValue> control
TValue value
System.Void* statePtr
Type Parameters
Name Description
TValue

WriteValueIntoState<TValue>(InputControl<TValue>, Void*)

Declaration
public static void WriteValueIntoState<TValue>(this InputControl<TValue> control, void *statePtr)
    where TValue : struct
Parameters
Type Name Description
InputControl<TValue> control
System.Void* statePtr
Type Parameters
Name Description
TValue

WriteValueIntoState<TValue, TState>(InputControl<TValue>, TValue, ref TState)

Declaration
public static void WriteValueIntoState<TValue, TState>(this InputControl<TValue> control, TValue value, ref TState state)
    where TValue : struct where TState : struct, IInputStateTypeInfo
Parameters
Type Name Description
InputControl<TValue> control
TValue value

Value for control to write into state.
TState state
Type Parameters
Name Description
TValue
TState
Exceptions
Type Condition
System.ArgumentNullException

control is null.
System.ArgumentException

Control's value does not fit within the memory of state.
System.NotSupportedException

control does not support writing.