Description

Lumiera time handling core implementation unit.

This translation unit generates code for the Lumiera internal time wrapper, based on gavl_time_t, associated constants, marker classes for the derived time entities (TimeVar, Offset, Duration, TimeSpan, FrameRate) and for the basic time and frame rate conversion functions.

Client code includes either time.h (for basics and conversion functions) or timevalue.hpp (for the time entities), timequant.hpp for grid aligned time values or timecode.hpp

See also: Time; TimeValue; Grid; TimeValue_test; QuantiserBasics_test

Definition in file time.cpp.

#include "lib/error.hpp"
#include "lib/time.h"
#include "lib/time/timevalue.hpp"
#include "lib/rational.hpp"
#include "lib/util-quant.hpp"
#include "lib/format-string.hpp"
#include "lib/util.hpp"
#include "lib/tmpbuf.h"
#include <math.h>
#include <limits>
#include <string>
#include <sstream>
#include <boost/rational.hpp>
#include <boost/lexical_cast.hpp>

Macros
#define	TIME_SCALE_MS (lib::time::TimeValue::SCALE / 1000)
	scale factor used locally within this implementation header. More...

Functions
boost::rational< uint >	__framerate_approximation (double fps)

boost::rational< uint >	__framerate_approximation (size_t cnt, Duration timeReference)

int64_t	calculate_drop_frame_number (gavl_time_t time)
	reverse the drop-frame calculation More...

int64_t	calculate_quantisation (gavl_time_t time, gavl_time_t origin, gavl_time_t grid)

int64_t	calculate_quantisation (gavl_time_t time, gavl_time_t origin, uint framerate, uint framerate_divisor=1)

gavl_time_t	lumiera_build_time (long millis, uint secs, uint mins, uint hours)
	Build a time value by summing up the given components. More...

gavl_time_t	lumiera_build_time_fps (uint fps, uint frames, uint secs, uint mins, uint hours)
	Builds a time value by summing up the given components. More...

gavl_time_t	lumiera_build_time_ntsc_drop (uint frames, uint secs, uint mins, uint hours)
	Builds a time value by summing up the given components. More...

gavl_time_t	lumiera_frame_duration (FrameRate const &fps)
	Calculates the duration of one frame in Lumiera time units. More...

gavl_time_t	lumiera_framecount_to_time (uint64_t frameCount, FrameRate const &fps)
	Converts a frame count into Lumiera's internal time scale. More...

int64_t	lumiera_quantise_frames (gavl_time_t time, gavl_time_t origin, gavl_time_t grid)
	Quantise the given time into a fixed grid, relative to the origin. More...

int64_t	lumiera_quantise_frames_fps (gavl_time_t time, gavl_time_t origin, uint framerate)

gavl_time_t	lumiera_quantise_time (gavl_time_t time, gavl_time_t origin, gavl_time_t grid)
	Similar to lumiera_quantise_frames, but returns a grid aligned relative time. More...

gavl_time_t	lumiera_rational_to_time (FSecs const &fractionalSeconds)

int	lumiera_time_frames (gavl_time_t time, uint fps)
	Extract the remaining frame part of given time. More...

int	lumiera_time_hours (gavl_time_t time)
	Extract the hour part of given time. More...

int	lumiera_time_millis (gavl_time_t time)
	Extract the milliseconds part of given time. More...

int	lumiera_time_minutes (gavl_time_t time)
	Extract the minute part of given time. More...

int	lumiera_time_ntsc_drop_frames (gavl_time_t time)
	Extract the frame part of given time, using NTSC drop-frame timecode.

int	lumiera_time_ntsc_drop_hours (gavl_time_t time)
	Extract the hour part of given time, using NTSC drop-frame timecode.

int	lumiera_time_ntsc_drop_minutes (gavl_time_t time)
	Extract the minute part of given time, using NTSC drop-frame timecode.

int	lumiera_time_ntsc_drop_seconds (gavl_time_t time)
	Extract the second part of given time, using NTSC drop-frame timecode.

gavl_time_t	lumiera_time_of_gridpoint (int64_t nr, gavl_time_t origin, gavl_time_t grid)
	Calculate time of a grid point (frame start) More...

int	lumiera_time_seconds (gavl_time_t time)
	Extract the seconds part of given time. More...

char *	lumiera_tmpbuf_print_time (gavl_time_t time)

template<typename RAT >
string	renderFraction (RAT const &frac, Literal postfx) noexcept

Variables
Literal	DIAGNOSTIC_FORMAT {"%s%01d:%02d:%02d.%03d"}

const uint	DISCREPANCY = (160 30) - FRAMES_PER_1min

const uint	FRAMES_PER_10min = 1060 30000/1001

const uint	FRAMES_PER_1min = 160 30000/1001

const FSecs	FSEC_MAX {std::numeric_limits<int64_t>::max() / lib::time::TimeValue::SCALE}

const uint	RATE_LIMIT {std::numeric_limits<uint>::max() / 1024}
	a rather arbitrary safety limit imposed on internal numbers used to represent a frame rate. More...

Namespaces
	lib
	Implementation namespace for support and library code.

Macro Definition Documentation

◆ TIME_SCALE_MS

#define TIME_SCALE_MS (lib::time::TimeValue::SCALE / 1000)

scale factor used locally within this implementation header.

GAVL_TIME_SCALE rsp. TimeValue::SCALE is the correct factor or dividend when using gavl_time_t for display on a scale with seconds. Since we want to use milliseconds, we need to multiply or divide by 1000 to get correct results.

Definition at line 109 of file time.cpp.

Referenced by lumiera_time_hours(), lumiera_time_millis(), lumiera_time_minutes(), lumiera_time_seconds(), and lumiera_tmpbuf_print_time().

Function Documentation

◆ __framerate_approximation() [1/2]

boost::rational< uint > __framerate_approximation ( double fps )

helper to work around the limitations of uint.

Returns: a fractional number approximating the floating-point spec.

Todo:: imposing a quite coarse limitation. If this turns out to be a problem: we can do better, use lib::reQuant (rational.hpp)

Definition at line 286 of file time.cpp.

References lib::time::__framerate_approximation(), and lib::time::RATE_LIMIT.

Referenced by lib::time::__framerate_approximation().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ __framerate_approximation() [2/2]

boost::rational< uint > __framerate_approximation	(	size_t	cnt,
		Duration	timeReference
	)

helper calculate the count per time span approximately, to the precision possible to represent as fractional uint.

Definition at line 317 of file time.cpp.

References lib::time::__framerate_approximation(), TimeValue::_raw, lib::time::RATE_LIMIT, and TimeValue::SCALE.

Here is the call graph for this function:

◆ lumiera_tmpbuf_print_time()

char* lumiera_tmpbuf_print_time ( gavl_time_t time )

Diagnostics helper: render time value in H:MM:SS.mmm format.

Returns: safeclib temporary buffer containing formatted time string

Note: any time output for real should go through quantisation followed by rendering into a suitable timecode format.

Definition at line 395 of file time.cpp.

References lumiera_tmpbuf_snprintf(), and TIME_SCALE_MS.

Here is the call graph for this function:

◆ lumiera_rational_to_time()

gavl_time_t lumiera_rational_to_time ( FSecs const & fractionalSeconds )

Todo:: this utility function could be factored out into a FSecs or RSec class ///////////////////////TICKET #1262

Definition at line 422 of file time.cpp.

References Offset::abs().

Here is the call graph for this function:

◆ lumiera_framecount_to_time()

gavl_time_t lumiera_framecount_to_time	(	uint64_t	frameCount,
		lib::time::FrameRate const &	fps
	)

Converts a frame count into Lumiera's internal time scale.

based on a framerate given as rational number (e.g. NTSC)

Note: handles only positive frame counts and assumes the origin to be at zero.

Definition at line 436 of file time.cpp.

Referenced by Offset::Offset().

Here is the caller graph for this function:

◆ lumiera_frame_duration()

gavl_time_t lumiera_frame_duration ( lib::time::FrameRate const & fps )

Calculates the duration of one frame in Lumiera time units.

Parameters

framerate underlying framerate as rational number

Exceptions

error::Logic on zero framerate

Definition at line 445 of file time.cpp.

◆ lumiera_quantise_frames()

int64_t lumiera_quantise_frames	(	gavl_time_t	time,
		gavl_time_t	origin,
		gavl_time_t	grid
	)

Quantise the given time into a fixed grid, relative to the origin.

The time grid used for quantisation is comprised of equally spaced intervals, rooted at the given origin. The interval starting with the origin is numbered as zero. Each interval includes its lower bound, but excludes its upper bound.

Parameters

grid	spacing of the grid intervals, measured in GAVL_TIME_SCALE

Returns: number of the grid interval containing the given time.

Warning: the resulting value is limited to (Time::Min, Time::MAX)

Definition at line 494 of file time.cpp.

Referenced by FixedFrameQuantiser::gridPoint().

Here is the caller graph for this function:

◆ lumiera_quantise_time()

gavl_time_t lumiera_quantise_time	(	gavl_time_t	time,
		gavl_time_t	origin,
		gavl_time_t	grid
	)

Similar to lumiera_quantise_frames, but returns a grid aligned relative time.

Returns: time of start of the grid interval containing the given time, but measured relative to the origin

Warning: because the resulting value needs to be limited to fit into a 64bit long, the addressable time range can be considerably reduced. For example, if origin = Time::MIN, then all original time values above zero will be clipped, because the result, relative to origin, needs to be <= Time::MAX

Definition at line 506 of file time.cpp.

Referenced by FixedFrameQuantiser::gridLocal().

Here is the caller graph for this function:

◆ lumiera_time_of_gridpoint()

gavl_time_t lumiera_time_of_gridpoint	(	int64_t	nr,
		gavl_time_t	origin,
		gavl_time_t	grid
	)

Calculate time of a grid point (frame start)

Parameters

nr	index number of the grid point (0 is at origin)
grid	spacing of the grid intervals, measured in GAVL_TIME_SCALE

Returns: time point (frame start) on the Lumiera internal time scale

Definition at line 514 of file time.cpp.

Referenced by FixedFrameQuantiser::timeOf().

Here is the caller graph for this function:

◆ lumiera_build_time()

gavl_time_t lumiera_build_time	(	long	millis,
		uint	secs,
		uint	mins,
		uint	hours
	)

Build a time value by summing up the given components.

Parameters

millis	number of milliseconds
secs	number of seconds
mins	number of minutes
hours	number of hours

Definition at line 522 of file time.cpp.

◆ lumiera_build_time_fps()

gavl_time_t lumiera_build_time_fps	(	uint	fps,
		uint	frames,
		uint	secs,
		uint	mins,
		uint	hours
	)

Builds a time value by summing up the given components.

Parameters

fps	framerate (frames per second)
frames	number of additional frames
secs	number of seconds
mins	number of minutes
hours	number of hours

Definition at line 533 of file time.cpp.

◆ lumiera_time_hours()

int lumiera_time_hours ( gavl_time_t time )

Extract the hour part of given time.

Definition at line 544 of file time.cpp.

References TIME_SCALE_MS.

◆ lumiera_time_minutes()

int lumiera_time_minutes ( gavl_time_t time )

Extract the minute part of given time.

Definition at line 550 of file time.cpp.

References TIME_SCALE_MS.

◆ lumiera_time_seconds()

int lumiera_time_seconds ( gavl_time_t time )

Extract the seconds part of given time.

Definition at line 556 of file time.cpp.

References TIME_SCALE_MS.

◆ lumiera_time_millis()

int lumiera_time_millis ( gavl_time_t time )

Extract the milliseconds part of given time.

Definition at line 562 of file time.cpp.

References TIME_SCALE_MS.

◆ lumiera_time_frames()

int lumiera_time_frames	(	gavl_time_t	time,
		uint	fps
	)

Extract the remaining frame part of given time.

Parameters

fps	frame rate (frames per second)

Definition at line 568 of file time.cpp.

◆ lumiera_build_time_ntsc_drop()

gavl_time_t lumiera_build_time_ntsc_drop	(	uint	frames,
		uint	secs,
		uint	mins,
		uint	hours
	)

Builds a time value by summing up the given components.

The components are interpreted as a NTSC drop-frame timecode.

Warning: take care not to specify time codes that are illegal NTSC drop-frame times.

Definition at line 635 of file time.cpp.

Variable Documentation

◆ RATE_LIMIT

const uint RATE_LIMIT {std::numeric_limits<uint>::max() / 1024}

a rather arbitrary safety limit imposed on internal numbers used to represent a frame rate.

Remarks: rational numbers bear the danger to overflow for quite ordinary computations; we stay away from the absolute maximum by an additional safety margin of 1/1000.

Definition at line 277 of file time.cpp.

Referenced by lib::time::__framerate_approximation().

Description

Macros

Functions

Variables

Namespaces

Macro Definition Documentation

◆ TIME_SCALE_MS

Function Documentation

◆ __framerate_approximation() [1/2]

◆ __framerate_approximation() [2/2]

◆ lumiera_tmpbuf_print_time()

◆ lumiera_rational_to_time()

◆ lumiera_framecount_to_time()

◆ lumiera_frame_duration()

◆ lumiera_quantise_frames()

◆ lumiera_quantise_time()

◆ lumiera_time_of_gridpoint()

◆ lumiera_build_time()

◆ lumiera_build_time_fps()

◆ lumiera_time_hours()

◆ lumiera_time_minutes()

◆ lumiera_time_seconds()

◆ lumiera_time_millis()

◆ lumiera_time_frames()

◆ lumiera_build_time_ntsc_drop()

Variable Documentation

◆ RATE_LIMIT