Timings Class Reference

#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 95 of file timings.hpp.

Public Member Functions
	Timings (FrameRate fps)
	Create a default initialised Timing constraint record. More...
	Timings (FrameRate fps, Time realTimeAnchor)
Duration	constantFrameTimingsInterval (TimeValue startPoint) const
	the frame spacing and duration remains constant for some time... More...
Timings	constrainedBy (Timings additionalConditions)
FrameCnt	establishNextPlanningChunkStart (FrameCnt anchorFrame) const
	establish the time point to anchor the next planning chunk, in accordance with getPlanningChunkDuration More...
FrameCnt	getBreakPointAfter (TimeValue refPoint) const
	the next grid point at or after the given reference time
Duration	getFrameDurationAt (TimeValue refPoint) const
Duration	getFrameDurationAt (FrameCnt refFrameNr) const
Time	getFrameStartAt (FrameCnt frameNr) const
Time	getOrigin () const
Duration	getPlanningChunkDuration () const
	the minimum time span to be covered by frame calculation jobs planned in one sway. More...
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. More...
Time	getTimeDue (FrameCnt frameOffset) const
	real time deadline for the given frame, without any latency. More...
bool	isOriginalSpeed () const
bool	isTimebound () const
bool	isValid () const
	Consistency self-check. More...

Static Public Attributes
static Timings	DISABLED
	marker for halted output More...

Public Attributes
Duration	engineLatency
	reasonable guess at the scheduling and dispatch-delay of the render engine
Duration	outputLatency
boost::rational< FrameCnt >	playbackSpeed
PlaybackUrgency	playbackUrgency
Time	scheduledDelivery
	a wall clock time corresponding to the Grid's origin. Can be Time::Never (=not time bound)

Private Attributes
lib::time::PQuant	grid_

Constructor & Destructor Documentation

Timings()

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 78 of file timings.cpp.

Member Function Documentation

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 168 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 189 of file timings.cpp.

Referenced by Timings::getTimeDue().

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 175 of file timings.cpp.

References Timings::getRealOffset(), Time::NEVER, and Timings::scheduledDelivery.

Referenced by JobPlanning::JobPlanning().

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 199 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 206 of file timings.cpp.

References Timings::getPlanningChunkDuration().

Here is the call graph for this function:

isValid()

bool isValid

(

)

const

Consistency self-check.

typically invoked from assertions

Definition at line 111 of file timings.cpp.

References Time::MAX, Time::NEVER, and Timings::scheduledDelivery.

Member Data Documentation

DISABLED

Timings DISABLED

static

marker for halted output

a special marker Timings record, indicating disabled or halted output

Definition at line 115 of file timings.hpp.

Collaboration diagram for Timings:

---

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

• timings.hpp
• timings.cpp