timevalue.hpp File Reference

a family of time value like entities and their relationships. More...

Go to the source code of this file.

Description

a family of time value like entities and their relationships.

This is the foundation for the Lumiera time handling framework. On the implementation level, time values are represented as 64bit integer values raw_time_64, similar to and inspired by gavl_time_t from the raw-video handling Lib-GAVL. But for the actual use, we create several kinds of time "values", based on their logical properties. These time values are considered to be fixed (immutable) values, which may only be created through some limited construction paths, and any time based calculation is forced to go through our time calculation library. This is prerequisite for the definition of frame aligned time values and time code representation implemented as display format based on these frame quantised time values.

Time entities

The value types defined in this header represent time points and time intervals based on an internal time scale (µs ticks) and not related to any known fixed time zone or time base; rather they are interpreted in usage context, and the intended way to retrieve such a value is by formatting it into a time code format.

The lib::time::TimeValue serves as foundation for all further time calculations; in fact it is implemented as a single 64bit µ-tick value (raw_time_64). The further time entities are implemented as value objects (without virtual functions):

• lib::time::Time represents a time instant and is the reference for any usage
• lib::time::TimeVar is a mutable time variable and can be used for calculations
• lib::time::Offset can be used to express a positive or negative shift on time scale
• lib::time::Duration represents the extension or an amount of time
• lib::time::TimeSpan represents a distinct interval, with start time and duration
• lib::time::FrameRate can be used to mark a number to denote a frames-per-second spec
• lib::time::FSecs is a rational number to represent seconds or fractions thereof

Manipulating time values

Time values are conceived as fixed, immutable entities, similar to numbers; you can't just change the number two, and likewise, two seconds are two seconds. However, for many use cases we have to combine time values to perform calculations

• Time entities can be combined with operators, to form new time entities
• the TimeVar can be used as accumulator or variable for ongoing calculations
• since TimeSpan, Duration (and the grid-aligned, "quantised" flavours) will often represent some time-like property or entity, e.g. the temporal specification of a media Clip with start and duration, there is the concept of an explicit mutation, which is accepted by these entities. Notably the lib::time::Control can be attached to these entities, and can then receive manipulations (nudging, offset); moreover it is possible to attach as listener to such a "controller" and be notified by any manipulation; this setup is the base for running time display, playback cursors etc.

Quantised time

While these internal time values can be considered sufficiently precise, in practice any time specifications in the context of media handling will be aligned to some grid, and expressed in a time code format. Typically, we want to know the number of frames since playback started at the beginning of the timeline, and such a specification also relies on some implicitly known frame rate (24fps for film in US, 25fps for film and TV in Europe, ...). By deliberate choice, in Lumiera we do not incorporate such implicit assumptions into the actual time values. Rather, they need to be made explicitly in the relevant usage context. This is also the reason why the time entities defined in this header do not offer an API to get the "real" time (whatever this means). Rather, the user of these time entities should get used to the concept that these abstract opaque values are the real thing, and a concrete, human readable time code is only a derivation, and any such derivation also incurs information loss. To reiterate that, any time quantisation is a lossy information; grid aligned values are not "cleaner", they are just easier to handle for humans.

how can I extract a time value?

Taking the aforementioned into account, it depends on the context what to expect and to get

• the standard path is to create a lib::time::QuTime by associating the internal time value with a pre-defined time grid. From there you can call QuTime::formatAs() to build an actual timecode instance, which can then be investigated or just printed.
• for debugging purpose, lib::time::Time defines an operator string(), which breaks down the internal values into the format -hh:mm:ss.mss
• advanced calculations with the need to access the implementation data in full precision should go through lib::time::TimeVar, which offers conversions to raw int64_t and the even more fine grained FSec, which is a rational (fraction) boost::rational<int64_t>

See also

time.h basic time calculation library functions

timequant.hpp

TimeValue_test

Definition in file timevalue.hpp.

#include "lib/error.hpp"
#include <boost/operators.hpp>
#include <boost/rational.hpp>
#include <compare>
#include <cstdlib>
#include <string>

Namespaces
namespace	lib
	Implementation namespace for support and library code.
namespace	lib::time
namespace	lib::time::anonymous_namespace{timevalue.hpp}
namespace	util

Typedefs
using	raw_time_64 = int64_t
	Raw µ-tick time representation used in Lumiera.
using	FSecs = boost::rational< int64_t >
	rational representation of fractional seconds

Classes
class	TimeValue
	basic constant internal time value. More...
class	TimeVar
	a mutable time value, behaving like a plain number, allowing copy and re-accessing More...
class	Time
	Lumiera's internal time value datatype. More...
class	Offset
	Offset measures a distance in time. More...
class	Duration
	Duration is the internal Lumiera time metric. More...
class	TimeSpan
	A time interval anchored at a specific point in time. More...
class	FrameRate
	Framerate specified as frames per second. More...
struct	StringConv< lib::time::FSecs, void >
	specialisation: render fractional seconds (for diagnostics) More...

Functions
Offset	operator+ (Offset const &start, Offset const &toChain)
Offset	operator- (Offset const &start, Offset const &toSubtract)
template<typename FAC >
Offset	operator* (Offset const &distance, FAC factor)
template<typename INT >
Offset	operator* (INT factor, Offset const &o)
template<typename INTX >
Offset	operator* (boost::rational< INTX > factor, Offset const &offset)
Offset	operator* (double factor, Offset const &offset)
Duration	operator+ (Duration const &base, Duration const &toAdd)
Duration	operator- (Duration const &base, Duration const &toRemove)
template<typename NUM >
Offset	operator* (NUM factor, Duration const &dur)
template<typename NUM >
Offset	operator* (Duration const &dur, NUM factor)
FSecs	operator/ (int n, FrameRate rate)
	convenient conversion to duration in fractional seconds
template<typename NUM >
NUM	__ensure_nonzero (NUM n)
raw_time_64	symmetricLimit (raw_time_64 raw, TimeValue lim)
HashVal	hash_value (TimeValue const &time)
	derive a hash from the µ-tick value
boost::rational< uint >	__framerate_approximation (size_t cnt, Duration timeReference)
boost::rational< uint >	__framerate_approximation (double fps)
bool	isnil (lib::time::Duration const &dur)