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.
Namespace: UnityEngine.InputSystem.LowLevel
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(Int64, Boolean, Int64, Int64)
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 = 1048576L, bool growBuffer = false, long maxBufferSizeInBytes = -1L, long growIncrementSizeInBytes = -1L)
Parameters
Type | Name | Description |
---|---|---|
Int64 | bufferSizeInBytes | Size of buffer that will be allocated on first event captured by trace. Defaults to 1MB. |
Boolean | growBuffer | If true, the event buffer will be grown automatically when it reaches capacity, up to a maximum
size of |
Int64 | maxBufferSizeInBytes | If |
Int64 | growIncrementSizeInBytes |
InputEventTrace(InputDevice, Int64, Boolean, Int64, Int64)
Declaration
public InputEventTrace(InputDevice device, long bufferSizeInBytes = 1048576L, bool growBuffer = false, long maxBufferSizeInBytes = -1L, long growIncrementSizeInBytes = -1L)
Parameters
Type | Name | Description |
---|---|---|
InputDevice | device | |
Int64 | bufferSizeInBytes | |
Boolean | growBuffer | |
Int64 | maxBufferSizeInBytes | |
Int64 | growIncrementSizeInBytes |
Properties
allocatedSizeInBytes
Total size of memory buffer (in bytes) currently allocated.
Declaration
public long allocatedSizeInBytes { get; }
Property Value
Type | Description |
---|---|
Int64 | 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 |
---|---|
Int32 |
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 |
---|---|
Boolean | True if the trace is currently recording events. |
See Also
eventCount
Total number of events currently in the trace.
Declaration
public long eventCount { get; }
Property Value
Type | Description |
---|---|
Int64 | Number of events recorded in the trace. |
FrameMarkerEvent
If
Declaration
public static FourCC FrameMarkerEvent { get; }
Property Value
Type | Description |
---|---|
FourCC |
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 |
---|---|
Int64 | 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, Boolean> | 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 |
---|---|
Boolean | 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
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 |
---|---|
Int64 | 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
Dispose()
Stop recording, if necessary, and clear the trace such that it released unmanaged memory which might be allocated.
Declaration
public void Dispose()
Implements
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
GetEnumerator()
Declaration
public IEnumerator<InputEventPtr> GetEnumerator()
Returns
Type | Description |
---|---|
IEnumerator<InputEventPtr> |
Implements
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 |
Returns
Type | Description |
---|---|
Boolean | True if |
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 |
|
ArgumentNullException |
|
IOException | The stream cannot be loaded (e.g. wrong format; details in the exception). |
See Also
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 |
|
FileNotFoundException |
|
DirectoryNotFoundException | A directory in |
UnauthorizedAccessException |
|
See Also
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 |
|
ArgumentException |
|
IOException | An error occurred trying to read from |
See Also
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 |
|
FileNotFoundException |
|
DirectoryNotFoundException | A directory in |
UnauthorizedAccessException |
|
See Also
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(Int64, Int64)
Resize the current event memory buffer to the specified size.
Declaration
public bool Resize(long newBufferSize, long newMaxBufferSize = -1L)
Parameters
Type | Name | Description |
---|---|---|
Int64 | newBufferSize | Size to allocate for the buffer. |
Int64 | 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 |
Returns
Type | Description |
---|---|
Boolean | True if the new buffer was successfully allocated. |
Exceptions
Type | Condition |
---|---|
ArgumentException |
|
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. |
Exceptions
Type | Condition |
---|---|
ArgumentNullException |
|
ArgumentException |
|
IOException | An error occurred trying to write to |
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 |
|
FileNotFoundException |
|
DirectoryNotFoundException | A directory in |
UnauthorizedAccessException |
|
See Also
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> |
Explicit Interface Implementations
IEnumerable.GetEnumerator()
Declaration
IEnumerator IEnumerable.GetEnumerator()
Returns
Type | Description |
---|---|
IEnumerator |