Chris@50: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
Chris@50: 
Chris@50: /*
Chris@50:     A waveform viewer and audio annotation editor.
Chris@50:     Chris Cannam, Queen Mary University of London, 2005-2006
Chris@50:     
Chris@50:     This is experimental software.  Not for distribution.
Chris@50: */
Chris@50: 
Chris@50: #ifndef _PLUGIN_INSTANCE_H_
Chris@50: #define _PLUGIN_INSTANCE_H_
Chris@50: 
Chris@50: #include <string>
Chris@50: #include <vector>
Chris@50: 
Chris@50: /**
Chris@50:  * A base class for plugins with optional configurable parameters,
Chris@50:  * programs, etc.
Chris@50:  *
Chris@50:  * This does not provide the necessary interfaces to instantiate or
Chris@50:  * run a plugin -- that depends on the plugin subclass, as different
Chris@50:  * plugin types may have quite different operating structures.  This
Chris@50:  * class just specifies the necessary interface to show editable
Chris@50:  * controls for the plugin to the user.
Chris@50:  */
Chris@50: 
Chris@50: class PluginInstance
Chris@50: {
Chris@50: public:
Chris@50:     /**
Chris@50:      * Get the computer-usable name of the plugin.  This should be
Chris@50:      * reasonably short and contain no whitespace or punctuation
Chris@50:      * characters.  It may be shown to the user, but it won't be the
Chris@50:      * main method for a user to identify a plugin (that will be the
Chris@50:      * description, below).
Chris@50:      */
Chris@50:     virtual std::string getName() const = 0;
Chris@50: 
Chris@50:     /**
Chris@50:      * Get a human-readable description of the plugin.  This should be
Chris@50:      * self-contained, as it may be shown to the user in isolation
Chris@50:      * without also showing the plugin's "name".
Chris@50:      */
Chris@50:     virtual std::string getDescription() const = 0;
Chris@50:     
Chris@50:     /**
Chris@50:      * Get the name of the author or vendor of the plugin in
Chris@50:      * human-readable form.
Chris@50:      */
Chris@50:     virtual std::string getMaker() const = 0;
Chris@50: 
Chris@50:     /**
Chris@50:      * Get the version number of the plugin.
Chris@50:      */
Chris@50:     virtual int getPluginVersion() const = 0;
Chris@50: 
Chris@50:     /**
Chris@50:      * Get the copyright statement or licensing summary of the plugin.
Chris@50:      */
Chris@50:     virtual std::string getCopyright() const = 0;
Chris@50: 
Chris@50: 
Chris@50:     struct ParameterDescriptor
Chris@50:     {
Chris@50: 	/**
Chris@50: 	 * The name of the parameter, in computer-usable form.  Should
Chris@50: 	 * be reasonably short and without whitespace or punctuation.
Chris@50: 	 */
Chris@50: 	std::string name;
Chris@50: 
Chris@50: 	/**
Chris@50: 	 * The human-readable name of the parameter.
Chris@50: 	 */
Chris@50: 	std::string description;
Chris@50: 
Chris@50: 	/**
Chris@50: 	 * The unit of the parameter, in human-readable form.
Chris@50: 	 */
Chris@50: 	std::string unit;
Chris@50: 
Chris@50: 	/**
Chris@50: 	 * The minimum value of the parameter.
Chris@50: 	 */
Chris@50: 	float minValue;
Chris@50: 
Chris@50: 	/**
Chris@50: 	 * The maximum value of the parameter.
Chris@50: 	 */
Chris@50: 	float maxValue;
Chris@50: 
Chris@50: 	/**
Chris@50: 	 * The default value of the parameter.
Chris@50: 	 */
Chris@50: 	float defaultValue;
Chris@50: 	
Chris@50: 	/**
Chris@50: 	 * True if the parameter values are quantized to a particular
Chris@50: 	 * resolution.
Chris@50: 	 */
Chris@50: 	bool isQuantized;
Chris@50: 
Chris@50: 	/**
Chris@50: 	 * Quantization resolution of the parameter values (e.g. 1.0
Chris@50: 	 * if they are all integers).  Undefined if isQuantized is
Chris@50: 	 * false.
Chris@50: 	 */
Chris@50: 	float quantizeStep;
Chris@50:     };
Chris@50: 
Chris@50:     typedef std::vector<ParameterDescriptor> ParameterList;
Chris@50: 
Chris@50:     /**
Chris@50:      * Get the controllable parameters of this plugin.
Chris@50:      */
Chris@50:     virtual ParameterList getParameterDescriptors() const {
Chris@50: 	return ParameterList();
Chris@50:     }
Chris@50: 
Chris@50:     /**
Chris@50:      * Get the value of a named parameter.  The argument is the name
Chris@50:      * field from that parameter's descriptor.
Chris@50:      */
Chris@50:     virtual float getParameter(std::string) const { return 0.0; }
Chris@50: 
Chris@50:     /**
Chris@50:      * Set a named parameter.  The first argument is the name field
Chris@50:      * from that parameter's descriptor.
Chris@50:      */
Chris@50:     virtual void setParameter(std::string, float) { } 
Chris@50: 
Chris@50:     
Chris@50:     typedef std::vector<std::string> ProgramList;
Chris@50: 
Chris@50:     /**
Chris@50:      * Get the program settings available in this plugin.
Chris@50:      * The programs must have unique names.
Chris@50:      */
Chris@50:     virtual ProgramList getPrograms() const { return ProgramList(); }
Chris@50: 
Chris@50:     /**
Chris@50:      * Get the current program.
Chris@50:      */
Chris@50:     virtual std::string getCurrentProgram() const { return ""; }
Chris@50: 
Chris@50:     /**
Chris@50:      * Select a program.  (If the given program name is not one of the
Chris@50:      * available programs, do nothing.)
Chris@50:      */
Chris@50:     virtual void selectProgram(std::string) { }
Chris@50: };
Chris@50: 
Chris@50: #endif