changeset 23:cc9c503535d1

add listPlugins, some docs

--- a/org/vamp_plugins/PluginLoader.java	Wed Nov 14 17:35:46 2012 +0000
+++ b/org/vamp_plugins/PluginLoader.java	Wed Nov 14 17:53:03 2012 +0000
@@ -1,10 +1,25 @@
 
 package org.vamp_plugins;
 
+/**
+ * PluginLoader loads a Vamp plugin by searching the standard Vamp
+ * installation path, and returns a Plugin object wrapping the native
+ * plugin.
+ *
+ * To load a plugin call PluginLoader.getInstance().loadPlugin(key,
+ * rate), where rate is the processing sample rate and key is the
+ * plugin key consisting of the plugin's library base name and its
+ * identifier, colon-separated. For example,
+ *
+ * Plugin p = PluginLoader.getInstance().loadPlugin("vamp-example-plugins:percussiononsets", 44100);
+ */
 public class PluginLoader
 {
     public class LoadFailedException extends Exception { };
 
+    /**
+     * PluginLoader is a singleton. Return the instance of it.
+     */
     public static synchronized PluginLoader getInstance() {
 	if (inst == null) {
 	    inst = new PluginLoader();
@@ -13,6 +28,23 @@
 	return inst;
     }
 
+    /**
+     * Search for all available Vamp plugins, and return a list of
+     * their plugin keys (suitable for passing to loadPlugin) in the
+     * order in which they were found.
+     */
+    public native ArrayList<String> listPlugins();
+
+    /**
+     * Load a native Vamp plugin from the plugin path. If the plugin
+     * cannot be loaded, throw LoadFailedException.
+     * 
+     * key is the plugin key consisting of the plugin's library base
+     * name and its identifier, colon-separated; inputSampleRate is
+     * the processing sample rate for input audio.
+     *
+     *!!! todo: adapter flags
+     */
     public Plugin loadPlugin(String key, float inputSampleRate)
 	throws LoadFailedException {
 	long handle = loadPluginNative(key, inputSampleRate);
@@ -20,6 +52,19 @@
 	else throw new LoadFailedException();
     }
 
+    /**
+     * Return the category hierarchy for a Vamp plugin, given its
+     * identifying key. The hierarchy is a sequence of category names
+     * giving the location of a plugin within a category forest,
+     * containing the human-readable names of the plugin's category
+     * tree root, followed by each of the nodes down to the leaf
+     * containing the plugin.
+     *
+     * If the plugin has no category information, return an empty
+     * list.
+     */
+    public native ArrayList<String> getPluginCategory(String key);
+
     private PluginLoader() { initialise(); }
     private native long loadPluginNative(String key, float inputSampleRate);
     private native void initialise();

--- a/src/PluginLoader.cpp	Wed Nov 14 17:35:46 2012 +0000
+++ b/src/PluginLoader.cpp	Wed Nov 14 17:53:03 2012 +0000
@@ -14,6 +14,20 @@
     setHandle(env, obj, inst);
 }
 
+jobjectArray
+Java_org_vamp_1plugins_PluginLoader_listPlugins(JNIEnv *env, jobject obj)
+{
+    PluginLoader *inst = getHandle<PluginLoader>(env, obj);
+    PluginLoader::PluginKeyList plugins = inst->listPlugins();
+    jobjectArray result = env->NewObjectArray
+	(plugins.size(), env->FindClass("java/lang/String"), 0);
+    for (int i = 0; i < plugins.size(); ++i) {
+	env->SetObjectArrayElement(result, i,
+				   env->NewStringUTF(plugins[i].c_str()));
+    }
+    return result;
+}    
+
 jlong
 Java_org_vamp_1plugins_PluginLoader_loadPluginNative(JNIEnv *env, jobject obj,
 						     jstring key, jfloat rate)
@@ -27,3 +41,6 @@
 
 
     
+//!!! todo: loadPlugin adapters
+//!!! todo: getPluginCategory
+