annotate plugin/api/ladspa.h @ 1716:021556fcd30b

Remove hardcoded application name - this shouldn't be necessary now we're no longer doing a shadow build
author Chris Cannam
date Fri, 17 May 2019 12:35:06 +0100
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 */