Spinning Topp Logo BlackTopp Studios
inc
entresol.h
1 // © Copyright 2010 - 2016 BlackTopp Studios Inc.
2 /* This file is part of The Mezzanine Engine.
3 
4  The Mezzanine Engine is free software: you can redistribute it and/or modify
5  it under the terms of the GNU General Public License as published by
6  the Free Software Foundation, either version 3 of the License, or
7  (at your option) any later version.
8 
9  The Mezzanine Engine is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  GNU General Public License for more details.
13 
14  You should have received a copy of the GNU General Public License
15  along with The Mezzanine Engine. If not, see <http://www.gnu.org/licenses/>.
16 */
17 /* The original authors have included a copy of the license specified above in the
18  'Docs' folder. See 'gpl.txt'
19 */
20 /* We welcome the use of the Mezzanine engine to anyone, including companies who wish to
21  Build professional software and charge for their product.
22 
23  However there are some practical restrictions, so if your project involves
24  any of the following you should contact us and we will try to work something
25  out:
26  - DRM or Copy Protection of any kind(except Copyrights)
27  - Software Patents You Do Not Wish to Freely License
28  - Any Kind of Linking to Non-GPL licensed Works
29  - Are Currently In Violation of Another Copyright Holder's GPL License
30  - If You want to change our code and not add a few hundred MB of stuff to
31  your distribution
32 
33  These and other limitations could cause serious legal problems if you ignore
34  them, so it is best to simply contact us or the Free Software Foundation, if
35  you have any questions.
36 
37  Joseph Toppi - toppij@gmail.com
38  John Blackwood - makoenergy02@gmail.com
39 */
40 #ifndef _entresol_h
41 #define _entresol_h
42 
43 #include "dox/mainpage.h"
44 
45 /**
46  @page Mezzanine
47  The Mezzanine Engine isn't really an engine. It is glue holding other code and libraries together. It is a series of other open source libraries (sometimes
48  less user friendly, and almost always more sophisticated) that are held together in a single API that will be stable after its 1.0 release. Others have
49  attempted to do things like this before. Usually simple mistakes are made along the way that have huge negative impacts later in the design. A common mistake
50  code is to copy and paste from open source projects with no plans for maintainability. This means that those projects get all the features and bugs
51  from when they copied, without updates, new features and bugfixes since they started integrating the code. We too have copy and pasted, however we are
52  keeping it up to date, and have a plan for upgrading each component we have brought in.
53 
54  There is no simple way to guarantee access to the most up to date libraries, this means there will meaningful work on integration. Many Linux distributions try
55  to keep the most up to date shared libraries around. What happens when they don't ship what you need, ship something broken or an older library. What about
56  Windows and Mac OS X which make no attempt to keep these kinds of software up to date. What if you do manage to get the software keep it up to date. After that you
57  still have to work on confusing compiler and linker options. IDEs like QT Creator, Code::Blocks or Visual Studio aren't going to set that up for you. The
58  Mezzanine Engine project depends on a dozen or more libaries, so would your project if it had high performance 3d graphics, easy to use 3d physics integrated
59  with the graphics and 3d positional audio ready to run on Windows, Linux and Mac OS X. We are figuring it out once, getting it right ( if we aren't, tell us and
60  we will fix it ), so it doesn't need to be done again and again, for each game.
61 
62  This is still in heavy development and is not in usable condition for all systems. Currently the synchronization of 3d graphics and physics works great. Some of
63  the more advanced features of both physics and graphics to do not yet work. There are a number of other features that are in varied states of development. XML,
64  User Interface, Lua Scripting, 3d Audio, Multithreading, Resource management...
65 
66  If we do our jobs right this will save time and effort making, updating and porting games between a variety of platforms. If you link only
67  against this library, not a single line of your standard compliant C++ code should need to change between platforms. At this early stage we are proving the
68  concept with "Catch!" our first sample game. It Currently runs on Linux, Windows and Mac OS X with an Identical
69  codebase. When we are done with "Catch!" We want it to have one codebase (with no messy \#IFDEFs in game code for compatibility), and downloadable in the Iphone
70  app store, in the Android Marketplace, on the PS3, Wii, downloadable on Steam, and in a variety of linux repositories.
71 
72  @section doxygen This Documention
73  This documentation is automatically extracted from the source code of the Mezzanine. It is intended as a reference to describe the Mezzanine API. We hope that
74  people with moderate or advanced C++ experience will be able to use this to increase their knowledge and get the most out of the Mezzanine. This is not a
75  tutorial and is not likely to helpful to novice C++ developers. For more information please see the following:
76  - An automatically generated list of issues with this documentation - http://mezzanineapi.github.io/DoxygenWarnings.txt
77  - The BlackTopp Studios Inc. website - http://www.blacktoppstudios.com/
78  - The Mezzanine Github page - https://github.com/BlackToppStudios/Mezzanine
79 
80  If you want to know more about Doxygen please see: http://www.stack.nl/~dimitri/doxygen/
81 
82  @section enginestructure Engine Structure
83  The engine is laid out in a variety of classes of a few generalized roles.
84 
85  Some classes are focal points for functionality and internally unify a number of components to do what they do. These managers sometimes conceal a large amount
86  of complexity and try to present a concise API. Managers ( Mezzanine::ManagerBase instances ) generally have a rigid place in the structure of the
87  running program. This is where are the logic that says how something is done exists, for example "how does something get drawn on the screen?" or
88  "how do you detect if two objects are colliding?". Managers are owned either by the Mezzanine::Entresol or a Mezzanine::World
89  depending on their roles and technical limitations.
90 
91  The Mezzanine::Threading::FrameScheduler is responsible for running the work each task requires. Most managers mantain one or more of
92  Mezzanine::Threading::iWorkUnit implementations/instances to do work each frame. The FrameScheduler performs some heuristics and manages when and where
93  the workunits will be run. Generally these are created early in the lifetime of a game and destroyed near the end.
94 
95  Other classes are more similar to data, things like the @ref Mezzanine::Vector3 and the @ref Mezzanine::Quaternion. You can create these things whenever you like
96  and generally have good support for integrating into a various parts of the system. In these classes there is a good deal of math and conversion routines. These
97  are commonly passed around by more sophisticated classes for a variety of reasons. Some of these are small enough to pass around value and some are not.
98 
99  There are some classes that are somewhere between data and singular large-scale aggregration of functionality in managers. The functionality is carefully controlled
100  and most commonly created, deleted and otherwised managed through managers. Many of these classes like the @ref Mezzanine::Graphics::Light or @ref Mezzanine::RigidDebris are
101  present inside the game simulation as well as having a presence as in the simulation visible to the user.
102 
103  Some classes are that really are just convient places to put functions, things like the @ref Mezzanine::StringTools are good examples of these logical grouping of functions.
104 
105  @subsection managers Managers
106 
107  The canonical source for the list of managers is the ManagerBase::ManagerType enum.
108 
109  A manager is simply a logical grouping of functionality. A number of them exist covering all the major functionality that a game using the the Mezzanine engine would
110  need in most situations.
111 
112  All Managers inherit from ManagerBase. Before the switch to the all support the basic callback and priority functionality because of this.
113 
114  // Entresol Managers // Namespaces
115  MT_AudioManager = 1, // Audio
116  MT_AnimationManager, // Graphics
117  MT_CollisionShapeManager, // Physics
118  MT_GraphicsManager, // Graphics
119  MT_EventManager, // Mezzanine
120  MT_InputManager, // Input-
121  MT_LogManager, // Mezzanine
122  MT_MaterialManager, // Graphics
123  MT_MeshManager, // Graphics
124  MT_NetworkManager, // Network
125  MT_ResourceManager, // Resource
126  MT_ScriptingManager, // Scripting
127  MT_UIManager, // UI
128 
129  // World Managers // Namespaces
130  MT_ActorManager = 100, // Mezzanine
131  MT_AreaEffectManager, // Mezzanine
132  MT_PagingManager, // Paging
133  MT_PhysicsManager, // Physics
134  MT_SceneManager, // Graphics
135  MT_SoundScapeManager, // Audio
136  MT_TerrainManager, // Mezzanine
137  MT_VehicleManager, // Mezzanine
138 
139  @subsubsection managerlist A list of Managers in the Mezzanine
140  - @ref Mezzanine::ActorManager - Store and allows retrieval of Actors, when an actor is in this it is part of the game simulaiton
141  - @ref Mezzanine::Audio::AudioManager - Play, stop and otherwise work with sound and music.
142  - @ref Mezzanine::Physics::CollisionShapeManager - Store/create/delete shapes that can be used for physics and collision detection
143  - @ref Mezzanine::EventManager - Get messages and events from the operating system (and user, but that will change)
144  - @ref Mezzanine::Graphics::GraphicsManager - Adjust Resolution, refresh rate, color depth and thing like that.
145  - @ref Mezzanine::Graphics::MeshManager - Manage Meshes that can be rendered to the the screen.
146  - @ref Mezzanine::Network::NetworkManager - Manages the transmission and retreival of network traffic.
147  - @ref Mezzanine::Physics::PhysicsManager - Control settings that have to do with the physics simulation.
148  - @ref Mezzanine::ResourceManager - Loads Files and locate them in an efficient way.
149  - @ref Mezzanine::Graphics::SceneManager - Control Lighting, skyboxes, particle effects etc...
150  - @ref Mezzanine::TerrainManager - Work with terrain components like height maps.
151  - @ref Mezzanine::UI::UIManager - Create and manage buttons, scrollbars and other widgets.
152 
153  @subsubsection The World, A manager of managers
154  A thorough description needs to go here
155 
156  @subpage mainloop1 "Main Loop Flow"
157 
158  @ref Mezzanine::World "World - It integrates everything"
159 
160  @ref Mezzanine::EventManager "Events - Handling messages, event and interupts from the outisde"
161 
162  @subpage actorcontainer1 "Actor Container - Keeping track of our in game objects"
163 
164  @section Types Data Types
165 
166  @subsection CompoundTypes Compound Data Type
167 
168  @ref Mezzanine::ColourValue
169 
170  @ref Mezzanine::Input::MetaCode "Mezzanine::MetaCode - A unit of user input"
171 
172  @ref Mezzanine::Plane
173 
174  @ref Mezzanine::Quaternion
175 
176  @ref Mezzanine::Ray
177 
178  @ref Mezzanine::Transform
179 
180  @ref Mezzanine::Vector2
181 
182  @ref Mezzanine::Vector3
183 
184  @subsection SimpleDataTypes Simple Data Types
185 
186  @ref Mezzanine::Char8
187 
188  @ref Mezzanine::Integer
189 
190  @ref Mezzanine::Real
191 
192  @ref Mezzanine::String
193 
194  @ref Mezzanine::Whole
195 
196  @par There are also a variety of enumerations. Aspect Ratio...
197  @todo Fill out the Simple Data Types with all the enumerations.
198 
199  @section Sophisticated Sophisticated Systems
200 
201  @ref Mezzanine::WorldObject "WorldObjects - Items in the world"
202 
203  @ref Mezzanine::EventBase
204 
205  @ref Mezzanine::Graphics::GraphicsManager
206 
207  @ref XMLManual
208 
209  @ref UIManual
210 
211  @ref ScriptingManual
212 
213  @ref Serialization
214 
215  @ref ThreadingManual
216 
217  @section Licensing Licensing Information
218 
219  @ref GPLLicense "Mezzanine GNU Public License 3"
220 
221  @ref OriginalpugixmlLicense "XML MIT License"
222 
223 
224 
225  @page GPLLicense Mezzanine GNU Public License 3
226  Here is a simple summary of the license terms. It is included at the top of every
227  source and header file in the engine:
228  \n \n
229  @verbatim
230  © Copyright 2010 - 2016 BlackTopp Studios Inc.
231  This file is part of The Mezzanine Engine.
232 
233  The Mezzanine Engine is free software: you can redistribute it and/or modify
234  it under the terms of the GNU General Public License as published by
235  the Free Software Foundation, either version 3 of the License, or
236  (at your option) any later version.
237 
238  The Mezzanine Engine is distributed in the hope that it will be useful,
239  but WITHOUT ANY WARRANTY; without even the implied warranty of
240  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
241  GNU General Public License for more details.
242 
243  You should have received a copy of the GNU General Public License
244  along with The Mezzanine Engine. If not, see <http://www.gnu.org/licenses/>.
245 
246  The original authors have included a copy of the license specified above in the
247  'Docs' folder. See 'gpl.txt'
248 
249  We welcome the use of the Mezzanine engine to anyone, including companies who wish to
250  Build professional software and charge for their product.
251 
252  However there are some practical restrictions, so if your project involves
253  any of the following you should contact us and we will try to work something
254  out:
255  - DRM or Copy Protection of any kind(except Copyrights)
256  - Software Patents You Do Not Wish to Freely License
257  - Any Kind of Linking to Non-GPL licensed Works
258  - Are Currently In Violation of Another Copyright Holder's GPL License
259  - If You want to change our code and not add a few hundred MB of stuff to
260  your distribution
261 
262  These and other limitations could cause serious legal problems if you ignore
263  them, so it is best to simply contact us or the Free Software Foundation, if
264  you have any questions.
265 
266  Joseph Toppi - toppij@gmail.com
267  John Blackwood - makoenergy02@gmail.com
268  @endverbatim
269  \n \n
270  Here is the contents of gpl.txt that comes in the docs/ folder of with every
271  complete repository of the engine:
272  \n \n
273  @verbinclude gpl.txt
274 */
275 
276 //And now for actual source code!
277 #include "datatypes.h"
278 #include "singleton.h"
279 #include "stringtool.h"
280 
281 #include "Resource/resourceenumerations.h"
282 #include "XML/xml.h"
283 
284 #ifndef SWIG
286 #endif
287 
288 //Other forward declarations
289 //forward Declarations so that we do not need #include "SDL.h"
290 class SDL_Surface;
291 
292 //forward Declarations so that we do not need #include <Ogre.h>
293 namespace Ogre
294 {
295  class ParticleFXPlugin;
296 }
297 
298 ///////////////////////////////////////////////////////////////////////////////
299 /// @namespace Mezzanine
300 /// @brief The bulk of the engine components go in this namspace
301 /// @details This is where imporant classes like World, GraphicsManager, and
302 /// The eventmanager reside. For more detailed usage information please refer
303 /// to individual class documentation or the @ref index main page.
304 ///////////////////////////////////////
305 namespace Mezzanine
306 {
307  class EntresolManager;
308  class EntresolManagerFactory;
309  class World;
310  class WorldManager;
311  namespace Physics
312  {
313  class ManagerConstructionInfo;
314  }
315  ///////////////////////////////////////////////////////////////////////////////
316  /// @class Entresol
317  /// @brief This is the main entry point for the entire library.
318  /// @details The entresol coordinates and integrates all the underlying subsystems,
319  /// Currently Ogre3d is used for 3d Graphics, Bullet is used for physics, and
320  /// SDL is used for user input and window management. Games will need a
321  /// container for all the playing pieces. It makes sense to tie all of this
322  /// functionality into one core object.
323  ///////////////////////////////////////
324  class MEZZ_LIB Entresol : public Singleton<Entresol>
325  {
326  public:
327  /// @brief Basic container type for factories that construct known manager types.
328  typedef std::map<String,EntresolManagerFactory*> ManagerFactoryMap;
329  /// @brief Basic container type for factories that construct known manager types.
330  typedef std::vector<EntresolManagerFactory*> ManagerFactoryVec;
331  /// @brief Iterator type for manager factories stored by this class.
332  typedef ManagerFactoryMap::iterator ManagerFactoryIterator;
333  /// @brief Const Iterator type for manager factories stored by this class.
334  typedef ManagerFactoryMap::const_iterator ConstManagerFactoryIterator;
335  /// @brief Basic container type for normal manager storage in this class.
336  typedef std::list<EntresolManager*> ManagerContainer;
337  /// @brief Iterator type for managers stored by this class.
338  typedef ManagerContainer::iterator ManagerIterator;
339  /// @brief Const Iterator type for managers stored by this class.
340  typedef ManagerContainer::const_iterator ConstManagerIterator;
341  /// @brief Container type for passing pre-created managers into the Entresol upon creation.
342  typedef std::vector<EntresolManager*> ManagerVec;
343  /// @brief Iterator type for containers of pre-created managers.
344  typedef ManagerVec::iterator ManagerVecIterator;
345  /// @brief Const Iterator type for containers of pre-created managers.
346  typedef ManagerVec::const_iterator ConstManagerVecIterator;
347  /// @brief Basic container type for World storage.
348  typedef std::vector<World*> WorldContainer;
349  /// @brief Iterator type for Worlds stored by this class.
350  typedef WorldContainer::iterator WorldIterator;
351  /// @brief Const Iterator type for Worlds stored by this class.
352  typedef WorldContainer::const_iterator ConstWorldIterator;
353  private:
354  /// @internal
355  /// @brief This is a map containing all the registered manager factories.
356  static ManagerFactoryMap ManagerFactories;
357  /// @internal
358  /// @brief The core structure responsible for our multi-threaded main loop.
359  Threading::FrameScheduler WorkScheduler;
360  /// @internal
361  /// @brief This is a listing of the priority and the Manager, and a pointer to the manager.
362  ManagerContainer ManagerList;
363  /// @internal
364  /// @brief This is a listing of the priority and the Manager, and a pointer to the manager.
365  WorldContainer Worlds;
366  /// @internal
367  /// @brief Used to track Ogre specific details for the statically linked Particle plugin
368  Ogre::ParticleFXPlugin* SubSystemParticleFXPlugin;
369  /// @internal
370  /// @brief Responsible for asynchronously flushing the logs to disk (or wherever they sync to).
371  Threading::LogAggregator* Aggregator;
372  /// @internal
373  /// @brief Internal value used to indicate during the main loop something wants the loop to end.
374  Int32 ManualLoopBreak;
375 
376  ///////////////////////////////////////////////////////////////////////////////
377  // Internal Initialization and Deinitialization Methods
378 
379  /// @internal
380  /// @brief This is called by most of the constructors so that the is one unified place to have all the settings made.
381  /// @param EngineDataPath The directory where engine specific data (as opposed to game/application data) reside, and it include the plugins file and potentially othe low level resources.
382  /// @param LogFileName This is the place that log messages get sent to. This is relative to the working directory of the application/game.
383  /// @param ManagersToBeAdded This is a vector of manager pointers that will be used instead of creating the default ones
384  void Construct(const String& EngineDataPath, const String& GraphicsLogFileName, const ManagerVec& ManagersToBeAdded);
385  /// @internal
386  /// @brief Used to intialize from XML
387  /// @param EngineDataPath The directory where engine specific data (as opposed to game/application data) reside, and it include the plugins file and potentially othe low level resources.
388  /// @param ArchType Should This be looking for raw or zip or whatever kind of files.
389  /// @param InitializerFile The Mezzanine MXI file to use to initialize the engine.
390  void ConstructFromXML(const String& EngineDataPath, const Resource::ArchiveType ArchType, const String& InitializerFile);
391 
392  /// @internal
393  /// @brief If not already created create an instance of Ogre.
394  void SetupOgre();
395  /// @internal
396  /// @brief Do any teardown required for Ogre, then destroy Ogre.
397  void DestroyOgre();
398  /// @internal
399  /// @brief Do any teardown required for SDL that may have been missed by other managers.
400  void DestroySDL();
401 
402  /// @internal
403  /// @brief Create and direct streams used for logging that are not part of the FrameScheduler.
404  /// @details This sets the name of the Ogre log file (so must be called after the SetupOgre
405  /// function is called). This will be changed in the future to change/set the framescheduler
406  /// log, in the meantime its only interaction with the framescheduler is adding a
407  /// LogAggregator WorkUnit.
408  /// @param LogFileName The name of the file to log to.
409  void SetupLogging(const String& OgreLogFileName);
410  /// @internal
411  /// @brief Creates the logging components used by ogre and configures them appropriately.
412  /// @param LogFileName The name of the file to log to.
413  void SetupOgreLogging(const String& OgreLogFileName);
414  /// @internal
415  /// @brief Creates the appropriate streams for multi-threaded logging and configures them appropriately.
416  void SetupInternalLogging();
417  /// @internal
418  /// @brief Closes log files/streams and removes any WorkUnits from Scheduling dedicated to logging.
419  void DestroyLogging();
420 
421  /// @internal
422  /// @brief Performs a small series of checks to verify assumptions made by the Mezzanine.
423  void SanityChecks();
424  /// @internal
425  /// @brief Checks if all managers currently stored in this Entresol have been initialized.
426  /// @return Returns true if all stored managers have been initialized, false otherwise.
427  Boole VerifyManagerInitializations();
428  public:
429  ///////////////////////////////////////////////////////////////////////////////
430  // Creation and Deletion methods
431 
432  /// @brief Initializer file constructor.
433  /// @details This function expects an ".mxi" (Mezzanine XML Initializer) file.
434  /// If the file provided is not one of this type this function will throw an exception. @n @n
435  /// When initializing factories in the XML file this constructor does not initialize any additional manager factories, so if they are called this will throw an exception.
436  /// @param EngineDataPath The directory where engine specific data resides. This is where it will search for the specified initializer file.
437  /// @param ArchType The type of archive at the path provided.
438  /// @param InitializerFile The file that describes how to initialize Mezzanine.
439  Entresol(const String& EngineDataPath, const Resource::ArchiveType ArchType, const String& InitializerFile = "Mezzanine.mxi");
440  /// @brief Factory and initializer file constructor.
441  /// @details This function expects an ".mxi" (Mezzanine XML Initializer) file.
442  /// If the file provided is not one of this type this function will throw an exception. @n @n
443  /// Also default factories are already added and thus do not need to be included in the Factory vector.
444  /// @param CustomFactories A vector containing the additional factories to be registered before initializing the engine.
445  /// @param EngineDataPath The directory where engine specific data resides. This is where it will search for the specified initializer file.
446  /// @param ArchType The type of archive at the path provided.
447  /// @param InitializerFile The file that describes how to initialize Mezzanine.
448  Entresol(ManagerFactoryVec& CustomFactories, const String& EngineDataPath, const Resource::ArchiveType ArchType, const String& InitializerFile = "Mezzanine.mxi");
449  /// @brief Descriptive constructor With Manager Pointers.
450  /// @param EngineDataPath The directory where engine specific data (as opposed to game/application data) reside, and it include the plugins file and potentially other low level resources.
451  /// @param LogFileName This is the place that log messages get sent to.
452  Entresol(const String& EngineDataPath, const String& LogFileName = "Mezzanine.log" );
453  /// @brief Descriptive constructor.
454  /// @details This constructor allows for an easier way to define the boundaries for items moving about inside the entresol.
455  /// This constructor provides no default arguments, but allows for a lot of customization. In addition to everything the other
456  /// constructors this one can accept a vector of pointers to managers which will be added.
457  /// @param EngineDataPath The directory where engine specific data (as opposed to game/application data) reside, and it include the plugins file and potentially othe low level resources.
458  /// @param LogFileName This is the place that log messages get sent to.
459  /// @param ManagersToBeAdded This is a vector of manager pointers that will be used instead of creating new ones.
460  Entresol(const String& EngineDataPath, const String& LogFileName, const ManagerVec& ManagersToBeAdded);
461  /// @brief Default constructor.
462  /// @details This simply performs the same work as the descriptive constructor with some sane defaults.
463  /// @warning Do not make a new entresol if one already exists. This can only cause problems.
464  Entresol();
465  /// @brief Deconstructor.
466  /// @details This Tears down all the items created by the entresol, and safely frees any graphical resources, we will also delete any Objects passed into the
467  /// entresol by pointer. We will not delete any pointers we pass out (like from the Events from the Event manager).
468  ~Entresol();
469 
470  ///////////////////////////////////////////////////////////////////////////////
471  // Utility
472 
473  /// @brief Gets the core structure responsible for scheduling work in the Entresol main loop.
474  /// @return Returns a reference to the FrameScheduler being used by this Entresol.
475  Threading::FrameScheduler& GetScheduler();
476 
477  ///////////////////////////////////////////////////////////////////////////////
478  // Timing system methods
479 
480  /// @brief This sets a new Target Frame Rate
481  /// @details This sets a new time for each frame. This divides 1000 by the NewFrameRate, drops and floating point amount and uses that amount in an call to
482  /// Entresol::SetTargetFrameTime. For example a target frame rate of 40 with cause each frame to take 25 milliseconds, and a Framerate of 70 would take 14 ms
483  /// @param NewFrameRate The new desired frame rate.
484  /// @warning Setting vary low or very High values could cause unknown errors, This is on our todo list of issues to fix.
485  void SetTargetFrameRate(const Whole NewFrameRate);
486  /// @brief This sets a new target time in milliseconds.
487  /// @details This sets a new time for each frame. Each iteration of the game loop will take around this long to run, but rarely exactly this long. Setting this value
488  /// Higher can results in power savings (battery life), but setting it too High can cause choppiness. Settings this value higher can result in smoother gameplay, but
489  /// set it too high, and system resources could becom completely taxed and power will be wasted.
490  /// @param NewTargetTime The new length of time, in milliseconds.
491  /// @warning Setting vary low or very High values could cause unknown errors, This is on our todo list of issues to fix.
492  void SetTargetFrameTimeMilliseconds(const Whole NewTargetTime);
493  /// @brief This sets a new target time microseconds.
494  /// @details This sets a new time for each frame. Each iteration of the game loop will take around this long to run, but rarely exactly this long. Setting this value
495  /// Higher can results in power savings (battery life), but setting it too High can cause choppiness. Settings this value higher can result in smoother gameplay, but
496  /// set it too high, and system resources could becom completely taxed and power will be wasted.
497  /// @param NewTargetTime The new length of time, in microseconds.
498  /// @warning Setting vary low or very High values could cause unknown errors, This is on our todo list of issues to fix.
499  void SetTargetFrameTimeMicroseconds(const Whole NewTargetTime);
500  /// @brief Retrieves the amount of milliseconds we would like each iteration of the Main Loop to be.
501  /// @details In practice I've done some more testing, started out digging through the code to see if there was anything wrong, there seemed to be random extra words inside our code that the compiler didn't mind that shouldn't be there. like there was a " Schedule : " right after a line where a pointer was initialized. I only found such occurrences in gamebase.cpp though, removed them and did two tests. First test I was just randomly clicking and then I inadvertently threw the metal sphere down into the abyss, the sphere was really close to the camera when this happened, about to go over. Second time I ran the game trying to click stuff, I simply couldn't click anything. I even tried zooming in on the robots, although I can only get so close to them before I have to tamper with the camera, which I haven't done yet, but there were no results with the Robots. The third time I was successfully able to stop two spheres and move them around the platform quite smoothly. These spheres were slightly further away from the camera compared to the first run. I stopped the wooden sphere and the second metal sphere. I included a screen shot and a copy of my log for the third run. The spheres in the screenshot are both in a rest position.dware performance or timing concerns can cause this goal to be unnaitanable or trivially easy. The main loop with actually
502  /// pause execution until this amount of time is reach is main loop iteration, However, the mainloop will always skip waiting if hardware is overburdened.
503  /// @return This returns a Whole with the current value in milliseconds.
504  Whole GetTargetFrameTimeMilliseconds() const;
505  /// @brief Retrieves the amount of milliseconds we would like each iteration of the Main Loop to be.
506  /// @details In practice I've done some more testing, started out digging through the code to see if there was anything wrong, there seemed to be random extra words inside our code that the compiler didn't mind that shouldn't be there. like there was a " Schedule : " right after a line where a pointer was initialized. I only found such occurrences in gamebase.cpp though, removed them and did two tests. First test I was just randomly clicking and then I inadvertently threw the metal sphere down into the abyss, the sphere was really close to the camera when this happened, about to go over. Second time I ran the game trying to click stuff, I simply couldn't click anything. I even tried zooming in on the robots, although I can only get so close to them before I have to tamper with the camera, which I haven't done yet, but there were no results with the Robots. The third time I was successfully able to stop two spheres and move them around the platform quite smoothly. These spheres were slightly further away from the camera compared to the first run. I stopped the wooden sphere and the second metal sphere. I included a screen shot and a copy of my log for the third run. The spheres in the screenshot are both in a rest position.dware performance or timing concerns can cause this goal to be unnaitanable or trivially easy. The main loop with actually
507  /// pause execution until this amount of time is reach is main loop iteration, However, the mainloop will always skip waiting if hardware is overburdened.
508  /// @return This returns a Whole with the current value in microseconds.
509  Whole GetTargetFrameTimeMicroseconds() const;
510 
511  /// @brief Gets the amount of time since the last time the last frame took to run.
512  /// @details This returns, in milliseconds the amount of time since the frame started.
513  /// @return This returns a whole number which can be used to aid in the timimg of various algorithms.
514  Whole GetLastFrameTimeMilliseconds() const;
515  /// @brief Gets the amount of time since the last time the last frame took to run.
516  /// @details This returns, in microseconds the amount of time since the frame started.
517  /// @return This returns a whole number which can be used to aid in the timimg of various algorithms.
518  Whole GetLastFrameTimeMicroseconds() const;
519 
520  ///////////////////////////////////////////////////////////////////////////////
521  // Initialization and Deinitialization
522 
523  /// @brief This initializes all managers and Worlds currently in the Entresol.
524  /// @remarks Worlds must be initialized prior to use. Passing in "false" should only be done in Tools, Tests, or if additional configuration needs
525  /// to be done in between Entresol managers and Worlds being initialized.
526  /// @param InitWorlds Whether or not to initialize every World stored in this manager. If false, then only Entresol managers will be initialized.
527  void Initialize(const Boole InitWorlds);
528  /// @brief This deinitializeds all managers and Worlds currently in the Entresol.
529  void Deinitialize();
530 
531  /// @brief Initialize any default managers and any added after construction. This should be called before DoOneFrame()
532  void PreMainLoopInit();
533 
534  ///////////////////////////////////////////////////////////////////////////////
535  // Main Loop
536 
537  /// @brief This Function house the main loop.
538  /// @details If using this you don't need to worry about initialization of managers or other pre main loop items.
539  void MainLoop();
540  /// @brief Run one frame
541  /// @details This should only be called after Managers and other Pre Main loop items
542  void DoOneFrame();
543 
544  /// @brief This makes the main loop end after it's current frame (or cancels a previous attempt to do so).
545  /// @param Break If true this will break the main loop after the next iteration or the end of the current one. If false the main loop will just keep running.
546  /// @details If called while not in the main loop, it will affect the next main loop iteration.
547  /// This function is thread safe and can be called from any work unit at any time.
548  void BreakMainLoop(Boole Break = true);
549  /// @brief How many frames have elasped?
550  /// @return A Whole containing the currect 0 based frame number.
551  Whole GetFrameCount() const;
552 
553  ///////////////////////////////////////////////////////////////////////////////
554  // Factory Management
555 
556  /// @brief Adds/registers a manager factory with this Entresol, allowing it to be constructed through this API.
557  /// @param ToBeAdded The manager factory to be added.
558  static void AddManagerFactory(EntresolManagerFactory* ToBeAdded);
559  /// @brief Removes a manager factory from this Entresol.
560  /// @param ToBeRemoved A pointer to the manager factory that is to be removed.
561  static void RemoveManagerFactory(EntresolManagerFactory* ToBeRemoved);
562  /// @brief Removes a manager factory from this Entresol.
563  /// @param ImplName The name of the manager implementation created by the factory to be removed.
564  static void RemoveManagerFactory(const String& ImplName);
565  /// @brief Removes and destroys a manager factory in this Entresol.
566  /// @param ToBeRemoved A pointer to the manager factory that is to be removed and destroyed.
567  static void DestroyManagerFactory(EntresolManagerFactory* ToBeRemoved);
568  /// @brief Removes and destroys a manager factory in this Entresol.
569  /// @param ImplName The name of the manager implementation created by the factory to be removed and destroyed.
570  static void DestroyManagerFactory(const String& ImplName);
571  /// @brief Destroys all manager factories in this Entresol.
572  /// @warning The destruction of manager factories should only be done after the corresponding managers have been destroyed, otherwise this will cause an exception.
573  static void DestroyAllManagerFactories();
574  /// @brief Adds all the default manager factories provided by the engine to the Entresol.
575  static void AddAllEngineDefaultManagerFactories();
576 
577  ///////////////////////////////////////////////////////////////////////////////
578  // Upper Management
579 
580  /// @brief Creates a new manager.
581  /// @param ManagerImplName The name of the manager implementation to create.
582  /// @param Params A list of name-value pairs for the params that are to be used when creating the manager.
583  /// @param AddToEntresol Whether or not to add the created manager to the Entresol after creation.
584  /// @return Returns a pointer to the created manager.
585  EntresolManager* CreateManager(const String& ManagerImplName, const NameValuePairList& Params, const Boole AddToEntresol = true);
586  /// @brief Creates a new manager.
587  /// @param ManagerImplName The name of the manager implementation to create.
588  /// @param XMLNode An XML node containing all construction and initialization info for the manager to be created.
589  /// @param AddToEntresol Whether or not to add the created manager to the Entresol after creation.
590  /// @return Returns a pointer to the created manager.
591  EntresolManager* CreateManager(const String& ManagerImplName, const XML::Node& XMLNode, const Boole AddToEntresol = true);
592  /// @brief Destroys a manager.
593  /// @param ToBeDestroyed The manager to be destroyed.
594  void DestroyManager(EntresolManager* ToBeDestroyed);
595  /// @brief Destroys all managers currently in the Entresol.
596  /// @warning Do not call this in anything that is run during the main loop. If you do you will have a bad time.
597  void DestroyAllManagers();
598 
599  /// @brief This adds a manager, in the correct order, to the list that the Entresol calls on.
600  /// @note This method will detect if a manager is being double inserted, and will silently fail in such a case.
601  /// @param ManagerToAdd The pointer to the manager to be added.
602  void AddManager(EntresolManager* ManagerToAdd);
603  /// @brief This removes a manager by finding the matching pointer.
604  /// @param ManagerToRemove A pointer to the manager to be removed.
605  void RemoveManager(EntresolManager* ManagerToRemove);
606  /// @brief This is will find the manager of a given type.
607  /// @param RetrieveType The type ID of the manager to get. Use ManagerBase::ManagerType enum values for this.
608  /// @param WhichOne If not getting the first/only manager of the given type, get one.
609  /// @return This returns a pointer to a ManagerBase, or a NULL pointer if no matching manager exists.
610  EntresolManager* GetManager(const Whole RetrieveType, UInt16 WhichOne = 0);
611  /// @brief This removes a manager of a specific type from the list.
612  /// @param RemoveType The type ID of the manager to remove. Use ManagerBase::ManagerType enum values for this.
613  /// @param WhichOne If not removing the first/only manager of the given type, which one by count are you erasing.
614  void RemoveManager(const Whole RemoveType, UInt16 WhichOne = 0);
615 
616  ///////////////////////////////////////////////////////////////////////////////
617  // World Management
618 
619  /// @brief This creates a world and adds it to the World List.
620  /// @param WorldName String name of the world.
621  /// @return Returns a pointer to the created world.
622  World* CreateWorld(const String& WorldName);
623  /// @brief This creates a world and adds it to the World List.
624  /// @param WorldName String name of the world.
625  /// @param Managers A container of pre-made managers to be used by this world.
626  /// @return Returns a pointer to the created world.
627  World* CreateWorld(const String& WorldName, const std::vector <WorldManager*>& ManagerToBeAdded);
628  /// @brief This creates a world and adds it to the World List.
629  /// @param WorldName String name of the world.
630  /// @param PhysicsInfo A ManagerConstructionInfo struct with data on how to configure the physics for this world.
631  /// @param SceneType A string containing the name of the underlying scene type for this world.
632  /// @return Returns a pointer to the created world.
633  World* CreateWorld(const String& WorldName, const Physics::ManagerConstructionInfo& PhysicsInfo, const String& SceneType);
634  /// @brief This creates a world and adds it to the World List.
635  /// @param WorldName String name of the world.
636  /// @param ManagersToBeAdded A container of pre-made managers to be used by this world.
637  /// @param PhysicsInfo A ManagerConstructionInfo struct with data on how to configure the physics for this world.
638  /// @param SceneType A string containing the name of the underlying scene type for this world.
639  /// @return Returns a pointer to the created world.
640  World* CreateWorld(const String& WorldName, const std::vector<WorldManager*>& ManagersToBeAdded, const Physics::ManagerConstructionInfo& PhysicsInfo, const String& SceneType);
641 
642  /// @brief This adds a world to the list of worlds in the entresol.
643  /// @param WorldToAdd The pointer to the world to be added.
644  void AddWorld(World* WorldToBeAdded);
645 
646  /// @brief This gets a world from the world list by name.
647  /// @param WorldName The string name of the world to retrieve.
648  /// @return Returns a pointer to the world with the given name, otherwise returns NULL.
649  World* GetWorld(const String& WorldName);
650  /// @brief This gets a world from the world list by index.
651  /// @param WorldIndex The index of the world to retrieve.
652  /// @return Returns a pointer to the world at the specified index.
653  World* GetWorld(const Whole Index);
654  /// @brief This gets the number of worlds in the world list.
655  /// @return Returns the number of worlds in the world list.
656  UInt16 GetNumWorlds();
657  /// @brief This removes the given world from the world list.
658  /// @param WorldToBeRemoved Pointer to the world to be removed from the world list.
659  /// @return Returns a pointer to the removed world.
660  World* RemoveWorld(World* WorldToBeRemoved);
661  /// @brief This removes the world with the given name from the world list.
662  /// @param WorldName The name of the world to be removed.
663  /// @return Returns a pointer to the removed world.
664  World* RemoveWorldByName(const String& WorldName);
665  /// @brief This removes all worlds from the world list.
666  void RemoveAllWorlds();
667  /// @brief This destroys the given world and removes it from the world list.
668  /// @param WorldToBeDestroyed The name of the world to be destroyed.
669  void DestroyWorld(World* WorldToBeDestroyed);
670  /// @brief This destroys the world with the given name and removes it from the world list.
671  /// @param WorldName The name of the world to be destroyed.
672  void DestroyWorldByName(const String& WorldName);
673  /// @brief This destroys all the worlds in the world list.
674  void DestroyAllWorlds();
675 
676  /// @brief Pauses all animations, particles, and object movement throughout all worlds.
677  /// @param Pause Pauses the world if true, unpauses if false.
678  void PauseAllWorlds(Boole Pause);
679 
680  ///////////////////////////////////////////////////////////////////////////////
681  // Internal Logging
682 
683  /// @brief Runtime event and message logging.
684  /// @param Message This is what will be streamed to the log.
685  /// @throws Anything GetLogStream could throw.
686  template <class T> void _Log(const T& Message)
687  { this->_LogString(StringTools::ConvertToString(Message)); }
688  /// @brief Log String directly with no conversion.
689  /// @param Message The string to log.
690  /// @throws Anything GetLogStream could throw.
691  void _LogString(const String& Message);
692  /// @brief A nearly threadsafe logging sink.
693  /// @details If ID is not supplied and the thread is managed by the framescheduler this should be thread safe.
694  /// @param ID Defaults to the id of the current thread, but can be used to retrieve the logger for any thread.
695  /// @return A Logger that can be used by the thread with given ID or outside of Framescheduling in a non-threadsafe way.
696  /// @exception This throws a ParametersRangeException if the thread is not managed by the frame scheduler or it Threading::FrameScheduler::CreateThreads() has not
697  /// been called (It creates the ThreadSpecific resources that contain the Loggers).
699  /// @internal
700  /// @brief This is used to asynchronously handle log messages.
701  /// @return Returns a pointer to the aggregator responsible for synchronizing logs between threads.
702  Threading::LogAggregator* _GetLogAggregator();
703  };//Entresol
704 }//Mezzanine
705 #endif
int32_t Int32
An 32-bit integer.
Definition: datatypes.h:124
ThreadId MEZZ_LIB get_id()
Return the thread ID of the calling thread.
std::stringstream Logger
In case we ever replace the stringstream with another class, this will allow us to swap it out...
Definition: datatypes.h:180
std::vector< EntresolManager * > ManagerVec
Container type for passing pre-created managers into the Entresol upon creation.
Definition: entresol.h:342
bool Boole
Generally acts a single bit, true or false.
Definition: datatypes.h:173
std::map< String, EntresolManagerFactory * > ManagerFactoryMap
Basic container type for factories that construct known manager types.
Definition: entresol.h:328
This is a base class for factories that construct managers used by the Entresol class.
String ConvertToString(const Vector2 &ToConvert)
Converts a Vector2 into a string.
Definition: stringtool.cpp:291
ManagerContainer::const_iterator ConstManagerIterator
Const Iterator type for managers stored by this class.
Definition: entresol.h:340
All the definitions for datatypes as well as some basic conversion functions are defined here...
This is a convenience base class intended to be used with classes that need to be singletons...
Definition: singleton.h:62
void _Log(const T &Message)
Runtime event and message logging.
Definition: entresol.h:686
ArchiveType
Used to indicate what kind of resources the Entrosol should look for.
ManagerVec::iterator ManagerVecIterator
Iterator type for containers of pre-created managers.
Definition: entresol.h:344
ManagerVec::const_iterator ConstManagerVecIterator
Const Iterator type for containers of pre-created managers.
Definition: entresol.h:346
uint16_t UInt16
An 16-bit unsigned integer.
Definition: datatypes.h:122
std::vector< World * > WorldContainer
Basic container type for World storage.
Definition: entresol.h:348
This is the base class for all managers that do no describe properties of a single world...
A light-weight handle for manipulating nodes in DOM tree.
Definition: node.h:89
This is central object in this algorithm, it is responsible for spawning threads and managing the ord...
std::list< NameValuePair > NameValuePairList
This is a datatype mostly used for describing settings or parameters that can't be declared in advanc...
Definition: datatypes.h:206
std::list< EntresolManager * > ManagerContainer
Basic container type for normal manager storage in this class.
Definition: entresol.h:336
This is the main entry point for the entire library.
Definition: entresol.h:324
Gather all the thread specific logs and commit them to the main log.
WorldContainer::const_iterator ConstWorldIterator
Const Iterator type for Worlds stored by this class.
Definition: entresol.h:352
#define MEZZ_LIB
Some platforms require special decorations to denote what is exported/imported in a share library...
The bulk of the engine components go in this namspace.
Definition: actor.cpp:56
unsigned long Whole
Whole is an unsigned integer, it will be at least 32bits in size.
Definition: datatypes.h:151
This class represents a world for objects to interact within.
Definition: world.h:74
ManagerFactoryMap::const_iterator ConstManagerFactoryIterator
Const Iterator type for manager factories stored by this class.
Definition: entresol.h:334
WorldContainer::iterator WorldIterator
Iterator type for Worlds stored by this class.
Definition: entresol.h:350
This is the file that code using this library should include. It includes all the required components...
The thread ID is a unique identifier for each thread.
Definition: thread.h:209
std::vector< EntresolManagerFactory * > ManagerFactoryVec
Basic container type for factories that construct known manager types.
Definition: entresol.h:330
std::string String
A datatype used to a series of characters.
Definition: datatypes.h:159
ManagerFactoryMap::iterator ManagerFactoryIterator
Iterator type for manager factories stored by this class.
Definition: entresol.h:332
ManagerContainer::iterator ManagerIterator
Iterator type for managers stored by this class.
Definition: entresol.h:338
This is a helper class storing information needed for the construction of a PhysicsManager.