Record and Playback

When you want to capture what happens visually during a simulation for further perusal, the best tool at your disposal is the recorder. A recording is not a complete sequence of the state of all objects in the simulation at all times. A recording contains only the kinematic data of the object during the simulation. In other words, to keep the recording light, simple and performant, we save only the position of objects during the recorded interval. These kinematic data can be replayed (playback) afterward resulting in a visual "replay" of the recorded simulation. You cannot, for example, pause a playback mid-way and start simulating from that point (re-starting simulation from a specific point in time is the role of the keyframe explained in another section of this guide). But it is the perfect tool if, for example, you want to save a student's performance in a particular scenario and review it later.

Setup

Use the Vortex Editor to add the recorder module to your application setup. In order to work properly, the Recorder module must be set on the Master node only. If you are using the Vortex Player UI page, the Record Playback Page can also be added to one of your nodes. The Vortex Player Console is using that page, see Record and Playback Tab.

Sending commands to the Recorder Module.

To control the recorder from inside your application, Vortex Studio SDK provides a convenient interface to its internal record and playback facilities called VxSim::KinematicRecorder, which is available from the ApplicationContext. Most methods of this class are asynchronous, ensuring no slow-down of your user interface, and all dispatch events to the internal objects running inside the simulation thread. Thus the KinematicRecorder can safely be called directly from UI callbacks such as a click of a button. To perform a recording, a file is needed. The KinematicRecorder API does not provide file management, it is up to the user to delete the files if needed. 

Using the KinematicRecorder to playback a recording changes the application mode to VxSim::kModePlayingBack. This is done automatically and you do not need to manually call VxApplication::setApplicationMode(), Your modules will get the application mode change callback as usual. . See Integrating the Application for details about the application mode.

The KinematicRecorder API

• open() is used for previously recorded files you want to play() and to create new empty files to which you will record(). The Recorder module always works with one file. Opening a file will stop any playback or recording and close the current file before opening a new file.  When recording, the file will always be appended. The result of recording multiple simulations into the same file, of playing back a recording on a different scene, is undefined. 

• close() closes the previously opened file. It will perform a stop if needed.

• The record() method is used to record the current simulation.

• The play() method is used to play the recording. It starts playing at the current frame index and plays 1 frame per update. This sets the application mode to kModePlayingBack and keeps a keyframe of the simulation. The key frame will be restored when leaving playback.

• The pause() method is used to suspend the current recording or playback. While recording, it actually stops and waits for a new instruction. In playback, the application mode remains kModePlayingBack.

• The setPlaySpeedMultiplier() method is used to play a recording at a faster pace than it was recorded. It can be called during a recording, it will only affect the next playback.

• The stop() method stops the current recording or playback. If the application is in playback mode, the mode before entering playback is restored and the saved key frame is restored to put back the simulation to where it was when the playback was started.

• The setCurrentFrameByIndex() is used to set the current playback frame by using the recorded frame index. Like play(), it changes the application mode to kModePlayingBack.

• The setCurrentFrameByTimestamp() is used to set the current playback frame by using the timestamp. If the given timestamp is not valid, it uses the nearest recorded timestamp.

• The getStatus() is used to get the recorder status. Since the KinematicRecorder behavior is asynchronous, the status of the recorder is not guaranteed to be updated immediately after an operation returns. The status contains the following information

  1. filename - The recorded resource filename.

  2. recorderMode - Indicates if the recording is playing, paused, recording, or idle. If there is no module, the mode will be not ready.

  3. openingMode - Indicates if the file is open for reading or writing. It always appends when writing. A file that is read-only cannot be written into and a record will fail. 

  4. lastErrorCode - The last error code, see enum KinematicRecorder::eErrorCode for details.

  5. playMultiplier - playback multiplier as set with setPlaySpeedMultiplier().

  6. first/current/lastFrameIndex - Indexes of the frames of the recording.
     
     

  7. first/current/lastFrameTimestamp- Timestamps of the frames of the recording.
     
     

  8. first/current/lastFrameSessionTime- VxApplication's Simulation times of the frames of the recording.

Stopping a playback or closing a file in playback which will set the application mode back to the value it used to be upon entering the VxSim::kModePlayingBack mode and restore the simulation as it was before entering playback.

When you are done using the KinematicRecorder's functionalities, you must call the close() method.

See the tutorial MechanismViewer for an example of a Keyboard extension using this API.