Audio::Timestamp Class Reference

#include <timestamp.h>

Public Member Functions
	Timestamp (uint msecs=0, uint framerate=1)
	Timestamp (uint secs, uint frames, uint framerate)
Timestamp	convertToFramerate (uint newFramerate) 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
bool	operator> (const Timestamp &ts) const
bool	operator>= (const Timestamp &ts) const
Timestamp	addFrames (int frames) const
Timestamp	addMsecs (int msecs) const
Timestamp	operator- () const
Timestamp	operator+ (const Timestamp &ts) const
Timestamp	operator- (const Timestamp &ts) const
int	frameDiff (const Timestamp &ts) const
int	msecsDiff (const Timestamp &ts) const
int	msecs () const
int	secs () const
int	totalNumberOfFrames () const
int	numberOfFrames () const
uint	framerate () const

Protected Member Functions
int	cmp (const Timestamp &ts) const
void	normalize ()
void	addIntern (const Timestamp &ts)

Protected Attributes
int	_secs
int	_numFrames
uint	_framerate
uint	_framerateFactor

Detailed Description

When dealing with audio and video decoding, it is often necessary to measure the 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 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. For example, 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 a similar rounding issue occurs 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 that ScummVM runs on still have only limited (and slow) floating point support.

This class provides an alternative solution. It stores time in terms of frames, but with a twist: client code can specify arbitrary (integral) frame rates but, internally, Timestamp modifies the frame rate to be a multiple of 1000. This way, both the number of frames (relative to the original frame rate), 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 possible to compute the difference between two timestamps in terms of 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 frame rates. 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", which is useful when using the timestamp to store a time interval.

Constructor & Destructor Documentation

Timestamp() [1/2]

Audio::Timestamp::Timestamp	(	uint	msecs = 0,
		uint	framerate = 1
	)

Set up a timestamp with a given time and frame rate.

Parameters

msecs	Starting time in milliseconds.
framerate	Number of frames per second (must be > 0).

Timestamp() [2/2]

Audio::Timestamp::Timestamp	(	uint	secs,
		uint	frames,
		uint	framerate
	)

Set up a timestamp with the given time, frames, and frame rate.

Parameters

secs	Starting time in seconds.
frames	Starting frames.
framerate	Number of frames per second (must be > 0).

Member Function Documentation

convertToFramerate()

Timestamp Audio::Timestamp::convertToFramerate

(

uint

newFramerate

)

const

Return a timestamp that represents as closely as possible the point in time described by this timestamp, but with a different frame rate.

operator==()

bool Audio::Timestamp::operator==

(

const Timestamp &

ts

)

const

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

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

operator!=()

bool Audio::Timestamp::operator!=

(

const Timestamp &

ts

)

const

Check whether two timestamps describe a different moment in time.

operator<()

bool Audio::Timestamp::operator<

(

const Timestamp &

ts

)

const

Check whether this timestamp describes an earlier moment in time than another timestamp.

operator<=()

bool Audio::Timestamp::operator<=

(

const Timestamp &

ts

)

const

Check whether this timestamp describes an earlier or the same moment in time as another timestamp.

operator>()

bool Audio::Timestamp::operator>

(

const Timestamp &

ts

)

const

Check whether this timestamp describes a later moment in time than another timestamp.

operator>=()

bool Audio::Timestamp::operator>=

(

const Timestamp &

ts

)

const

Check whether this timestamp describes a later or the same moment in time as another timestamp.

addFrames()

Timestamp Audio::Timestamp::addFrames

(

int

frames

)

const

Return a new timestamp that corresponds to the time encoded by this timestamp with the given number of frames added.

Parameters

frames

Number of frames to add.

addMsecs()

Timestamp Audio::Timestamp::addMsecs

(

int

msecs

)

const

Return a new timestamp that corresponds to the time encoded by this timestamp with the given number of milliseconds added.

Parameters

msecs

Number of milliseconds to add.

operator-() [1/2]

Timestamp Audio::Timestamp::operator-

(

)

const

Return a new timestamp with the negative value of the time encoded by this timestamp.

This is a unary minus operation.

operator+()

Timestamp Audio::Timestamp::operator+

(

const Timestamp &

ts

)

const

Compute the sum of two timestamps.

This is only allowed if they use the same frame rate.

operator-() [2/2]

Timestamp Audio::Timestamp::operator-

(

const Timestamp &

ts

)

const

Compute the difference between two timestamps.

This is only allowed if they use the same frame rate.

frameDiff()

int Audio::Timestamp::frameDiff

(

const Timestamp &

ts

)

const

Compute the number of frames between this timestamp and ts.

The frames are counted with respect to the frame rate used by this timestamp (which may differ from the frame rate used by ts).

msecsDiff()

int Audio::Timestamp::msecsDiff

(

const Timestamp &

ts

)

const

Compute the number of milliseconds between this timestamp and ts.

msecs()

int Audio::Timestamp::msecs

(

)

const

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

secs()

int Audio::Timestamp::secs ( ) const

inline

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

totalNumberOfFrames()

int Audio::Timestamp::totalNumberOfFrames ( ) const

inline

Return the time in frames described by this timestamp.

numberOfFrames()

int Audio::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.

framerate()

uint Audio::Timestamp::framerate ( ) const

inline

Return the frame rate used by this timestamp.

cmp()

int Audio::Timestamp::cmp ( const Timestamp &  ts ) const

protected

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

normalize()

void Audio::Timestamp::normalize ( )

protected

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

addIntern()

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

protected

Add another timestamp to this one and normalize the result.

Member Data Documentation

_secs

int Audio::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

_numFrames

int Audio::Timestamp::_numFrames

protected

The number of frames that, together with _secs, encode 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 frame rate, this value must be divided by _framerateFactor.

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

_framerate

uint Audio::Timestamp::_framerate

protected

The internal frame rate, i.e. the number of frames per second.

This is computed as the least common multiple of the frame rate specified by the client code, and 1000. This ensures that both frames and milliseconds can be stored without any rounding losses.

_framerateFactor

uint Audio::Timestamp::_framerateFactor

protected

Factor by which the original frame rate specified by the client code has been multiplied to obtain the internal _framerate value.

---

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

• audio/timestamp.h