2. The LADSPA Plugin Format

2.1 Finding and providing LADSPA_Descriptors

The ladspa format specifies how to obtain the LADSPA_Descriptors from a given plugin library. All LADSPA plugin libraries must define a function

---

LADSPA_Descriptor* ladspa_descriptor(unsigned long Index);

---

---

  unsigned long num_plugins = 0;
  while ((*ladspa_descriptor_func)(num_plugins) != NULL)
    num_plugins++;

---

More commonly though, you'll need to store and use the LADSPA_Descriptor that that function returns.

2.2 The descriptor's data

Now let's examine the LADSPA_Descriptor structure. It consists of a number of members which describe the plugin, and a collection of function pointers which provide its implementation.

Here are the data members:

unsigned long UniqueID

This numeric identifier indicates the plugin type uniquely. Plugin programmers may reserve ranges of IDs from a central body to avoid clashes. Hosts may assume that IDs are below 0x1000000.

const char * Label

This identifier can be used as a unique, case-sensitive identifier for the plugin type within the plugin file. Plugin types should be identified by file and label rather than by index or plugin name, which may be changed in new plugin versions. Labels must not contain white-space characters.

LADSPA_Properties Properties

This contains a number of properties of the plugin.

const char * Name

This member points to the NUL-terminated name of the plugin (e.g. "Sine Oscillator").

const char * Maker

This member points to the NUL-terminated string indicating the maker of the plugin. This can be an empty string but not NULL.

const char * Copyright

This member points to the NUL-terminated string indicating any copyright applying to the plugin. If no copyright applies, the string "None" should be used.

unsigned long PortCount

This indicates the number of ports, both input and output, present in the plugin. All the ports must be initialized by the host to valid pointer; this will be described better below.

const LADSPA_PortDescriptor * PortDescriptors

This member indicates an array of port descriptors. Valid indices vary from 0 to PortCount-1.

const char * const * PortNames

This member indicates an array of NUL-terminated strings describing ports (e.g. "Frequency (Hz)"). Valid indices vary from 0 to PortCount-1.

const LADSPA_PortRangeHint * PortRangeHints

This member indicates an array of range hints for each port (see above). Valid indices vary from 0 to PortCount-1.

void* ImplementationData

This may be used by the plugin developer to pass any custom implementation data into an instantiate call. It must not be used or interpreted by the host. It is expected that most plugin writers will not use this facility as the ladspa instance should be used to hold instance data, and plugin-descriptor data may as well be global, since it has to be cleaned up by _fini anyway.

The PortDescriptors and PortRangeHints members describe the available ports. The PortDescriptors are just bitmasks that are OR'd together:

LADSPA_PORT_INPUT

indicates that the port is an input.

LADSPA_PORT_OUTPUT

indicates that the port is an output.

LADSPA_PORT_CONTROL

indicates that the port is a control port.

LADSPA_PORT_AUDIO

indicates that the port is a audio port.

It is required that the port be an INPUT or an OUTPUT but not both, and a CONTROL or an AUDIO but not both. So there are really four possibilities which we can describe concretely.

LADSPA_PORT_INPUT | LADSPA_PORT_AUDIO

an audio input. The host is responsible for filling the port buffer with SampleCount samples before calling the plugin's run function.

LADSPA_PORT_INPUT | LADSPA_PORT_CONTROL

an input control. The host must set the single sample which the port buffer contains before calling run.

LADSPA_PORT_OUTPUT | LADSPA_PORT_AUDIO

an audio output. The plugin's run function fills this port buffer with SampleCount samples.

LADSPA_PORT_OUTPUT | LADSPA_PORT_CONTROL

an meter. This is a slowly varying signal produced by the plugin. For example a pitch estimator or level meter might have one of these.

2.3 The descriptor's implementation

The LADSPA_Descriptor contains a number of function pointers which implement the plugin. The primary function is run which renders and processes samples, but you must also define functions to manage the plugin's memory.

instantiate

function is the function which should allocate a new plugin handle. Generally I think all the allocation should be done here, although you may do it in activate as well.

activate

function is the function which clears and resets a plugin handle. For example, it should zero out delay buffers and filter buffers.

connect_port

function allows the host to specify input buffers to the plugin. Write the code so that the input and output buffers must be the same.

run

function processes samples. The host is responsible for filling each of the input port buffers before calling run and the run function is responsible for filling the output buffers.

run_adding

function is optional. It is the same as run except it adds the output to the output buffer with a host-settable gain instead of overwriting it. If you don't want to implement this, leave the function pointer NULL. I (daveb) don't recommend implementing or using this function as it is not usually much of a savings.

set_run_adding_gain

adjusts the gain that run_adding should use.

deactivate

function should free the memory allocated by activate. Often there is no need for a deactivate function: you may leave the pointer NULL in this case.

cleanup

function should free a plugin handle and all the memory it owns. (You must use the _fini function to free the data associated with LADSPA_Descriptor.)