annotate plugin/api/ladspa.h @ 661:a4faa1840384

* If a FileSource URL won't convert at all in strict mode, try again in tolerant mode (necessary for e.g. filenames with square brackets in them)
author Chris Cannam
date Tue, 19 Oct 2010 21:47:55 +0100 (2010-10-19)
parents da6937383da8
children
rev   line source
Chris@0 1 /* ladspa.h
Chris@0 2
Chris@0 3 Linux Audio Developer's Simple Plugin API Version 1.1[LGPL].
Chris@0 4 Copyright (C) 2000-2002 Richard W.E. Furse, Paul Barton-Davis,
Chris@0 5 Stefan Westerfeld.
Chris@0 6
Chris@0 7 This library is free software; you can redistribute it and/or
Chris@0 8 modify it under the terms of the GNU Lesser General Public License
Chris@0 9 as published by the Free Software Foundation; either version 2.1 of
Chris@0 10 the License, or (at your option) any later version.
Chris@0 11
Chris@0 12 This library is distributed in the hope that it will be useful, but
Chris@0 13 WITHOUT ANY WARRANTY; without even the implied warranty of
Chris@0 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Chris@0 15 Lesser General Public License for more details.
Chris@0 16
Chris@0 17 You should have received a copy of the GNU Lesser General Public
Chris@0 18 License along with this library; if not, write to the Free Software
Chris@0 19 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
Chris@0 20 USA. */
Chris@0 21
Chris@0 22 #ifndef LADSPA_INCLUDED
Chris@0 23 #define LADSPA_INCLUDED
Chris@0 24
Chris@0 25 #define LADSPA_VERSION "1.1"
Chris@0 26 #define LADSPA_VERSION_MAJOR 1
Chris@0 27 #define LADSPA_VERSION_MINOR 1
Chris@0 28
Chris@0 29 #ifdef __cplusplus
Chris@0 30 extern "C" {
Chris@0 31 #endif
Chris@0 32
Chris@0 33 /*****************************************************************************/
Chris@0 34
Chris@0 35 /* Overview:
Chris@0 36
Chris@0 37 There is a large number of synthesis packages in use or development
Chris@0 38 on the Linux platform at this time. This API (`The Linux Audio
Chris@0 39 Developer's Simple Plugin API') attempts to give programmers the
Chris@0 40 ability to write simple `plugin' audio processors in C/C++ and link
Chris@0 41 them dynamically (`plug') into a range of these packages (`hosts').
Chris@0 42 It should be possible for any host and any plugin to communicate
Chris@0 43 completely through this interface.
Chris@0 44
Chris@0 45 This API is deliberately short and simple. To achieve compatibility
Chris@0 46 with a range of promising Linux sound synthesis packages it
Chris@0 47 attempts to find the `greatest common divisor' in their logical
Chris@0 48 behaviour. Having said this, certain limiting decisions are
Chris@0 49 implicit, notably the use of a fixed type (LADSPA_Data) for all
Chris@0 50 data transfer and absence of a parameterised `initialisation'
Chris@0 51 phase. See below for the LADSPA_Data typedef.
Chris@0 52
Chris@0 53 Plugins are expected to distinguish between control and audio
Chris@0 54 data. Plugins have `ports' that are inputs or outputs for audio or
Chris@0 55 control data and each plugin is `run' for a `block' corresponding
Chris@0 56 to a short time interval measured in samples. Audio data is
Chris@0 57 communicated using arrays of LADSPA_Data, allowing a block of audio
Chris@0 58 to be processed by the plugin in a single pass. Control data is
Chris@0 59 communicated using single LADSPA_Data values. Control data has a
Chris@0 60 single value at the start of a call to the `run()' or `run_adding()'
Chris@0 61 function, and may be considered to remain this value for its
Chris@0 62 duration. The plugin may assume that all its input and output ports
Chris@0 63 have been connected to the relevant data location (see the
Chris@0 64 `connect_port()' function below) before it is asked to run.
Chris@0 65
Chris@0 66 Plugins will reside in shared object files suitable for dynamic
Chris@0 67 linking by dlopen() and family. The file will provide a number of
Chris@0 68 `plugin types' that can be used to instantiate actual plugins
Chris@0 69 (sometimes known as `plugin instances') that can be connected
Chris@0 70 together to perform tasks.
Chris@0 71
Chris@0 72 This API contains very limited error-handling. */
Chris@0 73
Chris@0 74 /*****************************************************************************/
Chris@0 75
Chris@0 76 /* Fundamental data type passed in and out of plugin. This data type
Chris@0 77 is used to communicate audio samples and control values. It is
Chris@0 78 assumed that the plugin will work sensibly given any numeric input
Chris@0 79 value although it may have a preferred range (see hints below).
Chris@0 80
Chris@0 81 For audio it is generally assumed that 1.0f is the `0dB' reference
Chris@0 82 amplitude and is a `normal' signal level. */
Chris@0 83
Chris@0 84 typedef float LADSPA_Data;
Chris@0 85
Chris@0 86 /*****************************************************************************/
Chris@0 87
Chris@0 88 /* Special Plugin Properties:
Chris@0 89
Chris@0 90 Optional features of the plugin type are encapsulated in the
Chris@0 91 LADSPA_Properties type. This is assembled by ORing individual
Chris@0 92 properties together. */
Chris@0 93
Chris@0 94 typedef int LADSPA_Properties;
Chris@0 95
Chris@0 96 /* Property LADSPA_PROPERTY_REALTIME indicates that the plugin has a
Chris@0 97 real-time dependency (e.g. listens to a MIDI device) and so its
Chris@0 98 output must not be cached or subject to significant latency. */
Chris@0 99 #define LADSPA_PROPERTY_REALTIME 0x1
Chris@0 100
Chris@0 101 /* Property LADSPA_PROPERTY_INPLACE_BROKEN indicates that the plugin
Chris@0 102 may cease to work correctly if the host elects to use the same data
Chris@0 103 location for both input and output (see connect_port()). This
Chris@0 104 should be avoided as enabling this flag makes it impossible for
Chris@0 105 hosts to use the plugin to process audio `in-place.' */
Chris@0 106 #define LADSPA_PROPERTY_INPLACE_BROKEN 0x2
Chris@0 107
Chris@0 108 /* Property LADSPA_PROPERTY_HARD_RT_CAPABLE indicates that the plugin
Chris@0 109 is capable of running not only in a conventional host but also in a
Chris@0 110 `hard real-time' environment. To qualify for this the plugin must
Chris@0 111 satisfy all of the following:
Chris@0 112
Chris@0 113 (1) The plugin must not use malloc(), free() or other heap memory
Chris@0 114 management within its run() or run_adding() functions. All new
Chris@0 115 memory used in run() must be managed via the stack. These
Chris@0 116 restrictions only apply to the run() function.
Chris@0 117
Chris@0 118 (2) The plugin will not attempt to make use of any library
Chris@0 119 functions with the exceptions of functions in the ANSI standard C
Chris@0 120 and C maths libraries, which the host is expected to provide.
Chris@0 121
Chris@0 122 (3) The plugin will not access files, devices, pipes, sockets, IPC
Chris@0 123 or any other mechanism that might result in process or thread
Chris@0 124 blocking.
Chris@0 125
Chris@0 126 (4) The plugin will take an amount of time to execute a run() or
Chris@0 127 run_adding() call approximately of form (A+B*SampleCount) where A
Chris@0 128 and B depend on the machine and host in use. This amount of time
Chris@0 129 may not depend on input signals or plugin state. The host is left
Chris@0 130 the responsibility to perform timings to estimate upper bounds for
Chris@0 131 A and B. */
Chris@0 132 #define LADSPA_PROPERTY_HARD_RT_CAPABLE 0x4
Chris@0 133
Chris@0 134 #define LADSPA_IS_REALTIME(x) ((x) & LADSPA_PROPERTY_REALTIME)
Chris@0 135 #define LADSPA_IS_INPLACE_BROKEN(x) ((x) & LADSPA_PROPERTY_INPLACE_BROKEN)
Chris@0 136 #define LADSPA_IS_HARD_RT_CAPABLE(x) ((x) & LADSPA_PROPERTY_HARD_RT_CAPABLE)
Chris@0 137
Chris@0 138 /*****************************************************************************/
Chris@0 139
Chris@0 140 /* Plugin Ports:
Chris@0 141
Chris@0 142 Plugins have `ports' that are inputs or outputs for audio or
Chris@0 143 data. Ports can communicate arrays of LADSPA_Data (for audio
Chris@0 144 inputs/outputs) or single LADSPA_Data values (for control
Chris@0 145 input/outputs). This information is encapsulated in the
Chris@0 146 LADSPA_PortDescriptor type which is assembled by ORing individual
Chris@0 147 properties together.
Chris@0 148
Chris@0 149 Note that a port must be an input or an output port but not both
Chris@0 150 and that a port must be a control or audio port but not both. */
Chris@0 151
Chris@0 152 typedef int LADSPA_PortDescriptor;
Chris@0 153
Chris@0 154 /* Property LADSPA_PORT_INPUT indicates that the port is an input. */
Chris@0 155 #define LADSPA_PORT_INPUT 0x1
Chris@0 156
Chris@0 157 /* Property LADSPA_PORT_OUTPUT indicates that the port is an output. */
Chris@0 158 #define LADSPA_PORT_OUTPUT 0x2
Chris@0 159
Chris@0 160 /* Property LADSPA_PORT_CONTROL indicates that the port is a control
Chris@0 161 port. */
Chris@0 162 #define LADSPA_PORT_CONTROL 0x4
Chris@0 163
Chris@0 164 /* Property LADSPA_PORT_AUDIO indicates that the port is a audio
Chris@0 165 port. */
Chris@0 166 #define LADSPA_PORT_AUDIO 0x8
Chris@0 167
Chris@0 168 #define LADSPA_IS_PORT_INPUT(x) ((x) & LADSPA_PORT_INPUT)
Chris@0 169 #define LADSPA_IS_PORT_OUTPUT(x) ((x) & LADSPA_PORT_OUTPUT)
Chris@0 170 #define LADSPA_IS_PORT_CONTROL(x) ((x) & LADSPA_PORT_CONTROL)
Chris@0 171 #define LADSPA_IS_PORT_AUDIO(x) ((x) & LADSPA_PORT_AUDIO)
Chris@0 172
Chris@0 173 /*****************************************************************************/
Chris@0 174
Chris@0 175 /* Plugin Port Range Hints:
Chris@0 176
Chris@0 177 The host may wish to provide a representation of data entering or
Chris@0 178 leaving a plugin (e.g. to generate a GUI automatically). To make
Chris@0 179 this more meaningful, the plugin should provide `hints' to the host
Chris@0 180 describing the usual values taken by the data.
Chris@0 181
Chris@0 182 Note that these are only hints. The host may ignore them and the
Chris@0 183 plugin must not assume that data supplied to it is meaningful. If
Chris@0 184 the plugin receives invalid input data it is expected to continue
Chris@0 185 to run without failure and, where possible, produce a sensible
Chris@0 186 output (e.g. a high-pass filter given a negative cutoff frequency
Chris@0 187 might switch to an all-pass mode).
Chris@0 188
Chris@0 189 Hints are meaningful for all input and output ports but hints for
Chris@0 190 input control ports are expected to be particularly useful.
Chris@0 191
Chris@0 192 More hint information is encapsulated in the
Chris@0 193 LADSPA_PortRangeHintDescriptor type which is assembled by ORing
Chris@0 194 individual hint types together. Hints may require further
Chris@0 195 LowerBound and UpperBound information.
Chris@0 196
Chris@0 197 All the hint information for a particular port is aggregated in the
Chris@0 198 LADSPA_PortRangeHint structure. */
Chris@0 199
Chris@0 200 typedef int LADSPA_PortRangeHintDescriptor;
Chris@0 201
Chris@0 202 /* Hint LADSPA_HINT_BOUNDED_BELOW indicates that the LowerBound field
Chris@0 203 of the LADSPA_PortRangeHint should be considered meaningful. The
Chris@0 204 value in this field should be considered the (inclusive) lower
Chris@0 205 bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also
Chris@0 206 specified then the value of LowerBound should be multiplied by the
Chris@0 207 sample rate. */
Chris@0 208 #define LADSPA_HINT_BOUNDED_BELOW 0x1
Chris@0 209
Chris@0 210 /* Hint LADSPA_HINT_BOUNDED_ABOVE indicates that the UpperBound field
Chris@0 211 of the LADSPA_PortRangeHint should be considered meaningful. The
Chris@0 212 value in this field should be considered the (inclusive) upper
Chris@0 213 bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also
Chris@0 214 specified then the value of UpperBound should be multiplied by the
Chris@0 215 sample rate. */
Chris@0 216 #define LADSPA_HINT_BOUNDED_ABOVE 0x2
Chris@0 217
Chris@0 218 /* Hint LADSPA_HINT_TOGGLED indicates that the data item should be
Chris@0 219 considered a Boolean toggle. Data less than or equal to zero should
Chris@0 220 be considered `off' or `false,' and data above zero should be
Chris@0 221 considered `on' or `true.' LADSPA_HINT_TOGGLED may not be used in
Chris@0 222 conjunction with any other hint except LADSPA_HINT_DEFAULT_0 or
Chris@0 223 LADSPA_HINT_DEFAULT_1. */
Chris@0 224 #define LADSPA_HINT_TOGGLED 0x4
Chris@0 225
Chris@0 226 /* Hint LADSPA_HINT_SAMPLE_RATE indicates that any bounds specified
Chris@0 227 should be interpreted as multiples of the sample rate. For
Chris@0 228 instance, a frequency range from 0Hz to the Nyquist frequency (half
Chris@0 229 the sample rate) could be requested by this hint in conjunction
Chris@0 230 with LowerBound = 0 and UpperBound = 0.5. Hosts that support bounds
Chris@0 231 at all must support this hint to retain meaning. */
Chris@0 232 #define LADSPA_HINT_SAMPLE_RATE 0x8
Chris@0 233
Chris@0 234 /* Hint LADSPA_HINT_LOGARITHMIC indicates that it is likely that the
Chris@0 235 user will find it more intuitive to view values using a logarithmic
Chris@0 236 scale. This is particularly useful for frequencies and gains. */
Chris@0 237 #define LADSPA_HINT_LOGARITHMIC 0x10
Chris@0 238
Chris@0 239 /* Hint LADSPA_HINT_INTEGER indicates that a user interface would
Chris@0 240 probably wish to provide a stepped control taking only integer
Chris@0 241 values. Any bounds set should be slightly wider than the actual
Chris@0 242 integer range required to avoid floating point rounding errors. For
Chris@0 243 instance, the integer set {0,1,2,3} might be described as [-0.1,
Chris@0 244 3.1]. */
Chris@0 245 #define LADSPA_HINT_INTEGER 0x20
Chris@0 246
Chris@0 247 /* The various LADSPA_HINT_HAS_DEFAULT_* hints indicate a `normal'
Chris@0 248 value for the port that is sensible as a default. For instance,
Chris@0 249 this value is suitable for use as an initial value in a user
Chris@0 250 interface or as a value the host might assign to a control port
Chris@0 251 when the user has not provided one. Defaults are encoded using a
Chris@0 252 mask so only one default may be specified for a port. Some of the
Chris@0 253 hints make use of lower and upper bounds, in which case the
Chris@0 254 relevant bound or bounds must be available and
Chris@0 255 LADSPA_HINT_SAMPLE_RATE must be applied as usual. The resulting
Chris@0 256 default must be rounded if LADSPA_HINT_INTEGER is present. Default
Chris@0 257 values were introduced in LADSPA v1.1. */
Chris@0 258 #define LADSPA_HINT_DEFAULT_MASK 0x3C0
Chris@0 259
Chris@0 260 /* This default values indicates that no default is provided. */
Chris@0 261 #define LADSPA_HINT_DEFAULT_NONE 0x0
Chris@0 262
Chris@0 263 /* This default hint indicates that the suggested lower bound for the
Chris@0 264 port should be used. */
Chris@0 265 #define LADSPA_HINT_DEFAULT_MINIMUM 0x40
Chris@0 266
Chris@0 267 /* This default hint indicates that a low value between the suggested
Chris@0 268 lower and upper bounds should be chosen. For ports with
Chris@0 269 LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.75 +
Chris@0 270 log(upper) * 0.25). Otherwise, this should be (lower * 0.75 + upper
Chris@0 271 * 0.25). */
Chris@0 272 #define LADSPA_HINT_DEFAULT_LOW 0x80
Chris@0 273
Chris@0 274 /* This default hint indicates that a middle value between the
Chris@0 275 suggested lower and upper bounds should be chosen. For ports with
Chris@0 276 LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.5 +
Chris@0 277 log(upper) * 0.5). Otherwise, this should be (lower * 0.5 + upper *
Chris@0 278 0.5). */
Chris@0 279 #define LADSPA_HINT_DEFAULT_MIDDLE 0xC0
Chris@0 280
Chris@0 281 /* This default hint indicates that a high value between the suggested
Chris@0 282 lower and upper bounds should be chosen. For ports with
Chris@0 283 LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.25 +
Chris@0 284 log(upper) * 0.75). Otherwise, this should be (lower * 0.25 + upper
Chris@0 285 * 0.75). */
Chris@0 286 #define LADSPA_HINT_DEFAULT_HIGH 0x100
Chris@0 287
Chris@0 288 /* This default hint indicates that the suggested upper bound for the
Chris@0 289 port should be used. */
Chris@0 290 #define LADSPA_HINT_DEFAULT_MAXIMUM 0x140
Chris@0 291
Chris@0 292 /* This default hint indicates that the number 0 should be used. Note
Chris@0 293 that this default may be used in conjunction with
Chris@0 294 LADSPA_HINT_TOGGLED. */
Chris@0 295 #define LADSPA_HINT_DEFAULT_0 0x200
Chris@0 296
Chris@0 297 /* This default hint indicates that the number 1 should be used. Note
Chris@0 298 that this default may be used in conjunction with
Chris@0 299 LADSPA_HINT_TOGGLED. */
Chris@0 300 #define LADSPA_HINT_DEFAULT_1 0x240
Chris@0 301
Chris@0 302 /* This default hint indicates that the number 100 should be used. */
Chris@0 303 #define LADSPA_HINT_DEFAULT_100 0x280
Chris@0 304
Chris@0 305 /* This default hint indicates that the Hz frequency of `concert A'
Chris@0 306 should be used. This will be 440 unless the host uses an unusual
Chris@0 307 tuning convention, in which case it may be within a few Hz. */
Chris@0 308 #define LADSPA_HINT_DEFAULT_440 0x2C0
Chris@0 309
Chris@0 310 #define LADSPA_IS_HINT_BOUNDED_BELOW(x) ((x) & LADSPA_HINT_BOUNDED_BELOW)
Chris@0 311 #define LADSPA_IS_HINT_BOUNDED_ABOVE(x) ((x) & LADSPA_HINT_BOUNDED_ABOVE)
Chris@0 312 #define LADSPA_IS_HINT_TOGGLED(x) ((x) & LADSPA_HINT_TOGGLED)
Chris@0 313 #define LADSPA_IS_HINT_SAMPLE_RATE(x) ((x) & LADSPA_HINT_SAMPLE_RATE)
Chris@0 314 #define LADSPA_IS_HINT_LOGARITHMIC(x) ((x) & LADSPA_HINT_LOGARITHMIC)
Chris@0 315 #define LADSPA_IS_HINT_INTEGER(x) ((x) & LADSPA_HINT_INTEGER)
Chris@0 316
Chris@0 317 #define LADSPA_IS_HINT_HAS_DEFAULT(x) ((x) & LADSPA_HINT_DEFAULT_MASK)
Chris@0 318 #define LADSPA_IS_HINT_DEFAULT_MINIMUM(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \
Chris@0 319 == LADSPA_HINT_DEFAULT_MINIMUM)
Chris@0 320 #define LADSPA_IS_HINT_DEFAULT_LOW(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \
Chris@0 321 == LADSPA_HINT_DEFAULT_LOW)
Chris@0 322 #define LADSPA_IS_HINT_DEFAULT_MIDDLE(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \
Chris@0 323 == LADSPA_HINT_DEFAULT_MIDDLE)
Chris@0 324 #define LADSPA_IS_HINT_DEFAULT_HIGH(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \
Chris@0 325 == LADSPA_HINT_DEFAULT_HIGH)
Chris@0 326 #define LADSPA_IS_HINT_DEFAULT_MAXIMUM(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \
Chris@0 327 == LADSPA_HINT_DEFAULT_MAXIMUM)
Chris@0 328 #define LADSPA_IS_HINT_DEFAULT_0(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \
Chris@0 329 == LADSPA_HINT_DEFAULT_0)
Chris@0 330 #define LADSPA_IS_HINT_DEFAULT_1(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \
Chris@0 331 == LADSPA_HINT_DEFAULT_1)
Chris@0 332 #define LADSPA_IS_HINT_DEFAULT_100(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \
Chris@0 333 == LADSPA_HINT_DEFAULT_100)
Chris@0 334 #define LADSPA_IS_HINT_DEFAULT_440(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \
Chris@0 335 == LADSPA_HINT_DEFAULT_440)
Chris@0 336
Chris@0 337 typedef struct _LADSPA_PortRangeHint {
Chris@0 338
Chris@0 339 /* Hints about the port. */
Chris@0 340 LADSPA_PortRangeHintDescriptor HintDescriptor;
Chris@0 341
Chris@0 342 /* Meaningful when hint LADSPA_HINT_BOUNDED_BELOW is active. When
Chris@0 343 LADSPA_HINT_SAMPLE_RATE is also active then this value should be
Chris@0 344 multiplied by the relevant sample rate. */
Chris@0 345 LADSPA_Data LowerBound;
Chris@0 346
Chris@0 347 /* Meaningful when hint LADSPA_HINT_BOUNDED_ABOVE is active. When
Chris@0 348 LADSPA_HINT_SAMPLE_RATE is also active then this value should be
Chris@0 349 multiplied by the relevant sample rate. */
Chris@0 350 LADSPA_Data UpperBound;
Chris@0 351
Chris@0 352 } LADSPA_PortRangeHint;
Chris@0 353
Chris@0 354 /*****************************************************************************/
Chris@0 355
Chris@0 356 /* Plugin Handles:
Chris@0 357
Chris@0 358 This plugin handle indicates a particular instance of the plugin
Chris@0 359 concerned. It is valid to compare this to NULL (0 for C++) but
Chris@0 360 otherwise the host should not attempt to interpret it. The plugin
Chris@0 361 may use it to reference internal instance data. */
Chris@0 362
Chris@0 363 typedef void * LADSPA_Handle;
Chris@0 364
Chris@0 365 /*****************************************************************************/
Chris@0 366
Chris@0 367 /* Descriptor for a Type of Plugin:
Chris@0 368
Chris@0 369 This structure is used to describe a plugin type. It provides a
Chris@0 370 number of functions to examine the type, instantiate it, link it to
Chris@0 371 buffers and workspaces and to run it. */
Chris@0 372
Chris@0 373 typedef struct _LADSPA_Descriptor {
Chris@0 374
Chris@0 375 /* This numeric identifier indicates the plugin type
Chris@0 376 uniquely. Plugin programmers may reserve ranges of IDs from a
Chris@0 377 central body to avoid clashes. Hosts may assume that IDs are
Chris@0 378 below 0x1000000. */
Chris@0 379 unsigned long UniqueID;
Chris@0 380
Chris@0 381 /* This identifier can be used as a unique, case-sensitive
Chris@0 382 identifier for the plugin type within the plugin file. Plugin
Chris@0 383 types should be identified by file and label rather than by index
Chris@0 384 or plugin name, which may be changed in new plugin
Chris@0 385 versions. Labels must not contain white-space characters. */
Chris@0 386 const char * Label;
Chris@0 387
Chris@0 388 /* This indicates a number of properties of the plugin. */
Chris@0 389 LADSPA_Properties Properties;
Chris@0 390
Chris@0 391 /* This member points to the null-terminated name of the plugin
Chris@0 392 (e.g. "Sine Oscillator"). */
Chris@0 393 const char * Name;
Chris@0 394
Chris@0 395 /* This member points to the null-terminated string indicating the
Chris@0 396 maker of the plugin. This can be an empty string but not NULL. */
Chris@0 397 const char * Maker;
Chris@0 398
Chris@0 399 /* This member points to the null-terminated string indicating any
Chris@0 400 copyright applying to the plugin. If no Copyright applies the
Chris@0 401 string "None" should be used. */
Chris@0 402 const char * Copyright;
Chris@0 403
Chris@0 404 /* This indicates the number of ports (input AND output) present on
Chris@0 405 the plugin. */
Chris@0 406 unsigned long PortCount;
Chris@0 407
Chris@0 408 /* This member indicates an array of port descriptors. Valid indices
Chris@0 409 vary from 0 to PortCount-1. */
Chris@0 410 const LADSPA_PortDescriptor * PortDescriptors;
Chris@0 411
Chris@0 412 /* This member indicates an array of null-terminated strings
Chris@0 413 describing ports (e.g. "Frequency (Hz)"). Valid indices vary from
Chris@0 414 0 to PortCount-1. */
Chris@0 415 const char * const * PortNames;
Chris@0 416
Chris@0 417 /* This member indicates an array of range hints for each port (see
Chris@0 418 above). Valid indices vary from 0 to PortCount-1. */
Chris@0 419 const LADSPA_PortRangeHint * PortRangeHints;
Chris@0 420
Chris@0 421 /* This may be used by the plugin developer to pass any custom
Chris@0 422 implementation data into an instantiate call. It must not be used
Chris@0 423 or interpreted by the host. It is expected that most plugin
Chris@0 424 writers will not use this facility as LADSPA_Handle should be
Chris@0 425 used to hold instance data. */
Chris@0 426 void * ImplementationData;
Chris@0 427
Chris@0 428 /* This member is a function pointer that instantiates a plugin. A
Chris@0 429 handle is returned indicating the new plugin instance. The
Chris@0 430 instantiation function accepts a sample rate as a parameter. The
Chris@0 431 plugin descriptor from which this instantiate function was found
Chris@0 432 must also be passed. This function must return NULL if
Chris@0 433 instantiation fails.
Chris@0 434
Chris@0 435 Note that instance initialisation should generally occur in
Chris@0 436 activate() rather than here. */
Chris@0 437 LADSPA_Handle (*instantiate)(const struct _LADSPA_Descriptor * Descriptor,
Chris@0 438 unsigned long SampleRate);
Chris@0 439
Chris@0 440 /* This member is a function pointer that connects a port on an
Chris@0 441 instantiated plugin to a memory location at which a block of data
Chris@0 442 for the port will be read/written. The data location is expected
Chris@0 443 to be an array of LADSPA_Data for audio ports or a single
Chris@0 444 LADSPA_Data value for control ports. Memory issues will be
Chris@0 445 managed by the host. The plugin must read/write the data at these
Chris@0 446 locations every time run() or run_adding() is called and the data
Chris@0 447 present at the time of this connection call should not be
Chris@0 448 considered meaningful.
Chris@0 449
Chris@0 450 connect_port() may be called more than once for a plugin instance
Chris@0 451 to allow the host to change the buffers that the plugin is
Chris@0 452 reading or writing. These calls may be made before or after
Chris@0 453 activate() or deactivate() calls.
Chris@0 454
Chris@0 455 connect_port() must be called at least once for each port before
Chris@0 456 run() or run_adding() is called. When working with blocks of
Chris@0 457 LADSPA_Data the plugin should pay careful attention to the block
Chris@0 458 size passed to the run function as the block allocated may only
Chris@0 459 just be large enough to contain the block of samples.
Chris@0 460
Chris@0 461 Plugin writers should be aware that the host may elect to use the
Chris@0 462 same buffer for more than one port and even use the same buffer
Chris@0 463 for both input and output (see LADSPA_PROPERTY_INPLACE_BROKEN).
Chris@0 464 However, overlapped buffers or use of a single buffer for both
Chris@0 465 audio and control data may result in unexpected behaviour. */
Chris@0 466 void (*connect_port)(LADSPA_Handle Instance,
Chris@0 467 unsigned long Port,
Chris@0 468 LADSPA_Data * DataLocation);
Chris@0 469
Chris@0 470 /* This member is a function pointer that initialises a plugin
Chris@0 471 instance and activates it for use. This is separated from
Chris@0 472 instantiate() to aid real-time support and so that hosts can
Chris@0 473 reinitialise a plugin instance by calling deactivate() and then
Chris@0 474 activate(). In this case the plugin instance must reset all state
Chris@0 475 information dependent on the history of the plugin instance
Chris@0 476 except for any data locations provided by connect_port() and any
Chris@0 477 gain set by set_run_adding_gain(). If there is nothing for
Chris@0 478 activate() to do then the plugin writer may provide a NULL rather
Chris@0 479 than an empty function.
Chris@0 480
Chris@0 481 When present, hosts must call this function once before run() (or
Chris@0 482 run_adding()) is called for the first time. This call should be
Chris@0 483 made as close to the run() call as possible and indicates to
Chris@0 484 real-time plugins that they are now live. Plugins should not rely
Chris@0 485 on a prompt call to run() after activate(). activate() may not be
Chris@0 486 called again unless deactivate() is called first. Note that
Chris@0 487 connect_port() may be called before or after a call to
Chris@0 488 activate(). */
Chris@0 489 void (*activate)(LADSPA_Handle Instance);
Chris@0 490
Chris@0 491 /* This method is a function pointer that runs an instance of a
Chris@0 492 plugin for a block. Two parameters are required: the first is a
Chris@0 493 handle to the particular instance to be run and the second
Chris@0 494 indicates the block size (in samples) for which the plugin
Chris@0 495 instance may run.
Chris@0 496
Chris@0 497 Note that if an activate() function exists then it must be called
Chris@0 498 before run() or run_adding(). If deactivate() is called for a
Chris@0 499 plugin instance then the plugin instance may not be reused until
Chris@0 500 activate() has been called again.
Chris@0 501
Chris@0 502 If the plugin has the property LADSPA_PROPERTY_HARD_RT_CAPABLE
Chris@0 503 then there are various things that the plugin should not do
Chris@0 504 within the run() or run_adding() functions (see above). */
Chris@0 505 void (*run)(LADSPA_Handle Instance,
Chris@0 506 unsigned long SampleCount);
Chris@0 507
Chris@0 508 /* This method is a function pointer that runs an instance of a
Chris@0 509 plugin for a block. This has identical behaviour to run() except
Chris@0 510 in the way data is output from the plugin. When run() is used,
Chris@0 511 values are written directly to the memory areas associated with
Chris@0 512 the output ports. However when run_adding() is called, values
Chris@0 513 must be added to the values already present in the memory
Chris@0 514 areas. Furthermore, output values written must be scaled by the
Chris@0 515 current gain set by set_run_adding_gain() (see below) before
Chris@0 516 addition.
Chris@0 517
Chris@0 518 run_adding() is optional. When it is not provided by a plugin,
Chris@0 519 this function pointer must be set to NULL. When it is provided,
Chris@0 520 the function set_run_adding_gain() must be provided also. */
Chris@0 521 void (*run_adding)(LADSPA_Handle Instance,
Chris@0 522 unsigned long SampleCount);
Chris@0 523
Chris@0 524 /* This method is a function pointer that sets the output gain for
Chris@0 525 use when run_adding() is called (see above). If this function is
Chris@0 526 never called the gain is assumed to default to 1. Gain
Chris@0 527 information should be retained when activate() or deactivate()
Chris@0 528 are called.
Chris@0 529
Chris@0 530 This function should be provided by the plugin if and only if the
Chris@0 531 run_adding() function is provided. When it is absent this
Chris@0 532 function pointer must be set to NULL. */
Chris@0 533 void (*set_run_adding_gain)(LADSPA_Handle Instance,
Chris@0 534 LADSPA_Data Gain);
Chris@0 535
Chris@0 536 /* This is the counterpart to activate() (see above). If there is
Chris@0 537 nothing for deactivate() to do then the plugin writer may provide
Chris@0 538 a NULL rather than an empty function.
Chris@0 539
Chris@0 540 Hosts must deactivate all activated units after they have been
Chris@0 541 run() (or run_adding()) for the last time. This call should be
Chris@0 542 made as close to the last run() call as possible and indicates to
Chris@0 543 real-time plugins that they are no longer live. Plugins should
Chris@0 544 not rely on prompt deactivation. Note that connect_port() may be
Chris@0 545 called before or after a call to deactivate().
Chris@0 546
Chris@0 547 Deactivation is not similar to pausing as the plugin instance
Chris@0 548 will be reinitialised when activate() is called to reuse it. */
Chris@0 549 void (*deactivate)(LADSPA_Handle Instance);
Chris@0 550
Chris@0 551 /* Once an instance of a plugin has been finished with it can be
Chris@0 552 deleted using the following function. The instance handle passed
Chris@0 553 ceases to be valid after this call.
Chris@0 554
Chris@0 555 If activate() was called for a plugin instance then a
Chris@0 556 corresponding call to deactivate() must be made before cleanup()
Chris@0 557 is called. */
Chris@0 558 void (*cleanup)(LADSPA_Handle Instance);
Chris@0 559
Chris@0 560 } LADSPA_Descriptor;
Chris@0 561
Chris@0 562 /**********************************************************************/
Chris@0 563
Chris@0 564 /* Accessing a Plugin: */
Chris@0 565
Chris@0 566 /* The exact mechanism by which plugins are loaded is host-dependent,
Chris@0 567 however all most hosts will need to know is the name of shared
Chris@0 568 object file containing the plugin types. To allow multiple hosts to
Chris@0 569 share plugin types, hosts may wish to check for environment
Chris@0 570 variable LADSPA_PATH. If present, this should contain a
Chris@0 571 colon-separated path indicating directories that should be searched
Chris@0 572 (in order) when loading plugin types.
Chris@0 573
Chris@0 574 A plugin programmer must include a function called
Chris@0 575 "ladspa_descriptor" with the following function prototype within
Chris@0 576 the shared object file. This function will have C-style linkage (if
Chris@0 577 you are using C++ this is taken care of by the `extern "C"' clause
Chris@0 578 at the top of the file).
Chris@0 579
Chris@0 580 A host will find the plugin shared object file by one means or
Chris@0 581 another, find the ladspa_descriptor() function, call it, and
Chris@0 582 proceed from there.
Chris@0 583
Chris@0 584 Plugin types are accessed by index (not ID) using values from 0
Chris@0 585 upwards. Out of range indexes must result in this function
Chris@0 586 returning NULL, so the plugin count can be determined by checking
Chris@0 587 for the least index that results in NULL being returned. */
Chris@0 588
Chris@0 589 const LADSPA_Descriptor * ladspa_descriptor(unsigned long Index);
Chris@0 590
Chris@0 591 /* Datatype corresponding to the ladspa_descriptor() function. */
Chris@0 592 typedef const LADSPA_Descriptor *
Chris@0 593 (*LADSPA_Descriptor_Function)(unsigned long Index);
Chris@0 594
Chris@0 595 /**********************************************************************/
Chris@0 596
Chris@0 597 #ifdef __cplusplus
Chris@0 598 }
Chris@0 599 #endif
Chris@0 600
Chris@0 601 #endif /* LADSPA_INCLUDED */
Chris@0 602
Chris@0 603 /* EOF */