OpenWalnut  1.4.0
WKernel.h
00001 //---------------------------------------------------------------------------
00002 //
00003 // Project: OpenWalnut ( http://www.openwalnut.org )
00004 //
00005 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
00006 // For more information see http://www.openwalnut.org/copying
00007 //
00008 // This file is part of OpenWalnut.
00009 //
00010 // OpenWalnut is free software: you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as published by
00012 // the Free Software Foundation, either version 3 of the License, or
00013 // (at your option) any later version.
00014 //
00015 // OpenWalnut is distributed in the hope that it will be useful,
00016 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00018 // GNU Lesser General Public License for more details.
00019 //
00020 // You should have received a copy of the GNU Lesser General Public License
00021 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
00022 //
00023 //---------------------------------------------------------------------------
00024 
00025 #ifndef WKERNEL_H
00026 #define WKERNEL_H
00027 
00028 #include <string>
00029 #include <vector>
00030 
00031 #include <boost/shared_ptr.hpp>
00032 
00033 #include "../common/WTimer.h"
00034 #include "../scripting/WScriptEngine.h"
00035 #include "../graphicsEngine/WGraphicsEngine.h"
00036 
00037 #include "WBatchLoader.h"
00038 
00039 // forward declarations
00040 class WUI;
00041 class WModule;
00042 class WModuleContainer;
00043 class WModuleFactory;
00044 class WROIManager;
00045 class WSelectionManager;
00046 class WThreadedRunner;
00047 
00048 /**
00049  * \defgroup kernel Kernel
00050  *
00051  * \brief
00052  * This library implements the central part of OpenWalnut that manages
00053  * the interaction between UI, GraphicsEngine and DataHandler.
00054  */
00055 
00056 /**
00057  * OpenWalnut kernel, managing modules and interaction between
00058  * UI, GE and DataHandler
00059  * \ingroup kernel
00060  */
00061 class WKernel: public WThreadedRunner
00062 {
00063 public:
00064     /**
00065      * Signal for generic events.
00066      *
00067      */
00068     typedef boost::function< void ( void ) > t_KernelGenericSignalHandlerType;
00069 
00070     /**
00071      * Generic signal type used in the most signals.
00072      */
00073     typedef boost::signals2::signal< void ( void ) >  t_KernelGenericSignalType;
00074 
00075     /**
00076      * Enum of all possible signals WKernel instances can emit.
00077      */
00078     typedef enum
00079     {
00080         KERNEL_STARTUPCOMPLETE  // when kernel, GE and UI are correctly initialized
00081     }
00082     KERNEL_SIGNAL;
00083 
00084     /**
00085      * Returns pointer to the running kernel or a new if no kernel was there.
00086      * If a running kernel exists the function return it and does not check if
00087      * GE and UI of the running kernel are equivalent to the ones given as parameters.
00088      *
00089      * \param ge initialized graphics engine.
00090      * \param ui initialized ui.
00091      * \return the kernel instance.
00092      */
00093     static WKernel* instance( boost::shared_ptr< WGraphicsEngine > ge, boost::shared_ptr< WUI > ui );
00094 
00095     /**
00096      * Destructor.
00097      */
00098     virtual ~WKernel();
00099 
00100     /**
00101      * Subscribe to several signals.
00102      *
00103      * \param signal the signal to subscribe
00104      * \param notifier the notifier to call
00105      *
00106      * \return connection variable. Keep this in any case. If not, the connection may be lost.
00107      */
00108     boost::signals2::connection subscribeSignal( KERNEL_SIGNAL signal, t_KernelGenericSignalHandlerType notifier );
00109 
00110     /**
00111      * Stops execution of the modules in the root container. Note that this does not wait for the kernel thread since this could
00112      * cause a dead lock. This is actually an alias for getRootContainer()->stop().
00113      */
00114     void finalize();
00115 
00116     /**
00117      * Returns pointer to currently running instance of graphics engine.
00118      *
00119      * \return the graphics engine instance.
00120      */
00121     boost::shared_ptr< WGraphicsEngine > getGraphicsEngine() const;
00122 
00123     /**
00124      * Returns pointer to the currently running kernel.
00125      *
00126      * \return the kernel instance.
00127      */
00128     static WKernel* getRunningKernel();
00129 
00130     /**
00131      * Determines whether all threads should finish.
00132      *
00133      * \return true if so.
00134      */
00135     const WBoolFlag& isFinishRequested() const;
00136 
00137     /**
00138      * Load specified datasets. It immediately returns and starts another thread, which actually loads the data.
00139      *
00140      * \param filenames list of filenames to load. The registered notification handler for the root container will get notified on
00141      * error and success.
00142      * \param suppressColormaps if true, the data modules are instructed to avoid registration of colormaps. This can be very handy if you
00143      * combine multiple data loaders into one new data loader or data set
00144      *
00145      * \return the batch loader responsible for loading. Can be queried for the list of data modules.
00146      */
00147     WBatchLoader::SPtr loadDataSets( std::vector< std::string > filenames, bool suppressColormaps = false );
00148 
00149     /**
00150      * Loads the specified files synchronously.
00151      *
00152      * \param filenames list of filenames to load. The registered notification handler for the root container will get notified on
00153      * error and success.
00154      * \param suppressColormaps if true, the data modules are instructed to avoid registration of colormaps. This can be very handy if you
00155      * combine multiple data loaders into one new data loader or data set
00156      *
00157      * \return the batch loader responsible for loading. Can be queried for the list of data modules.
00158      */
00159     WBatchLoader::SPtr loadDataSetsSynchronously( std::vector< std::string > filenames, bool suppressColormaps = false );
00160 
00161     /**
00162      * Function combines to modules. This is a simple alias for "getRootContainer()->applyModule". It runs synchronously, which
00163      * could freeze the calling thread for a couple of time.
00164      *
00165      * \param applyOn the module which already has to be in the container and to apply the other one on.
00166      * \param prototype the prototype of the module to apply on the other one specified.
00167      *
00168      * \return the newly created module connected with the one specified in applyOn.
00169      */
00170     boost::shared_ptr< WModule > applyModule( boost::shared_ptr< WModule > applyOn, boost::shared_ptr< WModule > prototype );
00171 
00172     /**
00173      * Returns the root module container. This is the actual module graph container.
00174      *
00175      * \return the root container.
00176      */
00177     boost::shared_ptr< WModuleContainer > getRootContainer() const;
00178 
00179     /**
00180      * Getter for the associated UI.
00181      *
00182      * \return the UI.
00183      */
00184     boost::shared_ptr< WUI > getUI() const;
00185 
00186     /**
00187      * get for roi manager
00188      *
00189      * \return Pointer to the ROI manager.
00190      */
00191     boost::shared_ptr< WROIManager> getRoiManager();
00192 
00193     /**
00194      * get for selection manager
00195      *
00196      * \return Pointer to the selection manager.
00197      */
00198     boost::shared_ptr< WSelectionManager> getSelectionManager();
00199 
00200     /**
00201      * Get the script engine of this kernel.
00202      *
00203      * \return A pointer to the script engine.
00204      */
00205     boost::shared_ptr< WScriptEngine > getScriptEngine();
00206 
00207     /**
00208      * Returns the system timer. If you need timing for animations and similar, use this one. This timer can change to frame based timing if the
00209      * user plays back some animation. So, everything which uses this timer can always do accurate per-frame animations even if frame time and
00210      * real-time differ.
00211      *
00212      * \return the timer
00213      */
00214     WTimer::ConstSPtr getTimer() const;
00215 
00216 protected:
00217     /**
00218      * Constructor is protected because this class is a singleton. Awaits an INITIALIZED graphics engine an UI.
00219      *
00220      * \param ge initialized graphics engine.
00221      * \param ui initialized UI.
00222      */
00223     WKernel( boost::shared_ptr< WGraphicsEngine > ge, boost::shared_ptr< WUI > ui );
00224 
00225     /**
00226      * Function that has to be overwritten for execution. It gets executed in a separate thread after run()
00227      * has been called.
00228      */
00229     virtual void threadMain();
00230 
00231     /**
00232      * The UI.
00233      */
00234     boost::shared_ptr< WUI > m_ui;
00235 
00236     /**
00237      * Pointer to an initialized graphics engine.
00238      */
00239     boost::shared_ptr< WGraphicsEngine > m_graphicsEngine;
00240 
00241     /**
00242      * Pointer to a roi manager
00243      */
00244     boost::shared_ptr< WROIManager >m_roiManager;
00245 
00246     /**
00247      * pointer to a selection manager
00248      */
00249     boost::shared_ptr< WSelectionManager >m_selectionManager;
00250 
00251     /**
00252      * The module factory to use.
00253      */
00254     boost::shared_ptr< WModuleFactory > m_moduleFactory;
00255 
00256     /**
00257      * The container containing the modules.
00258      */
00259     boost::shared_ptr< WModuleContainer > m_moduleContainer;
00260 
00261     /**
00262      * The script engine to use.
00263      */
00264     boost::shared_ptr< WScriptEngine > m_scriptEngine;
00265 
00266 private:
00267     /**
00268      * Loads all the modules it can find.
00269      */
00270     void loadModules();
00271 
00272     /**
00273      * Initializes the graphics engine, data handler and so on.
00274      */
00275     void init();
00276 
00277     /**
00278      * Pointer to the unique instance of this singleton class.
00279      */
00280     static WKernel* m_kernel;
00281 
00282     /**
00283      * The ow system timer.
00284      */
00285     WTimer::SPtr m_timer;
00286 
00287     /**
00288      * Notified when the startup, including GE and UI has been completed.
00289      */
00290     WConditionOneShot m_startupCompleted;
00291 };
00292 
00293 #endif  // WKERNEL_H
00294