aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2010-10-05 18:51:31 +0000
committerDavid Robillard <d@drobilla.net>2010-10-05 18:51:31 +0000
commit5c0e357c9167dc0bd17d5c365786b392ab456baf (patch)
treef83ed7163e0045d912518b022d93ee4859a694f3
parentff31add4bbdcd0b21a8f50482e65a521706c0597 (diff)
downloadlv2-5c0e357c9167dc0bd17d5c365786b392ab456baf.tar.xz
Move textey documentation to lv2.ttl (for nice generated documentation).
Update somewhat cobwebby documentation. Clean up and shrink lv2.h.
-rw-r--r--core.lv2/lv2.h135
-rw-r--r--core.lv2/lv2.ttl71
2 files changed, 93 insertions, 113 deletions
diff --git a/core.lv2/lv2.h b/core.lv2/lv2.h
index ded1512..f1758cf 100644
--- a/core.lv2/lv2.h
+++ b/core.lv2/lv2.h
@@ -1,9 +1,9 @@
-/* LV2 - LADSPA (Linux Audio Developer's Simple Plugin API) Version 2
- * Revision 1
+/* LV2 - An audio plugin interface specification
+ * Revision 4
*
* Copyright (C) 2000-2002 Richard W.E. Furse, Paul Barton-Davis,
* Stefan Westerfeld.
- * Copyright (C) 2006-2008 Steve Harris, David Robillard.
+ * Copyright (C) 2006-2010 Steve Harris, David Robillard.
*
* This header is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as published
@@ -21,6 +21,11 @@
* USA.
*/
+/** @file lv2.h
+ * C header for the LV2 specification <http://lv2plug.in/ns/lv2core>.
+ * Revision: 4
+ */
+
#ifndef LV2_H_INCLUDED
#define LV2_H_INCLUDED
@@ -30,85 +35,7 @@
extern "C" {
#endif
-
-/* ************************************************************************* */
-
-
-/** @file lv2.h
- * C header for the LV2 specification <http://lv2plug.in/ns/lv2core>.
- * Revision: 1
- *
- * == Overview ==
- *
- * There are a large number of open source and free software synthesis
- * packages in use or development at this time. This API ('LV2')
- * attempts to give programmers the ability to write simple 'plugin'
- * audio processors in C/C++ and link them dynamically ('plug') into
- * a range of these packages ('hosts'). It should be possible for any
- * host and any plugin to communicate completely through this interface.
- *
- * This API is deliberately as short and simple as possible.
- * The information required to use a plugin is in a companion data
- * (RDF) file. The shared library portion of the API (defined in this
- * header) does not contain enough information to make use of the plugin
- * possible - the data file is mandatory.
- *
- * Plugins are expected to distinguish between control rate and audio
- * rate data (or other types of data defined by extensions). Plugins have
- * 'ports' that are inputs or outputs and each plugin is 'run' for a 'block'
- * corresponding to a short time interval measured in samples. Audio rate
- * data is communicated using arrays with one element per sample processed,
- * allowing a block of audio to be processed by the plugin in a single
- * pass. Control rate data is communicated using single values. Control
- * rate data has a single value at the start of a call to the 'run()'
- * function, and may be considered to remain this value for its duration.
- * Thus the 'control rate' is determined by the block size, controlled by
- * the host. The plugin may assume that all its input and output ports have
- * been connected to the relevant data location (see the 'connect_port()'
- * function below) before it is asked to run, unless the port has been set
- * 'connection optional' in the plugin's data file.
- *
- * Plugins will reside in shared object files suitable for dynamic linking
- * by dlopen() and family. The file will provide a number of 'plugin
- * types' that can be used to instantiate actual plugins (sometimes known
- * as 'plugin instances') that can be connected together to perform tasks.
- * The host can access these plugin types using the lv2_descriptor()
- * function.
- *
- * This API contains very limited error-handling.
- *
- * == 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:
- *
- * - Discovery class: lv2_descriptor(), extension_data()
- * - Instantiation class: instantiate(), cleanup(), activate(), deactivate()
- * - Audio class: run(), connect_port()
- *
- * Extensions to this specification which add new functions MUST declare in
- * which of these classes the functions belong, or define new classes for them.
- * The rules that hosts must follow are these:
- *
- * - When a function from the Discovery class is running, no other
- * functions in the same shared object file may run.
- * - When a function from the Instantiation class is running for a plugin
- * instance, no other functions for that instance may run.
- * - When a function is running for a plugin instance, no other
- * function in the same class may run for that instance.
- *
- * Any simultaneous calls that are not explicitly forbidden by these rules
- * are allowed. For example, a host may call run() for two different plugin
- * instances simultaneously.
- */
-
-
-/* ************************************************************************* */
-
-
+
/** Plugin Handle.
*
* This plugin handle indicates a particular instance of the plugin
@@ -117,10 +44,7 @@ extern "C" {
* may use it to reference internal instance data. */
typedef void * LV2_Handle;
-
-/* ************************************************************************* */
-
-
+
/** Feature data.
*
* These are passed to a plugin's instantiate method to represent a special
@@ -130,6 +54,7 @@ typedef void * LV2_Handle;
* LV2 specification does not define any features; hosts are not required
* to use this facility. */
typedef struct _LV2_Feature {
+
/** A globally unique, case-sensitive identifier for this feature.
*
* This MUST be defined in the specification of any LV2 extension which
@@ -145,13 +70,11 @@ typedef struct _LV2_Feature {
* this feature.
* If no data is required, this may be set to NULL. */
void * data;
+
} LV2_Feature;
-/* ************************************************************************* */
-
-
-/** Descriptor for a Type of Plugin.
+/** Descriptor for a Plugin.
*
* This structure is used to describe a plugin type. It provides a number
* of functions to instantiate it, link it to buffers and run it. */
@@ -335,33 +258,28 @@ typedef struct _LV2_Descriptor {
} LV2_Descriptor;
-/* ****************************************************************** */
-
-
-/** Accessing Plugin Types.
+/** Accessing Plugins.
*
- * The exact mechanism by which plugins are loaded is host-dependent,
- * however all most hosts will need to know is the URI of the plugin they
- * wish to load. The environment variable LV2_PATH, if present, should
- * contain a colon-separated path indicating directories (containing
- * plugin bundle subdirectories) that should be searched (in order)
- * for plugins. It is expected that hosts will use a library to provide
- * this functionality.
+ * The exact mechanism by which plugins are loaded is host and system
+ * dependent, however all hosts need to know is the URI of the plugin they
+ * wish to load. Documentation on best practices for plugin discovery can
+ * be found at <http://lv2plug.in>, however it is expected that hosts use
+ * a library to provide this functionality.
*
- * A plugin programmer must include a function called "lv2_descriptor"
+ * A plugin programmer MUST include a function called "lv2_descriptor"
* with the following function prototype within the shared object
* file. This function will have C-style linkage (if you are using
* C++ this is taken care of by the 'extern "C"' clause at the top of
- * the file).
+ * this file).
*
* A host will find the plugin shared object file by one means or another,
* find the lv2_descriptor() function, call it, and proceed from there.
*
* Plugin types are accessed by index (not ID) using values from 0
- * upwards. Out of range indexes must result in this function returning
+ * upwards. Out of range indexes MUST result in this function returning
* NULL, so the plugin count can be determined by checking for the least
* index that results in NULL being returned. Index has no meaning,
- * hosts MUST NOT depend on it remaining constant (ie when serialising)
+ * hosts MUST NOT depend on it remaining constant (e.g. when serialising)
* in any way. */
const LV2_Descriptor * lv2_descriptor(uint32_t index);
@@ -371,12 +289,8 @@ typedef const LV2_Descriptor *
(*LV2_Descriptor_Function)(uint32_t index);
-/* ******************************************************************** */
-
-
/* Put this (LV2_SYMBOL_EXPORT) before any functions that are to be loaded
- * by the host as a symbol from the dynamic library.
- */
+ * by the host as a symbol from the dynamic library. */
#ifdef WIN32
#define LV2_SYMBOL_EXPORT __declspec(dllexport)
#else
@@ -389,4 +303,3 @@ typedef const LV2_Descriptor *
#endif
#endif /* LV2_H_INCLUDED */
-
diff --git a/core.lv2/lv2.ttl b/core.lv2/lv2.ttl
index 23f014d..c3abdbf 100644
--- a/core.lv2/lv2.ttl
+++ b/core.lv2/lv2.ttl
@@ -67,7 +67,7 @@ more details.
doap:name "LV2" ;
doap:homepage <http://lv2plug.in> ;
doap:created "2004-04-21" ;
- doap:shortdesc "An audio processing plugin specification" ;
+ doap:shortdesc "An audio plugin interface specification" ;
doap:programming-language "C" ;
doap:release [
doap:revision "4" ;
@@ -83,7 +83,74 @@ more details.
foaf:name "David Robillard" ;
foaf:homepage <http://drobilla.net/> ;
rdfs:seeAlso <http://drobilla.net/drobilla.rdf>
- ] .
+ ] ; rdfs:comment """
+<h4>Overview</h4>
+There are a large number of open source and free software synthesis packages in
+use or development at this time. This API ("LV2") attempts to give programmers
+the ability to write simple "plugin" audio processors in C/C++ and link
+them dynamically ("plug" them) into a range of these packages ("hosts").
+It should be possible for any host and any plugin to communicate completely
+through this interface.
+
+This API is deliberately as short and simple as possible. The information
+required to use a plugin is in a companion data (RDF) file. The shared
+library portion of the API does not contain enough information to make use
+of the plugin possible; the data file is mandatory.
+
+Plugins can operate on any type of data. Plugins have "ports" that are
+inputs or outputs and each plugin is "run" for a "block" corresponding to
+a short time interval measured in samples. The plugin may assume that all
+its input and output ports have been connected to the relevant data location
+(using the connect_port() function) before it is asked to run, unless the
+port has been set "connection optional" in the plugin's data file.
+
+This "core" specification defines two types of port data, equivalent to those
+in LADSPA: control rate and audio rate. Audio rate data is communicated using
+arrays with one <code>float</code> element per sample processed, allowing
+a block of audio to be processed by the plugin in a single pass. Control
+rate data is communicated using single <code>float</code> values. Control
+rate data has a single value at the start of a call to the run() function
+which is considered valid for the duration of the call to run(). Thus the
+"control rate" is determined by the block size, controlled by the host.
+
+Plugins reside in shared object files suitable for dynamic linking (e.g. by
+dlopen() and family). This file provides one or many plugins via the
+lv2_descriptor() function. These plugins can be instantiated to create
+"plugin instances", which can be connected together to perform tasks.
+
+This API contains very limited error-handling.
+
+<h4>Threading Rules</h4> 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:
+
+<dl>
+<dt>Discovery Class</dt>
+<dd>lv2_descriptor(), extension_data()</dd>
+<dt>Instantiation Class</dt>
+<dd>instantiate(), cleanup(), activate(), deactivate()</dd>
+<dt>Audio Class</dt>
+<dd>run(), connect_port()</dd>
+</dl>
+
+Extensions to this specification which add new functions MUST declare in
+which of these classes the functions belong, or define new classes for them.
+The rules that hosts MUST follow are:
+
+<ul>
+<li>When a function is running for a plugin instance, no other
+ function in the same class may run for that instance.</li>
+<li>When a function from the Discovery class is running, no other
+ functions in the same shared object file may run.</li>
+<li>When a function from the Instantiation class is running for a plugin
+ instance, no other functions for that instance may run.</li>
+</ul>
+Any simultaneous calls that are not explicitly forbidden by these rules
+are allowed. For example, a host may call run() for two different plugin
+instances simultaneously.
+""" .