ezEngine  Milestone 7
ezClock 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

typedef ezEvent< const
EventData &, ezMutex
Event
 

Public Member Functions

 ezClock ()
 Constructor.
 
void Reset (bool bEverything)
 Resets all values to their default. E.g. call this after a new level has loaded to start fresh. More...
 
void Update ()
 Updates the clock using the time difference since the last call to Update(). More...
 
void SetTimeStepSmoothing (ezTimeStepSmoothing *pSmoother)
 Sets a time step smoother for this clock. Pass nullptr to deactivate time step smoothing. More...
 
ezTimeStepSmoothingGetTimeStepSmoothing () 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 (ezTime tDiff=ezTime())
 Sets a fixed time step for updating the clock. More...
 
ezTime GetFixedTimeStep () const
 Returns the value for the fixed time step (zero if it is disabled).
 
void SetAccumulatedTime (ezTime t)
 Allows to replace the current accumulated time. More...
 
ezTime GetAccumulatedTime () const
 Returns the accumulated time since the last call to Reset(). More...
 
ezTime GetTimeDiff () const
 Returns the time difference between the last two calls to Update(). More...
 
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 (ezTime tMin)
 Sets the minimum time that must pass between clock updates. More...
 
void SetMaximumTimeStep (ezTime tMax)
 Sets the maximum time that may pass between clock updates. More...
 
ezTime GetMinimumTimeStep () const
 Returns the value for the minimum time step. More...
 
ezTime GetMaximumTimeStep () const
 Returns the value for the maximum time step. More...
 
void Save (ezStreamWriterBase &Stream) const
 Serializes the current clock state to a stream.
 
void Load (ezStreamReaderBase &Stream)
 Deserializes the current clock state from a stream.
 
void SetClockName (const char *szName)
 Sets the name of the clock. Useful to identify the clock in tools such as ezInspector.
 
const char * 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 void UpdateAllGlobalClocks ()
 Will call ezClock::Update() on all clocks that were created using SetNumGlobalClocks(). If SetNumGlobalClocks() has never been called before, this function will call it (with the default clock count to set up). More...
 
static void SetNumGlobalClocks (ezUInt32 uiNumClocks=ezGlobalClockCount)
 Sets the given number of clocks in a global array for easy access by all code. More...
 
static ezClockGet (ezUInt32 uiGlobalClock=ezGlobalClock_GameLogic)
 Returns the global clock with the given index. Does NOT ensure that clock exists (will assert).
 
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.
 

Private Attributes

ezString m_sName
 
ezTime m_AccumulatedTime
 
ezTime m_LastTimeDiff
 
ezTime m_FixedTimeStep
 
ezTime m_LastTimeUpdate
 
ezTime m_MinTimeStep
 
ezTime m_MaxTimeStep
 
double m_Speed
 
bool m_bPaused
 
ezTimeStepSmoothingm_pTimeStepSmoother
 

Static Private Attributes

static ezDynamicArray< ezClocks_GlobalClocks
 
static Event s_TimeEvents
 
static ezUInt32 s_uiClockCount = 0
 

Detailed Description

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


Class Documentation

struct ezClock::EventData

The data that is sent through the event interface.

Class Members
ezTime m_RawTimeStep
ezTime m_SmoothedTimeStep
const char * m_szClockName

Member Function Documentation

ezTime ezClock::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.

ezTime ezClock::GetMaximumTimeStep ( ) const
inline

Returns the value for the maximum time step.

See Also
SetMaximumTimeStep
ezTime ezClock::GetMinimumTimeStep ( ) const
inline

Returns the value for the minimum time step.

See Also
SetMinimumTimeStep
ezTime ezClock::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.

void ezClock::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.

void ezClock::SetAccumulatedTime ( ezTime  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.

void ezClock::SetFixedTimeStep ( ezTime  tDiff = ezTime())
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.

void ezClock::SetMaximumTimeStep ( ezTime  tMax)
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
void ezClock::SetMinimumTimeStep ( ezTime  tMin)
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.

void ezClock::SetNumGlobalClocks ( ezUInt32  uiNumClocks = ezGlobalClockCount)
static

Sets the given number of clocks in a global array for easy access by all code.

You should call this function once at startup before any game code is run to create all the global clocks that your game provides. You should never have to call that function again afterwards, as the different 'time zones' that are used in your game should be fixed. Then all your game code can access these clocks using the Get() function. If some piece of code needs an additional clock for its specific purposes, it should NOT use the global clock array for that, but instead just hold an instance of ezClock itself.

void ezClock::SetTimeStepSmoothing ( ezTimeStepSmoothing pSmoother)
inline

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

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

void ezClock::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.

void ezClock::UpdateAllGlobalClocks ( )
static

Will call ezClock::Update() on all clocks that were created using SetNumGlobalClocks(). If SetNumGlobalClocks() has never been called before, this function will call it (with the default clock count to set up).

Note
Only call this when you really want to step all global clocks in your game at the same time. If you decouple game state updates and rendering, you need to step each clock separately.

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