diff options
Diffstat (limited to 'plugins/eg-amp.lv2/amp.c')
| -rw-r--r-- | plugins/eg-amp.lv2/amp.c | 117 |
1 files changed, 95 insertions, 22 deletions
diff --git a/plugins/eg-amp.lv2/amp.c b/plugins/eg-amp.lv2/amp.c index 86f7a81..8dd7b4f 100644 --- a/plugins/eg-amp.lv2/amp.c +++ b/plugins/eg-amp.lv2/amp.c @@ -15,30 +15,43 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/** - @file amp.c Implementation of the LV2 Amp example plugin. - - This is a basic working LV2 plugin, about as small as one can get. It is - useful as a skeleton to copy to build more advanced plugins. See lv2.h for - more detailed descriptions of the rules for the various functions. -*/ - +/** Include standard C headers */ #include <math.h> #include <stdlib.h> -#include <string.h> +/** + LV2 headers are based on the URI of the specification they come from, so a + consistent convention can be used even for unofficial extensions. The URI + of the core LV2 specification is <http://lv2plug.in/ns/lv2core>, by + replacing `http:/` with `lv2` any header in the specification bundle can be + included, in this case `lv2.h`. +*/ #include "lv2/lv2plug.in/ns/lv2core/lv2.h" +/** + The URI is the identifier for a plugin, and how the host associates this + implementation in code with its description in data. In this plugin it is + only used once in the code, but defining the plugin URI at the top of the + file is a good convention to follow. If this URI does not match that used + in the data files, the host will fail to load the plugin. +*/ #define AMP_URI "http://lv2plug.in/plugins/eg-amp" -/** Port indices. */ +/** + In code, ports are referred to by index. An enumeration of port indices + should be defined for readability. +*/ typedef enum { AMP_GAIN = 0, AMP_INPUT = 1, AMP_OUTPUT = 2 } PortIndex; -/** Plugin instance. */ +/** + Every plugin defines a private structure for the plugin instance. All data + associated with a plugin instance is stored here, and is available to + every instance method. In this simple plugin, only port buffers need to be + stored, since there is no additional instance data. */ typedef struct { // Port buffers const float* gain; @@ -46,7 +59,16 @@ typedef struct { float* output; } Amp; -/** Create a new plugin instance. */ +/** + The instantiate() function is called by the host to create a new plugin + instance. The host passes the plugin descriptor, sample rate, and bundle + path for plugins that need to load additional resources (e.g. waveforms). + The features parameter contains host-provided features defined in LV2 + extensions, but this simple plugin does not use any. + + This function is in the ``instantiation'' threading class, so no other + methods on this instance will be called concurrently with it. +*/ static LV2_Handle instantiate(const LV2_Descriptor* descriptor, double rate, @@ -58,7 +80,14 @@ instantiate(const LV2_Descriptor* descriptor, return (LV2_Handle)amp; } -/** Connect a port to a buffer (audio thread, must be RT safe). */ +/** + The connect_port() method is called by the host to connect a particular port + to a buffer. The plugin must store the data location, but data may not be + accessed except in run(). + + This method is in the ``audio'' threading class, and is called in the same + context as run(). +*/ static void connect_port(LV2_Handle instance, uint32_t port, @@ -79,13 +108,21 @@ connect_port(LV2_Handle instance, } } -/** Initialise and prepare the plugin instance for running. */ +/** + The activate() method is called by the host to initialise and prepare the + plugin instance for running. The plugin must reset all internal state + except for buffer locations set by connect_port(). Since this plugin has + no other internal state, this method does nothing. + + This method is in the ``instantiation'' threading class, so no other + methods on this instance will be called concurrently with it. +*/ static void activate(LV2_Handle instance) { - /* Nothing to do here in this trivial mostly stateless plugin. */ } +/** Define a macro for converting a gain in dB to a coefficient */ #define DB_CO(g) ((g) > -90.0f ? powf(10.0f, (g) * 0.05f) : 0.0f) /** Process a block of audio (audio thread, must be RT safe). */ @@ -105,28 +142,55 @@ run(LV2_Handle instance, uint32_t n_samples) } } -/** Finish running (counterpart to activate()). */ +/** + The deactivate() method is the counterpart to activate() called by the host + after running the plugin. It indicates that the host will not call run() + again until another call to activate() and is mainly useful for more + advanced plugins with ``live'' characteristics such as those with auxiliary + processing threads. As with activate(), this plugin has no use for this + information so this method does nothing. + + This method is in the ``instantiation'' threading class, so no other + methods on this instance will be called concurrently with it. +*/ static void deactivate(LV2_Handle instance) { - /* Nothing to do here in this trivial mostly stateless plugin. */ } -/** Destroy a plugin instance (counterpart to instantiate()). */ +/** + Destroy a plugin instance (counterpart to instantiate()). + + This method is in the ``instantiation'' threading class, so no other + methods on this instance will be called concurrently with it. +*/ static void cleanup(LV2_Handle instance) { free(instance); } -/** Return extension data provided by the plugin. */ +/** + The extension_data function returns any extension data supported by the + plugin. Note that this is not an instance method, but a function on the + plugin descriptor. It is usually used by plugins to implement additional + interfaces. This plugin does not have any extension data, so this function + returns NULL. + + This method is in the ``discovery'' threading class, so no other functions + or methods in this plugin library will be called concurrently with it. +*/ static const void* extension_data(const char* uri) { - return NULL; /* This plugin has no extension data. */ + return NULL; } -/** The LV2_Descriptor for this plugin. */ +/** + Define the LV2_Descriptor for this plugin. It is best to define descriptors + statically to avoid leaking memory and non-portable shared library + constructors and destructors to clean up properly. +*/ static const LV2_Descriptor descriptor = { AMP_URI, instantiate, @@ -138,7 +202,16 @@ static const LV2_Descriptor descriptor = { extension_data }; -/** Entry point, the host will call this function to access descriptors. */ +/** + The lv2_descriptor() function is the entry point to the plugin library. The + host will load the library and call this function repeatedly with increasing + indices to find all the plugins defined in the library. The index is not an + indentifier, the URI of the returned descriptor is used to determine the + identify of the plugin. + + This method is in the ``discovery'' threading class, so no other functions + or methods in this plugin library will be called concurrently with it. +*/ LV2_SYMBOL_EXPORT const LV2_Descriptor* lv2_descriptor(uint32_t index) |