Lumiera  0.pre.03
»edit your freedom«
time.h File Reference

Go to the source code of this file.

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
fractionalSecondsgiven 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 372 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
framerateunderlying framerate as rational number
Exceptions
error::Logicon zero framerate

Definition at line 381 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
gridspacing 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 430 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 442 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
nrindex number of the grid point (0 is at origin)
gridspacing of the grid intervals, measured in GAVL_TIME_SCALE
Returns
time point (frame start) on the Lumiera internal time scale

Definition at line 450 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
millisnumber of milliseconds
secsnumber of seconds
minsnumber of minutes
hoursnumber of hours

Definition at line 458 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
fpsframerate (frames per second)
framesnumber of additional frames
secsnumber of seconds
minsnumber of minutes
hoursnumber of hours

Definition at line 469 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 571 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 480 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 486 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 492 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 498 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
fpsframe rate (frames per second)

Definition at line 504 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 331 of file time.cpp.

References lumiera_tmpbuf_snprintf(), and TIME_SCALE_MS.

+ Here is the call graph for this function: