Description

Common functions for handling of time values.

Working with time values in sexagesimal format, quantising time and converting to/from common timecode formats can be tricky to get right. Thus the goal is to concentrate the actual bits of math for these operations into a small number of library functions, which are easy to test thoroughly in isolation.

Built on top of that, the actual time handling in the GUI and within the Lumiera session is mostly confined to use the opaque lib::time::Time wrapper objects. When time values actually need to be quantised (aligned to a frame grid), this is expressed at the API through using the lib::time::QuTime type, which then in turn can be materialised into a number of timecode formats. These definitions ensure that whenever an actual quantisation (rounding) operation is performed, the link to the appropriate time grid is available, so that multiple output or rendering operations can use differing time origins and frame rates simultaneously on the same model.

The Lumiera Vault Layer functions mostly operate on raw frame counts, which in this model are defined to be a special kind of timecode, and thus dependent on a preceding time quantisation.

See also: lib::time::Time; timequant.hpp; TimeValue_test

Definition in file time.h.

#include <inttypes.h>
#include <gavl/gavl.h>
#include "lib/time/timevalue.hpp"

Functions
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 (lib::time::FrameRate const &fps)
	Calculates the duration of one frame in Lumiera time units. More...

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. 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 (lib::time::FSecs const &fractionalSeconds)
	Converts a fraction of seconds to Lumiera's internal opaque time scale. More...

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)

Function Documentation

◆ lumiera_rational_to_time()

gavl_time_t lumiera_rational_to_time ( lib::time::FSecs const & fractionalSeconds )

Converts a fraction of seconds to Lumiera's internal opaque time scale.

Parameters

fractionalSeconds given as rational number

Note: inconsistent with Lumiera's general quantisation behaviour, here negative fractional micro-ticks are truncated towards zero. This was deemed irrelevant in practice.

◆ 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 427 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 436 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 485 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 497 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 505 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 513 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 524 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 626 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 535 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 541 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 547 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 553 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 559 of file time.cpp.

◆ 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 386 of file time.cpp.

References lumiera_tmpbuf_snprintf(), and TIME_SCALE_MS.

Here is the call graph for this function:

Description

Functions

Function Documentation

◆ 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_build_time_ntsc_drop()

◆ lumiera_time_hours()

◆ lumiera_time_minutes()

◆ lumiera_time_seconds()

◆ lumiera_time_millis()

◆ lumiera_time_frames()

◆ lumiera_tmpbuf_print_time()