#include <ImFusion/Stream/PlaybackStreamBase.h>

Base class for various playback streams. More...

Detailed Description

template<typename T>
class ImFusion::PlaybackStreamBase< T >

Base class for various playback streams.

A playback stream converts a sequence of images or tracking positions into a continuous stream, which can be used in real-time streaming algorithms. An internal playbackTimer controls the stream timing. This class provides basic playback features, such as looping and playback speed adjustment.

The playback behavior depends on the timestamp validity mode, which is determined automatically from the input data. There are three possible timestamp modes:

NoTimestampsOrInvalid: The data has no timestamps or timestamps failed validation. In this mode, only FPS-based playback is available. Speed factor is inactive.
TimestampsValidAndEquidistant: Timestamps are valid and the intervals between consecutive frames are approximately equal (within 5% tolerance). Both FPS and speed factor modes are available and can be used interchangeably. When setting FPS, the corresponding speed factor is automatically calculated, and vice versa.
TimestampsValidAndIrregular: Timestamps are valid but intervals vary significantly. Both FPS and speed factor modes are available, but they operate independently without automatic conversion between them.

Playback can be controlled in two ways:

FPS mode: Set a fixed frames-per-second rate for playback. This is always available, regardless of timestamp validity.
Speed factor mode: Set a multiplier relative to the original playback speed (1.0 = normal speed, 2.0 = double speed, 0.5 = half speed). This mode is only available when timestamps are valid.

To update parameters, the derived stream must be restarted, and this base class requires access to the derived type. The CRTP (Curiously Recurring Template Pattern) is used for this purpose.

Public Types
enum class	TimestampsValidity { NoTimestampsOrInvalid = 0 , TimestampsValidAndEquidistant = 1 , TimestampsValidAndIrregular = 2 }
	Timestamp validity modes that determine playback behavior. More...

Public Member Functions
	PlaybackStreamBase (Stream *parentStream=nullptr)
void	setLoop (bool loop)
	Set whether the playback should loop when reaching the end.
bool	loop () const
	Get whether the playback is set to loop.
virtual void	setFps (const double fps)
	Set the playback frame rate in frames per second.
std::optional< double >	fps () const
	Get the current playback frame rate.
virtual void	setSpeedFactor (double const factor)
	Set the playback speed factor relative to the original playback speed.
std::optional< double >	speedFactor () const
	Get the current playback speed factor.
std::optional< double >	calculatedInitialFps () const
	Get the calculated initial frame rate from equidistant timestamps.
void	jumpToFocus (int focusFrame)
	Jump to a specific frame in the playback sequence.
int	playbackFocus () const
	Get the current playback frame index.
void	setSkipDelayedFrames (bool value)
	Set whether to skip frames in case their subsequent frame is already due.
bool	isSkippingDelayedFrames () const
	Return whether to skip frames in case their subsequent frame is already due.
void	setUseAbsoluteTimesteps (bool value)
	Set whether to use absolute timesteps for playback timing.
bool	useAbsoluteTimesteps () const
	Get whether absolute timesteps are being used.
TimestampsValidity	timestampsValidity () const

Public Attributes
Signal	signalPlaybackTimestampsChanged
	Signal emitted when playback timestamp parameters have changed.

Protected Member Functions
bool	startPlaybackTimer ()
	Start the internal playback timer, if not already running.
void	setTimestamps (const int numberOfRequiredSamples, const std::optional< std::vector< double > > inputData)
	Set input timestamps and initialize playback timing parameters.

Protected Attributes
Stream *	m_parentStream = nullptr
	If optional parent stream is set, stream data emission is triggered by parent stream.
std::unique_ptr< Threading::PlaybackTimer >	m_playbackTimer
	Core time controller for the playback stream.
int	m_frame {0}
	Save the current focus frame index.
TimestampsValidity	m_timestampsValidity
	check for the validity of the timestamps on the childer classes

Member Enumeration Documentation

◆ TimestampsValidity

template<typename T>

enum class ImFusion::PlaybackStreamBase::TimestampsValidity

strong

Timestamp validity modes that determine playback behavior.

Enumerator
NoTimestampsOrInvalid	The sample either has no timestamp or timestamps failed the validity test.
TimestampsValidAndEquidistant	Timestamps are valid and regular: consecutive timestamp differences must not differ by more than 5% (see equidistantTolerance).
TimestampsValidAndIrregular	Timestamps are valid and the distance between them is not the same.

Member Function Documentation

◆ setLoop()

template<typename T>

void ImFusion::PlaybackStreamBase< T >::setLoop ( bool loop )

inline

Set whether the playback should loop when reaching the end.

Parameters

loop	True to enable looping, false to disable.

◆ loop()

template<typename T>

bool ImFusion::PlaybackStreamBase< T >::loop ( ) const

inline

Get whether the playback is set to loop.

Returns: True if looping is enabled, false otherwise.

◆ setFps()

template<typename T>

virtual void ImFusion::PlaybackStreamBase< T >::setFps ( const double fps )

inlinevirtual

Set the playback frame rate in frames per second.

This method is available in all timestamp validity modes. The behavior depends on the current timestamp mode:

NoTimestampsOrInvalid: Sets the FPS directly. Speed factor is cleared and becomes inactive. Playback uses evenly spaced timestamps based on the specified FPS.
TimestampsValidAndEquidistant: Sets the FPS and automatically calculates the corresponding speed factor based on the original frame rate. The speed factor is computed as: new_fps / original_fps. Both FPS and speed factor are kept in sync.
TimestampsValidAndIrregular: Sets the FPS directly. Speed factor is cleared. Playback uses the original timestamps scaled by the FPS ratio.

If a parent playback stream exists, the FPS is set on the parent instead. The stream is automatically restarted if it is currently running.

Parameters

fps	The desired frame rate in frames per second. Must be greater than 0.001.

◆ fps()

template<typename T>

std::optional< double > ImFusion::PlaybackStreamBase< T >::fps ( ) const

inline

Get the current playback frame rate.

Returns: The current FPS setting, or empty optional if FPS has not been set or speed factor mode is active.

◆ setSpeedFactor()

template<typename T>

virtual void ImFusion::PlaybackStreamBase< T >::setSpeedFactor ( double const factor )

inlinevirtual

Set the playback speed factor relative to the original playback speed.

The speed factor is a multiplier: 1.0 = normal speed, 2.0 = double speed, 0.5 = half speed. This method is only available when timestamps are valid. The behavior depends on the current timestamp mode:

NoTimestampsOrInvalid: This method has no effect. A warning is logged and the call is ignored. Use setFps() instead for this mode.
TimestampsValidAndEquidistant: Sets the speed factor and automatically calculates the corresponding FPS based on the original frame rate. The FPS is computed as: original_fps * speed_factor. Both FPS and speed factor are kept in sync.
TimestampsValidAndIrregular: Sets the speed factor directly. FPS is cleared. Playback uses the original timestamps divided by the speed factor.

If a parent playback stream exists, the speed factor is set on the parent instead. The stream is automatically restarted if it is currently running.

Parameters

factor The speed multiplier. Must be greater than 0.001.

◆ speedFactor()

template<typename T>

std::optional< double > ImFusion::PlaybackStreamBase< T >::speedFactor ( ) const

inline

Get the current playback speed factor.

Returns: The current speed factor setting, or empty optional if speed factor has not been set, FPS mode is active, or timestamps are invalid.

◆ calculatedInitialFps()

template<typename T>

std::optional< double > ImFusion::PlaybackStreamBase< T >::calculatedInitialFps ( ) const

inline

Get the calculated initial frame rate from equidistant timestamps.

This value is only available when timestamps are valid and equidistant. It represents the frame rate calculated from the average time interval between consecutive frames in the input data. This value is used as the baseline for speed factor calculations in equidistant timestamp mode.

Returns: The calculated FPS from equidistant timestamps, or empty optional if timestamps are not equidistant or invalid.

◆ jumpToFocus()

template<typename T>

void ImFusion::PlaybackStreamBase< T >::jumpToFocus ( int focusFrame )

inline

Jump to a specific frame in the playback sequence.

If the stream is currently running, it will be stopped, the frame position updated, and then restarted. If the stream is not running, only the frame position is updated.

Parameters

focusFrame The frame index to jump to.

◆ playbackFocus()

template<typename T>

int ImFusion::PlaybackStreamBase< T >::playbackFocus ( ) const

inline

Get the current playback frame index.

Returns: The current frame index (0-based).

◆ setSkipDelayedFrames()

template<typename T>

void ImFusion::PlaybackStreamBase< T >::setSkipDelayedFrames ( bool value )

inline

Set whether to skip frames in case their subsequent frame is already due.

This can for instance happen if the time between frames is less than the time needed to process the callback.

◆ setUseAbsoluteTimesteps()

template<typename T>

void ImFusion::PlaybackStreamBase< T >::setUseAbsoluteTimesteps ( bool value )

inline

Set whether to use absolute timesteps for playback timing.

When enabled, the current system time is not taken into account, and the timer will wait for an amount of time equal to the difference between consecutive timestamps. In this mode, all frames will be played regardless of processing delays. When disabled, the timer accounts for the current system time and may skip frames if processing is delayed.

Parameters

value True to use absolute timesteps, false to account for system time.

◆ useAbsoluteTimesteps()

template<typename T>

bool ImFusion::PlaybackStreamBase< T >::useAbsoluteTimesteps ( ) const

inline

Get whether absolute timesteps are being used.

Returns: True if absolute timesteps are enabled, false otherwise.

◆ startPlaybackTimer()

template<typename T>

bool ImFusion::PlaybackStreamBase< T >::startPlaybackTimer ( )

inlineprotected

Start the internal playback timer, if not already running.

Configures the timer range from the timestamps previously provided via setTimestamps() and the current playback timing settings (FPS / speed factor), then starts the timer at the current focus frame.

Derived streams typically call this from their startImpl() implementation after any stream-specific preparation (e.g. making sure image data is ready on CPU).

◆ setTimestamps()

template<typename T>

void ImFusion::PlaybackStreamBase< T >::setTimestamps	(	const int	numberOfRequiredSamples,
		const std::optional< std::vector< double > >	inputData )

inlineprotected

Set input timestamps and initialize playback timing parameters.

This method must be called by derived streams before starting playback. It stores the timestamp vector (seconds), validates it (equidistant vs irregular), initializes default playback parameters for the inferred timestamp mode, and emits signalPlaybackTimestampsChanged.

Parameters

numberOfRequiredSamples	Number of samples/frames in the playback sequence.
inputData	Optional timestamp vector in seconds. If empty, playback operates in FPS mode with generated equidistant timestamps.

Member Data Documentation

◆ signalPlaybackTimestampsChanged

template<typename T>

Signal ImFusion::PlaybackStreamBase< T >::signalPlaybackTimestampsChanged

Signal emitted when playback timestamp parameters have changed.

This signal is emitted whenever FPS or speed factor are modified, which affects the playback timestamps.

The documentation for this class was generated from the following file:

ImFusion/Stream/PlaybackStreamBase.h

Detailed Description

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Member Enumeration Documentation

◆ TimestampsValidity

Member Function Documentation

◆ setLoop()

◆ loop()

◆ setFps()

◆ fps()

◆ setSpeedFactor()

◆ speedFactor()

◆ calculatedInitialFps()

◆ jumpToFocus()

◆ playbackFocus()

◆ setSkipDelayedFrames()

◆ setUseAbsoluteTimesteps()

◆ useAbsoluteTimesteps()

◆ startPlaybackTimer()

◆ setTimestamps()

Member Data Documentation

◆ signalPlaybackTimestampsChanged