ScummVM API documentation
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
msecsStarting time in milliseconds.
framerateNumber 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
secsStarting time in seconds.
framesStarting frames.
framerateNumber 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
framesNumber 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
msecsNumber 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:

◆ _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:

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: