#include <ImFusion/Stream/StreamRecorder.h>

Abstract base class for stream recorders. More...

Inheritance diagram for StreamRecorder:

Detailed Description

Abstract base class for stream recorders.

A StreamRecorder processes the StreamData emitted by the input Stream and aggregates the individual elements into one or more containers of type Data (e.g., SharedImageSet, TrackingSequence).

StreamRecorders do not write directly to disk; instead, recorded data is stored in memory.

Upon construction, the StreamRecorder is idle. Recording begins by calling start(), which creates a new output container and initiates data collection.

When stop() is called, the recording ends and the current output container is finalized. It can be retrieved via takeOutput(). The StreamRecorder can then be restarted for a new recording session.

See Stream Recording Overview for an overview of the control sequence.

Public Types
enum	CaptureMode { CaptureAll = 0 , OnRequest = 1 }

Public Member Functions
	StreamRecorder (Stream &stream)
	Constructs a StreamRecorder for the specified input stream. Recording is not started automatically.

void	start ()
	Starts recording if not already recording.

void	stop ()
	Stops recording if currently recording.

virtual OwningDataList	takeOutput ()=0
	Returns the recorded output as an OwningDataList.

bool	isRecording () const
	Returns true if a recording is currently in progress.

bool	allStreamsRunning () const
	Returns true if all streams being recorded are currently active.

virtual Stream &	stream () const
	Returns the recorded Stream instance.

void	setTimeLimit (double seconds)
	Sets the maximum duration of a recording session (in seconds).

void	setSystemMemoryLimit (double maxMemoryFraction)
	Sets the maximum fraction of available system memory allowed for recording [0.0-1.0].

void	setSamplesLimit (int maxSamples)
	Sets the maximum number of samples (frames, tracking data, etc.) to record.

void	setRecordedBytesLimit (size_t maxBytes)
	Sets the maximum number of recorded bytes.

size_t	recordedBytesLimit () const
	Returns the configured maximum number of recorded bytes. Zero if no limit is set.

double	passedTime () const
	Returns the duration of the current or most recent recording session (in seconds).

int	recordedSamples () const
	Returns the number of samples recorded during the current or most recent session.

bool	hasReachedLimit () const
	Returns true if any recording limit (time, memory, samples, bytes) was reached.

bool	hasReachedMemoryLimit () const
	Returns true if the memory limit was specifically reached during recording.

size_t	recordedBytes () const
	Returns the number of bytes recorded during the current or most recent session.

void	setUseDeviceTimestamp (bool flag)
	Specifies whether to record the device timestamp or the arrival timestamp.

bool	usesDeviceTimestamps () const
	Returns true if device timestamps are recorded instead of arrival timestamps.

void	setRecordBothTimestamps (bool flag)
	Sets whether both device and arrival timestamps should be recorded.

bool	recordBothTimestamps () const
	Returns true if both timestamp types will be recorded in a TimestampDataComponent.

void	setCaptureMode (CaptureMode captureMode)
	Sets the desired capture mode.

CaptureMode	captureMode () const
	Returns the current capture mode.

void	setCaptureNextSample ()
	Requests the recording of the next StreamData emitted by the Stream.

Public Attributes
ProtectedSignal< StreamRecorder * >	signalLimitReached
	Signal emitted when recording has stopped due to a limit being reached.

ProtectedSignal< StreamRecorder *, size_t >	recordedBytesChanged
	Signal emitted whenever the recorded byte count changes (i.e. a new sample is added).

Protected Member Functions
double	extractTimestamp (const StreamData *data)
	Extracts either the device or arrival timestamp from the given StreamData, based on m_useDeviceTimestamp.

virtual void	init ()=0
	Prepares everything necessary for recording. Called by start().

virtual void	finalize ()=0
	Finalizes the recording session, preparing the recorded data to be retrieved via takeOutput(). Automatically called by stop().

virtual size_t	processStreamData (const StreamData &data)=0
	Handles incoming StreamData.

virtual void	recordFrameDataComponents (ElementwiseDataComponentList &ewdcl, const StreamData &streamDataWithDCs, int finalContainerSize)
	Copies the DataComponents from streamDataWithDCs and appends them to the provided ElementwiseDataComponentList (ewdcl), continuing until the container reaches the specified final size (finalContainerSize).

void	resetRecordingStatistics ()
	Resets the recorded samples counter m_samplesRead and recorded byte counter m_recordedBytes to Zero and the m_limitReached flag to false.

Member Enumeration Documentation

◆ CaptureMode

enum CaptureMode

Enumerator
CaptureAll	Captures every newly available sample.
OnRequest	Captures samples upon explicit user request.

Member Function Documentation

◆ start()

void start ( )

Starts recording if not already recording.

Calls init() to prepare the output container. If the previously recorded container was not taken, it is discarded.

Note: Automatically starts the Stream if a time limit is specified via setTimeLimit(). Otherwise, no recording is happening as long as the Stream is stopped.

◆ stop()

void stop ( )

Stops recording if currently recording.

Calls finalize() to perform clean-up or finalize data, such as adding DataComponents.

◆ takeOutput()

virtual OwningDataList takeOutput ( )

pure virtual

Returns the recorded output as an OwningDataList.

Depending on the input stream, it may contain one or multiple data containers.

Implemented in ImageStreamRecorder, and TrackingStreamRecorder.

◆ allStreamsRunning()

bool allStreamsRunning ( ) const

Returns true if all streams being recorded are currently active.

Deprecated: "Query stream state directly from Stream"

◆ stream()

virtual Stream & stream ( ) const

virtual

Returns the recorded Stream instance.

Reimplemented in ImageStreamRecorder, and TrackingStreamRecorder.

◆ setTimeLimit()

void setTimeLimit ( double seconds )

Sets the maximum duration of a recording session (in seconds).

Set to zero for unlimited duration. Must be called before start(); otherwise, it is ignored. If the time limit is reached, recording will stop automatically.

◆ setSystemMemoryLimit()

void setSystemMemoryLimit ( double maxMemoryFraction )

Sets the maximum fraction of available system memory allowed for recording [0.0-1.0].

Zero disables the limit. Must be called before start(); otherwise, it is ignored. If memory usage exceeds the specified fraction, recording stops automatically.

◆ setSamplesLimit()

void setSamplesLimit ( int maxSamples )

Sets the maximum number of samples (frames, tracking data, etc.) to record.

Zero disables the limit. Must be called before start(); otherwise, it is ignored. If the sample count exceeds the limit, recording stops automatically.

◆ setRecordedBytesLimit()

void setRecordedBytesLimit ( size_t maxBytes )

Sets the maximum number of recorded bytes.

Zero disables the limit. Must be called before start(); otherwise, it is ignored. If the byte count exceeds the limit, recording stops automatically.