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.

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

Declaration
public InputStateHistory(int maxStateSizeInBytes)
Parameters
Type Name Description
int 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

Count

Total number of state records currently captured in the history.

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

Number of records in the collection.
Remarks

This will always be at most historyDepth.

See Also

this[int]

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

controls

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

extraMemoryPerRecord

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

historyDepth

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

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

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.

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, bool>

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
uint

Version stamp that indicates the number of mutations.
See Also

Methods

AddRecord(Record)

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

AllocateRecord(out int)

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

Clear()

Declaration
public void Clear()

Destroy()

Declaration
protected void Destroy()

Dispose()

Declaration
public void Dispose()

~InputStateHistory()

Declaration
protected ~InputStateHistory()

GetEnumerator()

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

GetRecord(int)

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

ReadValueAsObject(RecordHeader*)

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

ReadValue<TValue>(RecordHeader*)

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

RecordIndexToUserIndex(int)

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

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

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

Implements