Merged revisions 31972-31973,31975-31981,31984-31989,31993-31994,31996-32014,32016-32020,32022-32025,32027-32028,32030,32034,32037-32038,32040-32058,32060-32087,32089-32093,32095-32123 via svnmerge from

https://scummvm.svn.sourceforge.net/svnroot/scummvm/scummvm/trunk

svn-id: r32125

6 files changed, 323 insertions, 195 deletions

diff --git a/base/commandLine.cpp b/base/commandLine.cpp
index a4c867edee..d2f286cc4a 100644
--- a/base/commandLine.cpp
+++ b/base/commandLine.cpp
@@ -23,7 +23,7 @@
  *
  */
 
-#include "engines/engine.h"
+#include "engines/metaengine.h"
 #include "base/commandLine.h"
 #include "base/plugins.h"
 #include "base/version.h"
@@ -559,10 +559,10 @@ static void listGames() {
 	printf("Game ID              Full Title                                            \n"
 	       "-------------------- ------------------------------------------------------\n");
 
-	const PluginList &plugins = PluginManager::instance().getPlugins();
-	PluginList::const_iterator iter = plugins.begin();
+	const EnginePlugin::list &plugins = EngineMan.getPlugins();
+	EnginePlugin::list::const_iterator iter = plugins.begin();
 	for (iter = plugins.begin(); iter != plugins.end(); ++iter) {
-		GameList list = (*iter)->getSupportedGames();
+		GameList list = (**iter)->getSupportedGames();
 		for (GameList::iterator v = list.begin(); v != list.end(); ++v) {
 			printf("%-20s %s\n", v->gameid().c_str(), v->description().c_str());
 		}
@@ -586,7 +586,7 @@ static void listTargets() {
 			// to find the proper desc. In fact, the platform probably should
 			// be taken into account, too.
 			Common::String gameid(name);
-			GameDescriptor g = Base::findGame(gameid);
+			GameDescriptor g = EngineMan.findGame(gameid);
 			if (g.description().size() > 0)
 				description = g.description();
 		}
@@ -613,8 +613,8 @@ static void listSaves(const char *target) {
 	gameid.toLowercase();	// Normalize it to lower case
 
 	// Find the plugin that will handle the specified gameid
-	const Plugin *plugin = 0;
-	GameDescriptor game = Base::findGame(gameid, &plugin);
+	const EnginePlugin *plugin = 0;
+	GameDescriptor game = EngineMan.findGame(gameid, &plugin);
 
 	if (!plugin) {
 		error("Could not find any plugin to handle gameid '%s' (target '%s')", gameid.c_str(), target);
@@ -622,7 +622,7 @@ static void listSaves(const char *target) {
 	}
 
 	// Query the plugin for a list of savegames
-	SaveStateList saveList = plugin->listSaves(target);
+	SaveStateList saveList = (*plugin)->listSaves(target);
 
 	// TODO: Include more info about the target (desc, engine name, ...) ???
 	printf("Saves for target '%s':\n", target);
@@ -667,7 +667,7 @@ static void runDetectorTest() {
 			continue;
 		}
 
-		GameList candidates(PluginManager::instance().detectGames(files));
+		GameList candidates(EngineMan.detectGames(files));
 		bool gameidDiffers = false;
 		GameList::iterator x;
 		for (x = candidates.begin(); x != candidates.end(); ++x) {
@@ -740,7 +740,7 @@ bool processSettings(Common::String &command, Common::StringMap &settings) {
 	// domain (i.e. a target) matching this argument, or alternatively
 	// whether there is a gameid matching that name.
 	if (!command.empty()) {
-		GameDescriptor gd = Base::findGame(command);
+		GameDescriptor gd = EngineMan.findGame(command);
 		if (ConfMan.hasGameDomain(command) || !gd.gameid().empty()) {
 			bool idCameFromCommandLine = false;
 
diff --git a/base/game.cpp b/base/game.cpp
index a79cfddec9..9628543672 100644
--- a/base/game.cpp
+++ b/base/game.cpp
@@ -75,29 +75,3 @@ void SaveStateDescriptor::setThumbnail(Graphics::Surface *t) {
 	}
 	_thumbnail = t;
 }
-
-
-namespace Base {
-
-// TODO: Find a better name & place for this function.
-GameDescriptor findGame(const Common::String &gameName, const Plugin **plugin) {
-	// Find the GameDescriptor for this target
-	const PluginList &plugins = PluginManager::instance().getPlugins();
-	GameDescriptor result;
-
-	if (plugin)
-		*plugin = 0;
-
-	PluginList::const_iterator iter = plugins.begin();
-	for (iter = plugins.begin(); iter != plugins.end(); ++iter) {
-		result = (*iter)->findGame(gameName.c_str());
-		if (!result.gameid().empty()) {
-			if (plugin)
-				*plugin = *iter;
-			break;
-		}
-	}
-	return result;
-}
-
-} // End of namespace Base
diff --git a/base/game.h b/base/game.h
index 08d18247ef..18d7967388 100644
--- a/base/game.h
+++ b/base/game.h
@@ -179,15 +179,4 @@ public:
 /** List of savestates. */
 typedef Common::Array<SaveStateDescriptor> SaveStateList;
 
-
-class Plugin;
-
-namespace Base {
-
-// TODO: Find a better name & place for this function.
-GameDescriptor findGame(const Common::String &gameName, const Plugin **plugin = NULL);
-
-} // End of namespace Base
-
-
 #endif
diff --git a/base/main.cpp b/base/main.cpp
index 1f87708cc1..126700ef17 100644
--- a/base/main.cpp
+++ b/base/main.cpp
@@ -32,6 +32,7 @@
  */
 
 #include "engines/engine.h"
+#include "engines/metaengine.h"
 #include "base/commandLine.h"
 #include "base/plugins.h"
 #include "base/version.h"
@@ -77,8 +78,8 @@ static bool launcherDialog(OSystem &system) {
 	return (dlg.runModal() != -1);
 }
 
-static const Plugin *detectPlugin() {
-	const Plugin *plugin = 0;
+static const EnginePlugin *detectPlugin() {
+	const EnginePlugin *plugin = 0;
 
 	// Make sure the gameid is set in the config manager, and that it is lowercase.
 	Common::String gameid(ConfMan.getActiveDomainName());
@@ -90,7 +91,7 @@ static const Plugin *detectPlugin() {
 
 	// Query the plugins and find one that will handle the specified gameid
 	printf("Looking for %s\n", gameid.c_str());
-	GameDescriptor game = Base::findGame(gameid, &plugin);
+	GameDescriptor game = EngineMan.findGame(gameid, &plugin);
 
 	if (plugin == 0) {
 		printf("Failed game detection\n");
@@ -105,7 +106,7 @@ static const Plugin *detectPlugin() {
 }
 
 // TODO: specify the possible return values here
-static int runGame(const Plugin *plugin, OSystem &system, const Common::String &edebuglevels) {
+static int runGame(const EnginePlugin *plugin, OSystem &system, const Common::String &edebuglevels) {
 	Common::String gameDataPath(ConfMan.get("path"));
 	if (gameDataPath.empty()) {
 	} else if (gameDataPath.lastChar() != '/'
@@ -138,7 +139,7 @@ static int runGame(const Plugin *plugin, OSystem &system, const Common::String &
 
 	// Create the game engine
 	Engine *engine = 0;
-	PluginError err = plugin->createInstance(&system, &engine);
+	PluginError err = (*plugin)->createInstance(&system, &engine);
 	if (!engine || err != kNoError) {
 		// TODO: Show an error dialog or so?
 		// TODO: Also take 'err' into consideration...
@@ -168,7 +169,7 @@ static int runGame(const Plugin *plugin, OSystem &system, const Common::String &
 	// Set the window caption to the game name
 	Common::String caption(ConfMan.get("description"));
 
-	Common::String desc = Base::findGame(ConfMan.get("gameid")).description();
+	Common::String desc = EngineMan.findGame(ConfMan.get("gameid")).description();
 	if (caption.empty() && !desc.empty())
 		caption = desc;
 	if (caption.empty())
@@ -300,11 +301,11 @@ extern "C" int scummvm_main(int argc, char *argv[]) {
 	// cleanly, so this is now enabled to encourage people to fix bits :)
 	while (0 != ConfMan.getActiveDomain()) {
 		// Try to find a plugin which feels responsible for the specified game.
-		const Plugin *plugin = detectPlugin();
+		const EnginePlugin *plugin = detectPlugin();
 		if (plugin) {
 			// Unload all plugins not needed for this game,
 			// to save memory
-			PluginManager::instance().unloadPluginsExcept(plugin);
+			PluginManager::instance().unloadPluginsExcept(PLUGIN_TYPE_ENGINE, plugin);
 
 			// Try to run the game
 			int result = runGame(plugin, system, specialDebug);
@@ -331,7 +332,7 @@ extern "C" int scummvm_main(int argc, char *argv[]) {
 
 		launcherDialog(system);
 	}
-	PluginManager::instance().unloadPluginsExcept(NULL);
+	PluginManager::instance().unloadPlugins();
 	PluginManager::destroy();
 	Common::ConfigManager::destroy();
 	GUI::NewGui::destroy();
diff --git a/base/plugins.cpp b/base/plugins.cpp
index aa813297fc..ac8e498469 100644
--- a/base/plugins.cpp
+++ b/base/plugins.cpp
@@ -24,16 +24,21 @@
  */
 
 #include "base/plugins.h"
-#include "common/util.h"
 
 #ifdef DYNAMIC_MODULES
 #include "common/config-manager.h"
 #endif
 
+// Plugin versioning
+
 int pluginTypeVersions[PLUGIN_TYPE_MAX] = {
 	PLUGIN_TYPE_ENGINE_VERSION,
+	PLUGIN_TYPE_MIDI_VERSION,
 };
 
+
+// Abstract plugins
+
 PluginType Plugin::getType() const {
 	return _type;
 }
@@ -42,31 +47,6 @@ const char *Plugin::getName() const {
 	return _pluginObject->getName();
 }
 
-const char *Plugin::getCopyright() const {
-	return ((MetaEngine*)_pluginObject)->getCopyright();
-}
-
-PluginError Plugin::createInstance(OSystem *syst, Engine **engine) const {
-	return ((MetaEngine*)_pluginObject)->createInstance(syst, engine);
-}
-
-GameList Plugin::getSupportedGames() const {
-	return ((MetaEngine*)_pluginObject)->getSupportedGames();
-}
-
-GameDescriptor Plugin::findGame(const char *gameid) const {
-	return ((MetaEngine*)_pluginObject)->findGame(gameid);
-}
-
-GameList Plugin::detectGames(const FSList &fslist) const {
-	return ((MetaEngine*)_pluginObject)->detectGames(fslist);
-}
-
-SaveStateList Plugin::listSaves(const char *target) const {
-	return ((MetaEngine*)_pluginObject)->listSaves(target);
-}
-
-
 class StaticPlugin : public Plugin {
 public:
 	StaticPlugin(PluginObject *pluginobject, PluginType type) {
@@ -103,6 +83,7 @@ public:
 		// "Loader" for the static plugins.
 		// Iterate over all registered (static) plugins and load them.
 
+		// Engine plugins
 		#if PLUGIN_ENABLED_STATIC(SCUMM)
 		LINK_PLUGIN(SCUMM)
 		#endif
@@ -161,6 +142,49 @@ public:
 		LINK_PLUGIN(TOUCHE)
 		#endif
 
+		// MIDI plugins
+		// TODO: Use defines to disable or enable each MIDI driver as a
+		// static/dynamic plugin, like it's done for the engines
+		LINK_PLUGIN(NULL)
+		#if defined(WIN32) && !defined(_WIN32_WCE) && !defined(__SYMBIAN32__)
+		LINK_PLUGIN(WINDOWS)
+		#endif
+		#if defined(UNIX) && defined(USE_ALSA)
+		LINK_PLUGIN(ALSA)
+		#endif
+		#if defined(UNIX) && !defined(__BEOS__) && !defined(__MAEMO__)
+		LINK_PLUGIN(SEQ)
+		#endif
+		#if defined(IRIX)
+		LINK_PLUGIN(DMEDIA)
+		#endif
+		#if defined(__amigaos4__)
+		LINK_PLUGIN(CAMD)
+		#endif
+		#if defined(MACOSX)
+		LINK_PLUGIN(COREAUDIO)
+		LINK_PLUGIN(COREMIDI)
+		LINK_PLUGIN(QUICKTIME)
+		#endif
+		#if defined(PALMOS_MODE)
+		#  if defined(COMPILE_CLIE)
+		LINK_PLUGIN(YPA1)
+		#  elif defined(COMPILE_ZODIAC) && (!defined(ENABLE_SCUMM) || !defined(PALMOS_ARM))
+		LINK_PLUGIN(ZODIAC)
+		#  endif
+		#endif
+		#ifdef USE_FLUIDSYNTH
+		LINK_PLUGIN(FLUIDSYNTH)
+		#endif
+		#ifdef USE_MT32EMU
+		LINK_PLUGIN(MT32)
+		#endif
+		LINK_PLUGIN(ADLIB)
+		LINK_PLUGIN(TOWNS)
+		#if defined (UNIX)
+		LINK_PLUGIN(TIMIDITY)
+		#endif
+
 		return pl;
 	}
 };
@@ -171,38 +195,34 @@ PluginList FilePluginProvider::getPlugins() {
 	PluginList pl;
 
 	// Prepare the list of directories to search
-	Common::StringList pluginDirs;
+	FSList pluginDirs;
 
 	// Add the default directories
-	pluginDirs.push_back(".");
-	pluginDirs.push_back("plugins");
+	pluginDirs.push_back(FilesystemNode("."));
+	pluginDirs.push_back(FilesystemNode("plugins"));
 
 	// Add the provider's custom directories
 	addCustomDirectories(pluginDirs);
 
 	// Add the user specified directory
 	Common::String pluginsPath(ConfMan.get("pluginspath"));
-	if (!pluginsPath.empty()) {
-		FilesystemNode dir(pluginsPath);
-		pluginDirs.push_back(dir.getPath());
-	}
+	if (!pluginsPath.empty())
+		pluginDirs.push_back(FilesystemNode(pluginsPath));
 
-	Common::StringList::const_iterator d;
-	for (d = pluginDirs.begin(); d != pluginDirs.end(); d++) {
+	FSList::const_iterator dir;
+	for (dir = pluginDirs.begin(); dir != pluginDirs.end(); dir++) {
 		// Load all plugins.
 		// Scan for all plugins in this directory
-		FilesystemNode dir(*d);
 		FSList files;
-		if (!dir.getChildren(files, FilesystemNode::kListFilesOnly)) {
-			debug(1, "Couldn't open plugin directory '%s'", d->c_str());
+		if (!dir->getChildren(files, FilesystemNode::kListFilesOnly)) {
+			debug(1, "Couldn't open plugin directory '%s'", dir->getPath().c_str());
 			continue;
 		} else {
-			debug(1, "Reading plugins from plugin directory '%s'", d->c_str());
+			debug(1, "Reading plugins from plugin directory '%s'", dir->getPath().c_str());
 		}
 
 		for (FSList::const_iterator i = files.begin(); i != files.end(); ++i) {
-			Common::String name(i->getName());
-			if (name.hasPrefix(getPrefix()) && name.hasSuffix(getSuffix())) {
+			if (isPluginFilename(i->getName())) {
 				pl.push_back(createPlugin(i->getPath()));
 			}
 		}
@@ -211,25 +231,25 @@ PluginList FilePluginProvider::getPlugins() {
 	return pl;
 }
 
-const char* FilePluginProvider::getPrefix() const {
+bool FilePluginProvider::isPluginFilename(const Common::String &filename) const {
 #ifdef PLUGIN_PREFIX
-	return PLUGIN_PREFIX;
-#else
-	return "";
+	// Check the plugin prefix
+	if (!filename.hasPrefix(PLUGIN_PREFIX))
+		return false;
 #endif
-}
 
-const char* FilePluginProvider::getSuffix() const {
 #ifdef PLUGIN_SUFFIX
-	return PLUGIN_SUFFIX;
-#else
-	return "";
+	// Check the plugin suffix
+	if (!filename.hasSuffix(PLUGIN_SUFFIX))
+		return false;
 #endif
+
+	return true;
 }
 
-void FilePluginProvider::addCustomDirectories(Common::StringList &dirs) const {
+void FilePluginProvider::addCustomDirectories(FSList &dirs) const {
 #ifdef PLUGIN_DIRECTORY
-	dirs.push_back(PLUGIN_DIRECTORY);
+	dirs.push_back(FilesystemNode(PLUGIN_DIRECTORY));
 #endif
 }
 
@@ -273,12 +293,13 @@ void PluginManager::loadPlugins() {
 }
 
 void PluginManager::unloadPlugins() {
-	unloadPluginsExcept(NULL);
+	for (int i = 0; i < PLUGIN_TYPE_MAX; i++)
+		unloadPluginsExcept((PluginType)i, NULL);
 }
 
-void PluginManager::unloadPluginsExcept(const Plugin *plugin) {
+void PluginManager::unloadPluginsExcept(PluginType type, const Plugin *plugin) {
 	Plugin *found = NULL;
-	for (PluginList::iterator p = _plugins.begin(); p != _plugins.end(); ++p) {
+	for (PluginList::iterator p = _plugins[type].begin(); p != _plugins[type].end(); ++p) {
 		if (*p == plugin) {
 			found = *p;
 		} else {
@@ -286,9 +307,9 @@ void PluginManager::unloadPluginsExcept(const Plugin *plugin) {
 			delete *p;
 		}
 	}
-	_plugins.clear();
+	_plugins[type].clear();
 	if (found != NULL) {
-		_plugins.push_back(found);
+		_plugins[type].push_back(found);
 	}
 }
 
@@ -296,16 +317,26 @@ bool PluginManager::tryLoadPlugin(Plugin *plugin) {
 	assert(plugin);
 	// Try to load the plugin
 	if (plugin->loadPlugin()) {
-		// If successful, add it to the list of known plugins and return.
-		_plugins.push_back(plugin);
+		// The plugin is valid, see if it provides the same module as an
+		// already loaded one and should replace it.
+		bool found = false;
+
+		PluginList::iterator pl = _plugins[plugin->getType()].begin();
+		while (!found && pl != _plugins[plugin->getType()].end()) {
+			if (!strcmp(plugin->getName(), (*pl)->getName())) {
+				// Found a duplicated module. Replace the old one.
+				found = true;
+				delete *pl;
+				*pl = plugin;
+				debug(1, "Replaced the duplicated plugin: '%s'", plugin->getName());
+			}
+			pl++;
+		}
 
-		// TODO/FIXME: We should perform some additional checks here:
-		// * Check for some kind of "API version" (possibly derived from the
-		//   SVN tree revision?)
-		// * If two plugins provide the same engine, we should only load one.
-		//   To detect this situation, we could just compare the plugin name.
-		//   To handle it, simply prefer modules loaded earlier to those coming.
-		//   Or vice versa... to be determined... :-)
+		if (!found) {
+			// If it provides a new module, just add it to the list of known plugins.
+			_plugins[plugin->getType()].push_back(plugin);
+		}
 
 		return true;
 	} else {
@@ -315,15 +346,59 @@ bool PluginManager::tryLoadPlugin(Plugin *plugin) {
 	}
 }
 
-GameList PluginManager::detectGames(const FSList &fslist) const {
+
+// Engine plugins
+
+#include "engines/metaengine.h"
+
+DECLARE_SINGLETON(EngineManager);
+
+GameDescriptor EngineManager::findGame(const Common::String &gameName, const EnginePlugin **plugin) const {
+	// Find the GameDescriptor for this target
+	const EnginePlugin::list &plugins = getPlugins();
+	GameDescriptor result;
+
+	if (plugin)
+		*plugin = 0;
+
+	EnginePlugin::list::const_iterator iter = plugins.begin();
+	for (iter = plugins.begin(); iter != plugins.end(); ++iter) {
+		result = (**iter)->findGame(gameName.c_str());
+		if (!result.gameid().empty()) {
+			if (plugin)
+				*plugin = *iter;
+			break;
+		}
+	}
+	return result;
+}
+
+GameList EngineManager::detectGames(const FSList &fslist) const {
 	GameList candidates;
 
+	const EnginePlugin::list &plugins = getPlugins();
+
 	// Iterate over all known games and for each check if it might be
 	// the game in the presented directory.
-	PluginList::const_iterator iter;
-	for (iter = _plugins.begin(); iter != _plugins.end(); ++iter) {
-		candidates.push_back((*iter)->detectGames(fslist));
+	EnginePlugin::list::const_iterator iter;
+	for (iter = plugins.begin(); iter != plugins.end(); ++iter) {
+		candidates.push_back((**iter)->detectGames(fslist));
 	}
 
 	return candidates;
 }
+
+const EnginePlugin::list &EngineManager::getPlugins() const {
+	return (const EnginePlugin::list&)PluginManager::instance().getPlugins(PLUGIN_TYPE_ENGINE);
+}
+
+
+// MIDI plugins
+
+#include "sound/midiplugin.h"
+
+DECLARE_SINGLETON(MidiManager);
+
+const MidiPlugin::list &MidiManager::getPlugins() const {
+	return (const MidiPlugin::list&)PluginManager::instance().getPlugins(PLUGIN_TYPE_MIDI);
+}
diff --git a/base/plugins.h b/base/plugins.h
index ec947ee6ad..d03a240922 100644
--- a/base/plugins.h
+++ b/base/plugins.h
@@ -26,79 +26,56 @@
 #ifndef BASE_PLUGINS_H
 #define BASE_PLUGINS_H
 
-#include "common/array.h"
 #include "common/error.h"
-#include "common/list.h"
 #include "common/singleton.h"
 #include "common/util.h"
-#include "base/game.h"
+
+#ifdef DYNAMIC_MODULES
+#include "common/fs.h"
+#endif
 
 /**
- * Abstract base class for the plugin objects which handle plugins
- * instantiation. Subclasses for this may be used for engine plugins
- * and other types of plugins.
+ * @page pagePlugins An overview of the ScummVM plugin system
+ * This is a brief overview of how plugins (dynamically loadable code modules)
+ * work in ScummVM. We will explain how to write plugins, how they work internally,
+ * and sketch how porters can add support for them in their ports.
+ *
+ * \section secPluginImpl Implementing a plugin
+ * TODO
+ *
+ * \section secPluginUse Using plugins
+ * TODO
+ *
+ * \section secPluginInternals How plugins work internally
+ * TODO
+ *
+ * \section secPluginBackend How to add support for dynamic plugins to a port
+ * TODO
  */
-class PluginObject {
-public:
-	virtual ~PluginObject() {}
 
-	/** Returns the name of the plugin. */
-	virtual const char *getName() const = 0;
-};
 
-#include "engines/metaengine.h"
 
-// Global Plugin API version
+// Plugin versioning
+
+/** Global Plugin API version */
 #define PLUGIN_VERSION 1
 
 enum PluginType {
 	PLUGIN_TYPE_ENGINE = 0,
+	PLUGIN_TYPE_MIDI,
 
 	PLUGIN_TYPE_MAX
 };
 
 // TODO: Make the engine API version depend on ScummVM's version
-// because of the backlinking
+// because of the backlinking (posibly from the SVN revision)
 #define PLUGIN_TYPE_ENGINE_VERSION 1
+#define PLUGIN_TYPE_MIDI_VERSION 1
 
 extern int pluginTypeVersions[PLUGIN_TYPE_MAX];
 
-class Engine;
-class FSList;
-class OSystem;
-
-/**
- * Abstract base class for the plugin system.
- * Subclasses for this can be used to wrap both static and dynamic
- * plugins.
- */
-class Plugin {
-protected:
-	PluginObject *_pluginObject;
-	PluginType _type;
-
-public:
-	Plugin() : _pluginObject(0) {}
-	virtual ~Plugin() {
-		//if (isLoaded())
-			//unloadPlugin();
-	}
-
-//	virtual bool isLoaded() const = 0;	// TODO
-	virtual bool loadPlugin() = 0;	// TODO: Rename to load() ?
-	virtual void unloadPlugin() = 0;	// TODO: Rename to unload() ?
-
-	PluginType getType() const;
-	const char *getName() const;
-	const char *getCopyright() const;
-
-	PluginError createInstance(OSystem *syst, Engine **engine) const;
-	GameList getSupportedGames() const;
-	GameDescriptor findGame(const char *gameid) const;
-	GameList detectGames(const FSList &fslist) const;
-	SaveStateList listSaves(const char *target) const;
-};
 
+// Plugin linking
 
 #define STATIC_PLUGIN 1
 #define DYNAMIC_PLUGIN 2
@@ -116,14 +93,14 @@ public:
 	(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() { \
@@ -133,6 +110,15 @@ public:
 
 #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; } \
@@ -147,44 +133,149 @@ public:
 #endif // DYNAMIC_MODULES
 
 
-/** List of plugins. */
+// Abstract plugins
+
+/**
+ * Abstract base class for the plugin objects which handle plugins
+ * instantiation. Subclasses for this may be used for engine plugins
+ * and other types of plugins.
+ *
+ * FIXME: This class needs better documentation, esp. how it differs from class Plugin
+ */
+class PluginObject {
+public:
+	virtual ~PluginObject() {}
+
+	/** Returns the name of the plugin. */
+	virtual const char *getName() const = 0;
+};
+
+/**
+ * Abstract base class for the plugin system.
+ * Subclasses for this can be used to wrap both static and dynamic
+ * plugins.
+ *
+ * FIXME: This class needs better documentation, esp. how it differs from class PluginObject
+ */
+class Plugin {
+protected:
+	PluginObject *_pluginObject;
+	PluginType _type;
+
+public:
+	Plugin() : _pluginObject(0) {}
+	virtual ~Plugin() {
+		//if (isLoaded())
+			//unloadPlugin();
+	}
+
+//	virtual bool isLoaded() const = 0;	// TODO
+	virtual bool loadPlugin() = 0;	// TODO: Rename to load() ?
+	virtual void unloadPlugin() = 0;	// TODO: Rename to unload() ?
+
+	PluginType getType() const;
+	const char *getName() const;
+};
+
+/** List of Plugin instances. */
 typedef Common::Array<Plugin *> PluginList;
 
+/**
+ * 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:
+	PO_t *operator->() const {
+		return (PO_t *)_pluginObject;
+	}
+
+	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.
+	 *
+	 * @return a list of Plugin instances
 	 */
 	virtual PluginList getPlugins() = 0;
 };
 
+#ifdef DYNAMIC_MODULES
+
+/**
+ * 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:
+	/**
+	 * Return a list of Plugin objects loaded via createPlugin from disk.
+	 * For this, a list of directories is searched for plugin objects:
+	 * The current dir and its "plugins" subdirectory (if present), a list
+	 * of custom search dirs (see addCustomDirectories) and finally the 
+	 * directory specified via the "pluginspath" config variable (if any).
+	 *
+	 * @return a list of Plugin instances
+	 */
 	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 occurred.
+	 */
 	virtual Plugin* createPlugin(const Common::String &filename) const = 0;
 
-	virtual const char* getPrefix() const;
-	virtual const char* getSuffix() const;
+	/**
+	 * Check if the supplied filename corresponds to a loadable plugin file in
+	 * the current platform.
+	 *
+	 * @param filename	the name of the file to check
+	 * @return	true if the filename corresponds to a plugin, false otherwise
+	 */
+	virtual bool isPluginFilename(const Common::String &filename) const;
 
-	virtual void addCustomDirectories(Common::StringList &dirs) const;
+	/**
+	 * Optionally add to the list of directories to be searched for
+	 * plugins by getPlugins().
+	 *
+	 * @param dirs	the reference to the list of directories to be used when
+	 * 		searching for plugins.
+	 */
+	virtual void addCustomDirectories(FSList &dirs) const;
 };
 
+#endif // DYNAMIC_MODULES
+
 /**
- * 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;
+	typedef Common::Array<PluginProvider *> ProviderList;
 private:
-	PluginList _plugins;
+	PluginList _plugins[PLUGIN_TYPE_MAX];
 	ProviderList _providers;
 
 	bool tryLoadPlugin(Plugin *plugin);
@@ -199,11 +290,9 @@ public:
 
 	void loadPlugins();
 	void unloadPlugins();
-	void unloadPluginsExcept(const Plugin *plugin);
-
-	const PluginList &getPlugins()	{ return _plugins; }
+	void unloadPluginsExcept(PluginType type, const Plugin *plugin);
 
-	GameList detectGames(const FSList &fslist) const;
+	const PluginList &getPlugins(PluginType t) { return _plugins[t]; }
 };
 
 #endif