Class InputEventTrace.ReplayController
Controls replaying of events recorded in an InputEventTrace.
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
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
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()
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
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()
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
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.
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
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
.