Engine.h

00001 /***************************************************************************
00002  *                                                                         *
00003  *   (c) Art Tevs, MPI Informatik Saarbruecken                             *
00004  *       mailto: <tevs@mpi-sb.mpg.de>                                      *
00005  *                                                                         *
00006  *   This program is free software; you can redistribute it and/or modify  *
00007  *   it under the terms of the GNU General Public License as published by  *
00008  *   the Free Software Foundation; either version 2 of the License, or     *
00009  *   (at your option) any later version.                                   *
00010  *                                                                         *
00011  ***************************************************************************/
00012 
00013 #ifndef __NR_ENGINE_CORE_H_
00014 #define __NR_ENGINE_CORE_H_
00015 
00016 
00017 //----------------------------------------------------------------------------------
00018 // Includes
00019 //----------------------------------------------------------------------------------
00020 #include "Prerequisities.h"
00021 #include "Log.h"
00022 
00023 namespace nrEngine{
00024 
00025         //! Core class of the engine. Used to create subsystems.
00026         /**
00027         * This is our main class representing the engine itself. This class is
00028         * able to create and initialize particular elements of the engine's core.
00029         * So before you can use the engine you have to create an instance
00030         * of this class.
00031         *
00032         * The engine's core class is a singleton. We also store all subsystems as
00033         * static, to be sure that they exists also only once in memory.
00034         *
00035         * \ingroup engine
00036         **/
00037         class _NRExport Engine{
00038                 public:
00039 
00040                         /**
00041                         * Initialize the log component of the engine. You have to call
00042                         * this function before you get using of engine's components. They all
00043                         * will log their work information to appropriate log files, so the log
00044                         * part of the engie has to be initialized before.<br>
00045                         * If you do not initilaize the logging functionality, so no log
00046                         * files will be written. No error will occurs.
00047                         *
00048                         * \param logPath Under this directory all log files will be created
00049                         * \return false if error occurs or true otherwise
00050                         **/
00051                         bool initializeLog(const std::string& logPath);
00052 
00053                         /**
00054                         * Release the engine and all used memory. The call of this function
00055                         * will immidiately stop all kernel tasks and will stop the engine.<br>
00056                         * Call this function if you want to quit the engine.
00057                         **/
00058                         void stopEngine();
00059 
00060                         /**
00061                         * "Gentlemans, start your engines!" - This is the entry point for
00062                         * your application to start the engine. Starting of the engine will
00063                         * also start a kernel, which is running system + application tasks.
00064                         * If no more tasks is active, the kernel will be shutted down and engine
00065                         * will stop.
00066                         **/
00067                         void runEngine();
00068 
00069                         /**
00070                         * If you do not want to run the engine in their own loop (\a startEngine() )
00071                         * you can update the engine through this function. This function should be
00072                         * called each frame. This will update the kernel tasks and all engine's
00073                         * subsystems
00074                         **/
00075                         void updateEngine();
00076 
00077                         /**
00078                         * This method will initialize all engine's subsystems, that are essential
00079                         * for engine's work. Please call this function after you have intialized
00080                         * the logging, because there will be a lot of log information.
00081                         *
00082                         * \return true if all intialization are succeed, or false otherwise
00083                         **/
00084                         bool initializeEngine();
00085 
00086                         /**
00087                          * Load a certain plugin directly into the engine. The plugin will
00088                          * be loaded and the initialize subroutine will be called. If the plugin
00089                          * returns an invalid resulting code, so the plugin will be unloaded again.
00090                          *
00091                          * Use this function to load certain plugins needed for your application
00092                          * (i.e. ScriptLoader) and let them run with certain parameters, so you are
00093                          * able to use the engine as you need.
00094                          *
00095                          * @param path Path where the plugin can be founded
00096                          * @param file Filename relative to the path of the plugin
00097                          * @param name Name which will be then used to access the plugin later
00098                          *
00099                          * @return false if an error occurs
00100                          *
00101                          * NOTE: Check log files for more detailed error description
00102                          **/
00103                         bool loadPlugin(const std::string& path, const std::string& file, const std::string& name);
00104 
00105 
00106                         /**
00107                         * Get a pointer to a log subsystem of the engine.
00108                         * The pointer is always not equal to NULL. By initializing of
00109                         * the log subsystem you just setup the log target.
00110                         * So you can always log to the log-system without checking
00111                         * whenever pointer is valid or not.
00112                         **/
00113                         static Log* sLog();
00114 
00115                         /**
00116                         * Return a pointer to the kernel subsystem of the engine. Our kernel
00117                         * is normaly a singleton, so you can access to it, without this method.
00118                         * 
00119                         * Returned pointer is always valid.
00120                         * @see Kernel
00121                         **/
00122                         static Kernel* sKernel();
00123 
00124                         /**
00125                         * Return a pointer to the underlying clock of the engine. The clock
00126                         * is a singleton, so you can access it on another way.
00127                         *
00128                         * Returned pointer is always valid
00129                         * @see Clock
00130                         **/
00131                         static Clock* sClock();
00132 
00133                         /**
00134                         * Returns a pointer to the profiler object. The profiler
00135                         * is used to mess the time of execution
00136                         **/
00137                         static Profiler* sProfiler();
00138                         
00139                         /**
00140                         * Returns a pointer to the ressource manager object.
00141                         **/
00142                         static ResourceManager* sResourceManager() ;
00143                         
00144                         /**
00145                         * Return an instance of the event manager class
00146                         **/
00147                         static EventManager* sEventManager();
00148                         
00149                         /**
00150                         * Get a pointer to the scripting engine interface
00151                         **/
00152                         static ScriptEngine* sScriptEngine();
00153 
00154                         /**
00155                          * Get instance to the property manager of the engine.
00156                          **/
00157                         static PropertyManager* sPropertyManager();
00158                         
00159                         /**
00160                          * Get the singleton instance. Passing the parameter specify
00161                          * if the instance should be released
00162                          **/
00163                         static Engine* instance(bool release = false);
00164 
00165                         /**
00166                          * Get the pointer to the instance of the engine
00167                          **/
00168                         static Engine* sEngine() { return instance(); }
00169                         
00170                          /**
00171                          * Check whenever the engine'S singleton was created before
00172                          **/
00173                         static bool valid(void* p = sSingleton.get(), char* name = "Engine", bool showWarn = true);
00174                          
00175                         /**
00176                          * Release the singleton object
00177                          **/
00178                         static void release();
00179 
00180                         /**
00181                         * Delete the core object and try to deinitialize and to delete
00182                         * all subcomponents of the engine
00183                         **/
00184                         ~Engine();
00185 
00186                 private:
00187 
00188                         /**
00189                         * Create an instance of the engine's core object. The constructor
00190                         * is private, so you only can create instances through instance() method
00191                         **/
00192                         Engine();
00193 
00194                         static Log*                     _logger;
00195                         static Kernel*          _kernel;
00196                         static Clock*           _clock;
00197                         static Profiler*        _profiler;
00198                         static ResourceManager* _resmgr;
00199                         static ScriptEngine* _script;
00200                         static EventManager* _event;
00201                         static PropertyManager* _propmgr;
00202                         
00203                         //! Store pointer to the engine's core singleton object
00204                         static SharedPtr<Engine> sSingleton;
00205                         
00206         };
00207 
00208 }; // end namespace
00209 
00210 
00211 #endif

Generated on Wed Sep 12 23:19:42 2007 for nrEngine by  doxygen 1.5.1