changeset 209:ac4f5f8ee0e7

Merge branch 'dev/step-and-block-size'

--- a/vamp-client/CapnpRRClient.h	Thu Feb 09 12:54:00 2017 +0000
+++ b/vamp-client/CapnpRRClient.h	Thu Feb 09 14:16:37 2017 +0000
@@ -66,6 +66,16 @@
  * such as a subprocess pipe arrangement. Only one request can be
  * handled at a time. This class is thread-safe if and only if it is
  * constructed with a thread-safe SynchronousTransport implementation.
+ *
+ * This class takes Vamp-like structures (Plugin and the classes in
+ * vamp-support) and uses them to communicate with a Piper server
+ * using the Cap'n Proto serialisation of the Piper API. The transport
+ * layer (and thus the nature of the server) is defined by the
+ * SynchronousTransport passed to the constructor.
+ *
+ * This class implements both the Loader interface (which constructs
+ * PluginStub objects) and the PluginClient (which accepts PluginStubs
+ * and maps them into Piper handles).
  */
 class CapnpRRClient : public PluginClient,
                       public Loader

--- a/vamp-client/PluginClient.h	Thu Feb 09 12:54:00 2017 +0000
+++ b/vamp-client/PluginClient.h	Thu Feb 09 14:16:37 2017 +0000
@@ -43,6 +43,12 @@
 
 class PluginStub;
 
+/**
+ * Interface for a client that accepts Vamp-like structures (Plugin
+ * and the classes in vamp-support) and communicates with a Piper
+ * server, using some serialisation and transport defined by the
+ * specific implementation.
+ */
 class PluginClient
 {
 public:
@@ -63,7 +69,8 @@
 
     virtual
     void
-    reset(PluginStub *plugin, PluginConfiguration config) = 0;
+    reset(PluginStub *plugin,
+          PluginConfiguration config) = 0;
 };
 
 }

--- a/vamp-client/PluginStub.h	Thu Feb 09 12:54:00 2017 +0000
+++ b/vamp-client/PluginStub.h	Thu Feb 09 14:16:37 2017 +0000
@@ -50,6 +50,9 @@
 namespace piper_vamp {
 namespace client {
 
+/**
+ * PluginStub presents a Piper feature extractor in the form of a Vamp plugin.
+ */
 class PluginStub : public Vamp::Plugin
 {
     enum State {

--- a/vamp-client/qt/AutoPlugin.h	Thu Feb 09 12:54:00 2017 +0000
+++ b/vamp-client/qt/AutoPlugin.h	Thu Feb 09 14:16:37 2017 +0000
@@ -46,9 +46,26 @@
 namespace client {
 
 /**
- * This "plugin" make the Piper client abstraction behave like a local
- * Vamp plugin, with its own server that lasts only for the lifetime
- * of this plugin and serves only it.
+ * AutoPlugin presents a Piper feature extractor in the form of a Vamp
+ * plugin, managing its own single-use server instance. That is, the
+ * distinguishing quality of AutoPlugin (in comparison with
+ * PluginStub) is that it runs and terminates its own Piper server,
+ * whose lifetime matches that of the plugin.
+ *
+ * Example usage:
+ *
+ *    Vamp::Plugin *plugin = 
+ *        new AutoPlugin("piper-server-name.exe",
+ *                       "vamp-example-plugins:zerocrossing",
+ *                       44100.0f,
+ *                       Vamp::HostExt::PluginLoader::ADAPT_ALL_SAFE,
+ *                       nullptr);
+ *    plugin->initialise(...);
+ *    plugin->process(...);       <-- in the normal way for a Vamp plugin
+ *    delete plugin;              <-- causes the server to exit
+ *
+ * AutoPlugin makes use of the Loader and PluginClient interfaces,
+ * providing them its own transport layer object for its single server.
  *
  * Note that any method may throw ServerCrashed, RequestTimedOut or
  * ProtocolError exceptions.
@@ -56,11 +73,22 @@
 class AutoPlugin : public Vamp::Plugin
 {
 public:
+    /**
+     * Construct an AutoPlugin that runs an instance of the Piper
+     * server with the given server name (executable path), requesting
+     * the given plugin key from the server.
+     *
+     * \param adapterFlags a bitwise OR of the values in the
+     * Vamp::HostExt::PluginLoader::AdapterFlags enumeration
+     *
+     * \param logger an optional callback for log messages. Pass a
+     * null pointer to use cerr instead.
+     */
     AutoPlugin(std::string serverName,
                std::string pluginKey,
                float inputSampleRate,
                int adapterFlags,
-               LogCallback *logger) : // logger may be nullptr for cerr
+               LogCallback *logger) :
         Vamp::Plugin(inputSampleRate),
         m_logger(logger),
         m_transport(serverName, "capnp", logger),
@@ -81,6 +109,8 @@
 
     virtual ~AutoPlugin() {
         delete m_plugin;
+        // The transport is a plain data member and will be deleted
+        // here, which will have the effect of terminating the server
     }
 
     bool isOK() const {

--- a/vamp-support/PluginConfiguration.h	Thu Feb 09 12:54:00 2017 +0000
+++ b/vamp-support/PluginConfiguration.h	Thu Feb 09 14:16:37 2017 +0000
@@ -81,6 +81,10 @@
     ParameterMap parameterValues;
     std::string currentProgram;
 
+    /**
+     * Extract the configuration from the given plugin (without
+     * retaining any persistent reference to the plugin itself).
+     */
     static PluginConfiguration
     fromPlugin(Vamp::Plugin *p,
 	       int channelCount,