diff plugin/transform/TransformFactory.h @ 383:94fc0591ea43 1.2-stable

* merge from trunk (1.2 ended up being tracked from trunk, but we may want
  this branch for fixes later)

--- a/plugin/transform/TransformFactory.h	Fri Nov 30 17:36:14 2007 +0000
+++ b/plugin/transform/TransformFactory.h	Wed Feb 27 10:32:45 2008 +0000
@@ -18,11 +18,11 @@
 
 #include "TransformDescription.h"
 
+#include <vamp-sdk/Plugin.h>
+
 #include <map>
 #include <set>
 
-namespace Vamp { class PluginBase; }
-
 class TransformFactory : public QObject
 {
     Q_OBJECT
@@ -32,10 +32,10 @@
 
     static TransformFactory *getInstance();
 
-    TransformList getAllTransforms();
+    TransformList getAllTransformDescriptions();
+    TransformDescription getTransformDescription(TransformId id);
 
     std::vector<QString> getAllTransformTypes();
-
     std::vector<QString> getTransformCategories(QString transformType);
     std::vector<QString> getTransformMakers(QString transformType);
 
@@ -45,6 +45,13 @@
     bool haveTransform(TransformId identifier);
 
     /**
+     * A single transform ID can lead to many possible Transforms,
+     * with different parameters and execution context settings.
+     * Return the default one for the given transform.
+     */
+    Transform getDefaultTransformFor(TransformId identifier, size_t rate = 0);
+
+    /**
      * Full name of a transform, suitable for putting on a menu.
      */
     QString getTransformName(TransformId identifier);
@@ -57,6 +64,8 @@
 
     QString getTransformUnits(TransformId identifier);
 
+    Vamp::Plugin::InputDomain getTransformInputDomain(TransformId identifier);
+
     /**
      * Return true if the transform has any configurable parameters,
      * i.e. if getConfigurationForTransform can ever return a non-trivial
@@ -74,6 +83,35 @@
                                   int &minChannels, int &maxChannels);
 
     /**
+     * Load an appropriate plugin for the given transform and set the
+     * parameters, program and configuration strings on that plugin
+     * from the Transform object.
+     *
+     * Note that this requires that the transform has a meaningful
+     * sample rate set, as that is used as the rate for the plugin.  A
+     * Transform can legitimately have rate set at zero (= "use the
+     * rate of the input source"), so the caller will need to test for
+     * this case.
+     *
+     * Returns the plugin thus loaded.  This will be a
+     * Vamp::PluginBase, but not necessarily a Vamp::Plugin (only if
+     * the transform was a feature-extraction type -- call
+     * downcastVampPlugin if you only want Vamp::Plugins).  Returns
+     * NULL if no suitable plugin was available.
+     *
+     * The returned plugin is owned by the caller, and should be
+     * deleted (using "delete") when no longer needed.
+     */
+    Vamp::PluginBase *instantiatePluginFor(const Transform &transform);
+
+    /**
+     * Convert a Vamp::PluginBase to a Vamp::Plugin, if it is one.
+     * Return NULL otherwise.  This ill-fitting convenience function
+     * is really just a dynamic_cast wrapper.
+     */
+    Vamp::Plugin *downcastVampPlugin(Vamp::PluginBase *);
+
+    /**
      * Set the plugin parameters, program and configuration strings on
      * the given Transform object from the given plugin instance.
      * Note that no check is made whether the plugin is actually the
@@ -82,6 +120,12 @@
     void setParametersFromPlugin(Transform &transform, Vamp::PluginBase *plugin);
 
     /**
+     * Set the parameters, program and configuration strings on the
+     * given plugin from the given Transform object.
+     */
+    void setPluginParameters(const Transform &transform, Vamp::PluginBase *plugin);
+    
+    /**
      * If the given Transform object has no processing step and block
      * sizes set, set them to appropriate defaults for the given
      * plugin.
@@ -89,11 +133,27 @@
     void makeContextConsistentWithPlugin(Transform &transform, Vamp::PluginBase *plugin); 
 
     /**
-     * A single transform ID can lead to many possible Transforms,
-     * with different parameters and execution context settings.
-     * Return the default one for the given transform.
+     * Retrieve a <plugin ... /> XML fragment that describes the
+     * plugin parameters, program and configuration data for the given
+     * transform.
+     *
+     * This function is provided for backward compatibility only.  Use
+     * Transform::toXml where compatibility with PluginXml
+     * descriptions of transforms is not required.
      */
-    Transform getDefaultTransformFor(TransformId identifier, size_t rate = 0);
+    QString getPluginConfigurationXml(const Transform &transform);
+
+    /**
+     * Set the plugin parameters, program and configuration strings on
+     * the given Transform object from the given <plugin ... /> XML
+     * fragment.
+     *
+     * This function is provided for backward compatibility only.  Use
+     * Transform(QString) where compatibility with PluginXml
+     * descriptions of transforms is not required.
+     */
+    void setParametersFromPluginConfigurationXml(Transform &transform,
+                                                 QString xml);
 
 protected:
     typedef std::map<TransformId, TransformDescription> TransformDescriptionMap;
@@ -103,6 +163,8 @@
     void populateFeatureExtractionPlugins(TransformDescriptionMap &);
     void populateRealTimePlugins(TransformDescriptionMap &);
 
+    Vamp::PluginBase *instantiateDefaultPluginFor(TransformId id, size_t rate);
+
     static TransformFactory *m_instance;
 };