Timestamps allow specifying points in time and measuring time intervals with a sub-millisecond granularity. More...

#include <timestamp.h>

Public Member Functions
	Timestamp (uint64 msecs=0, uint64 framerate=1)
	Set up a timestamp with a given time and framerate. More...

	Timestamp (uint64 secs, uint64 frames, uint64 framerate)
	Set up a timestamp with a given time, frames and framerate. More...

	Timestamp (uint64 secs, uint64 frames, const Rational &framerate)
	Set up a timestamp with a given time, frames and framerate. More...

Timestamp	convertToFramerate (uint64 newFramerate) const
	Return a timestamp which represents as closely as possible the point in time describes by this timestamp, but with a different framerate. More...

bool	operator== (const Timestamp &ts) const
	Check whether to timestamps describe the exact same moment in time. More...

bool	operator!= (const Timestamp &ts) const

bool	operator< (const Timestamp &ts) const

bool	operator<= (const Timestamp &ts) const

bool	operator> (const Timestamp &ts) const

bool	operator>= (const Timestamp &ts) const

Timestamp	addFrames (int64 frames) const
	Returns a new timestamp, which corresponds to the time encoded by this timestamp with the given number of frames added. More...

Timestamp	addMsecs (int64 msecs) const
	Returns a new timestamp, which corresponds to the time encoded by this timestamp with the given number of milliseconds added. More...

Timestamp	operator- () const

Timestamp	operator+ (const Timestamp &ts) const
	Compute the sum of two timestamps. More...

Timestamp	operator- (const Timestamp &ts) const
	Compute the difference between two timestamps. More...

int64	frameDiff (const Timestamp &ts) const
	Computes the number of frames between this timestamp and ts. More...

int64	msecsDiff (const Timestamp &ts) const
	Computes the number off milliseconds between this timestamp and ts. More...

int64	msecs () const
	Return the time in milliseconds described by this timestamp, rounded down. More...

int64	secs () const
	Return the time in seconds described by this timestamp, rounded down. More...

int64	totalNumberOfFrames () const
	Return the time in frames described by this timestamp. More...

int64	numberOfFrames () const
	A timestamp consists of a number of seconds, plus a number of frames, the latter describing a fraction of a second. More...

uint64	framerate () const
	Return the framerate used by this timestamp. More...

Protected Member Functions
int64	cmp (const Timestamp &ts) const
	Compare this timestamp to another one and return a value similar to strcmp. More...

void	normalize ()
	Normalize this timestamp by making _numFrames non-negative and reducing it modulo _framerate. More...

void	addIntern (const Timestamp &ts)
	Add another timestamp to this one and normalize the result. More...

Protected Attributes
int64	_secs
	The seconds part of this timestamp. More...

int64	_numFrames
	The number of frames which together with _secs encodes the timestamp. More...

uint64	_framerate
	The internal framerate, i.e. More...

uint64	_framerateFactor
	Factor by which the original framerate specified by the client code was multipled to obtain the internal _framerate value. More...

Detailed Description

Timestamps allow specifying points in time and measuring time intervals with a sub-millisecond granularity.

When dealing with audio and video decoding, it is often necessary to measure time (intervals) in terms of frames, relative to a fixed frame rate (that is, a fixed number of frames per seconds). For example, in a typical video there are 24 frames per second, and in a typical sound there are 44100 frames (i.e. samples for mono sound and pairs of samples for stereo) per second.

At the same time, the system clock provided by ScummVM measures time in milliseconds. For syncing purposes and other reasons, it is often necessary to convert between and compare time measures given on the one hand as a frame count, and on the other hand as a number of milliseconds.

If handled carelessly, this can introduce rounding errors that quickly accumulate, resulting in user noticeable disturbance, such as audio and video running out of sync. E.g. a typical approach is to measure all time in milliseconds. But with a frame rate of 24 frames per second, one frame is 41.66666... milliseconds long. On the other hand, if measuring in frames, then similar rounding issue occur when converting from milliseconds to frames.

One solution is to use floating point arithmetic to compute with fractional frames resp. (milli)seconds. This has other undesirable side effects; foremost, some platforms ScummVM runs on still have only limited (and slow) floating point support.

This class provides an alternate solution: It stores time in terms of frames, but with a twist: Client code can specify arbitrary (integral) framerates; but internally, Timestamp modifies the framerate to be a multiple of 1000. This way, both numbers of frames (relative to the original framerate) as well as milliseconds can be represented as integers. This change is completely hidden from the user, however.

A Timestamp can be converted to a frame count or milliseconds at virtually no cost. Likewise, it is posible to compute the difference between two Timestamps in milliseconds or number of frames. Timestamps can be easily compared using regular comparison operators, resulting in nicely readable code; this is even possible for timestamps that are specified using different framerates. Client code can modify Timestamps by adding a number of frames to it, or adding a number of milliseconds. Adding negative amounts is also allowed, and a Timestamp can even represent a "negative time" (mainly useful when using the Timestamp to store a time interval).

Definition at line 108 of file timestamp.h.

Constructor & Destructor Documentation

◆ Timestamp() [1/3]

Common::Timestamp::Timestamp	(	uint64	msecs = `0`,
		uint64	framerate = `1`
	)

Set up a timestamp with a given time and framerate.

Parameters

msecs	starting time in milliseconds
framerate	number of frames per second (must be > 0)

Definition at line 57 of file timestamp.cpp.

References _framerate, _framerateFactor, _numFrames, and _secs.

◆ Timestamp() [2/3]

Common::Timestamp::Timestamp	(	uint64	secs,
		uint64	frames,
		uint64	framerate
	)

Set up a timestamp with a given time, frames and framerate.

Parameters

secs	starting time in seconds
frames	starting frames
framerate	number of frames per second (must be > 0)

Definition at line 69 of file timestamp.cpp.

References _framerate, _framerateFactor, _numFrames, and _secs.

◆ Timestamp() [3/3]

Common::Timestamp::Timestamp	(	uint64	secs,
		uint64	frames,
		const Rational &	framerate
	)

Set up a timestamp with a given time, frames and framerate.

Parameters

secs	starting time in seconds
frames	starting frames
framerate	number of frames per second (must be > 0)

Definition at line 79 of file timestamp.cpp.

References _framerate, _framerateFactor, _numFrames, _secs, Common::Rational::getDenominator(), Common::Rational::getInverse(), and Common::Rational::getNumerator().

Here is the call graph for this function:

Member Function Documentation

◆ addFrames()

Timestamp Common::Timestamp::addFrames ( int64 frames ) const

Returns a new timestamp, which corresponds to the time encoded by this timestamp with the given number of frames added.

Parameters

frames number of frames to add

Definition at line 179 of file timestamp.cpp.

References _framerateFactor, _numFrames, and normalize().

Referenced by Video::VideoDecoder::VideoTrack::getFrameTime().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ addIntern()

void Common::Timestamp::addIntern ( const Timestamp & ts )

protected

Add another timestamp to this one and normalize the result.

Definition at line 201 of file timestamp.cpp.

References _framerate, _numFrames, _secs, and normalize().

Referenced by operator+(), and operator-().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ addMsecs()

Timestamp Common::Timestamp::addMsecs ( int64 msecs ) const

Returns a new timestamp, which corresponds to the time encoded by this timestamp with the given number of milliseconds added.

Parameters

msecs number of milliseconds to add

Definition at line 190 of file timestamp.cpp.

References _framerate, _numFrames, _secs, and normalize().

Here is the call graph for this function:

◆ cmp()

int64 Common::Timestamp::cmp ( const Timestamp & ts ) const

protected

Compare this timestamp to another one and return a value similar to strcmp.

Definition at line 162 of file timestamp.cpp.

References _framerate, _numFrames, _secs, and Common::gcd().

Referenced by operator!=(), operator<(), operator<=(), operator==(), operator>(), and operator>=().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ convertToFramerate()

Timestamp Common::Timestamp::convertToFramerate ( uint64 newFramerate ) const

Return a timestamp which represents as closely as possible the point in time describes by this timestamp, but with a different framerate.

Definition at line 98 of file timestamp.cpp.

References _framerate, _framerateFactor, _numFrames, framerate(), Common::gcd(), and normalize().

Referenced by Video::QuickTimeDecoder::QuickTimeAudioTrack::queueAudio().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ frameDiff()

int64 Common::Timestamp::frameDiff ( const Timestamp & ts ) const

Computes the number of frames between this timestamp and ts.

The frames are with respect to the framerate used by this Timestamp (which may differ from the framerate used by ts).

Definition at line 231 of file timestamp.cpp.

References _framerate, _framerateFactor, _numFrames, _secs, and Common::gcd().

Here is the call graph for this function:

◆ framerate()

uint64 Common::Timestamp::framerate ( ) const

inline

Return the framerate used by this timestamp.

Definition at line 223 of file timestamp.h.

References _framerate, and _framerateFactor.

Referenced by convertToFramerate(), and Video::VideoDecoder::FixedRateVideoTrack::getFrameAtTime().

Here is the caller graph for this function:

◆ msecs()

int64 Common::Timestamp::msecs ( ) const

Return the time in milliseconds described by this timestamp, rounded down.

Definition at line 261 of file timestamp.cpp.

References _framerate, _numFrames, and _secs.

Referenced by msecsDiff().

Here is the caller graph for this function:

◆ msecsDiff()

int64 Common::Timestamp::msecsDiff ( const Timestamp & ts ) const

Computes the number off milliseconds between this timestamp and ts.

Definition at line 257 of file timestamp.cpp.

References msecs().

Here is the call graph for this function:

◆ normalize()

void Common::Timestamp::normalize ( )

protected

Normalize this timestamp by making _numFrames non-negative and reducing it modulo _framerate.

Definition at line 124 of file timestamp.cpp.

References _framerate, _numFrames, and _secs.

Referenced by addFrames(), addIntern(), addMsecs(), convertToFramerate(), and operator-().

Here is the caller graph for this function:

◆ numberOfFrames()

int64 Common::Timestamp::numberOfFrames ( ) const

inline

A timestamp consists of a number of seconds, plus a number of frames, the latter describing a fraction of a second.

This method returns the latter number.

Definition at line 218 of file timestamp.h.

References _framerateFactor, and _numFrames.

◆ operator!=()

bool Common::Timestamp::operator!= ( const Timestamp & ts ) const

Definition at line 142 of file timestamp.cpp.

References cmp().

Here is the call graph for this function:

◆ operator+()

Timestamp Common::Timestamp::operator+ ( const Timestamp & ts ) const

Compute the sum of two timestamps.

This is only allowed if they use the same framerate.

Definition at line 219 of file timestamp.cpp.

References addIntern().

Here is the call graph for this function:

◆ operator-() [1/2]

Timestamp Common::Timestamp::operator- ( ) const

Definition at line 211 of file timestamp.cpp.

References _numFrames, _secs, and normalize().

Here is the call graph for this function:

◆ operator-() [2/2]

Timestamp Common::Timestamp::operator- ( const Timestamp & ts ) const

Compute the difference between two timestamps.

This is only allowed if they use the same framerate.

Definition at line 225 of file timestamp.cpp.

References addIntern().

Here is the call graph for this function:

◆ operator<()

bool Common::Timestamp::operator< ( const Timestamp & ts ) const

Definition at line 146 of file timestamp.cpp.

References cmp().

Here is the call graph for this function:

◆ operator<=()

bool Common::Timestamp::operator<= ( const Timestamp & ts ) const

Definition at line 150 of file timestamp.cpp.

References cmp().

Here is the call graph for this function:

◆ operator==()

bool Common::Timestamp::operator== ( const Timestamp & ts ) const

Check whether to timestamps describe the exact same moment in time.

This means that two timestamps can compare as equal even if they use different framerates.

Definition at line 138 of file timestamp.cpp.

References cmp().

Here is the call graph for this function:

◆ operator>()

bool Common::Timestamp::operator> ( const Timestamp & ts ) const

Definition at line 154 of file timestamp.cpp.

References cmp().

Here is the call graph for this function:

◆ operator>=()

bool Common::Timestamp::operator>= ( const Timestamp & ts ) const

Definition at line 158 of file timestamp.cpp.

References cmp().

Here is the call graph for this function:

◆ secs()

int64 Common::Timestamp::secs ( ) const

inline

Return the time in seconds described by this timestamp, rounded down.

Definition at line 202 of file timestamp.h.

References _secs.

◆ totalNumberOfFrames()

int64 Common::Timestamp::totalNumberOfFrames ( ) const

inline

Return the time in frames described by this timestamp.

Definition at line 209 of file timestamp.h.

References _framerate, _framerateFactor, _numFrames, and _secs.

Referenced by Video::VideoDecoder::FixedRateVideoTrack::getFrameAtTime(), and Video::QuickTimeDecoder::QuickTimeAudioTrack::queueAudio().

Here is the caller graph for this function:

Member Data Documentation

◆ _framerate

uint64 Common::Timestamp::_framerate

protected

The internal framerate, i.e.

the number of frames per second. This is computed as the least common multiple of the framerate specified by the client code, and 1000. This way, we ensure that we can store both frames and milliseconds without any rounding losses.

Definition at line 273 of file timestamp.h.

Referenced by addIntern(), addMsecs(), cmp(), convertToFramerate(), frameDiff(), framerate(), msecs(), normalize(), Timestamp(), and totalNumberOfFrames().

◆ _framerateFactor

uint64 Common::Timestamp::_framerateFactor

protected

Factor by which the original framerate specified by the client code was multipled to obtain the internal _framerate value.

Definition at line 279 of file timestamp.h.

Referenced by addFrames(), convertToFramerate(), frameDiff(), framerate(), numberOfFrames(), Timestamp(), and totalNumberOfFrames().

◆ _numFrames

int64 Common::Timestamp::_numFrames

protected

The number of frames which together with _secs encodes the timestamp.

The total number of internal frames represented by this timestamp can be computed as follows: _numFrames + _secs * _framerate To obtain the number of frames with respect to the original framerate, this value has to be divided by _framerateFactor.

This is always a value greater or equal to zero. The only reason this is an int and not an uint is to allow intermediate negative values.

Definition at line 264 of file timestamp.h.

Referenced by addFrames(), addIntern(), addMsecs(), cmp(), convertToFramerate(), frameDiff(), msecs(), normalize(), numberOfFrames(), operator-(), Timestamp(), and totalNumberOfFrames().

◆ _secs

int64 Common::Timestamp::_secs

protected

The seconds part of this timestamp.

The total time in seconds represented by this timestamp can be computed as follows: _secs + (double)_numFrames / _framerate

Definition at line 250 of file timestamp.h.

Referenced by addIntern(), addMsecs(), cmp(), frameDiff(), msecs(), normalize(), operator-(), secs(), Timestamp(), and totalNumberOfFrames().

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

src/common/timestamp.h
src/common/timestamp.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Timestamp() [1/3]

◆ Timestamp() [2/3]

◆ Timestamp() [3/3]

Member Function Documentation

◆ addFrames()

◆ addIntern()

◆ addMsecs()

◆ cmp()

◆ convertToFramerate()

◆ frameDiff()

◆ framerate()

◆ msecs()

◆ msecsDiff()

◆ normalize()

◆ numberOfFrames()

◆ operator!=()

◆ operator+()

◆ operator-() [1/2]

◆ operator-() [2/2]

◆ operator<()

◆ operator<=()

◆ operator==()

◆ operator>()

◆ operator>=()

◆ secs()

◆ totalNumberOfFrames()

Member Data Documentation

◆ _framerate

◆ _framerateFactor

◆ _numFrames

◆ _secs