[Scummvm-cvs-logs] SF.net SVN: scummvm: [32083] scummvm/trunk
fingolfin at users.sourceforge.net
fingolfin at users.sourceforge.net
Tue May 13 12:41:32 CEST 2008
Revision: 32083
http://scummvm.svn.sourceforge.net/scummvm/?rev=32083&view=rev
Author: fingolfin
Date: 2008-05-13 03:41:32 -0700 (Tue, 13 May 2008)
Log Message:
-----------
Moved the engine plugin code to engines/metaengine.h; added/clarified/corrected various Doxygen comments for the plugin system
Modified Paths:
--------------
scummvm/trunk/base/plugins.h
scummvm/trunk/engines/metaengine.h
scummvm/trunk/gui/launcher.cpp
scummvm/trunk/gui/massadd.cpp
Modified: scummvm/trunk/base/plugins.h
===================================================================
--- scummvm/trunk/base/plugins.h 2008-05-13 09:30:23 UTC (rev 32082)
+++ scummvm/trunk/base/plugins.h 2008-05-13 10:41:32 UTC (rev 32083)
@@ -33,7 +33,7 @@
// Plugin versioning
-// Global Plugin API version
+/** Global Plugin API version */
#define PLUGIN_VERSION 1
enum PluginType {
@@ -67,14 +67,14 @@
(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 @@
#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 @@
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 @@
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 @@
};
/**
- * 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 @@
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
Modified: scummvm/trunk/engines/metaengine.h
===================================================================
--- scummvm/trunk/engines/metaengine.h 2008-05-13 09:30:23 UTC (rev 32082)
+++ scummvm/trunk/engines/metaengine.h 2008-05-13 10:41:32 UTC (rev 32083)
@@ -93,4 +93,25 @@
}
};
+
+// 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
Modified: scummvm/trunk/gui/launcher.cpp
===================================================================
--- scummvm/trunk/gui/launcher.cpp 2008-05-13 09:30:23 UTC (rev 32082)
+++ scummvm/trunk/gui/launcher.cpp 2008-05-13 10:41:32 UTC (rev 32083)
@@ -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"
Modified: scummvm/trunk/gui/massadd.cpp
===================================================================
--- scummvm/trunk/gui/massadd.cpp 2008-05-13 09:30:23 UTC (rev 32082)
+++ scummvm/trunk/gui/massadd.cpp 2008-05-13 10:41:32 UTC (rev 32083)
@@ -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()
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the Scummvm-git-logs
mailing list