#include "steam/play/timings.hpp"

Description

Generic frame timing specification.

Defines the expected delivery interval, optionally also the expected quality-of-service (urgency).

Note: copyable value class

Todo:: write type comment /////////////////////////////////////////////////////////////////TODO: WIP seems to become some kind of abstracted Grid representation!

Definition at line 86 of file timings.hpp.

Static Public Attributes
static Timings	DISABLED
	marker for halted output

Public Attributes
PlaybackUrgency	playbackUrgency

boost::rational< FrameCnt >	playbackSpeed

Time	scheduledDelivery
	a wall clock time corresponding to the Grid's origin. Can be Time::Never (=not time bound)

Duration	outputLatency

Duration	engineLatency
	reasonable guess at the scheduling and dispatch-delay of the render engine

Public Member Functions
	Timings (FrameRate fps)
	Create a default initialised Timing constraint record.

	Timings (FrameRate fps, Time realTimeAnchor)

Time	getOrigin () const

Time	getFrameStartAt (FrameCnt frameNr) const

Duration	getFrameDurationAt (TimeValue refPoint) const

Duration	getFrameDurationAt (FrameCnt refFrameNr) const

FrameCnt	getBreakPointAfter (TimeValue refPoint) const
	the next grid point at or after the given reference time

Duration	constantFrameTimingsInterval (TimeValue startPoint) const
	the frame spacing and duration remains constant for some time...

Offset	getRealOffset (FrameCnt frameOffset) const
	calculate the given frame's distance from origin, but do so using the real time scale, including any playback speed factor and similar corrections.

Time	getTimeDue (FrameCnt frameOffset) const
	real time deadline for the given frame, without any latency.

Duration	getPlanningChunkDuration () const
	the minimum time span to be covered by frame calculation jobs planned in one sway.

FrameCnt	establishNextPlanningChunkStart (FrameCnt anchorFrame) const
	establish the time point to anchor the next planning chunk, in accordance with getPlanningChunkDuration

bool	isOriginalSpeed () const

bool	isTimebound () const

bool	isValid () const
	Consistency self-check.

Timings	constrainedBy (Timings additionalConditions)

Private Attributes
lib::time::PQuant	grid_

Constructor & Destructor Documentation

◆ Timings() [1/2]

Timings ( FrameRate fps )

explicit

Create a default initialised Timing constraint record.

Using the standard optimistic settings for most values, no latency, no special requirements. The frame grid is rooted at the "natural" time origin; it is not related in any way to the current session.

Remarks: this ctor is intended rather for testing purposes! Usually, when creating a play/render process, the actual timings are related to the timeline and the latency/speed requirements of the output.

Definition at line 69 of file timings.cpp.

References Timings::grid_.

◆ Timings() [2/2]

Timings	(	FrameRate	fps,
		Time	realTimeAnchor
	)

Definition at line 80 of file timings.cpp.

References Timings::grid_.

Member Function Documentation

◆ getOrigin()

Time getOrigin ( ) const

Definition at line 114 of file timings.cpp.

References Timings::grid_.

Referenced by TimingConstraints_test::define_basicTimingConstraints(), and Timings_test::verify_simpleFrameStep().

Here is the caller graph for this function:

◆ getFrameStartAt()

Time getFrameStartAt ( FrameCnt frameNr ) const

Definition at line 121 of file timings.cpp.

References Timings::grid_.

Referenced by Dispatcher::PipeFrameTick::activate(), Dispatcher::PipeFrameTick::iterNext(), RenderDrive::prepareRenderPlanningFrom(), Timings_test::verify_next_startPoint(), and Timings_test::verify_simpleFrameStep().

Here is the caller graph for this function:

◆ getFrameDurationAt() [1/2]

Duration getFrameDurationAt ( TimeValue refPoint ) const

Definition at line 128 of file timings.cpp.

References Timings::getFrameDurationAt(), and Timings::grid_.

Referenced by TimingConstraints_test::define_basicTimingConstraints(), and Timings::getFrameDurationAt().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getFrameDurationAt() [2/2]

Duration getFrameDurationAt ( FrameCnt refFrameNr ) const

Definition at line 136 of file timings.cpp.

References Timings::grid_.

◆ getBreakPointAfter()

FrameCnt getBreakPointAfter ( TimeValue refPoint ) const

the next grid point at or after the given reference time

Definition at line 143 of file timings.cpp.

References Timings::grid_.

Referenced by Dispatcher::PipeFrameTick::activate(), and Timings_test::verify_next_startPoint().

Here is the caller graph for this function:

◆ constantFrameTimingsInterval()

Duration constantFrameTimingsInterval ( TimeValue startPoint ) const

the frame spacing and duration remains constant for some time...

Parameters

startPoint looking from that time point into future

Returns: duration after this starting point, where it's safe to assume unaltered frame dimensions

Remarks: the purpose of this function is to support scheduling and frame handling even in case the frame rate isn't constant. To indicate the case the frame rate is changing right now, this function might return Duration::NIL

Todo:: implement real support for variable frame rates

Definition at line 159 of file timings.cpp.

References Time::MAX.

◆ getRealOffset()

Offset getRealOffset ( FrameCnt frameOffset ) const

calculate the given frame's distance from origin, but do so using the real time scale, including any playback speed factor and similar corrections.

Parameters

frameOffset frame number relative to the implicit grid

Returns: real time value relative to the implicit grid's zero point

Note: since the Timings don't contain any information relating the nominal time scale to wall clock time, this result is just a relative offset, but expressed in real time scale values

See also: steam::engine::TimeAnchor for an absolutely anchored conversion

Definition at line 180 of file timings.cpp.

References Timings::grid_, Timings::isOriginalSpeed(), and Timings::playbackSpeed.

Referenced by Timings::getTimeDue().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getTimeDue()

Time getTimeDue ( FrameCnt frameOffset ) const

real time deadline for the given frame, without any latency.

This value is provided in case of scheduled time of delivery, which is signalled by playbackUrgency == TIMEBOUND

Returns: wall clock time to expect delivery of data corresponding to a frame specified relative to time axis origin

Note: for other playback urgencies Time::NEVER is returned

Warning: not clear as of 1/13 if it is even possible to have such a function on the Timings record.

Definition at line 166 of file timings.cpp.

References Timings::getRealOffset(), Time::NEVER, Timings::playbackUrgency, Timings::scheduledDelivery, and steam::play::TIMEBOUND.

Referenced by JobPlanning::doCalcDeadline().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getPlanningChunkDuration()

Duration getPlanningChunkDuration ( ) const

the minimum time span to be covered by frame calculation jobs planned in one sway.

The ongoing planning of additional jobs proceeds in chunks of jobs added at once to the schedule. This setting defines the minimum time to plan ahead; after covering at least this time span with new jobs, the frame dispatcher concludes "enough for now" and emits a continuation job for the next planning chunk.

Definition at line 190 of file timings.cpp.

Referenced by Timings::establishNextPlanningChunkStart().

Here is the caller graph for this function:

◆ establishNextPlanningChunkStart()

FrameCnt establishNextPlanningChunkStart ( FrameCnt anchorFrame ) const

establish the time point to anchor the next planning chunk, in accordance with getPlanningChunkDuration

Parameters

anchorFrame frame number where the current planning chunk started

Returns: number of the first frame, which is located strictly more than the planning chunk duration into the future

Remarks: this value is used by the frame dispatcher to create a follow-up planning job

Definition at line 197 of file timings.cpp.

References Timings::getPlanningChunkDuration(), and Timings::grid_.

Here is the call graph for this function:

◆ isOriginalSpeed()

bool isOriginalSpeed ( ) const

inline

Definition at line 187 of file timings.hpp.

References Timings::playbackSpeed.

Referenced by Timings::getRealOffset().

Here is the caller graph for this function:

◆ isTimebound()

bool isTimebound ( ) const

inline

Definition at line 193 of file timings.hpp.

References Timings::playbackUrgency, and steam::play::TIMEBOUND.

◆ isValid()

bool isValid ( ) const

Consistency self-check.

typically invoked from assertions

Definition at line 102 of file timings.cpp.

References steam::play::ASAP, Timings::grid_, Time::MAX, Time::MIN, Time::NEVER, steam::play::NICE, Timings::playbackUrgency, Timings::scheduledDelivery, and steam::play::TIMEBOUND.

◆ constrainedBy()

Timings constrainedBy ( Timings additionalConditions )

Definition at line 215 of file timings.cpp.

Referenced by LumieraRenderProcessBuilder::buildCalculationStreams().

Here is the caller graph for this function:

Member Data Documentation

◆ grid_

lib::time::PQuant grid_

private

Definition at line 88 of file timings.hpp.

Referenced by Timings::Timings(), Timings::Timings(), Timings::establishNextPlanningChunkStart(), Timings::getBreakPointAfter(), Timings::getFrameDurationAt(), Timings::getFrameDurationAt(), Timings::getFrameStartAt(), Timings::getOrigin(), Timings::getRealOffset(), and Timings::isValid().

◆ playbackUrgency

PlaybackUrgency playbackUrgency

Definition at line 91 of file timings.hpp.

Referenced by TimingConstraints_test::define_basicTimingConstraints(), JobPlanning::determineDeadline(), Timings::getTimeDue(), Timings::isTimebound(), and Timings::isValid().

◆ playbackSpeed

boost::rational<FrameCnt> playbackSpeed

Definition at line 92 of file timings.hpp.

Referenced by Timings::getRealOffset(), and Timings::isOriginalSpeed().

◆ scheduledDelivery

Time scheduledDelivery

a wall clock time corresponding to the Grid's origin. Can be Time::Never (=not time bound)

Definition at line 93 of file timings.hpp.

Referenced by Timings::getTimeDue(), and Timings::isValid().

◆ outputLatency

Duration outputLatency

Definition at line 94 of file timings.hpp.

Referenced by JobPlanning::doCalcDeadline().

◆ engineLatency

Duration engineLatency

reasonable guess at the scheduling and dispatch-delay of the render engine

Definition at line 95 of file timings.hpp.

Referenced by JobPlanning::doCalcDeadline().

◆ DISABLED

Timings DISABLED

static

marker for halted output

a special marker Timings record, indicating disabled or halted output

Definition at line 106 of file timings.hpp.

Collaboration diagram for Timings:

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

Description

Static Public Attributes

Public Attributes

Public Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ Timings() [1/2]

◆ Timings() [2/2]

Member Function Documentation

◆ getOrigin()

◆ getFrameStartAt()

◆ getFrameDurationAt() [1/2]

◆ getFrameDurationAt() [2/2]

◆ getBreakPointAfter()

◆ constantFrameTimingsInterval()

◆ getRealOffset()

◆ getTimeDue()

◆ getPlanningChunkDuration()

◆ establishNextPlanningChunkStart()

◆ isOriginalSpeed()

◆ isTimebound()

◆ isValid()

◆ constrainedBy()

Member Data Documentation

◆ grid_

◆ playbackUrgency

◆ playbackSpeed

◆ scheduledDelivery

◆ outputLatency

◆ engineLatency

◆ DISABLED