Runs the main game loop. More...
#include <Engine.h>
Public Member Functions | |
| Engine (const std::string &gameTitle, const std::string &settingsFilename="default") | |
| Constructor. More... | |
| Engine (const std::string &gameName, const PrefContainer &settings) | |
| Constructor. More... | |
| Engine (const Engine &)=delete | |
| Copy constructor. More... | |
| Engine & | operator= (const Engine &)=delete |
| Copy assignment operator. More... | |
| Engine (Engine &&)=delete | |
| Move constructor. More... | |
| Engine & | operator= (Engine &&)=delete |
| Move Assignment operator. More... | |
| void | initialize () |
| Initialize the engine. More... | |
| void | run () |
| Start the main loop. More... | |
| bool | isRunning () const |
| Check if the engine is running or not. More... | |
| void | quit () |
| Stop the engine. More... | |
| void | setPause (bool pause) |
| Pause or resume the engine. More... | |
| bool | isPaused () const |
| Check if then engine is paused or not. More... | |
| void | setPhysicsUpdateFrameRate (unsigned int frameRate) |
| Set the physics update frame rate. More... | |
| unsigned int | getPhysicsUpdateFrameRate () const |
| Get the fixed update frame rate. More... | |
| PrefContainer & | getConfigs () |
| Get the engines settings. More... | |
| const PrefContainer & | getConfigs () const |
| PropertyContainer & | getCache () |
| Get the engine level persistent data. More... | |
| const PropertyContainer & | getCache () const |
| PrefContainer & | getSavableCache () |
| Get the engine level savable persistent data. More... | |
| const PrefContainer & | getSavableCache () const |
| const std::string & | getGameName () const |
| Get the name of the game run by the engine. More... | |
| void | pushScene (Scene::Ptr scene) |
| Add a Scene to the engine. More... | |
| bool | pushCachedScene (const std::string &name) |
| Add a cached scene to the engine. More... | |
| void | popScene (int numScenes=1) |
| Remove scenes from the engine. More... | |
| void | cacheScene (const std::string &name, Scene::Ptr scene) |
| Add a scene to the cache list. More... | |
| bool | uncacheScene (const std::string &name) |
| Remove a scene from the cache list. More... | |
| bool | isSceneCached (const std::string &name) const |
| Check if a scene with a given name is cached or not. More... | |
| void | removeAllScenesExceptActive () |
| Remove all the scenes from the engine except the current active scene. More... | |
| void | removeAllScenes () |
| Remove all the scenes from the engine. More... | |
| std::size_t | getSceneCount () const |
| Get the number of scenes in the engine. More... | |
| Scene * | getActiveScene () |
| Get the active scene. More... | |
| const Scene * | getActiveScene () const |
| Scene * | getPreviousScene () |
| Get the scene that was previously active. More... | |
| const Scene * | getPreviousScene () const |
| Scene * | getCachedScene (const std::string &name) |
| Get access to a scene in the cache list. More... | |
| const Scene * | getCachedScene (const std::string &name) const |
| Time | getElapsedTime () const |
| Get the time passed since the engine was started. More... | |
| Window & | getWindow () |
| Get the engines game window. More... | |
| const Window & | getWindow () const |
| ui::GuiContainer & | getGui () |
| Get the engine level gui. More... | |
| const ui::GuiContainer & | getGui () const |
| audio::AudioManager & | getAudioManager () |
| Get the engine level audio manager. More... | |
| const audio::AudioManager & | getAudioManager () const |
| input::InputManager & | getInputManager () |
| Get the engine level input manager. More... | |
| const input::InputManager & | getInputManager () const |
| TimerManager & | getTimer () |
| Get the engine level timer manager. More... | |
| const TimerManager & | getTimer () const |
| void | suspendedEventListener (int id, bool suspend) |
| Pause or resume execution of an event listener. More... | |
| bool | isEventListenerSuspended (int id) const |
| Check if an event listener is suspended or not. More... | |
| bool | removeEventListener (int id) |
| Remove an event listener from an event. More... | |
| int | onInit (const Callback<> &callback) |
| Add an event listener to an initialize event. More... | |
| int | onSceneActivate (const Callback< Scene * > &callback, bool oneTime=false) |
| Add an event listener to a scene activation event. More... | |
| int | onFrameStart (const Callback<> &callback, bool oneTime=false) |
| Add an event listener to a current frame start event. More... | |
| int | onFrameEnd (const Callback<> &callback, bool oneTime=false) |
| Add an event listener to a current frame end event. More... | |
| int | onStart (const Callback<> &callback) |
| Add an event listener to an engine start event. More... | |
| int | onShutDown (const Callback<> &callback) |
| Execute a callback when the engine is about to shut down. More... | |
| void | onShutdownComplete (const Callback<> &callback) |
| Add an event listener to a shutdown complete event. More... | |
| priv::RenderTarget & | getRenderTarget () |
| ~Engine () | |
| Destructor. More... | |
Runs the main game loop.
ime::Engine is the entry point of Infinite Motion Engine.
It is responsible for running, updating and rendering the game world. External code interacts with the engine by pushing and popping ime::Scene at appropriate times
Usage example:
|
explicit |
Constructor.
| gameTitle | The name of the game run by the engine |
| settingsFilename | The name of the file that contains the engine settings |
If the settingsFilename argument is left unspecified the engine will be constructed with default settings
| ime::Engine::Engine | ( | const std::string & | gameName, |
| const PrefContainer & | settings | ||
| ) |
Constructor.
| gameName | The name of the game run by the engine |
| settings | Settings to construct the engine with |
|
delete |
Copy constructor.
|
delete |
Move constructor.
| ime::Engine::~Engine | ( | ) |
Destructor.
| void ime::Engine::cacheScene | ( | const std::string & | name, |
| Scene::Ptr | scene | ||
| ) |
Add a scene to the cache list.
| name | The unique name of the scene for later access |
| scene | The scene to be added |
A cached scene is not destroyed when popped from the Engine but rather saved for reuse. This means that you can have a single instance that you return to. For example, instead of instantiating a new main menu scene every time the user wants to go to the main menu, you can instantiate it once, cache it and use pushCachedScene()
Unlike ime::Scene::setCached, this function will cache the scene immediately
| Scene * ime::Engine::getActiveScene | ( | ) |
Get the active scene.
| audio::AudioManager & ime::Engine::getAudioManager | ( | ) |
Get the engine level audio manager.
Unlike ime::Scene::getAudio, this audio manager is not destroyed when the scene is destroyed, but rather when the engine is shutdown
| PropertyContainer & ime::Engine::getCache | ( | ) |
Get the engine level persistent data.
Data stored in this object persists from scene to scene. This means that the data is preserved during a scene push or a scene pop operation. The data stored inside the cache can be of any type.
For example, the code below saves the current level of the game in the cache such that it can be accessed in any ime::Scene
| Scene * ime::Engine::getCachedScene | ( | const std::string & | name | ) |
Get access to a scene in the cache list.
| name | The name of the scene |
| PrefContainer & ime::Engine::getConfigs | ( | ) |
Get the engines settings.
| AccessViolationException | If this function is called before the engine is initialized |
Note that this function returns the settings that were used during the initialization of the engine. Modifying then after the engine has been initialized has no effect
| Time ime::Engine::getElapsedTime | ( | ) | const |
Get the time passed since the engine was started.
The elapsed time starts counting after run() is called.
| const std::string & ime::Engine::getGameName | ( | ) | const |
Get the name of the game run by the engine.
This name is provided as an argument to the engines constructor(s)
| ui::GuiContainer & ime::Engine::getGui | ( | ) |
Get the engine level gui.
| AccessViolationException | If this function is called before the engine is initialized |
Unlike ime::Scene::getGui, this gui is not destroyed when the scene is destroyed, but rather when the engine is shutdown. It may be useful when the same UI is required across multiple scenes. Note that this gui is rendered on top of the scene level gui
| input::InputManager & ime::Engine::getInputManager | ( | ) |
Get the engine level input manager.
Unlike ime::Scene::getInput, event listeners registered to this input manager are executed regardless of which scene is active and are only destroyed when the engine is shutdown
| unsigned int ime::Engine::getPhysicsUpdateFrameRate | ( | ) | const |
Get the fixed update frame rate.
| Scene * ime::Engine::getPreviousScene | ( | ) |
Get the scene that was previously active.
Note that after a push operation, the previously active scene is the scene that was pushed over and after a pop operation, it is the scene that will be active is the current active scene is popped
| PrefContainer & ime::Engine::getSavableCache | ( | ) |
Get the engine level savable persistent data.
The savable cache behaves exactly the same way as the normal cahce (see getCache()). The difference between them is that the savable cache can only store data of a known type and can be saved/read to/from the disk. Its main purpose is to save player preferences. For example, you can use it to save the players desired audio levels
| std::size_t ime::Engine::getSceneCount | ( | ) | const |
Get the number of scenes in the engine.
| TimerManager & ime::Engine::getTimer | ( | ) |
Get the engine level timer manager.
Unlike ime::Scene::getTimer, event listeners registered to this timer manager are executed regardless of which scene is active and are destroyed when the engine is shutdown
| Window & ime::Engine::getWindow | ( | ) |
Get the engines game window.
| AccessViolationException | If this function is called before the engine is initialized |
| void ime::Engine::initialize | ( | ) |
Initialize the engine.
| bool ime::Engine::isEventListenerSuspended | ( | int | id | ) | const |
Check if an event listener is suspended or not.
| id | The identification number of the listener to be checked |
This function also returns false if the specified event listener does not exist
| bool ime::Engine::isPaused | ( | ) | const |
| bool ime::Engine::isRunning | ( | ) | const |
Check if the engine is running or not.
| bool ime::Engine::isSceneCached | ( | const std::string & | name | ) | const |
Check if a scene with a given name is cached or not.
| name | The name of the scene to be checked |
| int ime::Engine::onFrameEnd | ( | const Callback<> & | callback, |
| bool | oneTime = false |
||
| ) |
Add an event listener to a current frame end event.
| callback | Function to be executed when the current frame ends |
| oneTime | True to execute the callback one-time or false to execute it every time the event is triggered |
You can add any number of event listeners to this event
| int ime::Engine::onFrameStart | ( | const Callback<> & | callback, |
| bool | oneTime = false |
||
| ) |
Add an event listener to a current frame start event.
| callback | Function to executed when the current frame starts |
| oneTime | True to execute the callback one-time or false to execute it every time the event is triggered |
You can add any number of event listeners to this event
| int ime::Engine::onInit | ( | const Callback<> & | callback | ) |
Add an event listener to an initialize event.
| callback | The function to be executed after the engine is initialized |
You can add any number of event listeners to this event
Add an event listener to a scene activation event.
| callback | Function to be executed when a scene becomes active |
| oneTime | True to execute the callback one-time or false to execute it every time the event is triggered |
This event is emitted when a scene becomes active. The callback is passed a pointer to the scene that was activated.
You can add any number of event listeners to this event
| int ime::Engine::onShutDown | ( | const Callback<> & | callback | ) |
Execute a callback when the engine is about to shut down.
| callback | The function to be executed when the engine is starts to shut down |
This event is emitted when the engine is about to begin its shutdown sequence. To perform an action after the engine has completed its shutdown sequence, use onShutdownComplete()
You can add any number of event listeners to this event
| void ime::Engine::onShutdownComplete | ( | const Callback<> & | callback | ) |
Add an event listener to a shutdown complete event.
| callback | The function to be executed when the engine complete its shutdown sequence |
| int ime::Engine::onStart | ( | const Callback<> & | callback | ) |
Add an event listener to an engine start event.
| callback | Function to be executed when the engine starts running |
You can add any number of event listeners to this event
| void ime::Engine::popScene | ( | int | numScenes = 1 | ) |
Remove scenes from the engine.
| numScenes | The number of scenes to remove |
If the engine is not running, the scene(s) will be removed immediately, otherwise they will be removed at the end of the current frame.
You can remove multiple scenes in the same frame by calling this function as many times as the number of scenes to be removed or by specifying the number of scenes to be removed. For example the code below removes all scenes from the engine:
Note that calling this function when the engine has no scenes has no effect
| bool ime::Engine::pushCachedScene | ( | const std::string & | name | ) |
Add a cached scene to the engine.
| name | The name of the scene to add |
Note that after the push, the scene is removed from the cache and will be added back once its popped (if its cache state is still true)
| void ime::Engine::pushScene | ( | Scene::Ptr | scene | ) |
Add a Scene to the engine.
| scene | The scene to be added |
If the engine is running, the scene will not be pushed immediately but rather at the end of the current frame. You can push multiple scenes in the same frame, the last scene to be pushed will become the active scene. All the other scenes will be pushed without being entered
To be notified when a scene becomes active, see onSceneActivate()
| void ime::Engine::quit | ( | ) |
Stop the engine.
This function will remove all scenes that have been added to the engine and reset it's initialization state. Therefore, the engine must be reinitialized before it is re-run
| void ime::Engine::removeAllScenes | ( | ) |
Remove all the scenes from the engine.
If a scene is not pushed in the same frame as this function call, then the engine will automatically shutdown since it must have at least one scene to run.
This function is an alias to the following code:
| void ime::Engine::removeAllScenesExceptActive | ( | ) |
Remove all the scenes from the engine except the current active scene.
Note that if this function is called whilst the engine is not running, then all the scenes will be removed from the engine.
| bool ime::Engine::removeEventListener | ( | int | id | ) |
Remove an event listener from an event.
| id | The unique identification number of the event listener |
| void ime::Engine::run | ( | ) |
Start the main loop.
| AccessViolationException | If this function is called before the engine is initialized or before at least one Scene is pushed to the engine |
| void ime::Engine::setPause | ( | bool | pause | ) |
Pause or resume the engine.
| pause | True to pause the engine or false to resume it |
Pausing the engine suspends all time based updates such as animations, physics, movements, timers. The same effect can be achieved by setting a scenes timescale to 0. The difference between the two is that the latter invokes the scenes update functions with a delta time of ime::Time::Zero whilst the former does not invoke the update functions at all.
By default, the engine is not paused
| void ime::Engine::setPhysicsUpdateFrameRate | ( | unsigned int | frameRate | ) |
Set the physics update frame rate.
| frameRate | The new physics update frame rate |
| InvalidArgumentException | If the specified frame rate is 0 |
Physics based components are updated using a fixed timestep defined by the formula:
timestep = 1.0f / physicsUpdateFrameRate
By default the physics update frame rate is 60 fps
| void ime::Engine::suspendedEventListener | ( | int | id, |
| bool | suspend | ||
| ) |
Pause or resume execution of an event listener.
| id | The event listeners unique identification number |
| suspend | True to suspend/pause or false to unsuspend/resume |
| bool ime::Engine::uncacheScene | ( | const std::string & | name | ) |
Remove a scene from the cache list.
| name | The name of the scene to be removed |
Unlike calling ime::Scene::setCached with a false argument, which destroys the scene after it gets popped, this function will destroy the scene immediately