2009-03-04 06:58:28 +00:00
|
|
|
/* ScummVM - Graphic Adventure Engine
|
|
|
|
*
|
|
|
|
* ScummVM is the legal property of its developers, whose names
|
|
|
|
* are too numerous to list here. Please refer to the COPYRIGHT
|
|
|
|
* file distributed with this source distribution.
|
|
|
|
*
|
2021-12-26 17:47:58 +00:00
|
|
|
* This program is free software: you can redistribute it and/or modify
|
|
|
|
* it under the terms of the GNU General Public License as published by
|
|
|
|
* the Free Software Foundation, either version 3 of the License, or
|
|
|
|
* (at your option) any later version.
|
2014-02-18 01:34:17 +00:00
|
|
|
*
|
2009-03-04 06:58:28 +00:00
|
|
|
* This program is distributed in the hope that it will be useful,
|
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
|
* GNU General Public License for more details.
|
2014-02-18 01:34:17 +00:00
|
|
|
*
|
2009-03-04 06:58:28 +00:00
|
|
|
* You should have received a copy of the GNU General Public License
|
2021-12-26 17:47:58 +00:00
|
|
|
* along with this program. If not, see <http://www.gnu.org/licenses/>.
|
2009-03-04 06:58:28 +00:00
|
|
|
*
|
|
|
|
*/
|
|
|
|
|
2011-10-28 10:27:50 +00:00
|
|
|
#ifndef AUDIO_TIMESTAMP_H
|
|
|
|
#define AUDIO_TIMESTAMP_H
|
2009-03-04 06:58:28 +00:00
|
|
|
|
|
|
|
#include "common/scummsys.h"
|
|
|
|
|
|
|
|
namespace Audio {
|
|
|
|
|
2009-03-09 03:45:40 +00:00
|
|
|
/**
|
2020-11-30 01:54:01 +00:00
|
|
|
* @defgroup audio_timestamp Timestamp
|
|
|
|
* @ingroup audio
|
2011-02-09 00:14:24 +00:00
|
|
|
*
|
2020-11-30 01:54:01 +00:00
|
|
|
* @brief Timestamp class for specifying points in time and measuring time intervals.
|
|
|
|
* @{
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
* When dealing with audio and video decoding, it is often necessary to
|
|
|
|
* measure the time (intervals) in terms of frames, relative to a fixed
|
2011-02-09 00:14:24 +00:00
|
|
|
* 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
|
2020-11-30 01:54:01 +00:00
|
|
|
* necessary to convert between and compare time measures given on
|
2011-02-09 00:14:24 +00:00
|
|
|
* 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
|
2020-11-30 01:54:01 +00:00
|
|
|
* quickly accumulate, resulting in user-noticeable disturbance, such as
|
|
|
|
* audio and video running out of sync. For example, a typical approach is to
|
2011-02-09 00:14:24 +00:00
|
|
|
* 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
|
2020-11-30 01:54:01 +00:00
|
|
|
* hand, if measuring in frames, then a similar rounding issue occurs when
|
2011-02-09 00:14:24 +00:00
|
|
|
* 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
|
2020-11-30 01:54:01 +00:00
|
|
|
* side effects. Foremost, some platforms that ScummVM runs on still have
|
2011-02-09 00:14:24 +00:00
|
|
|
* only limited (and slow) floating point support.
|
|
|
|
*
|
2020-11-30 01:54:01 +00:00
|
|
|
* 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
|
2011-02-09 00:14:24 +00:00
|
|
|
* represented as integers. This change is completely hidden from the
|
|
|
|
* user, however.
|
|
|
|
*
|
2020-11-30 01:54:01 +00:00
|
|
|
* 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.
|
2011-02-09 00:14:24 +00:00
|
|
|
* Timestamps can be easily compared using regular comparison operators,
|
2020-11-30 01:54:01 +00:00
|
|
|
* 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
|
2011-02-09 00:14:24 +00:00
|
|
|
* to it, or adding a number of milliseconds. Adding negative amounts is
|
2020-11-30 01:54:01 +00:00
|
|
|
* also allowed, and a timestamp can even represent a "negative time",
|
|
|
|
* which is useful when using the timestamp to store a time interval.
|
2009-03-09 03:45:40 +00:00
|
|
|
*/
|
2009-03-04 06:58:28 +00:00
|
|
|
class Timestamp {
|
|
|
|
public:
|
2009-03-09 03:45:40 +00:00
|
|
|
/**
|
2020-11-30 01:54:01 +00:00
|
|
|
* Set up a timestamp with a given time and frame rate.
|
|
|
|
*
|
|
|
|
* @param msecs Starting time in milliseconds.
|
|
|
|
* @param framerate Number of frames per second (must be > 0).
|
2009-03-09 03:45:40 +00:00
|
|
|
*/
|
2011-02-07 22:57:35 +00:00
|
|
|
Timestamp(uint msecs = 0, uint framerate = 1);
|
2010-01-04 22:48:28 +00:00
|
|
|
|
2010-01-06 20:24:56 +00:00
|
|
|
/**
|
2020-11-30 01:54:01 +00:00
|
|
|
* Set up a timestamp with the given time, frames, and frame rate.
|
|
|
|
*
|
|
|
|
* @param secs Starting time in seconds.
|
|
|
|
* @param frames Starting frames.
|
|
|
|
* @param framerate Number of frames per second (must be > 0).
|
2010-01-06 20:24:56 +00:00
|
|
|
*/
|
2010-01-11 10:17:55 +00:00
|
|
|
Timestamp(uint secs, uint frames, uint framerate);
|
2010-01-06 20:24:56 +00:00
|
|
|
|
2010-01-04 22:48:28 +00:00
|
|
|
/**
|
2020-11-30 01:54:01 +00:00
|
|
|
* Return a timestamp that represents as closely as possible
|
|
|
|
* the point in time described by this timestamp, but with
|
|
|
|
* a different frame rate.
|
2010-01-04 22:48:28 +00:00
|
|
|
*/
|
2010-01-11 10:17:55 +00:00
|
|
|
Timestamp convertToFramerate(uint newFramerate) const;
|
2010-01-04 22:48:28 +00:00
|
|
|
|
2010-01-06 12:09:14 +00:00
|
|
|
/**
|
2020-11-30 01:54:01 +00:00
|
|
|
* 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.
|
2010-01-06 12:09:14 +00:00
|
|
|
*/
|
2010-01-04 22:48:28 +00:00
|
|
|
bool operator==(const Timestamp &ts) const;
|
2020-11-30 01:54:01 +00:00
|
|
|
/**
|
|
|
|
* Check whether two timestamps describe a different moment in time.
|
|
|
|
*/
|
2010-01-04 22:48:28 +00:00
|
|
|
bool operator!=(const Timestamp &ts) const;
|
2020-11-30 01:54:01 +00:00
|
|
|
/**
|
|
|
|
* Check whether this timestamp describes an earlier moment in time than another timestamp.
|
|
|
|
*/
|
2010-01-06 12:15:05 +00:00
|
|
|
bool operator<(const Timestamp &ts) const;
|
2020-11-30 01:54:01 +00:00
|
|
|
/**
|
|
|
|
* Check whether this timestamp describes an earlier or the same moment in time as another timestamp.
|
|
|
|
*/
|
2010-01-06 12:15:05 +00:00
|
|
|
bool operator<=(const Timestamp &ts) const;
|
2020-11-30 01:54:01 +00:00
|
|
|
/**
|
|
|
|
* Check whether this timestamp describes a later moment in time than another timestamp.
|
|
|
|
*/
|
2010-01-06 12:15:05 +00:00
|
|
|
bool operator>(const Timestamp &ts) const;
|
2020-11-30 01:54:01 +00:00
|
|
|
/**
|
|
|
|
* Check whether this timestamp describes a later or the same moment in time as another timestamp.
|
|
|
|
*/
|
2010-01-06 12:15:05 +00:00
|
|
|
bool operator>=(const Timestamp &ts) const;
|
2009-05-24 15:17:42 +00:00
|
|
|
|
2010-01-04 22:48:28 +00:00
|
|
|
/**
|
2020-11-30 01:54:01 +00:00
|
|
|
* Return a new timestamp that corresponds to the time encoded
|
2010-01-04 22:48:28 +00:00
|
|
|
* by this timestamp with the given number of frames added.
|
2020-11-30 01:54:01 +00:00
|
|
|
*
|
|
|
|
* @param frames Number of frames to add.
|
2010-01-04 22:48:28 +00:00
|
|
|
*/
|
2009-03-04 06:58:28 +00:00
|
|
|
Timestamp addFrames(int frames) const;
|
2009-05-24 15:17:42 +00:00
|
|
|
|
2010-01-04 22:48:28 +00:00
|
|
|
/**
|
2020-11-30 01:54:01 +00:00
|
|
|
* Return a new timestamp that corresponds to the time encoded
|
2010-01-04 22:48:28 +00:00
|
|
|
* by this timestamp with the given number of milliseconds added.
|
2020-11-30 01:54:01 +00:00
|
|
|
*
|
|
|
|
* @param msecs Number of milliseconds to add.
|
2010-01-04 22:48:28 +00:00
|
|
|
*/
|
2010-01-06 12:09:14 +00:00
|
|
|
Timestamp addMsecs(int msecs) const;
|
2009-05-28 10:29:25 +00:00
|
|
|
|
2010-01-11 10:17:55 +00:00
|
|
|
|
2020-11-30 01:54:01 +00:00
|
|
|
/**
|
|
|
|
* Return a new timestamp with the negative value of the time encoded
|
|
|
|
* by this timestamp.
|
|
|
|
*
|
|
|
|
* This is a unary minus operation.
|
|
|
|
*/
|
2010-01-11 10:17:55 +00:00
|
|
|
Timestamp operator-() const;
|
|
|
|
|
2011-02-09 00:12:22 +00:00
|
|
|
/**
|
2020-11-30 01:54:01 +00:00
|
|
|
* Compute the sum of two timestamps.
|
|
|
|
*
|
|
|
|
* This is only allowed if they use the same frame rate.
|
2011-02-09 00:12:22 +00:00
|
|
|
*/
|
2010-01-11 10:17:55 +00:00
|
|
|
Timestamp operator+(const Timestamp &ts) const;
|
|
|
|
|
2011-02-09 00:12:22 +00:00
|
|
|
/**
|
2020-11-30 01:54:01 +00:00
|
|
|
* Compute the difference between two timestamps.
|
|
|
|
*
|
|
|
|
* This is only allowed if they use the same frame rate.
|
2011-02-09 00:12:22 +00:00
|
|
|
*/
|
|
|
|
Timestamp operator-(const Timestamp &ts) const;
|
2010-01-11 10:17:55 +00:00
|
|
|
|
2010-01-04 22:48:28 +00:00
|
|
|
/**
|
2020-11-30 01:54:01 +00:00
|
|
|
* Compute the number of frames between this timestamp and @p ts.
|
|
|
|
*
|
|
|
|
* The frames are counted with respect to the frame rate used by this
|
|
|
|
* timestamp (which may differ from the frame rate used by @p ts).
|
2010-01-04 22:48:28 +00:00
|
|
|
*/
|
|
|
|
int frameDiff(const Timestamp &ts) const;
|
2009-05-24 15:17:42 +00:00
|
|
|
|
2020-11-30 01:54:01 +00:00
|
|
|
/** Compute the number of milliseconds between this timestamp and @p ts. */
|
2010-01-04 22:48:28 +00:00
|
|
|
int msecsDiff(const Timestamp &ts) const;
|
2009-05-24 15:17:42 +00:00
|
|
|
|
2010-01-04 22:48:28 +00:00
|
|
|
/**
|
2010-01-07 15:12:20 +00:00
|
|
|
* Return the time in milliseconds described by this timestamp,
|
2010-01-04 22:48:28 +00:00
|
|
|
* rounded down.
|
|
|
|
*/
|
2010-01-11 10:17:55 +00:00
|
|
|
int msecs() const;
|
2010-01-04 22:48:28 +00:00
|
|
|
|
2010-01-06 15:33:54 +00:00
|
|
|
/**
|
2010-01-07 15:12:20 +00:00
|
|
|
* Return the time in seconds described by this timestamp,
|
2010-01-06 15:33:54 +00:00
|
|
|
* rounded down.
|
|
|
|
*/
|
2010-01-11 10:17:55 +00:00
|
|
|
inline int secs() const {
|
2010-01-07 15:12:20 +00:00
|
|
|
return _secs;
|
|
|
|
}
|
2010-01-06 15:33:54 +00:00
|
|
|
|
|
|
|
/**
|
2010-01-07 15:12:20 +00:00
|
|
|
* Return the time in frames described by this timestamp.
|
2010-01-06 15:33:54 +00:00
|
|
|
*/
|
2010-01-07 15:12:20 +00:00
|
|
|
inline int totalNumberOfFrames() const {
|
2010-01-11 10:17:55 +00:00
|
|
|
return _numFrames / (int)_framerateFactor + _secs * (int)(_framerate / _framerateFactor);
|
2010-01-07 15:12:20 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* 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.
|
|
|
|
*/
|
|
|
|
inline int numberOfFrames() const {
|
2010-01-11 10:17:55 +00:00
|
|
|
return _numFrames / (int)_framerateFactor;
|
2010-01-07 15:12:20 +00:00
|
|
|
}
|
2010-01-06 15:56:04 +00:00
|
|
|
|
2020-11-30 01:54:01 +00:00
|
|
|
/** Return the frame rate used by this timestamp. */
|
2010-01-11 10:17:55 +00:00
|
|
|
inline uint framerate() const { return _framerate / _framerateFactor; }
|
2010-01-06 15:33:54 +00:00
|
|
|
|
2010-01-06 12:15:05 +00:00
|
|
|
protected:
|
2010-01-11 10:17:55 +00:00
|
|
|
/**
|
|
|
|
* Compare this timestamp to another one and return
|
|
|
|
* a value similar to strcmp.
|
|
|
|
*/
|
2010-01-06 12:15:05 +00:00
|
|
|
int cmp(const Timestamp &ts) const;
|
2010-01-09 22:36:32 +00:00
|
|
|
|
2010-01-11 10:17:55 +00:00
|
|
|
/**
|
|
|
|
* Normalize this timestamp by making _numFrames non-negative
|
2020-11-30 01:54:01 +00:00
|
|
|
* and reducing its modulo _framerate.
|
2010-01-11 10:17:55 +00:00
|
|
|
*/
|
|
|
|
void normalize();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Add another timestamp to this one and normalize the result.
|
|
|
|
*/
|
|
|
|
void addIntern(const Timestamp &ts);
|
2011-02-09 00:14:24 +00:00
|
|
|
|
|
|
|
protected:
|
|
|
|
/**
|
|
|
|
* The seconds part of this timestamp.
|
|
|
|
* The total time in seconds represented by this timestamp can be
|
|
|
|
* computed as follows:
|
2020-11-30 01:54:01 +00:00
|
|
|
* @code
|
2011-02-09 00:14:24 +00:00
|
|
|
* _secs + (double)_numFrames / _framerate
|
2020-11-30 01:54:01 +00:00
|
|
|
* @endcode
|
2011-02-09 00:14:24 +00:00
|
|
|
*/
|
|
|
|
int _secs;
|
|
|
|
|
|
|
|
/**
|
2020-11-30 01:54:01 +00:00
|
|
|
* The number of frames that, together with @c _secs, encode the
|
|
|
|
* timestamp.
|
|
|
|
*
|
|
|
|
* The total number of *internal* frames represented
|
2011-02-09 00:14:24 +00:00
|
|
|
* by this timestamp can be computed as follows:
|
2020-11-30 01:54:01 +00:00
|
|
|
* @code
|
2011-02-09 00:14:24 +00:00
|
|
|
* _numFrames + _secs * _framerate
|
2020-11-30 01:54:01 +00:00
|
|
|
* @endcode
|
2011-02-09 00:14:24 +00:00
|
|
|
* To obtain the number of frames with respect to the original
|
2020-11-30 01:54:01 +00:00
|
|
|
* frame rate, this value must be divided by _framerateFactor.
|
2011-02-09 00:14:24 +00:00
|
|
|
*
|
2020-11-30 01:54:01 +00:00
|
|
|
* This is always a value greater than or equal to zero.
|
|
|
|
* The only reason this is an int and not a uint is to
|
2011-02-09 00:14:24 +00:00
|
|
|
* allow intermediate negative values.
|
|
|
|
*/
|
|
|
|
int _numFrames;
|
|
|
|
|
|
|
|
/**
|
2020-11-30 01:54:01 +00:00
|
|
|
* The internal frame rate, i.e. the number of frames per second.
|
|
|
|
*
|
|
|
|
* This is computed as the least common multiple of the frame rate
|
2011-02-09 00:14:24 +00:00
|
|
|
* specified by the client code, and 1000.
|
2020-11-30 01:54:01 +00:00
|
|
|
* This ensures that both frames and milliseconds can be stored
|
|
|
|
* without any rounding losses.
|
2011-02-09 00:14:24 +00:00
|
|
|
*/
|
|
|
|
uint _framerate;
|
|
|
|
|
|
|
|
/**
|
2020-11-30 01:54:01 +00:00
|
|
|
* Factor by which the original frame rate specified by the client
|
|
|
|
* code has been multiplied to obtain the internal _framerate value.
|
2011-02-09 00:14:24 +00:00
|
|
|
*/
|
|
|
|
uint _framerateFactor;
|
2009-03-04 06:58:28 +00:00
|
|
|
};
|
|
|
|
|
2020-11-30 01:54:01 +00:00
|
|
|
/** @} */
|
2009-03-04 06:58:28 +00:00
|
|
|
} // End of namespace Audio
|
|
|
|
|
|
|
|
#endif
|