Class InputStateHistory

Record a history of state changes applied to one or more controls.

Inheritance
object
InputStateHistory
InputStateHistory<TValue>
Implements
Namespace: UnityEngine.InputSystem.LowLevel
Assembly: Unity.InputSystem.dll
Syntax
public class InputStateHistory : IDisposable, IEnumerable<InputStateHistory.Record>, IEnumerable, IInputStateChangeMonitor
Remarks

This class makes it easy to track input values over time. It will automatically retain input state up to a given maximum history depth (historyDepth). When the history is full, it will start overwriting the oldest entry each time a new history record is received.

The class listens to changes on the given controls by adding change monitors (IInputStateChangeMonitor) to each control.

Examples
// Track all stick controls in the system.
var history = new InputStateHistory<Vector2>("*/<Stick>");
foreach (var control in history.controls)
    Debug.Log("Capturing input on " + control);

// Start capturing.
history.StartRecording();

// Perform a couple artificial value changes.
Gamepad.current.leftStick.QueueValueChange(new Vector2(0.123f, 0.234f));
Gamepad.current.leftStick.QueueValueChange(new Vector2(0.234f, 0.345f));
Gamepad.current.leftStick.QueueValueChange(new Vector2(0.345f, 0.456f));
InputSystem.Update();

// Every value change will be visible in the history.
foreach (var record in history)
    Debug.Log($"{record.control} changed value to {record.ReadValue()}");

// Histories allocate unmanaged memory and must be disposed of in order to not leak.
history.Dispose();

Constructors

InputStateHistory(IEnumerable<InputControl>)

Creates a new InputStateHistory class to record state changes for a specified controls.

Declaration
public InputStateHistory(IEnumerable<InputControl> controls)
Parameters
Type Name Description
IEnumerable<InputControl> controls

Controls to monitor.
Remarks

Creates a new InputStateHistory to record a history of state changes for the specified controls.

See Also

InputStateHistory(int)

Creates a new InputStateHistory class to record all control state changes.

Declaration
public InputStateHistory(int maxStateSizeInBytes)
Parameters
Type Name Description
int maxStateSizeInBytes

Maximum size of control state in the record entries. Controls with larger state will not be recorded.
Remarks

Creates a new InputStateHistory to record a history of control state changes.

New controls are automatically added into the state history if their state is smaller than the threshold.

See Also

InputStateHistory(string)

Creates a new InputStateHistory class to record state changes for a specified control.

Declaration
public InputStateHistory(string path)
Parameters
Type Name Description
string path

Control path to identify which controls to monitor.
Remarks

Creates a new InputStateHistory to record a history of state changes for the specified controls.

Examples
// Track all stick controls in the system.
var history = new InputStateHistory("*/<Stick>");
See Also

InputStateHistory(InputControl)

Creates a new InputStateHistory class to record state changes for a specified control.

Declaration
public InputStateHistory(InputControl control)
Parameters
Type Name Description
InputControl control

Control to monitor.
Remarks

Creates a new InputStateHistory to record a history of state changes for the specified control.

See Also

Properties

Count

Total number of state records currently captured in the history.

Declaration
public int Count { get; }
Property Value
Type Description
int
Remarks

Number of records in the collection.

This will always be at most historyDepth. To record a change use RecordStateChange(InputControl, InputEventPtr).

See Also

this[int]

Returns an entry in the state history at the given index.

Declaration
public InputStateHistory.Record this[int index] { get; set; }
Parameters
Type Name Description
int index

Index into the array.
Property Value
Type Description
InputStateHistory.Record
Remarks

Returns a InputStateHistory.Record entry from the state history at the given index.

Exceptions
Type Condition
IndexOutOfRangeException

index is less than 0 or greater than Count.
See Also

controls

List of input controls the state history will be recording for.

Declaration
public ReadOnlyArray<InputControl> controls { get; }
Property Value
Type Description
ReadOnlyArray<InputControl>
Remarks

The list of input controls the state history will be recording for is specified on construction of the InputStateHistory

See Also

extraMemoryPerRecord

Size of additional data storage to allocate per record.

Declaration
public int extraMemoryPerRecord { get; set; }
Property Value
Type Description
int
Remarks

Additional custom data can be stored per record up to the size of this value. To retrieve a pointer to this memory use GetUnsafeExtraMemoryPtr() Used by history

Exceptions
Type Condition
ArgumentException

value is negative.
See Also

historyDepth

Maximum number of records that can be recorded in the history.

Declaration
public int historyDepth { get; set; }
Property Value
Type Description
int
Remarks

Upper limit on number of records. A fixed size memory block of unmanaged memory will be allocated to store history records. When the history is full, it will start overwriting the oldest entry each time a new history record is received.

Exceptions
Type Condition
ArgumentException

value is negative.
See Also

onRecordAdded

Optional delegate to perform when a record is added to the history array.

Declaration
public Action<InputStateHistory.Record> onRecordAdded { get; set; }
Property Value
Type Description
Action<InputStateHistory.Record>
Remarks

Can be used to fill in the extra memory with custom data using GetUnsafeExtraMemoryPtr()

See Also

onShouldRecordStateChange

Optional delegate to decide whether the state change should be stored in the history.

Declaration
public Func<InputControl, double, InputEventPtr, bool> onShouldRecordStateChange { get; set; }
Property Value
Type Description
Func<InputControl, double, InputEventPtr, bool>
Remarks

Can be used to filter out some events to focus on recording the ones you are most interested in.

If the callback returns true, a record will be added to the history If the callback returns false, the event will be ignored and not recorded.

See Also

updateMask

Specify which player loop positions the state history will be monitored for.

Declaration
public InputUpdateType updateMask { get; set; }
Property Value
Type Description
InputUpdateType
Remarks

The state history will only be monitored for the specified player loop positions. Editor is excluded from this list

Exceptions
Type Condition
ArgumentException

valueWhen an invalid mask is provided (e.g. None).
See Also

version

Current version stamp. Every time a record is stored in the history, this is incremented by one.

Declaration
public uint version { get; }
Property Value
Type Description
uint
Remarks

Version stamp that indicates the number of mutations. To record a change use RecordStateChange(InputControl, InputEventPtr).

See Also

Methods

AddRecord(Record)

Add a record to the input state history.

Declaration
public InputStateHistory.Record AddRecord(InputStateHistory.Record record)
Parameters
Type Name Description
InputStateHistory.Record record

Record to add.
Returns
Type Description
InputStateHistory.Record

The newly added record from the history array (as a copy is made).
Remarks

Add a record to the input state history. Allocates an entry in the history array and returns this copy of the original data passed to the function.

See Also

AllocateRecord(out int)

Allocate a new record in the input state history.

Declaration
protected InputStateHistory.RecordHeader* AllocateRecord(out int index)
Parameters
Type Name Description
int index

The index of the newly created record
Returns
Type Description
RecordHeader*

The header of the newly created record
Remarks

Allocate a new record in the input state history.

See Also

Clear()

Clear the history record.

Declaration
public void Clear()
Remarks

Clear the history record. Resetting the list to empty.

This won't clear controls that have been added on the fly.

See Also

Destroy()

Destroy the state history records.

Declaration
protected void Destroy()
Remarks

Deletes the state history records.

See Also

Dispose()

Dispose of the state history records.

Declaration
public void Dispose()
Remarks

Stops recording and cleans up the state history

See Also

~InputStateHistory()

InputStateHistory destructor.

Declaration
protected ~InputStateHistory()
See Also

GetEnumerator()

Enumerate all state history records.

Declaration
public IEnumerator<InputStateHistory.Record> GetEnumerator()
Returns
Type Description
IEnumerator<InputStateHistory.Record>

An enumerator going over the state history records.
Remarks

Enumerate all state history records.

See Also

GetRecord(int)

Retrieve a record from the input state history.

Declaration
protected InputStateHistory.RecordHeader* GetRecord(int index)
Parameters
Type Name Description
int index

Record index into the input state history records buffer.
Returns
Type Description
RecordHeader*

The record header for the specified index
Remarks

Retrieve a record from the input state history by Record index.

Exceptions
Type Condition
InvalidOperationException

When the buffer is no longer valid as it has been disposed.
ArgumentOutOfRangeException

If the index is out of range of the history depth.
See Also

ReadValueAsObject(RecordHeader*)

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

Declaration
protected object ReadValueAsObject(InputStateHistory.RecordHeader* data)
Parameters
Type Name Description
RecordHeader* data

The record header to query.
Returns
Type Description
object

The value of the control associated with the record header.
Remarks

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

Exceptions
Type Condition
InvalidOperationException

When the specified value is not present.
See Also

ReadValue<TValue>(RecordHeader*)

Returns value from the control in the specified record header.

Declaration
protected TValue ReadValue<TValue>(InputStateHistory.RecordHeader* data) where TValue : struct
Parameters
Type Name Description
RecordHeader* data

The record header to query.
Returns
Type Description
TValue

The value from the record.
Type Parameters
Name Description
TValue

The type of the value being read
Exceptions
Type Condition
InvalidOperationException

When the record is no longer value or the specified type is not present.
See Also

RecordIndexToUserIndex(int)

Remap a records internal index to an index from the start of the recording in the circular buffer.

Declaration
protected int RecordIndexToUserIndex(int index)
Parameters
Type Name Description
int index

Record index (from the start of the record array).
Returns
Type Description
int

An index relative to the start of the recording in the circular buffer.
Remarks

Remap a records internal index, which is relative to the start of the record buffer, to an index relative to the start of the recording in the circular buffer.

See Also

RecordStateChange(InputControl, void*, double)

Record a state change for a specific control.

Declaration
public InputStateHistory.Record RecordStateChange(InputControl control, void* statePtr, double time)
Parameters
Type Name Description
InputControl control

The control to record the state change for.
void* statePtr

The current state data to record.
double time

Time stamp to apply (overriding the event timestamp)
Returns
Type Description
InputStateHistory.Record

The newly added record.
Remarks

Record a state change for a specific control. Will call the onRecordAdded delegate after adding the record. Note this does not call the onShouldRecordStateChange delegate.

See Also

RecordStateChange(InputControl, InputEventPtr)

Record a state change for a specific control.

Declaration
public InputStateHistory.Record RecordStateChange(InputControl control, InputEventPtr eventPtr)
Parameters
Type Name Description
InputControl control

The control to record the state change for.
InputEventPtr eventPtr

The current event data to record.
Returns
Type Description
InputStateHistory.Record

The newly added record.
Remarks

Record a state change for a specific control. Will call the onRecordAdded delegate after adding the record. Note this does not call the onShouldRecordStateChange delegate.

See Also

StartRecording()

Start recording state history for the specified controls.

Declaration
public void StartRecording()
Remarks

Start recording state history for the controls specified in the InputStateHistory constructor.

Examples
using (var allTouchTaps = new InputStateHistory("<Touchscreen>/touch*/tap"))
{
    allTouchTaps.StartRecording();
    allTouchTaps.StopRecording();
}
See Also

StopRecording()

Stop recording state history for the specified controls.

Declaration
public void StopRecording()
Remarks

Stop recording state history for the controls specified in the InputStateHistory constructor.

Examples
using (var allTouchTaps = new InputStateHistory("<Touchscreen>/touch*/tap"))
{
    allTouchTaps.StartRecording();
    allTouchTaps.StopRecording();
}
See Also

UserIndexToRecordIndex(int)

Remap an index from the start of the recording in the circular buffer to a records internal index.

Declaration
protected int UserIndexToRecordIndex(int index)
Parameters
Type Name Description
int index

An index relative to the start of the recording in the circular buffer.
Returns
Type Description
int

Record index (from the start of the record array).
Remarks

Remap an index relative to the start of the recording in the circular buffer, to a records internal index, which is relative to the start of the record buffer.

See Also

Implements

See Also

Did you find this page useful? Please give it a rating: