falkTX
/
Carla
mirror of https://github.com/falkTX/Carla
1
0
Fork 0
Code Releases 42 Activity
Browse Source

Update to latest LV2 spec

tags/1.9.4
falkTX 11 years ago
parent
1b050433a5
commit
0df06188ae
6 changed files with 246 additions and 222 deletions
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +215
    -215
      source/includes/lv2/lv2.h
  2. +1
    -0
      source/includes/lv2/lv2_external_ui.h
  3. +4
    -1
      source/includes/lv2/lv2_programs.h
  4. +1
    -1
      source/includes/lv2/lv2_rtmempool.h
  5. +6
    -5
      source/includes/lv2/state.h
  6. +19
    -0
      source/includes/lv2/ui.h

+ 215
- 215
source/includes/lv2/lv2.h View File

@@ -138,20 +138,20 @@ typedef void * LV2_Handle;
Some features, such as lv2:isLive, do not require the host to pass data. Some features, such as lv2:isLive, do not require the host to pass data.
*/ */
typedef struct _LV2_Feature { typedef struct _LV2_Feature {
/**
A globally unique, case-sensitive identifier (URI) for this feature.
/**
A globally unique, case-sensitive identifier (URI) for this feature.


This MUST be a valid URI string as defined by RFC 3986.
*/
const char * URI;
This MUST be a valid URI string as defined by RFC 3986.
*/
const char * URI;


/**
Pointer to arbitrary data.
/**
Pointer to arbitrary data.


The format of this data is defined by the extension which describes the
feature with the given @ref URI.
*/
void * data;
The format of this data is defined by the extension which describes the
feature with the given @ref URI.
*/
void * data;
} LV2_Feature; } LV2_Feature;


/** /**
@@ -161,182 +161,182 @@ typedef struct _LV2_Feature {
a plugin. a plugin.
*/ */
typedef struct _LV2_Descriptor { typedef struct _LV2_Descriptor {
/**
A globally unique, case-sensitive identifier for this plugin.
This MUST be a valid URI string as defined by RFC 3986. All plugins with
the same URI MUST be compatible to some degree, see
http://lv2plug.in/ns/lv2core for details.
*/
const char * URI;
/**
Instantiate the plugin.
Note that instance initialisation should generally occur in activate()
rather than here. If a host calls instantiate(), it MUST call cleanup()
at some point in the future.
@param descriptor Descriptor of the plugin to instantiate.
@param sample_rate Sample rate, in Hz, for the new plugin instance.
@param bundle_path Path to the LV2 bundle which contains this plugin
binary. It MUST include the trailing directory separator (e.g. '/') so
that simply appending a filename will yield the path to that file in the
bundle.
@param features A NULL terminated array of LV2_Feature structs which
represent the features the host supports. Plugins may refuse to
instantiate if required features are not found here. However, hosts MUST
NOT use this as a discovery mechanism: instead, use the RDF data to
determine which features are required and do not attempt to instantiate
unsupported plugins at all. This parameter MUST NOT be NULL, i.e. a host
that supports no features MUST pass a single element array containing
NULL.
@return A handle for the new plugin instance, or NULL if instantiation
has failed.
*/
LV2_Handle (*instantiate)(const struct _LV2_Descriptor * descriptor,
double sample_rate,
const char * bundle_path,
const LV2_Feature *const * features);
/**
Connect a port on a plugin instance to a memory location.
Plugin writers should be aware that the host may elect to use the same
buffer for more than one port and even use the same buffer for both
input and output (see lv2:inPlaceBroken in lv2.ttl).
If the plugin has the feature lv2:hardRTCapable then there are various
things that the plugin MUST NOT do within the connect_port() function;
see lv2core.ttl for details.
connect_port() MUST be called at least once for each port before run()
is called, unless that port is lv2:connectionOptional. The plugin must
pay careful attention to the block size passed to run() since the block
allocated may only just be large enough to contain the data, and is not
guaranteed to remain constant between run() calls.
connect_port() may be called more than once for a plugin instance to
allow the host to change the buffers that the plugin is reading or
writing. These calls may be made before or after activate() or
deactivate() calls.
@param instance Plugin instance containing the port.
@param port Index of the port to connect. The host MUST NOT try to
connect a port index that is not defined in the plugin's RDF data. If
it does, the plugin's behaviour is undefined (a crash is likely).
@param data_location Pointer to data of the type defined by the port
type in the plugin's RDF data (e.g. an array of float for an
lv2:AudioPort). This pointer must be stored by the plugin instance and
used to read/write data when run() is called. Data present at the time
of the connect_port() call MUST NOT be considered meaningful.
*/
void (*connect_port)(LV2_Handle instance,
uint32_t port,
void * data_location);
/**
Initialise a plugin instance and activate it for use.
This is separated from instantiate() to aid real-time support and so
that hosts can reinitialise a plugin instance by calling deactivate()
and then activate(). In this case the plugin instance MUST reset all
state information dependent on the history of the plugin instance except
for any data locations provided by connect_port(). If there is nothing
for activate() to do then this field may be NULL.
When present, hosts MUST call this function once before run() is called
for the first time. This call SHOULD be made as close to the run() call
as possible and indicates to real-time plugins that they are now live,
however plugins MUST NOT rely on a prompt call to run() after
activate().
The host MUST NOT call activate() again until deactivate() has been
called first. If a host calls activate(), it MUST call deactivate() at
some point in the future. Note that connect_port() may be called before
or after activate().
*/
void (*activate)(LV2_Handle instance);
/**
Run a plugin instance for a block.
Note that if an activate() function exists then it must be called before
run(). If deactivate() is called for a plugin instance then run() may
not be called until activate() has been called again.
If the plugin has the feature lv2:hardRTCapable then there are various
things that the plugin MUST NOT do within the run() function (see
lv2core.ttl for details).
As a special case, when @p sample_count == 0, the plugin should update
any output ports that represent a single instant in time (e.g. control
ports, but not audio ports). This is particularly useful for latent
plugins, which should update their latency output port so hosts can
pre-roll plugins to compute latency. Plugins MUST NOT crash when
@p sample_count == 0.
@param instance Instance to be run.
@param sample_count The block size (in samples) for which the plugin
instance must run.
*/
void (*run)(LV2_Handle instance,
uint32_t sample_count);
/**
Deactivate a plugin instance (counterpart to activate()).
Hosts MUST deactivate all activated instances after they have been run()
for the last time. This call SHOULD be made as close to the last run()
call as possible and indicates to real-time plugins that they are no
longer live, however plugins MUST NOT rely on prompt deactivation. If
there is nothing for deactivate() to do then this field may be NULL
Deactivation is not similar to pausing since the plugin instance will be
reinitialised by activate(). However, deactivate() itself MUST NOT fully
reset plugin state. For example, the host may deactivate a plugin, then
store its state (using some extension to do so).
Hosts MUST NOT call deactivate() unless activate() was previously
called. Note that connect_port() may be called before or after
deactivate().
*/
void (*deactivate)(LV2_Handle instance);
/**
Clean up a plugin instance (counterpart to instantiate()).
Once an instance of a plugin has been finished with it must be deleted
using this function. The instance handle passed ceases to be valid after
this call.
If activate() was called for a plugin instance then a corresponding call
to deactivate() MUST be made before cleanup() is called. Hosts MUST NOT
call cleanup() unless instantiate() was previously called.
*/
void (*cleanup)(LV2_Handle instance);
/**
Return additional plugin data defined by some extenion.
A typical use of this facility is to return a struct containing function
pointers to extend the LV2_Descriptor API.
The actual type and meaning of the returned object MUST be specified
precisely by the extension. This function MUST return NULL for any
unsupported URI. If a plugin does not support any extension data, this
field may be NULL.
The host is never responsible for freeing the returned value.
*/
const void * (*extension_data)(const char * uri);
/**
A globally unique, case-sensitive identifier for this plugin.
This MUST be a valid URI string as defined by RFC 3986. All plugins with
the same URI MUST be compatible to some degree, see
http://lv2plug.in/ns/lv2core for details.
*/
const char * URI;
/**
Instantiate the plugin.
Note that instance initialisation should generally occur in activate()
rather than here. If a host calls instantiate(), it MUST call cleanup()
at some point in the future.
@param descriptor Descriptor of the plugin to instantiate.
@param sample_rate Sample rate, in Hz, for the new plugin instance.
@param bundle_path Path to the LV2 bundle which contains this plugin
binary. It MUST include the trailing directory separator (e.g. '/') so
that simply appending a filename will yield the path to that file in the
bundle.
@param features A NULL terminated array of LV2_Feature structs which
represent the features the host supports. Plugins may refuse to
instantiate if required features are not found here. However, hosts MUST
NOT use this as a discovery mechanism: instead, use the RDF data to
determine which features are required and do not attempt to instantiate
unsupported plugins at all. This parameter MUST NOT be NULL, i.e. a host
that supports no features MUST pass a single element array containing
NULL.
@return A handle for the new plugin instance, or NULL if instantiation
has failed.
*/
LV2_Handle (*instantiate)(const struct _LV2_Descriptor * descriptor,
double sample_rate,
const char * bundle_path,
const LV2_Feature *const * features);
/**
Connect a port on a plugin instance to a memory location.
Plugin writers should be aware that the host may elect to use the same
buffer for more than one port and even use the same buffer for both
input and output (see lv2:inPlaceBroken in lv2.ttl).
If the plugin has the feature lv2:hardRTCapable then there are various
things that the plugin MUST NOT do within the connect_port() function;
see lv2core.ttl for details.
connect_port() MUST be called at least once for each port before run()
is called, unless that port is lv2:connectionOptional. The plugin must
pay careful attention to the block size passed to run() since the block
allocated may only just be large enough to contain the data, and is not
guaranteed to remain constant between run() calls.
connect_port() may be called more than once for a plugin instance to
allow the host to change the buffers that the plugin is reading or
writing. These calls may be made before or after activate() or
deactivate() calls.
@param instance Plugin instance containing the port.
@param port Index of the port to connect. The host MUST NOT try to
connect a port index that is not defined in the plugin's RDF data. If
it does, the plugin's behaviour is undefined (a crash is likely).
@param data_location Pointer to data of the type defined by the port
type in the plugin's RDF data (e.g. an array of float for an
lv2:AudioPort). This pointer must be stored by the plugin instance and
used to read/write data when run() is called. Data present at the time
of the connect_port() call MUST NOT be considered meaningful.
*/
void (*connect_port)(LV2_Handle instance,
uint32_t port,
void * data_location);
/**
Initialise a plugin instance and activate it for use.
This is separated from instantiate() to aid real-time support and so
that hosts can reinitialise a plugin instance by calling deactivate()
and then activate(). In this case the plugin instance MUST reset all
state information dependent on the history of the plugin instance except
for any data locations provided by connect_port(). If there is nothing
for activate() to do then this field may be NULL.
When present, hosts MUST call this function once before run() is called
for the first time. This call SHOULD be made as close to the run() call
as possible and indicates to real-time plugins that they are now live,
however plugins MUST NOT rely on a prompt call to run() after
activate().
The host MUST NOT call activate() again until deactivate() has been
called first. If a host calls activate(), it MUST call deactivate() at
some point in the future. Note that connect_port() may be called before
or after activate().
*/
void (*activate)(LV2_Handle instance);
/**
Run a plugin instance for a block.
Note that if an activate() function exists then it must be called before
run(). If deactivate() is called for a plugin instance then run() may
not be called until activate() has been called again.
If the plugin has the feature lv2:hardRTCapable then there are various
things that the plugin MUST NOT do within the run() function (see
lv2core.ttl for details).
As a special case, when @p sample_count == 0, the plugin should update
any output ports that represent a single instant in time (e.g. control
ports, but not audio ports). This is particularly useful for latent
plugins, which should update their latency output port so hosts can
pre-roll plugins to compute latency. Plugins MUST NOT crash when
@p sample_count == 0.
@param instance Instance to be run.
@param sample_count The block size (in samples) for which the plugin
instance must run.
*/
void (*run)(LV2_Handle instance,
uint32_t sample_count);
/**
Deactivate a plugin instance (counterpart to activate()).
Hosts MUST deactivate all activated instances after they have been run()
for the last time. This call SHOULD be made as close to the last run()
call as possible and indicates to real-time plugins that they are no
longer live, however plugins MUST NOT rely on prompt deactivation. If
there is nothing for deactivate() to do then this field may be NULL
Deactivation is not similar to pausing since the plugin instance will be
reinitialised by activate(). However, deactivate() itself MUST NOT fully
reset plugin state. For example, the host may deactivate a plugin, then
store its state (using some extension to do so).
Hosts MUST NOT call deactivate() unless activate() was previously
called. Note that connect_port() may be called before or after
deactivate().
*/
void (*deactivate)(LV2_Handle instance);
/**
Clean up a plugin instance (counterpart to instantiate()).
Once an instance of a plugin has been finished with it must be deleted
using this function. The instance handle passed ceases to be valid after
this call.
If activate() was called for a plugin instance then a corresponding call
to deactivate() MUST be made before cleanup() is called. Hosts MUST NOT
call cleanup() unless instantiate() was previously called.
*/
void (*cleanup)(LV2_Handle instance);
/**
Return additional plugin data defined by some extenion.
A typical use of this facility is to return a struct containing function
pointers to extend the LV2_Descriptor API.
The actual type and meaning of the returned object MUST be specified
precisely by the extension. This function MUST return NULL for any
unsupported URI. If a plugin does not support any extension data, this
field may be NULL.
The host is never responsible for freeing the returned value.
*/
const void * (*extension_data)(const char * uri);
} LV2_Descriptor; } LV2_Descriptor;


/** /**
@@ -397,34 +397,34 @@ typedef void* LV2_Lib_Handle;
lv2_lib_descriptor() function in the shared object. lv2_lib_descriptor() function in the shared object.
*/ */
typedef struct { typedef struct {
/**
Opaque library data which must be passed as the first parameter to all
the methods of this struct.
*/
LV2_Lib_Handle handle;
/**
The total size of this struct. This allows for this struct to be
expanded in the future if necessary. This MUST be set by the library to
sizeof(LV2_Lib_Descriptor). The host MUST NOT access any fields of this
struct beyond get_plugin() unless this field indicates they are present.
*/
uint32_t size;
/**
Destroy this library descriptor and free all related resources.
*/
void (*cleanup)(LV2_Lib_Handle handle);
/**
Plugin accessor.
Plugins are accessed by index using values from 0 upwards. Out of range
indices MUST result in this function returning NULL, so the host can
enumerate plugins by increasing @a index until NULL is returned.
*/
const LV2_Descriptor * (*get_plugin)(LV2_Lib_Handle handle,
uint32_t index);
/**
Opaque library data which must be passed as the first parameter to all
the methods of this struct.
*/
LV2_Lib_Handle handle;
/**
The total size of this struct. This allows for this struct to be
expanded in the future if necessary. This MUST be set by the library to
sizeof(LV2_Lib_Descriptor). The host MUST NOT access any fields of this
struct beyond get_plugin() unless this field indicates they are present.
*/
uint32_t size;
/**
Destroy this library descriptor and free all related resources.
*/
void (*cleanup)(LV2_Lib_Handle handle);
/**
Plugin accessor.
Plugins are accessed by index using values from 0 upwards. Out of range
indices MUST result in this function returning NULL, so the host can
enumerate plugins by increasing @a index until NULL is returned.
*/
const LV2_Descriptor * (*get_plugin)(LV2_Lib_Handle handle,
uint32_t index);
} LV2_Lib_Descriptor; } LV2_Lib_Descriptor;


/** /**


+ 1
- 0
source/includes/lv2/lv2_external_ui.h View File

@@ -60,6 +60,7 @@ typedef struct _LV2_External_UI_Widget {
* @param _this_ the UI context * @param _this_ the UI context
*/ */
void (*hide)(struct _LV2_External_UI_Widget * _this_); void (*hide)(struct _LV2_External_UI_Widget * _this_);

} LV2_External_UI_Widget; } LV2_External_UI_Widget;


#define LV2_EXTERNAL_UI_RUN(ptr) (ptr)->run(ptr) #define LV2_EXTERNAL_UI_RUN(ptr) (ptr)->run(ptr)


+ 4
- 1
source/includes/lv2/lv2_programs.h View File

@@ -157,7 +157,10 @@ typedef struct _LV2_Programs_Host {
* Parameter index is program index to change. * Parameter index is program index to change.
* When index is -1, host should reload all the programs. * When index is -1, host should reload all the programs.
* *
* NOTE: The plugin MUST NEVER call this function on a RT context or during run().
* The plugin MUST NEVER call this function on a RT context or during run().
*
* NOTE: This call is to inform the host about a program's bank, program or name change.
* It DOES NOT change the current selected program.
*/ */
void (*program_changed)(LV2_Programs_Handle handle, void (*program_changed)(LV2_Programs_Handle handle,
int32_t index); int32_t index);


+ 1
- 1
source/includes/lv2/lv2_rtmempool.h View File

@@ -12,7 +12,7 @@


/** /**
* @file lv2_rtmempool.h * @file lv2_rtmempool.h
* C header for the LV2 rtmempool extension <http://kxstudio.sf.net/ns/lv2ext/rtmempool>
* C header for the LV2 rtmempool extension <http://kxstudio.sf.net/ns/lv2ext/rtmempool>.
* *
*/ */




+ 6
- 5
source/includes/lv2/state.h View File

@@ -31,11 +31,12 @@
#define LV2_STATE_URI "http://lv2plug.in/ns/ext/state" #define LV2_STATE_URI "http://lv2plug.in/ns/ext/state"
#define LV2_STATE_PREFIX LV2_STATE_URI "#" #define LV2_STATE_PREFIX LV2_STATE_URI "#"


#define LV2_STATE__State LV2_STATE_PREFIX "State"
#define LV2_STATE__interface LV2_STATE_PREFIX "interface"
#define LV2_STATE__makePath LV2_STATE_PREFIX "makePath"
#define LV2_STATE__mapPath LV2_STATE_PREFIX "mapPath"
#define LV2_STATE__state LV2_STATE_PREFIX "state"
#define LV2_STATE__State LV2_STATE_PREFIX "State"
#define LV2_STATE__interface LV2_STATE_PREFIX "interface"
#define LV2_STATE__loadDefaultState LV2_STATE_PREFIX "loadDefaultState"
#define LV2_STATE__makePath LV2_STATE_PREFIX "makePath"
#define LV2_STATE__mapPath LV2_STATE_PREFIX "mapPath"
#define LV2_STATE__state LV2_STATE_PREFIX "state"


#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {


+ 19
- 0
source/includes/lv2/ui.h View File

@@ -41,6 +41,7 @@
#define LV2_UI__X11UI LV2_UI_PREFIX "X11UI" #define LV2_UI__X11UI LV2_UI_PREFIX "X11UI"
#define LV2_UI__binary LV2_UI_PREFIX "binary" #define LV2_UI__binary LV2_UI_PREFIX "binary"
#define LV2_UI__fixedSize LV2_UI_PREFIX "fixedSize" #define LV2_UI__fixedSize LV2_UI_PREFIX "fixedSize"
#define LV2_UI__idleInterface LV2_UI_PREFIX "idleInterface"
#define LV2_UI__noUserResize LV2_UI_PREFIX "noUserResize" #define LV2_UI__noUserResize LV2_UI_PREFIX "noUserResize"
#define LV2_UI__notifyType LV2_UI_PREFIX "notifyType" #define LV2_UI__notifyType LV2_UI_PREFIX "notifyType"
#define LV2_UI__parent LV2_UI_PREFIX "parent" #define LV2_UI__parent LV2_UI_PREFIX "parent"
@@ -337,6 +338,24 @@ typedef struct _LV2UI_Touch {
bool grabbed); bool grabbed);
} LV2UI_Touch; } LV2UI_Touch;


/**
UI Idle Feature (LV2_UI__idle)

This feature is an addition to the UI API that provides a callback for the
host to call rapidly, e.g. to drive the idle callback of a toolkit.
*/
typedef struct _LV2UI_Idle_Interface {
/**
Run a single iteration of the UI's idle loop.

This will be called "frequently" in the UI thread at a rate appropriate
for a toolkit main loop. There are no precise timing guarantees.

@return 0 on success, or anything else to stop being called.
*/
int (*idle)(LV2UI_Handle ui);
} LV2UI_Idle_Interface;

/** /**
Peak data for a slice of time, the update format for ui:peakProtocol. Peak data for a slice of time, the update format for ui:peakProtocol.
*/ */


Write Preview
Loading…
Cancel
Save