The ladspa format specifies how to obtain the
LADSPA_Descriptors from a given plugin library.
All LADSPA plugin libraries must define a function
which will return each
LADSPA_Descriptor* ladspa_descriptor(unsigned long Index);
LADSPA_Descriptorby index. It must return NULL for all invalid indices. So a simple way to determine the number of plugins for a given plugin is:
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
that that function returns.
Now let's examine the
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:
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.
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.
This contains a number of properties of the plugin.
This member points to the NUL-terminated name of the plugin (e.g. "Sine Oscillator").
This member points to the NUL-terminated string indicating the maker of the plugin. This can be an empty string but not NULL.
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.
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.
This member indicates an array of port descriptors. Valid indices
This member indicates an array of NUL-terminated strings
describing ports (e.g. "Frequency (Hz)"). Valid indices vary from
This member indicates an array of range hints for each port (see
above). Valid indices vary from
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.
describe the available ports. The PortDescriptors
are just bitmasks that are OR'd together:
indicates that the port is an input.
indicates that the port is an output.
indicates that the port is a control port.
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.
an audio input. The host is responsible for
filling the port buffer with
before calling the plugin's
an input control. The host must set the single sample
which the port buffer contains before calling
an audio output. The plugin's
fills this port buffer with
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.
LADSPA_Descriptor contains a number of function
pointers which implement the plugin. The primary
run which renders and processes samples,
but you must also define functions to manage the plugin's memory.
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.
function is the function which clears and resets a plugin handle. For example, it should zero out delay buffers and filter buffers.
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.
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.
function is optional. It is the
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.
adjusts the gain that
function should free the memory allocated by
Often there is no need for a
deactivate function: you may
leave the pointer
NULL in this case.
function should free a plugin handle
and all the memory it owns. (You must use the
function to free the data associated with LADSPA_Descriptor.)