From 301a6f2267a795420a6e8bd3d7ea814670a02bfd Mon Sep 17 00:00:00 2001 From: David Robillard Date: Thu, 14 Jun 2012 21:09:39 +0000 Subject: Improve documentation. --- plugins/eg-amp.lv2/amp.c | 15 ++++++++------- plugins/eg-amp.lv2/manifest.ttl.in | 31 +++++++++++++++++++++++-------- 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 | | lv2:binary | # 3 | | rdfs:seeAlso | # -# 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: -# -# a lv2:Plugin . -# lv2:binary . -# rdfs:seeAlso . + + a lv2:Plugin . + lv2:binary . + rdfs:seeAlso . + +# (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 -# . If you encounter a predicate in some -# data which you do not understand, try this first. +# . 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: a lv2:Plugin -- cgit v1.2.1 8' href='#n78'>78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168