Class InputEventTrace

InputEventTrace lets you record input events for later processing. It also has features for writing traces to disk, for loading them from disk, and for playing back previously recorded traces.

Inheritance

object

InputEventTrace

Implements

IDisposable

IEnumerable<InputEventPtr>

IEnumerable

Namespace: UnityEngine.InputSystem.LowLevel

Assembly: Unity.InputSystem.dll

Syntax

[Serializable]
public sealed class InputEventTrace : IDisposable, IEnumerable<InputEventPtr>, IEnumerable

Remarks

InputEventTrace lets you record input events into a buffer for either a specific device, or for all events received by the input system. This is useful for testing purposes or for replaying recorded input.

Note that event traces must be disposed of (by calling Dispose()) after use or they will leak memory on the unmanaged (C++) memory heap.

Event traces are serializable such that they can survive domain reloads in the editor.

Constructors

InputEventTrace(long, bool, long, long)

Create a disabled event trace that does not perform any allocation yet. An event trace only starts consuming resources the first time it is enabled.

Declaration

public InputEventTrace(long bufferSizeInBytes = 1048576, bool growBuffer = false, long maxBufferSizeInBytes = -1, long growIncrementSizeInBytes = -1)

Parameters

Type	Name	Description
long	bufferSizeInBytes	Size of buffer that will be allocated on first event captured by trace. Defaults to 1MB.
bool	growBuffer	If true, the event buffer will be grown automatically when it reaches capacity, up to a maximum size of maxBufferSizeInBytes. This is off by default.
long	maxBufferSizeInBytes	If growBuffer is true, this is the maximum size that the buffer should be grown to. If the maximum size is reached, old events are being overwritten.
long	growIncrementSizeInBytes

InputEventTrace(InputDevice, long, bool, long, long)

Declaration

public InputEventTrace(InputDevice device, long bufferSizeInBytes = 1048576, bool growBuffer = false, long maxBufferSizeInBytes = -1, long growIncrementSizeInBytes = -1)

Parameters

Type	Name	Description
InputDevice	device
long	bufferSizeInBytes
bool	growBuffer
long	maxBufferSizeInBytes
long	growIncrementSizeInBytes

Properties

FrameMarkerEvent

If is enabled, an InputEvent with this FourCC code in its type is recorded whenever the input system starts a new update, i.e. whenever onBeforeUpdate is triggered. This is useful for replaying events in such a way that they are correctly spaced out over frames.

Declaration

public static FourCC FrameMarkerEvent { get; }

Property Value

Type	Description
FourCC

allocatedSizeInBytes

Total size of memory buffer (in bytes) currently allocated.

Declaration

public long allocatedSizeInBytes { get; }

Property Value

Type	Description
long	Size of memory currently allocated.

Remarks

The buffer is allocated on the unmanaged heap.

deviceId

Set device to record events for. Set to InvalidDeviceId by default in which case events from all devices are recorded.

Declaration

public int deviceId { get; set; }

Property Value

Type	Description
int

deviceInfos

Information about all devices for which events have been recorded in the trace.

Declaration

public ReadOnlyArray<InputEventTrace.DeviceInfo> deviceInfos { get; }

Property Value

Type	Description
ReadOnlyArray<InputEventTrace.DeviceInfo>	Record of devices recorded in the trace.

enabled

Whether the trace is currently recording input.

Declaration

public bool enabled { get; }

Property Value

Type	Description
bool	True if the trace is currently recording events.

See Also

Enable()

Disable()

eventCount

Total number of events currently in the trace.

Declaration

public long eventCount { get; }

Property Value

Type	Description
long	Number of events recorded in the trace.

maxSizeInBytes

Largest size (in bytes) that the memory buffer is allowed to grow to. By default, this is the same as allocatedSizeInBytes meaning that the buffer is not allowed to grow but will rather wrap around when full.

Declaration

public long maxSizeInBytes { get; }

Property Value

Type	Description
long	Largest size the memory buffer is allowed to grow to.

onFilterEvent

Optional delegate to decide whether an input should be stored in a trace. Null by default.

Declaration

public Func<InputEventPtr, InputDevice, bool> onFilterEvent { get; set; }

Property Value

Type	Description
Func<InputEventPtr, InputDevice, bool>	Delegate to accept or reject individual events.

Remarks

When this is set, the callback will be invoked on every event that would otherwise be stored directly in the trace. If the callback returns true, the trace will continue to record the event. If the callback returns false, the event will be ignored and not recorded.

The callback should generally mutate the event. If you do so, note that this will impact event processing in general, not just recording of the event in the trace.

recordFrameMarkers

If true, input update boundaries will be recorded as events. By default, this is off.

Declaration

public bool recordFrameMarkers { get; set; }

Property Value

Type	Description
bool	Whether frame boundaries should be recorded in the trace.

Remarks

When recording with this off, all events are written one after the other for as long as the recording is active. This means that when a recording runs over multiple frames, it is no longer possible for the trace to tell which events happened in distinct frames.

By turning this feature on, frame marker events (i.e. InputEvent instances with type set to FrameMarkerEvent) will be written to the trace every time an input update occurs. When playing such a trace back via PlayAllFramesOneByOne(), events will get spaced out over frames corresponding to how they were spaced out when input was initially recorded.

Note that having this feature enabled will fill up traces much quicker. Instead of being filled up only when there is input, TODO

See Also

PlayAllFramesOneByOne()

FrameMarkerEvent

totalEventSizeInBytes

The amount of memory consumed by all events combined that are currently stored in the trace.

Declaration

public long totalEventSizeInBytes { get; }

Property Value

Type	Description
long	Total size of event data currently in trace.

Methods

Clear()

Reset the trace. Clears all recorded events.

Declaration

public void Clear()

Disable()

Stop recording events.

Declaration

public void Disable()

See Also

Enable()

Dispose()

Stop recording, if necessary, and clear the trace such that it released unmanaged memory which might be allocated.

Declaration

public void Dispose()

Remarks

For any trace that has recorded events, calling this method is crucial in order to not leak memory on the unmanaged (C++) memory heap.

Enable()

Start recording events.

Declaration

public void Enable()

See Also

Disable()

GetEnumerator()

Declaration

public IEnumerator<InputEventPtr> GetEnumerator()

Returns

Type	Description
IEnumerator<InputEventPtr>

GetNextEvent(ref InputEventPtr)

Based on the given event pointer, return a pointer to the next event in the trace.

Declaration

public bool GetNextEvent(ref InputEventPtr current)

Parameters

Type	Name	Description
InputEventPtr	current	A pointer to an event in the trace or a default(InputEventTrace). In the former case, the pointer will be updated to the next event, if there is one. In the latter case, the pointer will be updated to the first event in the trace, if there is one.

Returns

Type	Description
bool	True if current has been set to the next event, false otherwise.

Remarks

Event storage in memory may be circular if the event buffer is fixed in size or has reached maximum size and new events start overwriting old events. This method will automatically start with the first event when the given current event is null. Any subsequent call with then loop over the remaining events until no more events are available.

Note that it is VERY IMPORTANT that the buffer is not modified while iterating over events this way. If this is not ensured, invalid memory accesses may result.

// Loop over all events in the InputEventTrace in the `trace` variable.
var current = default(InputEventPtr);
while (trace.GetNextEvent(ref current))
{
    Debug.Log(current);
}

LoadFrom(Stream)

Load an event trace from a previously captured event stream.

Declaration

public static InputEventTrace LoadFrom(Stream stream)

Parameters

Type	Name	Description
Stream	stream	A stream as written by WriteTo(Stream). Must support reading.

Returns

Type	Description
InputEventTrace	The loaded event trace.

Exceptions

Type	Condition
ArgumentException	stream is not readable.
ArgumentNullException	stream is null.
IOException	The stream cannot be loaded (e.g. wrong format; details in the exception).

See Also

WriteTo(Stream)

LoadFrom(string)

Load an input event trace from the given file.

Declaration

public static InputEventTrace LoadFrom(string filePath)

Parameters

Type	Name	Description
string	filePath	Path to a file.

Returns

Type	Description
InputEventTrace

Exceptions

Type	Condition
ArgumentNullException	filePath is null or empty.
FileNotFoundException	filePath is invalid.
DirectoryNotFoundException	A directory in filePath is invalid.
UnauthorizedAccessException	filePath cannot be accessed.

See Also

WriteTo(string)

ReadFrom(string)

ReadFrom(Stream)

Read the contents of an input event trace from the given stream.

Declaration

public void ReadFrom(Stream stream)

Parameters

Type	Name	Description
Stream	stream	A stream of binary data containing a recorded event trace as written out with WriteTo(Stream). Must support reading.

Remarks

This method replaces the contents of the event trace with those read from the stream. It does not append to the existing trace.

Exceptions

Type	Condition
ArgumentNullException	stream is null.
ArgumentException	stream does not support reading.
IOException	An error occurred trying to read from stream.

See Also

WriteTo(Stream)

ReadFrom(string)

Read the contents of an input event trace stored in the given file.

Declaration

public void ReadFrom(string filePath)

Parameters

Type	Name	Description
string	filePath	Path to a file.

Remarks

This method replaces the contents of the trace with those read from the given file.

Exceptions

Type	Condition
ArgumentNullException	filePath is null or empty.
FileNotFoundException	filePath is invalid.
DirectoryNotFoundException	A directory in filePath is invalid.
UnauthorizedAccessException	filePath cannot be accessed.

See Also

WriteTo(string)

Replay()

Start a replay of the events in the trace.

Declaration

public InputEventTrace.ReplayController Replay()

Returns

Type	Description
InputEventTrace.ReplayController	An object that controls playback.

Remarks

Calling this method implicitly turns off recording, if currently enabled (i.e. it calls Disable()), as replaying an event trace cannot be done while it is also concurrently modified.

Resize(long, long)

Resize the current event memory buffer to the specified size.

Declaration

public bool Resize(long newBufferSize, long newMaxBufferSize = -1)

Parameters

Type	Name	Description
long	newBufferSize	Size to allocate for the buffer.
long	newMaxBufferSize	Optional parameter to specifying the mark up to which the buffer is allowed to grow. By default, this is negative which indicates the buffer should not grow. In this case, maxSizeInBytes will be set to newBufferSize. If this parameter is a non-negative number, it must be greater than or equal to newBufferSize and will become the new value for maxSizeInBytes.

Returns

Type	Description
bool	True if the new buffer was successfully allocated.

Exceptions

Type	Condition
ArgumentException	newBufferSize is negative.

WriteTo(Stream)

Write the contents of the event trace to the given stream.

Declaration

public void WriteTo(Stream stream)

Parameters

Type	Name	Description
Stream	stream	Stream to write the data to. Must support seeking (i.e. Stream.canSeek must be true).

Exceptions

Type	Condition
ArgumentNullException	stream is null.
ArgumentException	stream does not support seeking.
IOException	An error occurred trying to write to stream.

WriteTo(string)

Write the contents of the event trace to a file.

Declaration

public void WriteTo(string filePath)

Parameters

Type	Name	Description
string	filePath	Path of the file to write.

Exceptions

Type	Condition
ArgumentNullException	filePath is null or empty.
FileNotFoundException	filePath is invalid.
DirectoryNotFoundException	A directory in filePath is invalid.
UnauthorizedAccessException	filePath cannot be accessed.

See Also

ReadFrom(string)

Events

onEvent

Event that is triggered every time an event has been recorded in the trace.

Declaration

public event Action<InputEventPtr> onEvent

Event Type

Type	Description
Action<InputEventPtr>

Implements

IDisposable

IEnumerable<T>

IEnumerable