Class InputEventTrace.ReplayController

Controls replaying of events recorded in an InputEventTrace.

Inheritance

Object

InputEventTrace.ReplayController

Namespace: UnityEngine.InputSystem.LowLevel

Syntax

public class ReplayController : IDisposable

Remarks

Playback can be controlled either on a per-event or a per-frame basis. Note that playing back events frame by frame requires frame markers to be present in the trace (see recordFrameMarkers).

By default, events will be queued as is except for their timestamps which will be set to the current time that each event is queued at.

What this means is that events replay with the same device ID (see deviceId) they were captured on. If the trace is replayed in the same session that it was recorded in, this means that the events will replay on the same device (if it still exists).

To map recorded events to a different device, you can either call WithDeviceMappedFromTo(Int32, Int32) to map an arbitrary device ID to a new one or call WithAllDevicesMappedToNewInstances() to create new (temporary) devices for the duration of playback.

var trace = new InputEventTrace(myDevice);
trace.Enable();

// ... run one or more frames ...

trace.Replay().OneFrame();

Properties

createdDevices

List of devices created by the replay controller.

Declaration

public IEnumerable<InputDevice> createdDevices { get; }

Property Value

Type	Description
IEnumerable<InputDevice>	Devices created by the replay controller.

Remarks

By default, a replay controller will queue events as is, i.e. with deviceId of each event left as is. This means that the events will target existing devices (if any) that have the respective ID.

Using WithAllDevicesMappedToNewInstances(), a replay controller can be instructed to create new, temporary devices instead for each unique deviceId encountered in the stream. All devices created by the controller this way will be put on this list.

See Also

WithAllDevicesMappedToNewInstances()

finished

Whether replay has finished.

Declaration

public bool finished { get; }

Property Value

Type	Description
Boolean	True if replay has finished or is not in progress.

See Also

PlayAllFramesOneByOne()

PlayAllEvents()

paused

Whether replay is paused.

Declaration

public bool paused { get; set; }

Property Value

Type	Description
Boolean	True if replay is currently paused.

position

Current position in the event stream.

Declaration

public int position { get; }

Property Value

Type	Description
Int32	Index of current event in trace.

trace

The event trace associated with the replay controller.

Declaration

public InputEventTrace trace { get; }

Property Value

Type	Description
InputEventTrace	Trace from which events are replayed.

Methods

Dispose()

Removes devices created by the controller when using WithAllDevicesMappedToNewInstances().

Declaration

public void Dispose()

Implements

IDisposable.Dispose()

OnEvent(Action<InputEventPtr>)

Invoke the given callback when an event is about to be queued.

Declaration

public InputEventTrace.ReplayController OnEvent(Action<InputEventPtr> action)

Parameters

Type	Name	Description
Action<InputEventPtr>	action	A callback to invoke when an event is getting queued.

Returns

Type	Description
InputEventTrace.ReplayController	The same ReplayController instance.

OnFinished(Action)

Invoke the given callback when playback finishes.

Declaration

public InputEventTrace.ReplayController OnFinished(Action action)

Parameters

Type	Name	Description
Action	action	A callback to invoke when playback finishes.

Returns

Type	Description
InputEventTrace.ReplayController	The same ReplayController instance.

PlayAllEvents()

Go through all remaining event in the trace starting at the current read position and queue them using QueueEvent(InputEventPtr).

Declaration

public InputEventTrace.ReplayController PlayAllEvents()

Returns

Type	Description
InputEventTrace.ReplayController	The same ReplayController instance.

Remarks

Unlike methods such as PlayAllFramesOneByOne(), this method immediately queues events and immediately completes playback upon return from the method.

See Also

PlayAllFramesOneByOne()

PlayAllEventsAccordingToTimestamps()

PlayAllEventsAccordingToTimestamps()

Replay events in a way that tries to preserve the original timing sequence.

Declaration

public InputEventTrace.ReplayController PlayAllEventsAccordingToTimestamps()

Returns

Type	Description
InputEventTrace.ReplayController	The same ReplayController instance.

Remarks

This method will take the current time as the starting time to which make all events relative to. Based on this time, it will try to correlate the original event timing with the timing of input updates as they happen. When successful, this will compensate for differences in frame timings compared to when input was recorded and instead queue input in frames that are closer to the original timing.

Note that this method will perform one initial scan of the trace to determine a linear ordering of the events by time (the input system does not require any such ordering on the events in its queue and thus events in a trace, especially if there are multiple devices involved, may be out of order).

See Also

PlayAllFramesOneByOne()

PlayAllEvents()

PlayAllFramesOneByOne()

Replay all frames one by one from the current playback position.

Declaration

public InputEventTrace.ReplayController PlayAllFramesOneByOne()

Returns

Type	Description
InputEventTrace.ReplayController	The same ReplayController instance.

Remarks

Events will be fed to the input system from within onBeforeUpdate. Each update will receive events for one frame.

Note that for this method to correctly space out events and distribute them to frames, frame markers must be present in the trace (see recordFrameMarkers). If not present, all events will be fed into first frame.

See Also

recordFrameMarkers

onBeforeUpdate

PlayAllEvents()

PlayAllEventsAccordingToTimestamps()

PlayOneEvent()

Takes the next event from the trace and queues it.

Declaration

public InputEventTrace.ReplayController PlayOneEvent()

Returns

Type	Description
InputEventTrace.ReplayController	The same ReplayController instance.

Remarks

This method takes the next event at the current read position and queues it using QueueEvent(InputEventPtr). The read position is advanced past the taken event.

Frame marker events (see FrameMarkerEvent) are skipped.

Exceptions

Type	Condition
InvalidOperationException	There are no more events in the trace -or- the only events left are frame marker events (see FrameMarkerEvent).

Rewind()

Rewind playback all the way to the beginning of the event trace.

Declaration

public InputEventTrace.ReplayController Rewind()

Returns

Type	Description
InputEventTrace.ReplayController	The same ReplayController instance.

WithAllDevicesMappedToNewInstances()

For all events, create new devices to replay the events on instead of replaying the events on existing devices.

Declaration

public InputEventTrace.ReplayController WithAllDevicesMappedToNewInstances()

Returns

Type	Description
InputEventTrace.ReplayController	The same ReplayController instance.

Remarks

Note that devices created by the ReplayController will stick around for as long as the replay controller is not disposed of. This means that multiple successive replays using the same ReplayController will replay the events on the same devices that were created on the first replay. It also means that in order to do away with the created devices, it is necessary to call Dispose().

See Also

Dispose()

createdDevices

WithDeviceMappedFromTo(Int32, Int32)

Replace deviceId values of events that are equal to recordedDeviceId with device ID playbackDeviceId.

Declaration

public InputEventTrace.ReplayController WithDeviceMappedFromTo(int recordedDeviceId, int playbackDeviceId)

Parameters

Type	Name	Description
Int32	recordedDeviceId	deviceId to map from.
Int32	playbackDeviceId	deviceId to map to.

Returns

Type	Description
InputEventTrace.ReplayController	The same ReplayController instance.

WithDeviceMappedFromTo(InputDevice, InputDevice)

Replay events recorded from recordedDevice on device playbackDevice.

Declaration

public InputEventTrace.ReplayController WithDeviceMappedFromTo(InputDevice recordedDevice, InputDevice playbackDevice)

Parameters

Type	Name	Description
InputDevice	recordedDevice	Device events have been recorded from.
InputDevice	playbackDevice	Device events should be played back on.

Returns

Type	Description
InputEventTrace.ReplayController	The same ReplayController instance.

Remarks

This method causes all events with a device ID (see deviceId and deviceId) corresponding to the one of to be queued with the device ID of playbackDevice.

Exceptions

Type	Condition
ArgumentNullException	recordedDevice is null -or- playbackDevice is null.

See Also

Replay()