From 40e23fa7596906edf7096ed6f4938bcf4b561f66 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Fri, 21 Oct 2011 00:46:10 +0000 Subject: Rewrite description. --- core.lv2/lv2.ttl | 140 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 72 insertions(+), 68 deletions(-) diff --git a/core.lv2/lv2.ttl b/core.lv2/lv2.ttl index 8d33877..f77a2c4 100644 --- a/core.lv2/lv2.ttl +++ b/core.lv2/lv2.ttl @@ -34,12 +34,11 @@ An LV2 Resource (e.g. plugin, specification, or any other LV2 related thing). lv2:Specification a rdfs:Class , owl:Class ; rdfs:subClassOf lv2:Resource ; - rdfs:comment """ + lv2:documentation """ An LV2 specification (i.e. this specification, or an LV2 extension). -Specification data, like plugin data, is distributed in standardized bundles -so hosts may discover all present LV2 data. See http://lv2plug.in/docs for -more details. +Specification data, like plugin data, is distributed in bundles +so hosts may discover all present LV2 data. """ . lv2:documentation a rdf:Property , owl:DatatypeProperty ; @@ -85,75 +84,72 @@ devices). See Overview -

LV2 gives programmers the ability to write audio processors (or -plugins) in C/C++ which can be dynamically loaded into a range of -applications (or hosts).

- -

This core specification is deliberately as short and simple as -possible, but is designed so that extensions can be defined to add more -advanced features. The shared library portion of the API includes only what -must necessarily be written in code. The information required to use a plugin -is in a companion data file, written in Turtle. Plugin libraries do -not contain enough information to make use of the plugin possible; the data -file is mandatory. This makes using, adding, and manipulating plugin data -flexible and avoids binary compatibility issues.

- -

Plugins can operate on any type of data, which is input/output via -ports. Data is processed by first connecting each port to a -buffer, then repeatedly calling a plugin's run() method to process -a block of data of some host-specified length (measured in audio -frames).

- -

The LV2 core specification defines two types of port, equivalent to those in -LADSPA: control and -audio. Audio data is communicated using arrays with one -float element per sample, allowing a block of audio to be -processed by the plugin in a single call to run(). Control data is -communicated using single float values, which are fixed and valid -for the duration of the call to run(). Thus the control -rate is determined by the block size, which is controlled by the host (and -not necessarily constant).

- -

Plugins reside in shared object files suitable for dynamic linking (e.g. via -dlopen()). This library provides one or more LV2 is an interface for writing audio processors, or plugins, in +C/C++ which can be dynamically loaded into many applications, or hosts. +This core specification is simple and minimal, but is designed so that +extensions can be defined to add more advanced features, making it +possibly to implement nearly any feature imaginable.

+ +

LV2 maintains a strong distinction between code and data. +Plugin code is in a shared library, while data is in a companion data file +written in Turtle. +Code, data, and any other resources (e.g. waveforms) are shipped together in a +bundle directory. The code contains only the executable portions of the +plugin which inherently must be written in code. All other data is +provided in the data file(s). This makes plugin data flexible and extensible, +and allows the host to do everything but run the plugin without executing any +code at all. Among other advantages, this makes hosts more robust (broken +plugins can't crash a host during discovery) and allows non-C programs to work +with LV2 data (such as the pure Python script +which generated this page). LV2 itself and extensions are distributed +similarly.

+ +

An LV2 plugin library is suitable for dynamic loading (e.g. via +dlopen()) and provides one or more plugin descriptors via the -lv2_descriptor() function. These plugins can be instantiated to -create plugin instances, which can be run directly on data or connected +lv2_descriptor() function. These can be instantiated to create +plugin instances, which can be run directly on data or connected together to perform advanced signal processing tasks.

-

Threading Rules

- -

Certain hosts may need to call the functions provided by a plugin from -multiple threads. For this to be safe, the plugin must be written so that those -functions can be executed simultaneously without problems. To facilitate this, -the functions provided by a plugin are divided into classes:

+

Plugins communicate via ports, which can transmit any type of data. +Data is processed by first connecting each port to a buffer, then +repeatedly calling a plugin's run() method to process blocks of +data.

+ +

This core specification defines two types of port, equivalent to those in LADSPA: ControlPort and AudioPort. +Audio ports contain arrays with one float element per sample, +allowing a block of audio to be processed in a single call to +run(). Control ports contain single float values, +which are fixed and valid for the duration of the call to run(). +Thus the control rate is determined by the block size, which is +controlled by the host (and not necessarily constant).

-
-
Discovery Class
-
lv2_descriptor(), -LV2_Descriptor::extension_data()
- -
Instantiation Class
-
LV2_Descriptor::instantiate(), -LV2_Descriptor::cleanup(), -LV2_Descriptor::activate(), -LV2_Descriptor::deactivate()
- -
Audio Class
-
LV2_Descriptor::run(), -LV2_Descriptor::connect_port()
-
- -

Plugin functions in any class MUST NOT manipulate any state which might -affect other plugin or host code, e.g. by using non-reentrant global -functions.

+

Threading Rules

-

Extensions to this specification which add new plugin functions MUST declare -in which of these classes the functions belong, or define new classes for -them. Extensions which add new host-provided functions MUST declare from which -of these classes the functions may be called, or otherwise precisely describe -their threading rules.

+

To faciliate use in multi-threaded programs, LV2 functions are partitioned +into several threading classes:

+ + + + + + + + + + + + + + + + + + + +
Discovery ClassInstantiation ClassAudio Class
lv2_descriptor()LV2_Descriptor::instantiate()LV2_Descriptor::run()
LV2_Descriptor::extension_data()LV2_Descriptor::cleanup()LV2_Descriptor::connect_port()
LV2_Descriptor::activate()
LV2_Descriptor::deactivate()

The rules that hosts MUST follow are: