lv2dynparam.h File Reference

LV2 dynparam extension definition. More...

Go to the source code of this file.

Classes
struct	lv2dynparam_hints
struct	lv2dynparam_host_callbacks
struct	lv2dynparam_plugin_callbacks
Defines
#define	LV2DYNPARAM_BASE_URI   "http://home.gna.org/lv2dynparam/v1"
#define	LV2DYNPARAM_URI   LV2DYNPARAM_BASE_URI
#define	LV2DYNPARAM_MAX_STRING_SIZE   1024
#define	LV2DYNPARAM_PARAMETER_TYPE_FLOAT_URI   LV2DYNPARAM_BASE_URI "#parameter_float"
#define	LV2DYNPARAM_PARAMETER_TYPE_INT_URI   LV2DYNPARAM_BASE_URI "#parameter_int"
#define	LV2DYNPARAM_PARAMETER_TYPE_NOTE_URI   LV2DYNPARAM_BASE_URI "#parameter_note"
#define	LV2DYNPARAM_PARAMETER_TYPE_STRING_URI   LV2DYNPARAM_BASE_URI "#parameter_string"
#define	LV2DYNPARAM_PARAMETER_TYPE_FILENAME_URI   LV2DYNPARAM_BASE_URI "#parameter_filename"
#define	LV2DYNPARAM_PARAMETER_TYPE_BOOLEAN_URI   LV2DYNPARAM_BASE_URI "#parameter_boolean"
#define	LV2DYNPARAM_PARAMETER_TYPE_ENUM_URI   LV2DYNPARAM_BASE_URI "#parameter_enum"
Typedefs
typedef void *	lv2dynparam_parameter_handle
typedef void *	lv2dynparam_group_handle
typedef void *	lv2dynparam_command_handle

---

Detailed Description

LV2 dynparam extension definition.

Purpose

The purpose of this extension is to allow plugin parameters appear and disappear as response of existing parameter changes (i.e. number of voices) or executing commands (i.e. "add new voice"). It also allows grouping of parameters and groups. Groups can be used for things like ADSR abstraction, i.e. group of 4 float parameters.

Architectural overview

Plugin notifies host for changes through callbacks. During initialization, plugin notifies host about initial groups, parameters and commands through same callbacks used for later notification. There are callbacks to notify host for group, parameter and command disappears.

Groups are containers of other groups, parameters and commands. Parameters and groups have URIs. Parameter URIs are used to describe type of parameter (i.e. boolean, integer, string, etc.). Parameters are as simple as possible. There is one predefined Group URI for "generic group" type, i.e. container that is just that - a container of other groups, parameters and commands. Other group types are just hints and ones that are unknown to host, can be looked as generic ones. Only generic groups can contain groups. Groups of other types can contain only parameters. There is always one, root group. Name of the root groop is expected to match name of the plugin.

Groups, parameters and commands, have "name" containing short human readble description of object purpose.

Parameter ports, are bidirectional. Parameters have values, and some of them (depending of type) - range. Data storage for current, min and max values is in plugin memory. Host gets pointers to that memory and accesses the data in type specific way.

When plugin decides to change parameter value or range (as response to command execution or other parameter value change), it notifies host through callback.

When host decides to change parameter value or execute command (as resoponse to user action, i.e. knob rotation/button press, or some kind of automation), it calls plugin callback. In case of parameter, it first changes the value in the plugin data storage for particular parameter. Host ensures that values being set are within current range (if range is defined for particular port type).

Apart from initialization (host_attach), plugin may call host callbacks only as response to command execution or parameter change notification (from host).

Host serializes calls to plugin dynparam callbacks and the run/connect_port lv2 callbacks. Thus plugin does not need to take special measures for thread safety. in callbacks called by host.

Plugin can assume that host will never call dynamic parameter functions when lv2 plugin callbacks (like run and connect_port) are being called. I.e. calls are serialized, no need for locks in plugin. Plugin must not suspend execution (sleep/lock) while being called by host. If it needs to sleep to implement action requested by host, like allocation of data for new voice, the allocation should be done in background thread and when ready, transfered to the realtime code. During initialization (host_attach) plugin is allowed to sleep. Thus conventional memory allocation is allowed in host_attach.

Intialization sequence

1. Host discovers whether plugin supports the extension by inspecting the RDF Turtle file.
2. Host calls lv2 extension_data callback, plugin returns pointer to struct lv2dynparam_plugin_callbacks containing pointers to several funtions, including host_attach.
3. For each instantiated plugin supporting this extension, host calls host_attach function with parameters:
   • a LV2_Handle, plugin instance handle
   • pointer to struct lv2dynparam_host_callbacks, containing pointers to several functions, to be called by plugin.
   • instance host context, opaque pointer
4. During initialization (host_attach), initial groups and parameters appear and host callbacks are called by plugin.

Parameter types

• float, with range
• 32-bit 2's complement signed int, with range
• midi note, value stored as byte, with range
• string
• filename
• boolean, value stored as byte, non-zero means TRUE, zero means FALSE

Notes:

• if function fails, variables where output parameters are normally stored remain unmodified.
• If host callback, called by plugin, fails - plugin should try the operation later.

---

Define Documentation

#define LV2DYNPARAM_BASE_URI   "http://home.gna.org/lv2dynparam/v1"

base URI to be used for composing real URIs (internal use only)

#define LV2DYNPARAM_MAX_STRING_SIZE   1024

max size of name and type_uri buffers, including terminating zero char

#define LV2DYNPARAM_PARAMETER_TYPE_BOOLEAN_URI   LV2DYNPARAM_BASE_URI "#parameter_boolean"

URI for boolean parameter

#define LV2DYNPARAM_PARAMETER_TYPE_ENUM_URI   LV2DYNPARAM_BASE_URI "#parameter_enum"

URI for enumeration parameter

#define LV2DYNPARAM_PARAMETER_TYPE_FILENAME_URI   LV2DYNPARAM_BASE_URI "#parameter_filename"

URI for filename parameter

#define LV2DYNPARAM_PARAMETER_TYPE_FLOAT_URI   LV2DYNPARAM_BASE_URI "#parameter_float"

URI for float parameter

#define LV2DYNPARAM_PARAMETER_TYPE_INT_URI   LV2DYNPARAM_BASE_URI "#parameter_int"

URI for integer parameter

#define LV2DYNPARAM_PARAMETER_TYPE_NOTE_URI   LV2DYNPARAM_BASE_URI "#parameter_note"

URI for note parameter

#define LV2DYNPARAM_PARAMETER_TYPE_STRING_URI   LV2DYNPARAM_BASE_URI "#parameter_string"

URI for string parameter

#define LV2DYNPARAM_URI   LV2DYNPARAM_BASE_URI

URI of the LV2 extension defined in this file

---

Typedef Documentation

typedef void* lv2dynparam_command_handle

handle identifying command, supplied by plugin

typedef void* lv2dynparam_group_handle

handle identifying group, supplied by plugin

typedef void* lv2dynparam_parameter_handle

handle identifying parameter, supplied by plugin

---