aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2012-06-14 21:09:39 +0000
committerDavid Robillard <d@drobilla.net>2012-06-14 21:09:39 +0000
commit301a6f2267a795420a6e8bd3d7ea814670a02bfd (patch)
tree9756dfaf55f2a069230812a82e2469ab48417dfa
parent0faeed1d24ce6c9a30c62311c6c409d5bacde0f6 (diff)
downloadlv2-301a6f2267a795420a6e8bd3d7ea814670a02bfd.tar.xz
Improve documentation.
-rw-r--r--plugins/eg-amp.lv2/amp.c15
-rw-r--r--plugins/eg-amp.lv2/manifest.ttl.in31
2 files changed, 31 insertions, 15 deletions
diff --git a/plugins/eg-amp.lv2/amp.c b/plugins/eg-amp.lv2/amp.c
index 344f7b4..189a697 100644
--- a/plugins/eg-amp.lv2/amp.c
+++ b/plugins/eg-amp.lv2/amp.c
@@ -40,12 +40,13 @@ typedef enum {
/** Plugin instance. */
typedef struct {
+ // Port buffers
float* gain;
float* input;
float* output;
} Amp;
-/** Called to create a new plugin instance. */
+/** Create a new plugin instance. */
static LV2_Handle
instantiate(const LV2_Descriptor* descriptor,
double rate,
@@ -57,7 +58,7 @@ instantiate(const LV2_Descriptor* descriptor,
return (LV2_Handle)amp;
}
-/** Called to connect a port to a buffer (audio thread, must be RT safe). */
+/** Connect a port to a buffer (audio thread, must be RT safe). */
static void
connect_port(LV2_Handle instance,
uint32_t port,
@@ -78,7 +79,7 @@ connect_port(LV2_Handle instance,
}
}
-/** Called to initialise and prepare the instance for running. */
+/** Initialise and prepare the plugin instance for running. */
static void
activate(LV2_Handle instance)
{
@@ -87,7 +88,7 @@ activate(LV2_Handle instance)
#define DB_CO(g) ((g) > -90.0f ? powf(10.0f, (g) * 0.05f) : 0.0f)
-/** Called to process a block of audio (audio thread, must be RT safe). */
+/** Process a block of audio (audio thread, must be RT safe). */
static void
run(LV2_Handle instance, uint32_t n_samples)
{
@@ -104,21 +105,21 @@ run(LV2_Handle instance, uint32_t n_samples)
}
}
-/** Called when running is finished (counterpart to activate()). */
+/** Finish running (counterpart to activate()). */
static void
deactivate(LV2_Handle instance)
{
/* Nothing to do here in this trivial mostly stateless plugin. */
}
-/** Called to destroy a plugin instance (counterpart to instantiate()). */
+/** Destroy a plugin instance (counterpart to instantiate()). */
static void
cleanup(LV2_Handle instance)
{
free(instance);
}
-/** Called to access extension data provided by the plugin. */
+/** Return extension data provided by the plugin. */
const void*
extension_data(const char* uri)
{
diff --git a/plugins/eg-amp.lv2/manifest.ttl.in b/plugins/eg-amp.lv2/manifest.ttl.in
index 9d02b02..2813473 100644
--- a/plugins/eg-amp.lv2/manifest.ttl.in
+++ b/plugins/eg-amp.lv2/manifest.ttl.in
@@ -33,8 +33,13 @@
# Explanation
#
+# The token @LIB_EXT@ above is replaced by the build system (waf) by the
+# appropriate extension for the current platform (e.g. .so, .dylib, .dll),
+# which is why this file is called manifest.ttl.in and not manifest.ttl. This
+# documentation assumes .so for simplicity.
+#
# In short, this declares that the resource with URI
-# "http://lv2plug.in/plugins/eg-amp") is an LV2 plugin, with executable code in
+# "http://lv2plug.in/plugins/eg-amp" is an LV2 plugin, with executable code in
# the file "amp.so" and a full description in "amp.ttl". These paths are
# relative to the bundle directory.
#
@@ -46,17 +51,19 @@
# 2 | <http://lv2plug.in/plugins/eg-amp> | lv2:binary | <amp.so>
# 3 | <http://lv2plug.in/plugins/eg-amp> | rdfs:seeAlso | <amp.ttl>
#
-# The semicolon is used to continue the previous subject, an equivalent
+# The semicolon is used to continue the previous subject; an equivalent
# but more verbose syntax for the same data is:
-#
-# <http://lv2plug.in/plugins/eg-amp> a lv2:Plugin .
-# <http://lv2plug.in/plugins/eg-amp> lv2:binary <amp.so> .
-# <http://lv2plug.in/plugins/eg-amp> rdfs:seeAlso <amp.ttl> .
+
+<http://lv2plug.in/plugins/eg-amp> a lv2:Plugin .
+<http://lv2plug.in/plugins/eg-amp> lv2:binary <amp.so> .
+<http://lv2plug.in/plugins/eg-amp> rdfs:seeAlso <amp.ttl> .
+
+# (Since this data is equivalent, it is safe, if pointless, to list it twice)
#
# Note that the documentation for a URI can often be found by visiting that URI
# in a web browser, e.g. the documentation for lv2:binary can be found at
-# <http://lv2plug.in/ns/lv2core#binary>. If you encounter a predicate in some
-# data which you do not understand, try this first.
+# <http://lv2plug.in/ns/lv2core#binary>. If you encounter a URI in some data
+# which you do not understand, try this first.
#
# Note the URI of a plugin does NOT need to be an actual web address, it's just
# a global identifier. It is, however, a good idea to use an actual web
@@ -64,6 +71,14 @@
# downloads, etc. Note there are compatibility rules for when the URI of a
# plugin must be changed, see the LV2 specification[4] for details.
#
+# AUTHORS MUST NOT CREATE URIS AT DOMAINS THEY DO NOT CONTROL WITHOUT
+# PERMISSION, AND *ESPECIALLY* MUST NOT CREATE SYNTACTICALLY INVALID URIS,
+# E.G. WHERE THE PORTION FOLLOWING "http://" IS NOT AN ACTUAL DOMAIN NAME. If
+# you need an example URI, the domain http://example.org/ is reserved for this
+# purpose. It is best to use web URIs, e.g. at the domain where plugins are
+# hosted for download, even if there is currently no documents hosted there.
+# If this is truly impossible, use a URN, e.g. urn:myplugs:superamp.
+#
# A detailed explanation of each statement follows.
#
# 1: <http://lv2plug.in/plugins/eg-amp> a lv2:Plugin