1 /* 2 * LadspaManager.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 LMMS - https://lmms.io 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_t index; 77 ladspaPluginType type; 78 uint16_t inputChannels; 79 uint16_t 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_t 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_t _port ); 131 132 /* Indicates that the port is an output. */ 133 bool isPortOutput( const ladspa_key_t & _plugin, uint32_t _port ); 134 135 /* Indicates that the port is an audio. */ 136 bool isPortAudio( const ladspa_key_t & _plugin, uint32_t _port ); 137 138 /* Indicates that the port is an control. */ 139 bool isPortControl( const ladspa_key_t & _plugin, uint32_t _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_t _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_t _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_t _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_t _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_t _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_t _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_t _port ); 181 182 /* Returns the name of the port. */ 183 QString getPortName( const ladspa_key_t & _plugin, uint32_t _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_t _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_t _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_t _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_t _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_t getPluginInputs( const LADSPA_Descriptor * _descriptor ); 329 uint16_t 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 339