nrEngine::Clock Class Reference
[Clock and Timers]

Global clock of the engine used to retrieve time or create timers. More...

Inheritance diagram for nrEngine::Clock:

Public Member Functions
void	setTimeSource (SharedPtr< TimeSource > timeSource)
bool	isAnySourceBounded ()
SharedPtr< TimeSource >	getTimeSource ()
Result	onStartTask ()
Result	updateTask ()
Result	stopTask ()
void	Ticks ()
float64	getTime () const
float32	getFrameInterval () const
int32	getFrameNumber () const
float32	getFrameRate () const
float32	getRealFrameInterval () const
float32	getRealFrameRate () const
void	setMaxFrameRate (bool set, float32 maxFPS=60.0)
int32	addObserver (SharedPtr< ITimeObserver > timeObserver)
Result	removeObserver (int32 observerID)
Result	addObserver (const std::string &obsName, SharedPtr< ITimeObserver > timeObserver)
Result	removeObserver (const std::string &obsName)
void	setFrameWindow (int32 frameCount=10, float32 defaultFrameTime=0.03333)
void	setFixFrameRate (bool setFixRate, float32 fixFrameRate=60.0f)
SharedPtr< Timer >	createTimer ()
void	setSyncInterval (uint32 milliseconds)
void	reset (float64 resetToTime=0.0f, bool resetAllObservers=false)
	ScriptFunctionDef (scriptResetClock)
Friends
class	Engine
	Only engine's core object can create instance.

---

Detailed Description

Global clock of the engine used to retrieve time or create timers.

Clock allows you to create timers from it. Clock is always ticks if any time source is bounded. In contrast to Einstein's relativity theory we have only one global clock. So your complete application has one time which runs with the same speed. But to be able to use Einstein's theory you can create timers from each clock, which allows you to use different time speeds. Clock can also derive/create timers. But if you want to create the timer by yourself you can do this.

Note:

• Our clock works internal with 64Bit float64 values to stay precise. Because using of float32 values is enough for every simulation you will get 32Bit float32 values as frame interval time.
• If you compile the engine on 64Bit systems, so you can change this and use 64Bit doubles instead.
• Each created timer dies when clock dies.
• You can only destroy timers through the clock interface or it will be deleted automaticly from the memory when clock is deleted
• Deleting the timer outside from the clock has no effect

Definition at line 55 of file Clock.h.

---

Member Function Documentation

void nrEngine::Clock::setTimeSource

(

SharedPtr< TimeSource >

timeSource

)

Set the time source to be used to get current time. Our clock class is platform independent but the time get code depends mostly on the platform you using. So just derive your time source from ITimeSource interface and add this source into our clock.

Parameters:

timeSource

smart pointer containing to the time source

Definition at line 126 of file Clock.cpp.

Referenced by nrEngine::Engine::initializeEngine(), and reset().

bool nrEngine::Clock::isAnySourceBounded

(

)

Returns true if any time source is bounded to our clock.

Definition at line 143 of file Clock.cpp.

SharedPtr<TimeSource> nrEngine::Clock::getTimeSource

(

)

Return a smart pointer to the current time source

Returns:

a smart pointer pointing to the current time source or NULL if no time source is bound at now.

Definition at line 77 of file Clock.h.

Result nrEngine::Clock::onStartTask

(

)

[virtual]

This method will be called by the kernel to start the clock. It is called when clock is added to the kernel pipeline.

Reimplemented from nrEngine::ITask.

Definition at line 170 of file Clock.cpp.

References nrEngine::ScriptEngine::add(), nrEngine::OK, and nrEngine::Engine::sScriptEngine().

Result nrEngine::Clock::updateTask

(

)

[virtual]

Updates the clock task by getting time values and calculating of frame rate and frame interval. Also each connected time observer will be notified so it can do own updates. This allows you just to create any observer (like timer) bind them to the clock and forgett it.

Implements nrEngine::ITask.

Definition at line 197 of file Clock.cpp.

References nrEngine::CLOCK_NO_TIME_SOURCE, and nrEngine::OK.

Result nrEngine::Clock::stopTask

(

)

[virtual]

Stop the clock task and release all used objects. So all observers will be deleted from the observer list and also the time source is removed. After this function you still able to access to the clock and timers (because of smart pointers), but the time will hold on and no updates of the time will be made.

Reimplemented from nrEngine::ITask.

Definition at line 181 of file Clock.cpp.

References nrEngine::ScriptEngine::del(), nrEngine::OK, reset(), and nrEngine::Engine::sScriptEngine().

void nrEngine::Clock::Ticks

(

)

Same as taskUpdate(). This name is choosen to separate calls to the clock by not knowing, that it is a task. Use this function from somewhere else than a kernel.

Definition at line 108 of file Clock.h.

float64 nrEngine::Clock::getTime

(

)

const

Returns current time since clock start ticking.

Definition at line 239 of file Clock.cpp.

float32 nrEngine::Clock::getFrameInterval

(

)

const

Returns filtered interval time between two or more frames. nrEngine's clock does not only calculate the interval between two following frames, but it uses a arithmetic average to compute the frame interval between a lot of frames. This helps you to ignore some frames if their update time was to big or to less.

Definition at line 244 of file Clock.cpp.

Referenced by getFrameRate(), and nrEngine::Timer::notifyTimeObserver().

int32 nrEngine::Clock::getFrameNumber

(

)

const

Returns number of frames drawn since clock start ticking

Definition at line 261 of file Clock.cpp.

float32 nrEngine::Clock::getFrameRate

(

)

const

Returns FPS. Like the frameinterval this value is also computed as average between a lot of frames. So this value is more smooth.

Definition at line 266 of file Clock.cpp.

References getFrameInterval().

float32 nrEngine::Clock::getRealFrameInterval

(

)

const

Get the frame interval time of a real time. If you use fix frame rate, so you get as an interval a 1.0 / fix frame rate. This method allows you to get the time which your frame really need to render.

Definition at line 249 of file Clock.cpp.

Referenced by nrEngine::Timer::getRealFrameInterval(), and getRealFrameRate().

float32 nrEngine::Clock::getRealFrameRate

(

)

const

Get real frame rate based on getRealFrameInterval() method

Definition at line 255 of file Clock.cpp.

References getRealFrameInterval().

void nrEngine::Clock::setMaxFrameRate	(	bool	set,
		float32	maxFPS = 60.0
	)

This method allows you to set the maximal frame rate at which the clock shoudl run. It will use this frame rate as an upper bound. If applications runs faster than this time, so it will retard to this speed. If app runs much slower so nothing happens. At speed above the given boundaries the clock runs as for fixed frame rate. So you would retrieve fixed frame interval values. Function which retrieves real values are not affected by them, so you are still able to get information about the real time, which you frame need

Definition at line 355 of file Clock.cpp.

int32 nrEngine::Clock::addObserver

(

SharedPtr< ITimeObserver >

timeObserver

)

Add new time observer to our list of observers. Each observer will be notified on each frame after clock calculations are done. With this system we can separate our timers from game loop, but they still be updated on each frame.

Parameters:

timeObserver

smart pointers to the observer

Returns:

internal ID of observer to allow of removing them from the list

Note:

Each observer has to implement the ITimeObserver interface

Definition at line 271 of file Clock.cpp.

Referenced by createTimer().

Result nrEngine::Clock::removeObserver

(

int32

observerID

)

Removes an observer from the list by given ID

Parameters:

observerID

id of the observer returned by addObserver()

Returns:

either OK or:

• CLOCK_OBSERVER_NOT_FOUND if such id is not valid

Definition at line 286 of file Clock.cpp.

References nrEngine::CLOCK_OBSERVER_NOT_FOUND, and nrEngine::OK.

Result nrEngine::Clock::addObserver	(	const std::string &	obsName,
		SharedPtr< ITimeObserver >	timeObserver
	)

Add an time observer by a name. So you can delete them also by using this name.

Parameters:

	obsName	name of the observer
	timeObserver	smart pointer pointing to the observer

Returns:

either OK or:

• CLOCK_OBSERVER_ALREADY_ADDED if such is already added

Definition at line 307 of file Clock.cpp.

References nrEngine::CLOCK_OBSERVER_ALREADY_ADDED, and nrEngine::OK.

Result nrEngine::Clock::removeObserver

(

const std::string &

obsName

)

Removes an observer by using it's name.

Parameters:

obsName

name of the observer

Returns:

either OK or:

• CLOCK_OBSERVER_NOT_FOUND if such an observer not exists

Definition at line 327 of file Clock.cpp.

References nrEngine::CLOCK_OBSERVER_NOT_FOUND, and nrEngine::OK.

void nrEngine::Clock::setFrameWindow	(	int32	frameCount = 10,
		float32	defaultFrameTime = 0.03333
	)

Set the count of frames to be computed to calculate frame rate/interval. We need this to smooth big peaks on frame rates to allow application run smoother than without this window. Here we just using averaging of the frame intervals during certain number of frames.

Parameters:

	frameCount	size of such frame calculation window
	defaultFrameTime	is a frame interval added by default as if there was a frame rendered with this speed. This allows us to start smoothly

Definition at line 340 of file Clock.cpp.

Referenced by reset().

void nrEngine::Clock::setFixFrameRate	(	bool	setFixRate,
		float32	fixFrameRate = 60.0f
	)

If you set this to true so fix frame rate will be used. This helps us to run our application on console or do internal calculations based on fix frame rate like Doom3 does.

Parameters:

	setFixRate	if true fix frame rate will be used.
	fixFrameRate	frame rate to be used

Definition at line 349 of file Clock.cpp.

SharedPtr< Timer > nrEngine::Clock::createTimer

(

)

Create a new timer which does use this clock as reference.

Definition at line 148 of file Clock.cpp.

References addObserver(), nrEngine::Log::LL_DEBUG, nrEngine::Log::LL_WARNING, and nrEngine::Log::LOG_ENGINE.

void nrEngine::Clock::setSyncInterval

(

uint32

milliseconds

)

Setup the syncing interval. The clock will be synced with system time so it helps to prevent timing errors produced by high performance time counters in addidition to CPU speed stepping functionality of the processor unit.

Definition at line 137 of file Clock.cpp.

void nrEngine::Clock::reset	(	float64	resetToTime = 0.0f,
		bool	resetAllObservers = false
	)

Reset the clock. The clock time will be resetted to the given time.

Parameters:

	resetToTime	Reset the clock to the given time value
	resetAllObservers	if true all registered obseervers would be also resetted

Definition at line 97 of file Clock.cpp.

References nrEngine::Log::LOG_ENGINE, setFrameWindow(), and setTimeSource().

Referenced by nrEngine::ScriptFunctionDec(), and stopTask().

nrEngine::Clock::ScriptFunctionDef

(

scriptResetClock

)

Script-Function to reset the clock. You can specify in parameters if all timers, which were created before should be also reseted.

---

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

• Clock.h
• Clock.cpp

---