ResidualVM logo ResidualVM website - Forums - Contact us BuildBot - Doxygen - Wiki curved edge

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

#include <timestamp.h>

List of all members.

Public Member Functions

 Timestamp (uint msecs=0, uint framerate=1)
 Set up a timestamp with a given time and framerate.
 Timestamp (uint secs, uint frames, uint framerate)
 Set up a timestamp with a given time, frames and framerate.
Timestamp convertToFramerate (uint newFramerate) const
 Return a timestamp which represents as closely as possible the point in time describes by this timestamp, but with a different framerate.
bool operator== (const Timestamp &ts) const
 Check whether to timestamps describe the exact same moment in time.
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
 Returns a new timestamp, which corresponds to the time encoded by this timestamp with the given number of frames added.
Timestamp addMsecs (int msecs) const
 Returns a new timestamp, which corresponds to the time encoded by this timestamp with the given number of milliseconds added.
Timestamp operator- () const
Timestamp operator+ (const Timestamp &ts) const
 Compute the sum of two timestamps.
Timestamp operator- (const Timestamp &ts) const
 Compute the difference between two timestamps.
int frameDiff (const Timestamp &ts) const
 Computes the number of frames between this timestamp and ts.
int msecsDiff (const Timestamp &ts) const
 Computes the number off milliseconds between this timestamp and ts.
int msecs () const
 Return the time in milliseconds described by this timestamp, rounded down.
int secs () const
 Return the time in seconds described by this timestamp, rounded down.
int totalNumberOfFrames () const
 Return the time in frames described by this timestamp.
int numberOfFrames () const
 A timestamp consists of a number of seconds, plus a number of frames, the latter describing a fraction of a second.
uint framerate () const
 Return the framerate used by this timestamp.

Protected Member Functions

int cmp (const Timestamp &ts) const
 Compare this timestamp to another one and return a value similar to strcmp.
void normalize ()
 Normalize this timestamp by making _numFrames non-negative and reducing it modulo _framerate.
void addIntern (const Timestamp &ts)
 Add another timestamp to this one and normalize the result.

Protected Attributes

int _secs
 The seconds part of this timestamp.
int _numFrames
 The number of frames which together with _secs encodes the timestamp.
uint _framerate
 The internal framerate, i.e.
uint _framerateFactor
 Factor by which the original framerate specified by the client code was multipled to obtain the internal _framerate value.

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 79 of file timestamp.h.


Constructor & Destructor Documentation

Audio::Timestamp::Timestamp ( uint  msecs = 0,
uint  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 28 of file timestamp.cpp.

Audio::Timestamp::Timestamp ( uint  secs,
uint  frames,
uint  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 39 of file timestamp.cpp.


Member Function Documentation

Timestamp Audio::Timestamp::addFrames ( int  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 123 of file timestamp.cpp.

void Audio::Timestamp::addIntern ( const Timestamp ts  )  [protected]

Add another timestamp to this one and normalize the result.

Definition at line 145 of file timestamp.cpp.

Timestamp Audio::Timestamp::addMsecs ( int  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 134 of file timestamp.cpp.

int Audio::Timestamp::cmp ( const Timestamp ts  )  const [protected]

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

Definition at line 109 of file timestamp.cpp.

Timestamp Audio::Timestamp::convertToFramerate ( uint  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 48 of file timestamp.cpp.

int Audio::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 173 of file timestamp.cpp.

uint Audio::Timestamp::framerate (  )  const [inline]

Return the framerate used by this timestamp.

Definition at line 186 of file timestamp.h.

int Audio::Timestamp::msecs (  )  const

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

Definition at line 201 of file timestamp.cpp.

int Audio::Timestamp::msecsDiff ( const Timestamp ts  )  const

Computes the number off milliseconds between this timestamp and ts.

Definition at line 197 of file timestamp.cpp.

void Audio::Timestamp::normalize (  )  [protected]

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

Definition at line 71 of file timestamp.cpp.

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.

Definition at line 181 of file timestamp.h.

bool Audio::Timestamp::operator!= ( const Timestamp ts  )  const

Definition at line 89 of file timestamp.cpp.

Timestamp Audio::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 161 of file timestamp.cpp.

Timestamp Audio::Timestamp::operator- (  )  const

Definition at line 153 of file timestamp.cpp.

Timestamp Audio::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 167 of file timestamp.cpp.

bool Audio::Timestamp::operator< ( const Timestamp ts  )  const

Definition at line 93 of file timestamp.cpp.

bool Audio::Timestamp::operator<= ( const Timestamp ts  )  const

Definition at line 97 of file timestamp.cpp.

bool Audio::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 85 of file timestamp.cpp.

bool Audio::Timestamp::operator> ( const Timestamp ts  )  const

Definition at line 101 of file timestamp.cpp.

bool Audio::Timestamp::operator>= ( const Timestamp ts  )  const

Definition at line 105 of file timestamp.cpp.

int Audio::Timestamp::secs (  )  const [inline]

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

Definition at line 165 of file timestamp.h.

int Audio::Timestamp::totalNumberOfFrames (  )  const [inline]

Return the time in frames described by this timestamp.

Definition at line 172 of file timestamp.h.


Member Data Documentation

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 236 of file timestamp.h.

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

Definition at line 242 of file timestamp.h.

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 227 of file timestamp.h.

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

Definition at line 213 of file timestamp.h.


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


Generated on Sat Nov 16 2019 05:02:40 for ResidualVM by doxygen 1.7.1
curved edge   curved edge