cannam@0: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
cannam@0: 
cannam@0: /*
cannam@0:     Sonic Visualiser
cannam@0:     An audio file viewer and annotation editor.
cannam@0:     Centre for Digital Music, Queen Mary, University of London.
cannam@0:     This file copyright 2006 Chris Cannam.
cannam@0:     
cannam@0:     This program is free software; you can redistribute it and/or
cannam@0:     modify it under the terms of the GNU General Public License as
cannam@0:     published by the Free Software Foundation; either version 2 of the
cannam@0:     License, or (at your option) any later version.  See the file
cannam@0:     COPYING included with this distribution for more information.
cannam@0: */
cannam@0: 
cannam@0: #ifndef _VAMP_PLUGIN_BASE_H_
cannam@0: #define _VAMP_PLUGIN_BASE_H_
cannam@0: 
cannam@0: #include <string>
cannam@0: #include <vector>
cannam@0: 
cannam@0: namespace Vamp {
cannam@0: 
cannam@0: /**
cannam@0:  * A base class for plugins with optional configurable parameters,
cannam@0:  * programs, etc.
cannam@0:  *
cannam@0:  * This does not provide the necessary interfaces to instantiate or
cannam@0:  * run a plugin -- that depends on the plugin subclass, as different
cannam@0:  * plugin types may have quite different operating structures.  This
cannam@0:  * class just specifies the necessary interface to show editable
cannam@0:  * controls for the plugin to the user.
cannam@0:  */
cannam@0: 
cannam@0: class PluginBase 
cannam@0: {
cannam@0: public:
cannam@0:     /**
cannam@0:      * Get the computer-usable name of the plugin.  This should be
cannam@0:      * reasonably short and contain no whitespace or punctuation
cannam@0:      * characters.  It may be shown to the user, but it won't be the
cannam@0:      * main method for a user to identify a plugin (that will be the
cannam@0:      * description, below).
cannam@0:      */
cannam@0:     virtual std::string getName() const = 0;
cannam@0: 
cannam@0:     /**
cannam@0:      * Get a human-readable description of the plugin.  This should be
cannam@0:      * self-contained, as it may be shown to the user in isolation
cannam@0:      * without also showing the plugin's "name".
cannam@0:      */
cannam@0:     virtual std::string getDescription() const = 0;
cannam@0:     
cannam@0:     /**
cannam@0:      * Get the name of the author or vendor of the plugin in
cannam@0:      * human-readable form.
cannam@0:      */
cannam@0:     virtual std::string getMaker() const = 0;
cannam@0: 
cannam@0:     /**
cannam@0:      * Get the version number of the plugin.
cannam@0:      */
cannam@0:     virtual int getPluginVersion() const = 0;
cannam@0: 
cannam@0:     /**
cannam@0:      * Get the copyright statement or licensing summary of the plugin.
cannam@0:      */
cannam@0:     virtual std::string getCopyright() const = 0;
cannam@0: 
cannam@0:     /**
cannam@0:      * Get the type of plugin (e.g. DSSI, etc).  This is likely to be
cannam@0:      * implemented by the immediate subclass, not by actual plugins.
cannam@0:      */
cannam@0:     virtual std::string getType() const = 0;
cannam@0: 
cannam@0: 
cannam@0:     struct ParameterDescriptor
cannam@0:     {
cannam@0: 	/**
cannam@0: 	 * The name of the parameter, in computer-usable form.  Should
cannam@0: 	 * be reasonably short, and may only contain the characters
cannam@0: 	 * [a-zA-Z0-9_].
cannam@0: 	 */
cannam@0: 	std::string name;
cannam@0: 
cannam@0: 	/**
cannam@0: 	 * The human-readable name of the parameter.
cannam@0: 	 */
cannam@0: 	std::string description;
cannam@0: 
cannam@0: 	/**
cannam@0: 	 * The unit of the parameter, in human-readable form.
cannam@0: 	 */
cannam@0: 	std::string unit;
cannam@0: 
cannam@0: 	/**
cannam@0: 	 * The minimum value of the parameter.
cannam@0: 	 */
cannam@0: 	float minValue;
cannam@0: 
cannam@0: 	/**
cannam@0: 	 * The maximum value of the parameter.
cannam@0: 	 */
cannam@0: 	float maxValue;
cannam@0: 
cannam@0: 	/**
cannam@0: 	 * The default value of the parameter.
cannam@0: 	 */
cannam@0: 	float defaultValue;
cannam@0: 	
cannam@0: 	/**
cannam@0: 	 * True if the parameter values are quantized to a particular
cannam@0: 	 * resolution.
cannam@0: 	 */
cannam@0: 	bool isQuantized;
cannam@0: 
cannam@0: 	/**
cannam@0: 	 * Quantization resolution of the parameter values (e.g. 1.0
cannam@0: 	 * if they are all integers).  Undefined if isQuantized is
cannam@0: 	 * false.
cannam@0: 	 */
cannam@0: 	float quantizeStep;
cannam@0:     };
cannam@0: 
cannam@0:     typedef std::vector<ParameterDescriptor> ParameterList;
cannam@0: 
cannam@0:     /**
cannam@0:      * Get the controllable parameters of this plugin.
cannam@0:      */
cannam@0:     virtual ParameterList getParameterDescriptors() const {
cannam@0: 	return ParameterList();
cannam@0:     }
cannam@0: 
cannam@0:     /**
cannam@0:      * Get the value of a named parameter.  The argument is the name
cannam@0:      * field from that parameter's descriptor.
cannam@0:      */
cannam@0:     virtual float getParameter(std::string) const { return 0.0; }
cannam@0: 
cannam@0:     /**
cannam@0:      * Set a named parameter.  The first argument is the name field
cannam@0:      * from that parameter's descriptor.
cannam@0:      */
cannam@0:     virtual void setParameter(std::string, float) { } 
cannam@0: 
cannam@0:     
cannam@0:     typedef std::vector<std::string> ProgramList;
cannam@0: 
cannam@0:     /**
cannam@0:      * Get the program settings available in this plugin.
cannam@0:      * The programs must have unique names.
cannam@0:      */
cannam@0:     virtual ProgramList getPrograms() const { return ProgramList(); }
cannam@0: 
cannam@0:     /**
cannam@0:      * Get the current program.
cannam@0:      */
cannam@0:     virtual std::string getCurrentProgram() const { return ""; }
cannam@0: 
cannam@0:     /**
cannam@0:      * Select a program.  (If the given program name is not one of the
cannam@0:      * available programs, do nothing.)
cannam@0:      */
cannam@0:     virtual void selectProgram(std::string) { }
cannam@0: };
cannam@0: 
cannam@0: }
cannam@0: 
cannam@0: #endif