From 7b67c423a084898a2bc2f6569285550c0b6c3961 Mon Sep 17 00:00:00 2001 From: fundamental Date: Sun, 27 May 2018 23:12:15 -0400 Subject: Add initial WIP for more user friendly docs See May 2018 lv2-devel discussion for some of the motivations for the different style of documentation. --- plugins/eg-amp.lv2/amp.c | 27 +++++++++++++++++++++++---- plugins/eg-amp.lv2/amp.ttl | 4 ++++ 2 files changed, 27 insertions(+), 4 deletions(-) (limited to 'plugins/eg-amp.lv2') diff --git a/plugins/eg-amp.lv2/amp.c b/plugins/eg-amp.lv2/amp.c index c3ba279..433a9d4 100644 --- a/plugins/eg-amp.lv2/amp.c +++ b/plugins/eg-amp.lv2/amp.c @@ -36,17 +36,21 @@ file is a good convention to follow. If this URI does not match that used in the data files, the host will fail to load the plugin. */ +// tag::AMP_URI[] #define AMP_URI "http://lv2plug.in/plugins/eg-amp" +// end::AMP_URI[] /** In code, ports are referred to by index. An enumeration of port indices should be defined for readability. */ +// tag::PortIndex[] typedef enum { AMP_GAIN = 0, AMP_INPUT = 1, AMP_OUTPUT = 2 } PortIndex; +// end::PortIndex[] /** Every plugin defines a private structure for the plugin instance. All data @@ -54,12 +58,13 @@ typedef enum { every instance method. In this simple plugin, only port buffers need to be stored, since there is no additional instance data. */ +// tag::Amp[] typedef struct { - // Port buffers - const float* gain; - const float* input; - float* output; + const float* gain; // Gain control input + const float* input; // Audio input + float* output; // Audio output } Amp; +// end::Amp[] /** The `instantiate()` function is called by the host to create a new plugin @@ -71,6 +76,7 @@ typedef struct { This function is in the ``instantiation'' threading class, so no other methods on this instance will be called concurrently with it. */ +// tag::instantiate[] static LV2_Handle instantiate(const LV2_Descriptor* descriptor, double rate, @@ -81,6 +87,7 @@ instantiate(const LV2_Descriptor* descriptor, return (LV2_Handle)amp; } +// end::instantiate[] /** The `connect_port()` method is called by the host to connect a particular @@ -90,6 +97,7 @@ instantiate(const LV2_Descriptor* descriptor, This method is in the ``audio'' threading class, and is called in the same context as run(). */ +// tag::connect_port[] static void connect_port(LV2_Handle instance, uint32_t port, @@ -109,6 +117,7 @@ connect_port(LV2_Handle instance, break; } } +// end::connect_port[] /** The `activate()` method is called by the host to initialise and prepare the @@ -124,6 +133,8 @@ activate(LV2_Handle instance) { } +// tag::run[] + /** Define a macro for converting a gain in dB to a coefficient. */ #define DB_CO(g) ((g) > -90.0f ? powf(10.0f, (g) * 0.05f) : 0.0f) @@ -149,6 +160,8 @@ run(LV2_Handle instance, uint32_t n_samples) } } +// end::run[] + /** The `deactivate()` method is the counterpart to `activate()`, and is called by the host after running the plugin. It indicates that the host will not call @@ -171,11 +184,13 @@ deactivate(LV2_Handle instance) This method is in the ``instantiation'' threading class, so no other methods on this instance will be called concurrently with it. */ +// tag::cleanup[] static void cleanup(LV2_Handle instance) { free(instance); } +// end::cleanup[] /** The `extension_data()` function returns any extension data supported by the @@ -193,6 +208,8 @@ extension_data(const char* uri) return NULL; } +// tag::descriptor[] + /** Every plugin must define an `LV2_Descriptor`. It is best to define descriptors statically to avoid leaking memory and non-portable shared @@ -228,3 +245,5 @@ lv2_descriptor(uint32_t index) default: return NULL; } } + +// end::descriptor[] diff --git a/plugins/eg-amp.lv2/amp.ttl b/plugins/eg-amp.lv2/amp.ttl index 9f522a1..87fd76a 100644 --- a/plugins/eg-amp.lv2/amp.ttl +++ b/plugins/eg-amp.lv2/amp.ttl @@ -2,11 +2,13 @@ # `manifest.ttl`. This is done so the host only needs to scan the relatively # small `manifest.ttl` files to quickly discover all plugins. +# tag::prefixes[] @prefix doap: . @prefix lv2: . @prefix rdf: . @prefix rdfs: . @prefix units: . +# end::prefixes[] # First the type of the plugin is described. All plugins must explicitly list # `lv2:Plugin` as a type. A more specific type should also be given, where @@ -36,6 +38,7 @@ "Просто Усилитель"@ru ; doap:license ; lv2:optionalFeature lv2:hardRTCapable ; +# tag::ports[] lv2:port [ # Every port must have at least two types, one that specifies direction # (lv2:InputPort or lv2:OutputPort), and another to describe the data type. @@ -88,3 +91,4 @@ lv2:symbol "out" ; lv2:name "Out" ] . +# end::ports[] -- cgit v1.2.1