Class InputStateHistory

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

Inheritance
Object
InputStateHistory
InputStateHistory<TValue>
Namespace: UnityEngine.InputSystem.LowLevel
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.

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

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

InputStateHistory(Int32)

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

InputStateHistory(String)

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

InputStateHistory(InputControl)

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

Properties

controls

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

Count

Total number of state records currently captured in the history.

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

Number of records in the collection.
Remarks

This will always be at most historyDepth.

See Also

extraMemoryPerRecord

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

historyDepth

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

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

Upper limit on number of records.
Remarks

A fixed size memory block of unmanaged memory will be allocated to store history records. This property determines TODO

Exceptions
Type Condition
ArgumentException

value is negative.

Item[Int32]

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

onRecordAdded

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

onShouldRecordStateChange

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

updateMask

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

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
UInt32

Version stamp that indicates the number of mutations.
See Also

Methods

AddRecord(InputStateHistory.Record)

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

AllocateRecord(out Int32)

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

Clear()

Declaration
public void Clear()

Destroy()

Declaration
protected void Destroy()

Dispose()

Declaration
public void Dispose()
Implements

Finalize()

Declaration
protected void Finalize()

GetEnumerator()

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

GetRecord(Int32)

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

ReadValue<TValue>(InputStateHistory.RecordHeader*)

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

ReadValueAsObject(InputStateHistory.RecordHeader*)

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

RecordIndexToUserIndex(Int32)

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

RecordStateChange(InputControl, Void*, Double)

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

RecordStateChange(InputControl, InputEventPtr)

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

StartRecording()

Declaration
public void StartRecording()

StopRecording()

Declaration
public void StopRecording()

UserIndexToRecordIndex(Int32)

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

Explicit Interface Implementations

IEnumerable.GetEnumerator()

Declaration
IEnumerator IEnumerable.GetEnumerator()
Returns
Type Description
IEnumerator
Implements

IInputStateChangeMonitor.NotifyControlStateChanged(InputControl, Double, InputEventPtr, Int64)

Declaration
void IInputStateChangeMonitor.NotifyControlStateChanged(InputControl control, double time, InputEventPtr eventPtr, long monitorIndex)
Parameters
Type Name Description
InputControl control
Double time
InputEventPtr eventPtr
Int64 monitorIndex
Implements

IInputStateChangeMonitor.NotifyTimerExpired(InputControl, Double, Int64, Int32)

Declaration
void IInputStateChangeMonitor.NotifyTimerExpired(InputControl control, double time, long monitorIndex, int timerIndex)
Parameters
Type Name Description
InputControl control
Double time
Int64 monitorIndex
Int32 timerIndex
Implements