#include "lib/time/quantiser.hpp"

Description

Simple stand-alone Quantiser implementation based on a constant sized gird.

This is a self-contained quantiser implementation without any implicit referral to the Lumiera session. As such it is suited for simplified unit testing.

Warning: real Stage and Steam-Layer code should always fetch a quantiser from the Session, referring to a pre defined TimeGrid. Basically, the overall purpose of the time-quantisation framework is to enforce such a link to a distinct time scale and quantisation, so to prevent "wild and uncoordinated" rounding attempts.

Definition at line 135 of file quantiser.hpp.

Public Member Functions
	FixedFrameQuantiser (FrameRate const &frames_per_second, TimeValue referencePoint=TimeValue(0))
	Create a quantiser based on a fixed constant spaced grid, rooted at the reference point as origin of the scale.

	FixedFrameQuantiser (Duration const &frame_duration, TimeValue referencePoint=TimeValue(0))

FrameCnt	gridPoint (TimeValue const &) const override
	grid quantisation (alignment).

Offset	gridLocal (TimeValue const &) const override
	transform into the local time scale grid aligned.

TimeValue	timeOf (FrameCnt gridPoint) const override
	calculate time value of a grid interval (frame) start point

TimeValue	timeOf (FSecs, int=0) const override
	calculate time coordinates of a time spec relative to this quantised time scale

Public Member Functions inherited from Quantiser
template<class FMT >
bool	supports () const

TimeValue	materialise (TimeValue const &raw) const
	convenience shortcut: materialise a raw time value based on this grid or time axis, but returning a raw time value.

Public Member Functions inherited from Grid
virtual	~Grid ()
	this is an Interface

Static Private Member Functions
static int64_t	grid_aligned (TimeValue const &, TimeValue const &)
	Quantise the given time into a fixed grid, relative to the origin.

Private Attributes
Time	origin_

Duration	raster_

Additional Inherited Members
Static Public Member Functions inherited from Quantiser
static PQuant	retrieve (Symbol gridID)
	Access an existing grid definition or quantiser, known by the given symbolic ID.

Protected Member Functions inherited from Quantiser
	Quantiser ()

Protected Attributes inherited from Quantiser
format::Supported	supportedFormats_

Constructor & Destructor Documentation

◆ FixedFrameQuantiser() [1/2]

FixedFrameQuantiser	(	FrameRate const &	frames_per_second,
		TimeValue	referencePoint = `TimeValue(0)`
	)

Create a quantiser based on a fixed constant spaced grid, rooted at the reference point as origin of the scale.

Quantisation then means to determine the grid interval containing a given raw time value. Here, the grid interval number zero starts at the origin; each interval includes its lower bound and excludes its upper bound.

Definition at line 131 of file quantiser.cpp.

◆ FixedFrameQuantiser() [2/2]

FixedFrameQuantiser	(	Duration const &	frame_duration,
		TimeValue	referencePoint = `TimeValue(0)`
	)

Definition at line 136 of file quantiser.cpp.

Member Function Documentation

◆ gridPoint()

FrameCnt gridPoint ( TimeValue const & rawTime ) const

overridevirtual

grid quantisation (alignment).

Determine the next lower grid interval start point, using a simple constant spaced time grid defined by origin and framerate stored within this quantiser.

Warning: returned frame count might exceed the valid range when converting back into a TimeValue.

See also: FixedFrameQuantiser::grid_aligned

Implements Quantiser.

Definition at line 173 of file quantiser.cpp.

References FixedFrameQuantiser::grid_aligned(), FixedFrameQuantiser::origin_, and FixedFrameQuantiser::raster_.

Referenced by QuantiserBasics_test::coverQuantisationCornerCases(), and FixedFrameQuantiser::timeOf().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ gridLocal()

Offset gridLocal ( TimeValue const & rawTime ) const

overridevirtual

transform into the local time scale grid aligned.

The actual calculation first determines the number of the grid interval containing the given rawTime, followed by multiplying this interval number with the grid spacing.

Returns: time of the start point of the grid interval containing the rawTime, relative to the origin of the time scale used by this quantiser.

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

See also: FixedFrameQuantiser::grid_aligned

Implements Quantiser.

Definition at line 192 of file quantiser.cpp.

References FixedFrameQuantiser::grid_aligned(), FixedFrameQuantiser::origin_, and FixedFrameQuantiser::raster_.

Referenced by QuantiserBasics_test::checkSimpleQuantisation(), QuantiserBasics_test::coverQuantisationCornerCases(), and QuantiserBasics_test::TestQuant::quant().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ timeOf() [1/2]

TimeValue timeOf ( FrameCnt gridPoint ) const

overridevirtual

calculate time value of a grid interval (frame) start point

Parameters

gridPoint index number of the grid point (0 is at origin)

Returns: time point measured in Lumiera internal time

Warning: returned time values are limited by the valid range of lumiera::Time

Implements Quantiser.

Definition at line 206 of file quantiser.cpp.

References FixedFrameQuantiser::gridPoint(), FixedFrameQuantiser::origin_, and FixedFrameQuantiser::raster_.

Referenced by QuantiserBasics_test::coverQuantisationCornerCases().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ timeOf() [2/2]

TimeValue timeOf	(	FSecs	gridTime,
		int	gridOffset = `0`
	)		const

overridevirtual

calculate time coordinates of a time spec relative to this quantised time scale

Parameters

gridTime	seconds relative to the origin of this scale
gridOffset	additional offset in grid intervals (frames)

Returns: time point measured in Lumiera internal time

Warning: returned time values are limited by the valid range of lumiera::Time

Implements Quantiser.

Definition at line 220 of file quantiser.cpp.

References FixedFrameQuantiser::origin_, and FixedFrameQuantiser::raster_.

◆ grid_aligned()

int64_t grid_aligned	(	TimeValue const &	time,
		TimeValue const &	grid
	)

staticprivate

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 TimeValue::Scale (µ-ticks)

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

Definition at line 86 of file quantiser.cpp.

References util::floordiv().

Referenced by FixedFrameQuantiser::gridLocal(), and FixedFrameQuantiser::gridPoint().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ origin_

Time origin_

private

Definition at line 138 of file quantiser.hpp.

Referenced by FixedFrameQuantiser::gridLocal(), FixedFrameQuantiser::gridPoint(), FixedFrameQuantiser::timeOf(), and FixedFrameQuantiser::timeOf().

◆ raster_

Duration raster_

private

Definition at line 139 of file quantiser.hpp.

Referenced by FixedFrameQuantiser::gridLocal(), FixedFrameQuantiser::gridPoint(), FixedFrameQuantiser::timeOf(), and FixedFrameQuantiser::timeOf().

Inheritance diagram for FixedFrameQuantiser:

Collaboration diagram for FixedFrameQuantiser:

The documentation for this class was generated from the following files:

Description

Public Member Functions

Static Private Member Functions

Private Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ FixedFrameQuantiser() [1/2]

◆ FixedFrameQuantiser() [2/2]

Member Function Documentation

◆ gridPoint()

◆ gridLocal()

◆ timeOf() [1/2]

◆ timeOf() [2/2]

◆ grid_aligned()

Member Data Documentation

◆ origin_

◆ raster_