~ubuntu-branches/ubuntu/wily/muse/wily : revision 1.1.11

1

/* ladspa.h

2

3

Linux Audio Developer's Simple Plugin API Version 1.1[provisional,

4

5

Barton-Davis, Stefan Westerfeld.

6

7

This library is free software; you can redistribute it and/or

8

modify it under the terms of the GNU Lesser General Public License

9

as published by the Free Software Foundation; either version 2.1 of

10

the License, or (at your option) any later version.

11

12

This library is distributed in the hope that it will be useful, but

13

WITHOUT ANY WARRANTY; without even the implied warranty of

14

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

15

Lesser General Public License for more details.

16

17

You should have received a copy of the GNU Lesser General Public

18

License along with this library; if not, write to the Free Software

19

Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,

20

USA. */

21

22

#ifndef LADSPA_INCLUDED

23

#define LADSPA_INCLUDED

24

25

#ifdef __cplusplus

26

extern "C" {

27

#endif

28

29

/*****************************************************************************/

30

31

/* Overview:

32

33

There is a large number of synthesis packages in use or development

34

on the Linux platform at this time. This API (`The Linux Audio

35

Developer's Simple Plugin API') attempts to give programmers the

36

ability to write simple `plugin' audio processors in C/C++ and link

37

them dynamically (`plug') into a range of these packages (`hosts').

38

It should be possible for any host and any plugin to communicate

39

completely through this interface.

40

41

This API is deliberately short and simple. To achieve compatibility

42

with a range of promising Linux sound synthesis packages it

43

attempts to find the `greatest common divisor' in their logical

44

behaviour. Having said this, certain limiting decisions are

45

implicit, notably the use of a fixed type (LADSPA_Data) for all

46

data transfer and absence of a parameterised `initialisation'

47

phase. See below for the LADSPA_Data typedef.

48

49

Plugins are expected to distinguish between control and audio

50

data. Plugins have `ports' that are inputs or outputs for audio or

51

control data and each plugin is `run' for a `block' corresponding

52

to a short time interval measured in samples. Audio data is

53

communicated using arrays of LADSPA_Data, allowing a block of audio

54

to be processed by the plugin in a single pass. Control data is

55

communicated using single LADSPA_Data values. Control data has a

56

single value at the start of a call to the `run()' or `run_adding()'

57

function, and may be considered to remain this value for its

58

duration. The plugin may assume that all its input and output ports

59

have been connected to the relevant data location (see the

60

`connect_port()' function below) before it is asked to run.

61

62

Plugins will reside in shared object files suitable for dynamic

63

linking by dlopen() and family. The file will provide a number of

64

`plugin types' that can be used to instantiate actual plugins

65

(sometimes known as `plugin instances') that can be connected

66

together to perform tasks.

67

68

This API contains very limited error-handling. */

69

70

/*****************************************************************************/

71

72

/* Fundamental data type passed in and out of plugin. This data type

73

is used to communicate audio samples and control values. It is

74

assumed that the plugin will work sensibly given any numeric input

75

value although it may have a preferred range (see hints below).

76

77

For audio it is generally assumed that 1.0f is the `0dB' reference

78

amplitude and is a `normal' signal level. */

79

80

typedef float LADSPA_Data;

81

82

/*****************************************************************************/

83

84

/* Special Plugin Properties:

85

86

Optional features of the plugin type are encapsulated in the

87

LADSPA_Properties type. This is assembled by ORing individual

88

properties together. */

89

90

typedef int LADSPA_Properties;

91

92

/* Property LADSPA_PROPERTY_REALTIME indicates that the plugin has a

93

real-time dependency (e.g. listens to a MIDI device) and so its

94

output must not be cached or subject to significant latency. */

95

#define LADSPA_PROPERTY_REALTIME 0x1

96

97

/* Property LADSPA_PROPERTY_INPLACE_BROKEN indicates that the plugin

98

may cease to work correctly if the host elects to use the same data

99

location for both input and output (see connect_port()). This

100

should be avoided as enabling this flag makes it impossible for

101

hosts to use the plugin to process audio `in-place.' */

102

#define LADSPA_PROPERTY_INPLACE_BROKEN 0x2

103

104

/* Property LADSPA_PROPERTY_HARD_RT_CAPABLE indicates that the plugin

105

is capable of running not only in a conventional host but also in a

106

`hard real-time' environment. To qualify for this the plugin must

107

satisfy all of the following:

108

109

(1) The plugin must not use malloc(), free() or other heap memory

110

management within its run() or run_adding() functions. All new

111

memory used in run() must be managed via the stack. These

112

restrictions only apply to the run() function.

113

114

(2) The plugin will not attempt to make use of any library

115

functions with the exceptions of functions in the ANSI standard C

116

and C maths libraries, which the host is expected to provide.

117

118

(3) The plugin will not access files, devices, pipes, sockets, IPC

119

or any other mechanism that might result in process or thread

120

blocking.

121

122

(4) The plugin will take an amount of time to execute a run() or

123

run_adding() call approximately of form (A+B*SampleCount) where A

124

and B depend on the machine and host in use. This amount of time

125

may not depend on input signals or plugin state. The host is left

126

the responsibility to perform timings to estimate upper bounds for

127

A and B. */

128

#define LADSPA_PROPERTY_HARD_RT_CAPABLE 0x4

129

130

#define LADSPA_IS_REALTIME(x) ((x) & LADSPA_PROPERTY_REALTIME)

131

#define LADSPA_IS_INPLACE_BROKEN(x) ((x) & LADSPA_PROPERTY_INPLACE_BROKEN)

132

#define LADSPA_IS_HARD_RT_CAPABLE(x) ((x) & LADSPA_PROPERTY_HARD_RT_CAPABLE)

133

134

/*****************************************************************************/

135

136

/* Plugin Ports:

137

138

Plugins have `ports' that are inputs or outputs for audio or

139

data. Ports can communicate arrays of LADSPA_Data (for audio

140

inputs/outputs) or single LADSPA_Data values (for control

141

input/outputs). This information is encapsulated in the

142

LADSPA_PortDescriptor type which is assembled by ORing individual

143

properties together.

144

145

Note that a port must be an input or an output port but not both

146

and that a port must be a control or audio port but not both. */

147

148

typedef int LADSPA_PortDescriptor;

149

150

/* Property LADSPA_PORT_INPUT indicates that the port is an input. */

151

#define LADSPA_PORT_INPUT 0x1

152

153

/* Property LADSPA_PORT_OUTPUT indicates that the port is an output. */

154

#define LADSPA_PORT_OUTPUT 0x2

155

156

/* Property LADSPA_PORT_CONTROL indicates that the port is a control

157

port. */

158

#define LADSPA_PORT_CONTROL 0x4

159

160

/* Property LADSPA_PORT_AUDIO indicates that the port is a audio

161

port. */

162

#define LADSPA_PORT_AUDIO 0x8

163

164

#define LADSPA_IS_PORT_INPUT(x) ((x) & LADSPA_PORT_INPUT)

165

#define LADSPA_IS_PORT_OUTPUT(x) ((x) & LADSPA_PORT_OUTPUT)

166

#define LADSPA_IS_PORT_CONTROL(x) ((x) & LADSPA_PORT_CONTROL)

167

#define LADSPA_IS_PORT_AUDIO(x) ((x) & LADSPA_PORT_AUDIO)

168

169

/*****************************************************************************/

170

171

/* Plugin Port Range Hints:

172

173

The host may wish to provide a representation of data entering or

174

leaving a plugin (e.g. to generate a GUI automatically). To make

175

this more meaningful, the plugin should provide `hints' to the host

176

describing the usual values taken by the data.

177

178

Note that these are only hints. The host may ignore them and the

179

plugin must not assume that data supplied to it is meaningful. If

180

the plugin receives invalid input data it is expected to continue

181

to run without failure and, where possible, produce a sensible

182

output (e.g. a high-pass filter given a negative cutoff frequency

183

might switch to an all-pass mode).

184

185

Hints are meaningful for all input and output ports but hints for

186

input control ports are expected to be particularly useful.

187

188

More hint information is encapsulated in the

189

LADSPA_PortRangeHintDescriptor type which is assembled by ORing

190

individual hint types together. Hints may require further

191

LowerBound and UpperBound information.

192

193

All the hint information for a particular port is aggregated in the

194

LADSPA_PortRangeHint structure. */

195

196

typedef int LADSPA_PortRangeHintDescriptor;

197

198

/* Hint LADSPA_HINT_BOUNDED_BELOW indicates that the LowerBound field

199

of the LADSPA_PortRangeHint should be considered meaningful. The

200

value in this field should be considered the (inclusive) lower

201

bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also

202

specified then the value of LowerBound should be multiplied by the

203

sample rate. */

204

#define LADSPA_HINT_BOUNDED_BELOW 0x1

205

206

/* Hint LADSPA_HINT_BOUNDED_ABOVE indicates that the UpperBound field

207

of the LADSPA_PortRangeHint should be considered meaningful. The

208

value in this field should be considered the (inclusive) upper

209

bound of the valid range. If LADSPA_HINT_SAMPLE_RATE is also

210

specified then the value of UpperBound should be multiplied by the

211

sample rate. */

212

#define LADSPA_HINT_BOUNDED_ABOVE 0x2

213

214

/* Hint LADSPA_HINT_TOGGLED indicates that the data item should be

215

considered a Boolean toggle. Data less than or equal to zero should

216

be considered `off' or `false,' and data above zero should be

217

considered `on' or `true.' LADSPA_HINT_TOGGLED may not be used in

218

conjunction with any other hint except LADSPA_HINT_DEFAULT_0 or

219

LADSPA_HINT_DEFAULT_1. */

220

#define LADSPA_HINT_TOGGLED 0x4

221

222

/* Hint LADSPA_HINT_SAMPLE_RATE indicates that any bounds specified

223

should be interpreted as multiples of the sample rate. For

224

instance, a frequency range from 0Hz to the Nyquist frequency (half

225

the sample rate) could be requested by this hint in conjunction

226

with LowerBound = 0 and UpperBound = 0.5. Hosts that support bounds

227

at all must support this hint to retain meaning. */

228

#define LADSPA_HINT_SAMPLE_RATE 0x8

229

230

/* Hint LADSPA_HINT_LOGARITHMIC indicates that it is likely that the

231

user will find it more intuitive to view values using a logarithmic

232

scale. This is particularly useful for frequencies and gains. */

233

#define LADSPA_HINT_LOGARITHMIC 0x10

234

235

/* Hint LADSPA_HINT_INTEGER indicates that a user interface would

236

probably wish to provide a stepped control taking only integer

237

values. Any bounds set should be slightly wider than the actual

238

integer range required to avoid floating point rounding errors. For

239

instance, the integer set {0,1,2,3} might be described as [-0.1,

240

3.1]. */

241

#define LADSPA_HINT_INTEGER 0x20

242

243

/* The various LADSPA_HINT_HAS_DEFAULT_* hints indicate a `normal'

244

value for the port that is sensible as a default. For instance,

245

this value is suitable for use as an initial value in a user

246

interface or as a value the host might assign to a control port

247

when the user has not provided one. Defaults are encoded using a

248

mask so only one default may be specified for a port. Some of the

249

hints make use of lower and upper bounds, in which case the

250

relevant bound or bounds must be available and

251

LADSPA_HINT_SAMPLE_RATE must be applied as usual. The resulting

252

default must be rounded if LADSPA_HINT_INTEGER is present. Default

253

values were introduced in LADSPA v1.1. */

254

#define LADSPA_HINT_DEFAULT_MASK 0x3C0

255

256

/* This default values indicates that no default is provided. */

257

#define LADSPA_HINT_DEFAULT_NONE 0x0

258

259

/* This default hint indicates that the suggested lower bound for the

260

port should be used. */

261

#define LADSPA_HINT_DEFAULT_MINIMUM 0x40

262

263

/* This default hint indicates that a low value between the suggested

264

lower and upper bounds should be chosen. For ports with

265

LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.75 +

266

log(upper) * 0.25). Otherwise, this should be (lower * 0.75 + upper

267

* 0.25). */

268

#define LADSPA_HINT_DEFAULT_LOW 0x80

269

270

/* This default hint indicates that a middle value between the

271

suggested lower and upper bounds should be chosen. For ports with

272

LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.5 +

273

log(upper) * 0.5). Otherwise, this should be (lower * 0.5 + upper *

274

0.5). */

275

#define LADSPA_HINT_DEFAULT_MIDDLE 0xC0

276

277

/* This default hint indicates that a high value between the suggested

278

lower and upper bounds should be chosen. For ports with

279

LADSPA_HINT_LOGARITHMIC, this should be exp(log(lower) * 0.25 +

280

log(upper) * 0.75). Otherwise, this should be (lower * 0.25 + upper

281

* 0.75). */

282

#define LADSPA_HINT_DEFAULT_HIGH 0x100

283

284

/* This default hint indicates that the suggested upper bound for the

285

port should be used. */

286

#define LADSPA_HINT_DEFAULT_MAXIMUM 0x140

287

288

/* This default hint indicates that the number 0 should be used. Note

289

that this default may be used in conjunction with

290

LADSPA_HINT_TOGGLED. */

291

#define LADSPA_HINT_DEFAULT_0 0x200

292

293

/* This default hint indicates that the number 1 should be used. Note

294

that this default may be used in conjunction with

295

LADSPA_HINT_TOGGLED. */

296

#define LADSPA_HINT_DEFAULT_1 0x240

297

298

/* This default hint indicates that the number 100 should be used. */

299

#define LADSPA_HINT_DEFAULT_100 0x280

300

301

/* This default hint indicates that the Hz frequency of `concert A'

302

should be used. This will be 440 unless the host uses an unusual

303

tuning convention, in which case it may be within a few Hz. */

304

#define LADSPA_HINT_DEFAULT_440 0x2C0

305

306

#define LADSPA_IS_HINT_BOUNDED_BELOW(x) ((x) & LADSPA_HINT_BOUNDED_BELOW)

307

#define LADSPA_IS_HINT_BOUNDED_ABOVE(x) ((x) & LADSPA_HINT_BOUNDED_ABOVE)

308

#define LADSPA_IS_HINT_TOGGLED(x) ((x) & LADSPA_HINT_TOGGLED)

309

#define LADSPA_IS_HINT_SAMPLE_RATE(x) ((x) & LADSPA_HINT_SAMPLE_RATE)

310

#define LADSPA_IS_HINT_LOGARITHMIC(x) ((x) & LADSPA_HINT_LOGARITHMIC)

311

#define LADSPA_IS_HINT_INTEGER(x) ((x) & LADSPA_HINT_INTEGER)

312

313

#define LADSPA_IS_HINT_HAS_DEFAULT(x) ((x) & LADSPA_HINT_DEFAULT_MASK)

314

#define LADSPA_IS_HINT_DEFAULT_MINIMUM(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \

315

== LADSPA_HINT_DEFAULT_MINIMUM)

316

#define LADSPA_IS_HINT_DEFAULT_LOW(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \

317

== LADSPA_HINT_DEFAULT_LOW)

318

#define LADSPA_IS_HINT_DEFAULT_MIDDLE(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \

319

== LADSPA_HINT_DEFAULT_MIDDLE)

320

#define LADSPA_IS_HINT_DEFAULT_HIGH(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \

321

== LADSPA_HINT_DEFAULT_HIGH)

322

#define LADSPA_IS_HINT_DEFAULT_MAXIMUM(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \

323

== LADSPA_HINT_DEFAULT_MAXIMUM)

324

#define LADSPA_IS_HINT_DEFAULT_0(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \

325

== LADSPA_HINT_DEFAULT_0)

326

#define LADSPA_IS_HINT_DEFAULT_1(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \

327

== LADSPA_HINT_DEFAULT_1)

328

#define LADSPA_IS_HINT_DEFAULT_100(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \

329

== LADSPA_HINT_DEFAULT_100)

330

#define LADSPA_IS_HINT_DEFAULT_440(x) (((x) & LADSPA_HINT_DEFAULT_MASK) \

331

== LADSPA_HINT_DEFAULT_440)

332

333

typedef struct _LADSPA_PortRangeHint {

334

335

/* Hints about the port. */

336

LADSPA_PortRangeHintDescriptor HintDescriptor;

337

338

/* Meaningful when hint LADSPA_HINT_BOUNDED_BELOW is active. When

339

LADSPA_HINT_SAMPLE_RATE is also active then this value should be

340

multiplied by the relevant sample rate. */

341

LADSPA_Data LowerBound;

342

343

/* Meaningful when hint LADSPA_HINT_BOUNDED_ABOVE is active. When

344

LADSPA_HINT_SAMPLE_RATE is also active then this value should be

345

multiplied by the relevant sample rate. */

346

LADSPA_Data UpperBound;

347

348

} LADSPA_PortRangeHint;

349

350

/*****************************************************************************/

351

352

/* Plugin Handles:

353

354

This plugin handle indicates a particular instance of the plugin

355

concerned. It is valid to compare this to NULL (0 for C++) but

356

otherwise the host should not attempt to interpret it. The plugin

357

may use it to reference internal instance data. */

358

359

typedef void * LADSPA_Handle;

360

361

/*****************************************************************************/

362

363

/* Descriptor for a Type of Plugin:

364

365

This structure is used to describe a plugin type. It provides a

366

number of functions to examine the type, instantiate it, link it to

367

buffers and workspaces and to run it. */

368

369

typedef struct _LADSPA_Descriptor {

370

371

/* This numeric identifier indicates the plugin type

372

uniquely. Plugin programmers may reserve ranges of IDs from a

373

central body to avoid clashes. Hosts may assume that IDs are

374

below 0x1000000. */

375

unsigned long UniqueID;

376

377

/* This identifier can be used as a unique, case-sensitive

378

identifier for the plugin type within the plugin file. Plugin

379

types should be identified by file and label rather than by index

380

or plugin name, which may be changed in new plugin

381

versions. Labels must not contain white-space characters. */

382

const char * Label;

383

384

/* This indicates a number of properties of the plugin. */

385

LADSPA_Properties Properties;

386

387

/* This member points to the null-terminated name of the plugin

388

(e.g. "Sine Oscillator"). */

389

const char * Name;

390

391

/* This member points to the null-terminated string indicating the

392

maker of the plugin. This can be an empty string but not NULL. */

393

const char * Maker;

394

395

/* This member points to the null-terminated string indicating any

396

copyright applying to the plugin. If no Copyright applies the

397

string "None" should be used. */

398

const char * Copyright;

399

400

/* This indicates the number of ports (input AND output) present on

401

the plugin. */

402

unsigned long PortCount;

403

404

/* This member indicates an array of port descriptors. Valid indices

405

vary from 0 to PortCount-1. */

406

const LADSPA_PortDescriptor * PortDescriptors;

407

408

/* This member indicates an array of null-terminated strings

409

describing ports (e.g. "Frequency (Hz)"). Valid indices vary from

410

0 to PortCount-1. */

411

const char * const * PortNames;

412

413

/* This member indicates an array of range hints for each port (see

414

above). Valid indices vary from 0 to PortCount-1. */

415

const LADSPA_PortRangeHint * PortRangeHints;

416

417

/* This may be used by the plugin developer to pass any custom

418

implementation data into an instantiate call. It must not be used

419

or interpreted by the host. It is expected that most plugin

420

writers will not use this facility as LADSPA_Handle should be

421

used to hold instance data. */

422

void * ImplementationData;

423

424

/* This member is a function pointer that instantiates a plugin. A

425

handle is returned indicating the new plugin instance. The

426

instantiation function accepts a sample rate as a parameter. The

427

plugin descriptor from which this instantiate function was found

428

must also be passed. This function must return NULL if

429

instantiation fails.

430

431

Note that instance initialisation should generally occur in

432

activate() rather than here. */

433

LADSPA_Handle (*instantiate)(const struct _LADSPA_Descriptor * Descriptor,

434

unsigned long SampleRate);

435

436

/* This member is a function pointer that connects a port on an

437

instantiated plugin to a memory location at which a block of data

438

for the port will be read/written. The data location is expected

439

to be an array of LADSPA_Data for audio ports or a single

440

LADSPA_Data value for control ports. Memory issues will be

441

managed by the host. The plugin must read/write the data at these

442

locations every time run() or run_adding() is called and the data

443

present at the time of this connection call should not be

444

considered meaningful.

445

446

connect_port() may be called more than once for a plugin instance

447

to allow the host to change the buffers that the plugin is

448

reading or writing. These calls may be made before or after

449

activate() or deactivate() calls.

450

451

connect_port() must be called at least once for each port before

452

run() or run_adding() is called. When working with blocks of

453

LADSPA_Data the plugin should pay careful attention to the block

454

size passed to the run function as the block allocated may only

455

just be large enough to contain the block of samples.

456

457

Plugin writers should be aware that the host may elect to use the

458

same buffer for more than one port and even use the same buffer

459

for both input and output (see LADSPA_PROPERTY_INPLACE_BROKEN).

460

However, overlapped buffers or use of a single buffer for both

461

audio and control data may result in unexpected behaviour. */

462

void (*connect_port)(LADSPA_Handle Instance,

463

unsigned long Port,

464

LADSPA_Data * DataLocation);

465

466

/* This member is a function pointer that initialises a plugin

467

instance and activates it for use. This is separated from

468

instantiate() to aid real-time support and so that hosts can

469

reinitialise a plugin instance by calling deactivate() and then

470

activate(). In this case the plugin instance must reset all state

471

information dependent on the history of the plugin instance

472

except for any data locations provided by connect_port() and any

473

gain set by set_run_adding_gain(). If there is nothing for

474

activate() to do then the plugin writer may provide a NULL rather

475

than an empty function.

476

477

When present, hosts must call this function once before run() (or

478

run_adding()) is called for the first time. This call should be

479

made as close to the run() call as possible and indicates to

480

real-time plugins that they are now live. Plugins should not rely

481

on a prompt call to run() after activate(). activate() may not be

482

called again unless deactivate() is called first. Note that

483

connect_port() may be called before or after a call to

484

activate(). */

485

void (*activate)(LADSPA_Handle Instance);

486

487

/* This method is a function pointer that runs an instance of a

488

plugin for a block. Two parameters are required: the first is a

489

handle to the particular instance to be run and the second

490

indicates the block size (in samples) for which the plugin

491

instance may run.

492

493

Note that if an activate() function exists then it must be called

494

before run() or run_adding(). If deactivate() is called for a

495

plugin instance then the plugin instance may not be reused until

496

activate() has been called again.

497

498

If the plugin has the property LADSPA_PROPERTY_HARD_RT_CAPABLE

499

then there are various things that the plugin should not do

500

within the run() or run_adding() functions (see above). */

501

void (*run)(LADSPA_Handle Instance,

502

unsigned long SampleCount);

503

504

/* This method is a function pointer that runs an instance of a

505

plugin for a block. This has identical behaviour to run() except

506

in the way data is output from the plugin. When run() is used,

507

values are written directly to the memory areas associated with

508

the output ports. However when run_adding() is called, values

509

must be added to the values already present in the memory

510

areas. Furthermore, output values written must be scaled by the

511

current gain set by set_run_adding_gain() (see below) before

512

addition.

513

514

run_adding() is optional. When it is not provided by a plugin,

515

this function pointer must be set to NULL. When it is provided,

516

the function set_run_adding_gain() must be provided also. */

517

void (*run_adding)(LADSPA_Handle Instance,

518

unsigned long SampleCount);

519

520

/* This method is a function pointer that sets the output gain for

521

use when run_adding() is called (see above). If this function is

522

never called the gain is assumed to default to 1. Gain

523

information should be retained when activate() or deactivate()

524

are called.

525

526

This function should be provided by the plugin if and only if the

527

run_adding() function is provided. When it is absent this

528

function pointer must be set to NULL. */

529

void (*set_run_adding_gain)(LADSPA_Handle Instance,

530

LADSPA_Data Gain);

531

532

/* This is the counterpart to activate() (see above). If there is

533

nothing for deactivate() to do then the plugin writer may provide

534

a NULL rather than an empty function.

535

536

Hosts must deactivate all activated units after they have been

537

run() (or run_adding()) for the last time. This call should be

538

made as close to the last run() call as possible and indicates to

539

real-time plugins that they are no longer live. Plugins should

540

not rely on prompt deactivation. Note that connect_port() may be

541

called before or after a call to deactivate().

542

543

Deactivation is not similar to pausing as the plugin instance

544

will be reinitialised when activate() is called to reuse it. */

545

void (*deactivate)(LADSPA_Handle Instance);

546

547

/* Once an instance of a plugin has been finished with it can be

548

deleted using the following function. The instance handle passed

549

ceases to be valid after this call.

550

551

If activate() was called for a plugin instance then a

552

corresponding call to deactivate() must be made before cleanup()

553

is called. */

554

void (*cleanup)(LADSPA_Handle Instance);

555

556

} LADSPA_Descriptor;

557

558

/**********************************************************************/

559

560

/* Accessing a Plugin: */

561

562

/* The exact mechanism by which plugins are loaded is host-dependent,

563

however all most hosts will need to know is the name of shared

564

object file containing the plugin types. To allow multiple hosts to

565

share plugin types, hosts may wish to check for environment

566

variable LADSPA_PATH. If present, this should contain a

567

colon-separated path indicating directories that should be searched

568

(in order) when loading plugin types.

569

570

A plugin programmer must include a function called

571

"ladspa_descriptor" with the following function prototype within

572

the shared object file. This function will have C-style linkage (if

573

you are using C++ this is taken care of by the `extern "C"' clause

574

at the top of the file).

575

576

A host will find the plugin shared object file by one means or

577

another, find the ladspa_descriptor() function, call it, and

578

proceed from there.

579

580

Plugin types are accessed by index (not ID) using values from 0

581

upwards. Out of range indexes must result in this function

582

returning NULL, so the plugin count can be determined by checking

583

for the least index that results in NULL being returned. */

584

585

const LADSPA_Descriptor * ladspa_descriptor(unsigned long Index);

586

587

/* Datatype corresponding to the ladspa_descriptor() function. */

588

typedef const LADSPA_Descriptor *

589

(*LADSPA_Descriptor_Function)(unsigned long Index);

590

591

/**********************************************************************/

592

593

#ifdef __cplusplus

594

}

595

#endif

596

597

#endif /* LADSPA_INCLUDED */

598

599

/* EOF */