plClock Class Reference

A clock that can be speed up, slowed down, paused, etc. Useful for updating game logic, rendering, etc. More...

#include <Clock.h>

Classes
struct	EventData
	The data that is sent through the event interface. More...

Public Types
using	Event = plEvent<const EventData&, plMutex>

Public Member Functions
	plClock (plStringView sName)
	Constructor.
void	Reset (bool bEverything)
	Resets all values to their default. E.g. call this after a new level has loaded to start fresh.
void	Update ()
	Updates the clock using the time difference since the last call to Update().
void	SetTimeStepSmoothing (plTimeStepSmoothing *pSmoother)
	Sets a time step smoother for this clock. Pass nullptr to deactivate time step smoothing.
plTimeStepSmoothing *	GetTimeStepSmoothing () const
	Returns the object used for time step smoothing (if any).
void	SetPaused (bool bPaused)
	Sets the clock to be paused or running.
bool	GetPaused () const
	Returns the paused state.
void	SetFixedTimeStep (plTime diff=plTime())
	Sets a fixed time step for updating the clock.
plTime	GetFixedTimeStep () const
	Returns the value for the fixed time step (zero if it is disabled).
void	SetAccumulatedTime (plTime t)
	Allows to replace the current accumulated time.
plTime	GetAccumulatedTime () const
	Returns the accumulated time since the last call to Reset().
plTime	GetTimeDiff () const
	Returns the time difference between the last two calls to Update().
void	SetSpeed (double fFactor)
	The factor with which to scale the time step during calls to Update().
double	GetSpeed () const
	Returns the clock speed multiplier.
void	SetMinimumTimeStep (plTime min)
	Sets the minimum time that must pass between clock updates.
void	SetMaximumTimeStep (plTime max)
	Sets the maximum time that may pass between clock updates.
plTime	GetMinimumTimeStep () const
	Returns the value for the minimum time step.
plTime	GetMaximumTimeStep () const
	Returns the value for the maximum time step.
void	Save (plStreamWriter &inout_stream) const
	Serializes the current clock state to a stream.
void	Load (plStreamReader &inout_stream)
	Deserializes the current clock state from a stream.
void	SetClockName (plStringView sName)
	Sets the name of the clock. Useful to identify the clock in tools such as plInspector.
plStringView	GetClockName () const
	Returns the name of the clock. All clocks get default names 'Clock N', unless the user specifies another name with SetClockName.

Static Public Member Functions
static plClock *	GetGlobalClock ()
	Returns the global clock.
static void	AddEventHandler (Event::Handler handler)
	Allows to register a function as an event receiver. All receivers will be notified in the order that they registered.
static void	RemoveEventHandler (Event::Handler handler)
	Unregisters a previously registered receiver. It is an error to unregister a receiver that was not registered.

Detailed Description

A clock that can be speed up, slowed down, paused, etc. Useful for updating game logic, rendering, etc.

Member Function Documentation

GetAccumulatedTime()

plTime plClock::GetAccumulatedTime ( ) const

inline

Returns the accumulated time since the last call to Reset().

The accumulated time is basically the 'absolute' time in the game world. Since this is the accumulation of all scaled, paused and clamped time steps, it will most likely have no relation to the real time that has passed.

GetMaximumTimeStep()

plTime plClock::GetMaximumTimeStep ( ) const

inline

Returns the value for the maximum time step.

See also

SetMaximumTimeStep

GetMinimumTimeStep()

plTime plClock::GetMinimumTimeStep ( ) const

inline

Returns the value for the minimum time step.

See also

SetMinimumTimeStep

GetTimeDiff()

plTime plClock::GetTimeDiff ( ) const

inline

Returns the time difference between the last two calls to Update().

This is the main function to use to query how much to advance some simulation. The time step is already scaled, clamped, etc.

Reset()

void plClock::Reset

(

bool

bEverything

)

Resets all values to their default. E.g. call this after a new level has loaded to start fresh.

If bEverything is false, only the current state of the clock is reset (accumulated time, speed, paused). Otherwise the clock is entirely reset, clearing also the time step smoother, min/max time steps and fixed time step.

SetAccumulatedTime()

void plClock::SetAccumulatedTime

(

plTime

t

)

Allows to replace the current accumulated time.

This can be used to reset the time to a specific point, e.g. when a game state is loaded from file, one should also reset the time to the time that was used when the game state was saved, to ensure that game objects that stored the accumulated time for reference, will continue to work. However, prefer to use Save() and Load() as those functions will store and restore the entire clock state.

SetFixedTimeStep()

void plClock::SetFixedTimeStep ( plTime diff = plTime() )

inline

Sets a fixed time step for updating the clock.

If tDiff is set to zero (the default), fixed time stepping is disabled. Fixed time stepping allows to run the simulation at a constant rate, which is useful for recording videos or to step subsystems that require constant steps. Clock speed, pause and min/max time step are still being applied even when the time step is fixed.

SetMaximumTimeStep()

void plClock::SetMaximumTimeStep ( plTime max )

inline

Sets the maximum time that may pass between clock updates.

By default a maximum time step of 0.1 seconds is enabled to ensure that code does not break down due to very large time steps. The maximum time step is applied after the clock speed is applied. When a custom time step smoother is set, that class needs to apply the clock speed AND also clamp the value to the min/max time step (which means it can ignore or override that feature).

See also

SetMinimumTimeStep

SetMinimumTimeStep()

void plClock::SetMinimumTimeStep ( plTime min )

inline

Sets the minimum time that must pass between clock updates.

By default a minimum time step of 0.001 seconds is enabled to ensure that code does not break down due to very small time steps. The minimum time step is applied after the clock speed is applied. When a custom time step smoother is set, that class needs to apply the clock speed AND also clamp the value to the min/max time step (which means it can ignore or override that feature). When the clock is paused, it will always return a time step of zero.

SetTimeStepSmoothing()

void plClock::SetTimeStepSmoothing ( plTimeStepSmoothing * pSmoother )

inline

Sets a time step smoother for this clock. Pass nullptr to deactivate time step smoothing.

Also calls plTimeStepSmoothing::Reset() on any non-nullptr pSmoother.

Update()

void plClock::Update

(

)

Updates the clock using the time difference since the last call to Update().

If a fixed time step is set, that will be used as the time difference. If the timer is paused, the time difference is set to zero. The time difference will then be scaled and clamped according to the clock speed and minimum and maximum time step.

---

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

• Code/Engine/Foundation/Time/Clock.h
• Code/Engine/Foundation/Time/Implementation/Clock.cpp
• Code/Engine/Foundation/Time/Implementation/Clock_inl.h