# Plugin Instances

LilvInstance *lilv_plugin_instantiate(const LilvPlugin *plugin, double sample_rate, const LV2_Feature *const *features)

  Instantiate a plugin.

  The returned value is a lightweight handle for an LV2 plugin instance, it does not refer to `plugin`, or any other Lilv state. The caller must eventually free it with `lilv_instance_free()`. `features` is a NULL-terminated array of features the host supports. NULL may be passed if the host supports no additional features.

  This function is in the “discovery” threading class: it isn’t real-time safe, and may not be called concurrently with itself for the same plugin.

  Returns:

    NULL if instantiation failed.

void lilv_instance_free(LilvInstance *instance)

  Free a plugin instance.

  It is safe to call this function on NULL. The `instance` is invalid after this call.

  This function is in the “discovery” threading class: it isn’t real-time safe, and may not be called concurrently with any other function for the same instance, or with `lilv_plugin_instantiate()` for the same plugin.

const char *lilv_instance_get_uri(const LilvInstance *instance)

  Get the URI of the plugin which `instance` is an instance of.

  This function is a simple accessor and may be called at any time. The returned string is shared and must not be modified or deleted.

void lilv_instance_connect_port(LilvInstance *instance, uint32_t port_index, void *data_location)

  Connect a port to a data location.

  This may be called regardless of whether the plugin is activated, activation and deactivation does not destroy port connections.

  This function is in the “audio” threading class: it’s real-time safe if the plugin is http://lv2plug.in/ns/lv2core#hardRTCapable, but may not be called concurrently with any other function for the same instance.

void lilv_instance_activate(LilvInstance *instance)

  Activate a plugin instance.

  This resets all state information in the plugin, except for port data locations (as set by lilv_instance_connect_port()). This MUST be called before calling lilv_instance_run().

  This function is in the “instantiation” threading class: it isn’t real-time safe, and may not be called concurrently with any other function for the same instance.

void lilv_instance_run(LilvInstance *instance, uint32_t sample_count)

  Run `instance` for `sample_count` frames.

  If the hint lv2:hardRTCapable is set for this plugin, this function is guaranteed not to block.

  This function is in the “audio” threading class: it’s real-time safe if the plugin is http://lv2plug.in/ns/lv2core#hardRTCapable, but may not be called concurrently with any other function for the same instance.

void lilv_instance_deactivate(LilvInstance *instance)

  Deactivate a plugin instance.

  Note that to run the plugin after this you must activate it, which will reset all state information (except port connections).

  This function is in the “instantiation” threading class: it isn’t real-time safe and may not be called concurrently with any other function for the same instance.

const void *lilv_instance_get_extension_data(const LilvInstance *instance, const char *uri)

  Get extension data from the plugin instance.

  The type and semantics of the data returned is specific to the particular extension, though in all cases it is shared and must not be deleted.

  This function is in the “discovery” threading class: it isn’t real-time safe and may not be called concurrently with any other function for the same instance.

const LV2_Descriptor *lilv_instance_get_descriptor(const LilvInstance *instance)

  Get the LV2_Descriptor of the plugin instance.

  Normally hosts should not need to access the LV2_Descriptor directly, use the lilv_instance_* functions.

  The returned descriptor is shared and must not be deleted.

  This function is a simple accessor and may be called at any time.

LV2_Handle lilv_instance_get_handle(const LilvInstance *instance)

  Get the LV2_Handle of the plugin instance.

  Normally hosts should not need to access the LV2_Handle directly, use the lilv_instance_* functions.

  The returned handle is shared and must not be deleted.

  This function is a simple accessor and may be called at any time.