← Back to branch summary

~ubuntu-branches/ubuntu/hardy/lmms/hardy

« back to all changes in this revision

Viewing changes to plugins/ladspa_base/ladspa_manager.h

  • Committer: Bazaar Package Importer
  • Author(s): Tobias Doerffel
  • Date: 2007-09-17 15:00:24 UTC
  • mfrom: (1.1.4 upstream)
  • Revision ID: james.westby@ubuntu.com-20070917150024-mo0zk4ks81jawqii
Tags: 0.3.0-1ubuntu1
https://launchpad.net/bugs/139759
https://launchpad.net/bugs/90806
https://launchpad.net/bugs/102639
https://launchpad.net/bugs/113447
https://launchpad.net/bugs/121172
https://launchpad.net/bugs/124890
* Resynchronized with Debian (LP: #139759, LP: #90806, LP: #102639,
  LP: #113447, LP: #121172, LP: #124890)
* reverted changes from 0.2.1-1.1ubuntu1 as upstream merged/included them

Show diffs side-by-side

added added

removed removed

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