include/ladspa_manager.h

   1 /*
   2  * ladspa_manager.h - declaration of class ladspaManager
   3  *                    a class to manage loading and instantiation
   4  *                    of ladspa plugins
   5  *
   6  * Copyright (c) 2005-2008 Danny McRae <khjklujn@netscape.net>
   7  *
   8  * This file is part of Linux MultiMedia Studio - http://lmms.sourceforge.net
   9  *
  10  * This program is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU General Public
  12  * License as published by the Free Software Foundation; either
  13  * version 2 of the License, or (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public
  21  * License along with this program (see COPYING); if not, write to the
  22  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  23  * Boston, MA 02110-1301 USA.
  24  *
  25  */
  26
  27
  28 #ifndef _LADSPA_MANAGER_H
  29 #define _LADSPA_MANAGER_H
  30
  31 #include <ladspa.h>
  32
  33 #include <QtCore/QMap>
  34 #include <QtCore/QPair>
  35 #include <QtCore/QString>
  36 #include <QtCore/QStringList>
  37
  38
  39 #include "export.h"
  40 #include "lmms_basics.h"
  41
  42
  43 const float NOHINT = -99342.2243f;
  44
  45 typedef QPair<QString, QString> ladspa_key_t;
  46 typedef QPair<QString, ladspa_key_t> sortable_plugin_t;
  47 typedef QList<sortable_plugin_t> l_sortable_plugin_t;
  48 typedef QList<ladspa_key_t> l_ladspa_key_t;
  49
  50 /* ladspaManager provides a database of LADSPA plug-ins.  Upon instantiation,
  51 it loads all of the plug-ins found in the LADSPA_PATH environmental variable
  52 and stores their access descriptors according in a dictionary keyed on
  53 the filename the plug-in was loaded from and the label of the plug-in.
  54
  55 The can be retrieved by using ladspa_key_t.  For example, to get the
  56 "Phase Modulated Voice" plug-in from the cmt library, you would perform the
  57 calls using:
  58
  59         ladspa_key_t key( "cmt.so", "phasemod" )
  60
  61 as the plug-in key. */
  62
  63 enum ladspaPluginType
  64 {
  65         SOURCE,
  66         TRANSFER,
  67         VALID,
  68         INVALID,
  69         SINK,
  70         OTHER
  71 };
  72
  73 typedef struct ladspaManagerStorage
  74 {
  75         LADSPA_Descriptor_Function descriptorFunction;
  76         Uint32 index;
  77         ladspaPluginType type;
  78         Uint16 inputChannels;
  79         Uint16 outputChannels;
  80 } ladspaManagerDescription;
  81
  82
  83 class EXPORT ladspaManager
  84 {
  85 public:
  86
  87         ladspaManager();
  88         virtual ~ladspaManager();
  89
  90         l_sortable_plugin_t getSortedPlugins();
  91         ladspaManagerDescription * getDescription( const ladspa_key_t &
  92                                                                 _plugin );
  93
  94         /* This identifier can be used as a unique, case-sensitive
  95         identifier for the plugin type within the plugin file. Plugin
  96         types should be identified by file and label rather than by index
  97         or plugin name, which may be changed in new plugin
  98         versions. Labels must not contain white-space characters. */
  99         QString  getLabel( const ladspa_key_t & _plugin );
 100
 101         /* Indicates that the plugin has a real-time dependency
 102         (e.g. listens to a MIDI device) and so its output must not
 103         be cached or subject to significant latency. */
 104         bool  hasRealTimeDependency( const ladspa_key_t & _plugin );
 105
 106         /* Indicates that the plugin may cease to work correctly if the
 107         host elects to use the same data location for both input and output
 108         (see connectPort). */
 109         bool  isInplaceBroken( const ladspa_key_t & _plugin );
 110
 111         /* Indicates that the plugin is capable of running not only in a
 112         conventional host but also in a 'hard real-time' environment. */
 113         bool  isRealTimeCapable( const ladspa_key_t & _plugin );
 114
 115         /* Returns the name of the plug-in */
 116         QString  getName( const ladspa_key_t & _plugin );
 117
 118         /* Returns the the plug-in's author */
 119         QString  getMaker( const ladspa_key_t & _plugin );
 120
 121         /* Returns the copyright for the plug-in */
 122         QString  getCopyright( const ladspa_key_t & _plugin );
 123
 124         /* This indicates the number of ports (input AND output) present on
 125         the plugin. */
 126         Uint32  getPortCount( const ladspa_key_t & _plugin );
 127
 128
 129         /* Indicates that the port is an input. */
 130         bool  isPortInput( const ladspa_key_t & _plugin, Uint32 _port );
 131
 132         /* Indicates that the port is an output. */
 133         bool  isPortOutput( const ladspa_key_t & _plugin, Uint32 _port );
 134
 135         /* Indicates that the port is an audio. */
 136         bool  isPortAudio( const ladspa_key_t & _plugin, Uint32 _port );
 137
 138         /* Indicates that the port is an control. */
 139         bool  isPortControl( const ladspa_key_t & _plugin, Uint32 _port );
 140
 141         /* Indicates that any bounds specified should be interpreted as
 142         multiples of the sample rate. For instance, a frequency range from
 143         0Hz to the Nyquist frequency (half the sample rate) could be requested
 144         by this hint in conjunction with LowerBound = 0 and UpperBound = 0.5.
 145         Hosts that support bounds at all must support this hint to retain
 146         meaning. */
 147         bool  areHintsSampleRateDependent( const ladspa_key_t & _plugin,
 148                                                                 Uint32 _port );
 149
 150         /* Returns the lower boundary value for the given port. If
 151         no lower bound is provided by the plug-in, returns -999e-99. When
 152         areHintsSampleRateDependent() is also true then this value should be
 153         multiplied by the relevant sample rate. */
 154         float  getLowerBound( const ladspa_key_t & _plugin, Uint32 _port );
 155
 156         /* Returns the upper boundary value for the given port. If
 157         no upper bound is provided by the plug-in, returns -999e-99. When
 158         areHintsSampleRateDependent() is also true then this value should be
 159         multiplied by the relevant sample rate. */
 160         float  getUpperBound( const ladspa_key_t & _plugin, Uint32 _port );
 161
 162         /* Indicates whether the given port should be considered 0 or 1
 163         boolean switch. */
 164         bool  isPortToggled( const ladspa_key_t & _plugin, Uint32 _port );
 165
 166         /* Retrieves any default setting hints offered by the plug-in for
 167         the given port. */
 168         float  getDefaultSetting( const ladspa_key_t & _plugin, Uint32 _port );
 169
 170         /* Indicates that it is likely that the user will find it more
 171         intuitive to view values using a logarithmic scale. This is
 172         particularly useful for frequencies and gains. */
 173         bool  isLogarithmic( const ladspa_key_t & _plugin, Uint32 _port );
 174
 175         /* Indicates that a user interface would probably wish to provide a
 176         stepped control taking only integer values. Any bounds set should be
 177         slightly wider than the actual integer range required to avoid floating
 178         point rounding errors. For instance, the integer set {0,1,2,3} might
 179         be described as [-0.1, 3.1]. */
 180         bool  isInteger( const ladspa_key_t & _plugin, Uint32 _port );
 181
 182         /* Returns the name of the port. */
 183         QString  getPortName( const ladspa_key_t & _plugin, Uint32 _port );
 184
 185
 186         /* This may be used by the plugin developer to pass any custom
 187         implementation data into an instantiate call. It must not be used
 188         or interpreted by the host. It is expected that most plugin
 189         writers will not use this facility as LADSPA_Handle should be
 190         used to hold instance data. */
 191         const void *  getImplementationData(
 192                                                 const ladspa_key_t & _plugin );
 193
 194
 195         /* Returns a pointer to the plug-in's descriptor from which control
 196         of the plug-in is accessible */
 197         const LADSPA_Descriptor *  getDescriptor(
 198                                                 const ladspa_key_t & _plugin );
 199
 200
 201         /* The following methods are convenience functions for use during
 202         development.  A real instrument should use the getDescriptor()
 203         method and implement the plug-in manipulations internally to avoid
 204         the overhead associated with QMap lookups. */
 205
 206
 207         /* Returns a handle to an instantiation of the given plug-in. */
 208         LADSPA_Handle  instantiate( const ladspa_key_t & _plugin,
 209                                                 Uint32 _sample_rate );
 210
 211         /* This method calls a function pointer that connects a port on an
 212         instantiated plugin to a memory location at which a block of data
 213         for the port will be read/written. The data location is expected
 214         to be an array of LADSPA_Data for audio ports or a single
 215         LADSPA_Data value for control ports. Memory issues will be
 216         managed by the host. The plugin must read/write the data at these
 217         locations every time run() or runAdding() is called and the data
 218         present at the time of this connection call should not be
 219         considered meaningful.
 220
 221         connectPort() may be called more than once for a plugin instance
 222         to allow the host to change the buffers that the plugin is
 223         reading or writing. These calls may be made before or after
 224         activate() or deactivate() calls.
 225
 226         connectPort() must be called at least once for each port before
 227         run() or runAdding() is called. */
 228         bool  connectPort( const ladspa_key_t & _plugin,
 229                                         LADSPA_Handle _instance,
 230                                         Uint32 _port,
 231                                         LADSPA_Data * _data_location );
 232
 233         /* This method calls a function pointer that initialises a plugin
 234         instance and activates it for use. This is separated from
 235         instantiate() to aid real-time support and so that hosts can
 236         reinitialise a plugin instance by calling deactivate() and then
 237         activate(). In this case the plugin instance must reset all state
 238         information dependent on the history of the plugin instance
 239         except for any data locations provided by connectPort() and any
 240         gain set by setRunAddingGain(). If there is nothing for
 241         activate() to do then the plugin writer may provide a NULL rather
 242         than an empty function.
 243
 244         When present, hosts must call this function once before run() (or
 245         runAdding()) is called for the first time. This call should be
 246         made as close to the run() call as possible and indicates to
 247         real-time plugins that they are now live. Plugins should not rely
 248         on a prompt call to run() after activate(). activate() may not be
 249         called again unless deactivate() is called first. Note that
 250         connectPort() may be called before or after a call to
 251         activate(). */
 252         bool  activate( const ladspa_key_t & _plugin,
 253                                                 LADSPA_Handle _instance );
 254
 255         /* This method calls a function pointer that runs an instance of a
 256         plugin for a block. Two parameters are required: the first is a
 257         handle to the particular instance to be run and the second
 258         indicates the block size (in samples) for which the plugin
 259         instance may run.
 260
 261         Note that if an activate() function exists then it must be called
 262         before run() or run_adding(). If deactivate() is called for a
 263         plugin instance then the plugin instance may not be reused until
 264         activate() has been called again. */
 265         bool  run( const ladspa_key_t & _plugin,
 266                                         LADSPA_Handle _instance,
 267                                         Uint32 _sample_count );
 268
 269         /* This method calls a function pointer that runs an instance of a
 270         plugin for a block. This has identical behaviour to run() except
 271         in the way data is output from the plugin. When run() is used,
 272         values are written directly to the memory areas associated with
 273         the output ports. However when runAdding() is called, values
 274         must be added to the values already present in the memory
 275         areas. Furthermore, output values written must be scaled by the
 276         current gain set by setRunAddingGain() (see below) before
 277         addition.
 278
 279         runAdding() is optional. When it is not provided by a plugin,
 280         this function pointer must be set to NULL. When it is provided,
 281         the function setRunAddingGain() must be provided also. */
 282         bool  runAdding( const ladspa_key_t & _plugin,
 283                                                 LADSPA_Handle _instance,
 284                                                 Uint32 _sample_count );
 285
 286         /* This method calls a function pointer that sets the output gain for
 287         use when runAdding() is called (see above). If this function is
 288         never called the gain is assumed to default to 1. Gain
 289         information should be retained when activate() or deactivate()
 290         are called.
 291
 292         This function should be provided by the plugin if and only if the
 293         runAdding() function is provided. When it is absent this
 294         function pointer must be set to NULL. */
 295         bool  setRunAddingGain( const ladspa_key_t & _plugin,
 296                                                 LADSPA_Handle _instance,
 297                                                 LADSPA_Data _gain );
 298
 299         /* This is the counterpart to activate() (see above). If there is
 300         nothing for deactivate() to do then the plugin writer may provide
 301         a NULL rather than an empty function.
 302
 303         Hosts must deactivate all activated units after they have been
 304         run() (or run_adding()) for the last time. This call should be
 305         made as close to the last run() call as possible and indicates to
 306         real-time plugins that they are no longer live. Plugins should
 307         not rely on prompt deactivation. Note that connect_port() may be
 308         called before or after a call to deactivate().
 309
 310         Deactivation is not similar to pausing as the plugin instance
 311         will be reinitialised when activate() is called to reuse it. */
 312         bool  deactivate( const ladspa_key_t & _plugin,
 313                                                 LADSPA_Handle _instance );
 314
 315         /* Once an instance of a plugin has been finished with it can be
 316         deleted using the following function. The instance handle passed
 317         ceases to be valid after this call.
 318
 319         If activate() was called for a plugin instance then a
 320         corresponding call to deactivate() must be made before cleanup()
 321         is called. */
 322         bool  cleanup( const ladspa_key_t & _plugin,
 323                                                 LADSPA_Handle _instance );
 324
 325 private:
 326         void  addPlugins( LADSPA_Descriptor_Function _descriptor_func,
 327                                                 const QString & _file );
 328         Uint16  getPluginInputs( const LADSPA_Descriptor * _descriptor );
 329         Uint16  getPluginOutputs( const LADSPA_Descriptor * _descriptor );
 330
 331         typedef QMap<ladspa_key_t, ladspaManagerDescription *>
 332                                                 ladspaManagerMapType;
 333         ladspaManagerMapType m_ladspaManagerMap;
 334         l_sortable_plugin_t m_sortedPlugins;
 335
 336 } ;
 337
 338 #endif