source: nrEngine/include/Plugin.h @ 30

Revision 30, 8.3 KB checked in by art, 12 years ago (diff)

::std wurde durch std ueberall ersetzt!

Line 
1/***************************************************************************
2 *                                                                         *
3 *   (c) Art Tevs, MPI Informatik Saarbruecken                             *
4 *       mailto: <tevs@mpi-sb.mpg.de>                                      *
5 *                                                                         *
6 *   This program is free software; you can redistribute it and/or modify  *
7 *   it under the terms of the GNU General Public License as published by  *
8 *   the Free Software Foundation; either version 2 of the License, or     *
9 *   (at your option) any later version.                                   *
10 *                                                                         *
11 ***************************************************************************/
12
13
14#ifndef _NR_PLUGIN_RESOURCE__H_
15#define _NR_PLUGIN_RESOURCE__H_
16
17
18//----------------------------------------------------------------------------------
19// Includes
20//----------------------------------------------------------------------------------
21#include "Prerequisities.h"
22#include "Resource.h"
23#include "PluginLoader.h"
24
25/*!
26 * \defgroup plugin Plugin managment
27 *
28 * Plugins are used to extend the functionality of the underlying system
29 * without recompiling it. So our engine does support plugins, which allows
30 * programm new functionality to the engine without recompiling it.
31 *
32 * One of the best examples of such a plugin is a possibility to extend the resource
33 * managment system to new resources. You can program addiditional texture loader
34 * for example and "plug in" this into the engine. The new loader could load
35 * textures and prepare them as resources, so your program can get use of them.
36 *
37 * Another example could be a plugin that runs as task in the engine's kernel
38 * and do something. For example an ingame console could be such a task, which can
39 * be fully programmed as external plugin.
40 *
41 * Each plugin is a simple dynamic library (*.dll, *.so) file, which contains the plugin.
42 * Each plugin will be loaded if it is added to the plugin manager. The plgLoad() function
43 * of the plugin will be called. If the plugin is unloaded, so call plgUnload().
44 *
45 * Each plugin should export some default functions to be able to be loaded by the manager.
46 * Plugins could be simple functionality plugins (like any loader) or a new task
47 * in the engine's kernel (like a console). This capability of each plugin is readed
48 * through special plugin functions.
49 *
50 * Also each plugin should provide a function which can be used to access internal
51 * functionality of that plugin by using of strings. In our case this subroutine
52 * should be called plgCall and accept as first the name of the function and then a
53 * parameter list of parameters and their values. We use this to provide the user
54 * applications a possibility to call certain functions from plugins which are not
55 * replace a default behaviour of the engine but add some new functionality. The good
56 * example where it can be used is a scripting. You load a plugins from the script
57 * and then call some functions from the plugin whithin scripting.
58 *
59 **/
60 
61namespace nrEngine{
62       
63               
64        /**
65        * Each plugin is an dynamic library. So we have to use some handles
66        * given by the os api to handle with these libraries. On each os
67        * this handle is of different type. So we have to find out
68        * which os do we using now and define the right type
69        *
70        * \ingroup plugin
71        **/
72        #if NR_PLATFORM == NR_PLATFORM_WIN32
73                typedef HINSTANCE PluginHandle;
74        #elif NR_PLATFORM == NR_PLATFORM_LINUX
75                typedef void* PluginHandle;
76        #elif NR_PLATFORM == NR_PLATFORM_APPLE
77                typedef CFBundleRef PluginHandle;
78        #endif
79
80        //! General interface for any plugin in the engine
81        /**
82        * Plugins are used to extend the functionality of the engine without rewriting it.
83        * You can just write new plugin and add this to the engine, so the engine could get
84        * it loaded. The user will then get the new functionality automaticaly or by using
85        * the concept of application - plugin - communication.
86        *
87        * Plugins are resources that used in the same way like normal resources.
88        *
89        * Each plugin library has to export following symbols:
90        *       - int plgInitialize(Engine*)
91        *               - will be called after library is loaded
92        *               - plugin will get the pointer to the root object of the engine
93        *               - return 0 for success otherwise error code
94        *
95        *       - unsigned int plgEngineVersion()
96        *               - plugin should return a version number according to the engine
97        *               - return the value also if not initialized before
98        *
99        *       - char* plgVersionString()
100        *               - return a full string containing information about the plugin version/name
101        *               - return the strign also if not initialized before
102        *
103        *       - char* plgError (int)
104        *               - return a short error string for the given code
105        *
106        *       - void plgRelease()
107        *               - will be called before plugin is getting unloaded
108        *
109        *
110        * Following symbols are optional:
111        *
112        *       - void plgGetMethods (std::vector<PlgMethod> &)
113        *               - should fill the given vector whithin informations of plugin methods
114        *                 which could be used as extra calls from the user point of view (e.g. scripts)
115        *
116        *       - void plgCall (const std::string&, std::vector<PlgParam>& )
117        *               - call a subroutine from the plugin, also send parameters
118        *
119        *
120        * @see IResource
121        * \ingroup plugin
122        **/
123        class _NRExport Plugin : public IResource{
124        public:
125                       
126                Plugin();
127                virtual ~Plugin();
128
129                /**
130                 * Retuns the addres of a symbol (function,variable) from the plugin.
131                 * You have to cast this addres for using.
132                 *
133                 * @param name Unique name of the symbol
134                 **/
135                virtual void* getSymbol(const std::string& name) const;
136
137                //! Each method in the plugin accept parameters of this type
138                /*typedef struct _plgParam {
139
140                        //! Parameter name
141                        std::string name;
142
143                        //! Parameter value as string
144                        std::string value;
145
146                } PlgParam;
147               
148                //! This structure describes a subroutine in a plugin
149                typedef struct _plgMethod {
150
151                        //! Name of the subroutine
152                        std::string name;
153
154                        //! parameter names which can be passed to this method
155                        std::vector<PlgParam> param;
156
157                        //! Pointer pointing to the provided method
158                        void* symbol_ptr;
159                       
160                } PlgMethod;*/
161                 
162        protected:
163       
164                //! Plugin loader is a friend, so it get full accecc to our functions
165                friend class PluginLoader;
166
167                //! Handle of the used dynamic library
168                PluginHandle    mPluginHandle;
169
170                //! this is the list of methods from the plugin
171                //std::vector<PlgMethod> mPlgMethods;
172
173                //! This defines the interface of the initialization function of the plugin
174                typedef int (*plgInitialize) ( Engine*, PropertyList* );
175               
176                //! Define the type of the error get function of th eplugin
177                typedef char* (*plgError) ( int );
178                               
179                //! This is the interface of the release function of the plugin
180                typedef void (*plgRelease) ( void );
181               
182                //! Interface for the version information
183                typedef unsigned int (*plgEngineVersion) ( void );
184               
185                //! Get full version string of the plugin
186                typedef char* (*plgVersionString) ( void );
187               
188                /*//! Get a list of exported functions
189                typedef void (*plgGetMethods) ( std::vector<PlgMethod>& );
190
191                //! Call a method whithin given parameters
192                typedef void (*plgCall) (const std::string&, const std::vector<PlgParam>& );
193                */
194               
195                plgInitialize           m_plgInitialize;
196                plgError                        m_plgError;
197                plgRelease                      m_plgRelease;
198                plgEngineVersion        m_plgEngineVersion;
199                plgVersionString        m_plgVersionString;
200                       
201                /*plgGetMethods         m_plgGetMethods;
202                plgCall                         m_plgCall;
203                */
204                /**
205                 * This method is called by the plugin loader after it has loaed the library.
206                 * The plugin object has now to get all symbols and initialize the library.
207                 * @return error code
208                 **/
209                Result initialize(PropertyList* params = NULL);
210               
211                /**
212                 * Derived function from IResource
213                 **/
214                Result unloadRes();
215               
216                                       
217
218        };
219
220       
221        //! Simple class for empty plugin. This plugin doesn't have any effect
222        /**
223         * This class represents an empty plugin object. This corresponds
224         * to our empty resource interface, needed to work for resource managment.
225         * Empty plugin does not do anything.
226         *
227         * \ingroup plugin
228         **/
229        class _NRExport EmptyPlugin : public Plugin{
230        public:
231       
232                //! Constructor does not call anything
233                EmptyPlugin();
234               
235                //! Release used memory
236                ~EmptyPlugin();
237               
238                //! Unload the empty resource
239                Result unloadRes();
240               
241               
242                //! Return always NULL
243                void* getSymbol(const std::string& name) const;
244               
245        };
246       
247};
248
249#endif
Note: See TracBrowser for help on using the repository browser.