aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMax Horn2008-05-13 10:41:32 +0000
committerMax Horn2008-05-13 10:41:32 +0000
commit2bb39e591f4184f0ae8102c8f547586bf95d2b50 (patch)
tree9b4288df29db3aaace1039badc7ae18d18022edc
parentfe58f0ee4b9d91f4ed349bafb16d2a8d6fb59faa (diff)
downloadscummvm-rg350-2bb39e591f4184f0ae8102c8f547586bf95d2b50.tar.gz
scummvm-rg350-2bb39e591f4184f0ae8102c8f547586bf95d2b50.tar.bz2
scummvm-rg350-2bb39e591f4184f0ae8102c8f547586bf95d2b50.zip
Moved the engine plugin code to engines/metaengine.h; added/clarified/corrected various Doxygen comments for the plugin system
svn-id: r32083
-rw-r--r--base/plugins.h77
-rw-r--r--engines/metaengine.h21
-rw-r--r--gui/launcher.cpp3
-rw-r--r--gui/massadd.cpp3
4 files changed, 67 insertions, 37 deletions
diff --git a/base/plugins.h b/base/plugins.h
index 858c8d9106..b1236eeeb1 100644
--- a/base/plugins.h
+++ b/base/plugins.h
@@ -33,7 +33,7 @@
// Plugin versioning
-// Global Plugin API version
+/** Global Plugin API version */
#define PLUGIN_VERSION 1
enum PluginType {
@@ -67,14 +67,14 @@ extern int pluginTypeVersions[PLUGIN_TYPE_MAX];
(defined(ENABLE_##ID) && (ENABLE_##ID == DYNAMIC_PLUGIN) && defined(DYNAMIC_MODULES))
/**
- * REGISTER_PLUGIN is a convenience macro meant to ease writing
- * the plugin interface for our modules. In particular, using it
- * makes it possible to compile the very same code in a module
- * both as a static and a dynamic plugin.
+ * REGISTER_PLUGIN_STATIC is a convenience macro which is used to declare
+ * the plugin interface for static plugins. Code (such as game engines)
+ * which needs to implement a static plugin can simply invoke this macro
+ * with a plugin ID, plugin type and PluginObject subclass, and the correct
+ * wrapper code will be inserted.
*
- * @todo add some means to query the plugin API version etc.
+ * @see REGISTER_PLUGIN_DYNAMIC
*/
-
#define REGISTER_PLUGIN_STATIC(ID,TYPE,PLUGINCLASS) \
PluginType g_##ID##_type = TYPE; \
PluginObject *g_##ID##_getObject() { \
@@ -84,6 +84,15 @@ extern int pluginTypeVersions[PLUGIN_TYPE_MAX];
#ifdef DYNAMIC_MODULES
+/**
+ * REGISTER_PLUGIN_DYNAMIC is a convenience macro which is used to declare
+ * the plugin interface for dynamically loadable plugins. Code (such as game engines)
+ * which needs to implement a dynamic plugin can simply invoke this macro
+ * with a plugin ID, plugin type and PluginObject subclass, and the correct
+ * wrapper code will be inserted.
+ *
+ * @see REGISTER_PLUGIN_STATIC
+ */
#define REGISTER_PLUGIN_DYNAMIC(ID,TYPE,PLUGINCLASS) \
extern "C" { \
PLUGIN_EXPORT int32 PLUGIN_getVersion() { return PLUGIN_VERSION; } \
@@ -138,10 +147,14 @@ public:
const char *getName() const;
};
-/** List of plugins. */
+/** List of Plugin instances. */
typedef Common::Array<Plugin *> PluginList;
-/** Template to help defining Plugin subclasses */
+/**
+ * Convenience template to make it easier defining normal Plugin
+ * subclasses. Namely, the PluginSubclass will manage PluginObjects
+ * of a type specified via the PO_t template parameter.
+ */
template<class PO_t>
class PluginSubclass : public Plugin {
public:
@@ -152,24 +165,43 @@ public:
typedef Common::Array<PluginSubclass *> list;
};
+/**
+ * Abstract base class for Plugin factories. Subclasses of this
+ * are responsible for creating plugin objects, e.g. by loading
+ * loadable modules from storage media; by creating "fake" plugins
+ * from static code; or whatever other means.
+ */
class PluginProvider {
public:
virtual ~PluginProvider() {}
/**
* Return a list of Plugin objects. The caller is responsible for actually
- * loading/unloading them (by invoking the appropriate methods).
+ * loading/unloading them (by invoking the appropriate Plugin methods).
* Furthermore, the caller is responsible for deleting these objects
* eventually.
*/
virtual PluginList getPlugins() = 0;
};
+/**
+ * Abstract base class for Plugin factories which load binary code from files.
+ * Subclasses only have to implement the createPlugin() method, and optionally
+ * can overload the other protected methods to achieve custom behavior.
+ */
class FilePluginProvider : public PluginProvider {
public:
virtual PluginList getPlugins();
protected:
+ /**
+ * Create a Plugin instance from a loadable code module with the specified name.
+ * Subclasses of FilePluginProvider have to at least overload this method.
+ * If the file is not found, or does not contain loadable code, 0 is returned instead.
+ *
+ * @param filename the name of the loadable code module
+ * @return a pointer to a Plugin instance, or 0 if an error occured.
+ */
virtual Plugin* createPlugin(const Common::String &filename) const = 0;
virtual const char* getPrefix() const;
@@ -179,8 +211,8 @@ protected:
};
/**
- * Instances of this class manage all plugins, including loading them,
- * making wrapper objects of class Plugin available, and unloading them.
+ * Singleton class which manages all plugins, including loading them,
+ * managing all Plugin class instances, and unloading them.
*/
class PluginManager : public Common::Singleton<PluginManager> {
typedef Common::List<PluginProvider *> ProviderList;
@@ -205,25 +237,4 @@ public:
const PluginList &getPlugins(PluginType t) { return _plugins[t]; }
};
-
-// Engine plugins
-
-class FSList;
-class MetaEngine;
-
-typedef PluginSubclass<MetaEngine> EnginePlugin;
-
-class EngineManager : public Common::Singleton<EngineManager> {
-private:
- friend class Common::Singleton<SingletonBaseType>;
-
-public:
- GameDescriptor findGame(const Common::String &gameName, const EnginePlugin **plugin = NULL) const;
- GameList detectGames(const FSList &fslist) const;
- const EnginePlugin::list &getPlugins() const;
-};
-
-/** Shortcut for accessing the engine manager. */
-#define EngineMan EngineManager::instance()
-
#endif
diff --git a/engines/metaengine.h b/engines/metaengine.h
index 5db791a1b7..c5fb006faa 100644
--- a/engines/metaengine.h
+++ b/engines/metaengine.h
@@ -93,4 +93,25 @@ public:
}
};
+
+// Engine plugins
+
+typedef PluginSubclass<MetaEngine> EnginePlugin;
+
+/**
+ * Singleton class which manages all Engine plugins.
+ */
+class EngineManager : public Common::Singleton<EngineManager> {
+private:
+ friend class Common::Singleton<SingletonBaseType>;
+
+public:
+ GameDescriptor findGame(const Common::String &gameName, const EnginePlugin **plugin = NULL) const;
+ GameList detectGames(const FSList &fslist) const;
+ const EnginePlugin::list &getPlugins() const;
+};
+
+/** Convenience shortcut for accessing the engine manager. */
+#define EngineMan EngineManager::instance()
+
#endif
diff --git a/gui/launcher.cpp b/gui/launcher.cpp
index 505ecf842b..92867562ad 100644
--- a/gui/launcher.cpp
+++ b/gui/launcher.cpp
@@ -22,8 +22,7 @@
* $Id$
*/
-#include "engines/engine.h"
-#include "base/plugins.h"
+#include "engines/metaengine.h"
#include "base/version.h"
#include "common/config-manager.h"
diff --git a/gui/massadd.cpp b/gui/massadd.cpp
index 446285af2d..b39b51f1fb 100644
--- a/gui/massadd.cpp
+++ b/gui/massadd.cpp
@@ -22,8 +22,7 @@
* $Id$
*/
-#include "engines/engine.h"
-#include "base/plugins.h"
+#include "engines/metaengine.h"
#include "common/events.h"
#include "gui/launcher.h" // For addGameToConf()