Order examples in a sensible progression for the book.

6 files changed, 501 insertions, 0 deletions

diff --git a/plugins/eg01-amp.lv2/README.txt b/plugins/eg01-amp.lv2/README.txt
new file mode 100644
index 0000000..f024a4d
--- /dev/null
+++ b/plugins/eg01-amp.lv2/README.txt
@@ -0,0 +1,21 @@
+== Simple Amplifier ==
+
+This plugin is a simple example of a basic LV2 plugin with no additional features.
+It has audio ports which contain an array of `float`,
+and a control port which contain a single `float`.
+
+LV2 plugins are defined in two parts: code and data.
+The code is written in C, or any C compatible language such as C++.
+Static data is described separately in the human and machine friendly http://www.w3.org/TeamSubmission/turtle/[Turtle] syntax.
+Turtle is a syntax for the RDF data model,
+but familiarity with RDF is not required to understand this documentation.
+
+Generally, code is kept minimal,
+and all static information is described in the data.
+There are several advantages to this approach:
+
+ * Hosts can discover and inspect plugins without loading or executing any plugin code
+ * It is simple to work with plugin data using scripting languages, command line tools, etc.
+ * The standard format allow the use of existing vocabularies to describe plugins and related information
+ * The data inherently integrates with the web, databases, etc.
+ * Labels and documentation are translatable, and available to hosts for display in user interfaces
diff --git a/plugins/eg01-amp.lv2/amp.c b/plugins/eg01-amp.lv2/amp.c
new file mode 100644
index 0000000..8dd7b4f
--- /dev/null
+++ b/plugins/eg01-amp.lv2/amp.c
@@ -0,0 +1,225 @@
+/*
+  Copyright 2006-2011 David Robillard <d@drobilla.net>
+  Copyright 2006 Steve Harris <steve@plugin.org.uk>
+
+  Permission to use, copy, modify, and/or distribute this software for any
+  purpose with or without fee is hereby granted, provided that the above
+  copyright notice and this permission notice appear in all copies.
+
+  THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+
+/** Include standard C headers */
+#include <math.h>
+#include <stdlib.h>
+
+/**
+   LV2 headers are based on the URI of the specification they come from, so a
+   consistent convention can be used even for unofficial extensions.  The URI
+   of the core LV2 specification is <http://lv2plug.in/ns/lv2core>, by
+   replacing `http:/` with `lv2` any header in the specification bundle can be
+   included, in this case `lv2.h`.
+*/
+#include "lv2/lv2plug.in/ns/lv2core/lv2.h"
+
+/**
+   The URI is the identifier for a plugin, and how the host associates this
+   implementation in code with its description in data.  In this plugin it is
+   only used once in the code, but defining the plugin URI at the top of the
+   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.
+*/
+#define AMP_URI "http://lv2plug.in/plugins/eg-amp"
+
+/**
+   In code, ports are referred to by index.  An enumeration of port indices
+   should be defined for readability.
+*/
+typedef enum {
+	AMP_GAIN   = 0,
+	AMP_INPUT  = 1,
+	AMP_OUTPUT = 2
+} PortIndex;
+
+/**
+   Every plugin defines a private structure for the plugin instance.  All data
+   associated with a plugin instance is stored here, and is available to
+   every instance method.  In this simple plugin, only port buffers need to be
+   stored, since there is no additional instance data.  */
+typedef struct {
+	// Port buffers
+	const float* gain;
+	const float* input;
+	float*       output;
+} Amp;
+
+/**
+   The instantiate() function is called by the host to create a new plugin
+   instance.  The host passes the plugin descriptor, sample rate, and bundle
+   path for plugins that need to load additional resources (e.g. waveforms).
+   The features parameter contains host-provided features defined in LV2
+   extensions, but this simple plugin does not use any.
+
+   This function is in the ``instantiation'' threading class, so no other
+   methods on this instance will be called concurrently with it.
+*/
+static LV2_Handle
+instantiate(const LV2_Descriptor*     descriptor,
+            double                    rate,
+            const char*               bundle_path,
+            const LV2_Feature* const* features)
+{
+	Amp* amp = (Amp*)malloc(sizeof(Amp));
+
+	return (LV2_Handle)amp;
+}
+
+/**
+   The connect_port() method is called by the host to connect a particular port
+   to a buffer.  The plugin must store the data location, but data may not be
+   accessed except in run().
+
+   This method is in the ``audio'' threading class, and is called in the same
+   context as run().
+*/
+static void
+connect_port(LV2_Handle instance,
+             uint32_t   port,
+             void*      data)
+{
+	Amp* amp = (Amp*)instance;
+
+	switch ((PortIndex)port) {
+	case AMP_GAIN:
+		amp->gain = (const float*)data;
+		break;
+	case AMP_INPUT:
+		amp->input = (const float*)data;
+		break;
+	case AMP_OUTPUT:
+		amp->output = (float*)data;
+		break;
+	}
+}
+
+/**
+   The activate() method is called by the host to initialise and prepare the
+   plugin instance for running.  The plugin must reset all internal state
+   except for buffer locations set by connect_port().  Since this plugin has
+   no other internal state, this method does nothing.
+
+   This method is in the ``instantiation'' threading class, so no other
+   methods on this instance will be called concurrently with it.
+*/
+static void
+activate(LV2_Handle instance)
+{
+}
+
+/** 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)
+
+/** Process a block of audio (audio thread, must be RT safe). */
+static void
+run(LV2_Handle instance, uint32_t n_samples)
+{
+	const Amp* amp = (const Amp*)instance;
+
+	const float        gain   = *(amp->gain);
+	const float* const input  = amp->input;
+	float* const       output = amp->output;
+
+	const float coef = DB_CO(gain);
+
+	for (uint32_t pos = 0; pos < n_samples; pos++) {
+		output[pos] = input[pos] * coef;
+	}
+}
+
+/**
+   The deactivate() method is the counterpart to activate() called by the host
+   after running the plugin.  It indicates that the host will not call run()
+   again until another call to activate() and is mainly useful for more
+   advanced plugins with ``live'' characteristics such as those with auxiliary
+   processing threads.  As with activate(), this plugin has no use for this
+   information so this method does nothing.
+
+   This method is in the ``instantiation'' threading class, so no other
+   methods on this instance will be called concurrently with it.
+*/
+static void
+deactivate(LV2_Handle instance)
+{
+}
+
+/**
+   Destroy a plugin instance (counterpart to instantiate()).
+
+   This method is in the ``instantiation'' threading class, so no other
+   methods on this instance will be called concurrently with it.
+*/
+static void
+cleanup(LV2_Handle instance)
+{
+	free(instance);
+}
+
+/**
+   The extension_data function returns any extension data supported by the
+   plugin.  Note that this is not an instance method, but a function on the
+   plugin descriptor.  It is usually used by plugins to implement additional
+   interfaces.  This plugin does not have any extension data, so this function
+   returns NULL.
+
+   This method is in the ``discovery'' threading class, so no other functions
+   or methods in this plugin library will be called concurrently with it.
+*/
+static const void*
+extension_data(const char* uri)
+{
+	return NULL;
+}
+
+/**
+   Define the LV2_Descriptor for this plugin.  It is best to define descriptors
+   statically to avoid leaking memory and non-portable shared library
+   constructors and destructors to clean up properly.
+*/
+static const LV2_Descriptor descriptor = {
+	AMP_URI,
+	instantiate,
+	connect_port,
+	activate,
+	run,
+	deactivate,
+	cleanup,
+	extension_data
+};
+
+/**
+   The lv2_descriptor() function is the entry point to the plugin library.  The
+   host will load the library and call this function repeatedly with increasing
+   indices to find all the plugins defined in the library.  The index is not an
+   indentifier, the URI of the returned descriptor is used to determine the
+   identify of the plugin.
+   
+   This method is in the ``discovery'' threading class, so no other functions
+   or methods in this plugin library will be called concurrently with it.
+*/
+LV2_SYMBOL_EXPORT
+const LV2_Descriptor*
+lv2_descriptor(uint32_t index)
+{
+	switch (index) {
+	case 0:
+		return &descriptor;
+	default:
+		return NULL;
+	}
+}
diff --git a/plugins/eg01-amp.lv2/amp.ttl b/plugins/eg01-amp.lv2/amp.ttl
new file mode 100644
index 0000000..f4a87f2
--- /dev/null
+++ b/plugins/eg01-amp.lv2/amp.ttl
@@ -0,0 +1,86 @@
+# The full description of the plugin is in this file, which is linked to from
+# `manifest.ttl`.  This is done so the host only needs to scan the relatively
+# small `manifest.ttl` files to quickly discover all plugins.
+
+@prefix doap: <http://usefulinc.com/ns/doap#> .
+@prefix lv2:  <http://lv2plug.in/ns/lv2core#> .
+@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+# 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
+# applicable, so hosts can present a nicer UI for loading plugins.  Note that
+# this URI is the identifier of the plugin, so if it does not match the one in
+# `manifest.ttl`, the host will not discover the plugin data at all.
+<http://lv2plug.in/plugins/eg-amp>
+	a lv2:Plugin ,
+		lv2:AmplifierPlugin ;
+# Plugins are associated with a project, where common information like
+# developers, home page, and so on are described.  This plugin is part of the
+# LV2 project, which has URI <http://lv2plug.in/ns/lv2>, and is described
+# elsewhere.  Typical plugin collections will describe the project in
+# manifest.ttl
+	lv2:project <http://lv2plug.in/ns/lv2> ;
+# Every plugin must have a name, described with the doap:name property.
+# Translations to various languages can be added by putting a language tag
+# after strings as shown.
+	doap:name "Simple Amplifier" ,
+		"简单放大器"@ch ,
+		"Einfacher Verstärker"@de ,
+		"Simple Amp"@en-gb ,
+		"Amplificador Simple"@es ,
+		"Amplificateur de Base"@fr ,
+		"Amplificatore Semplice"@it ,
+		"簡単なアンプ"@jp ,
+		"Просто Усилитель"@ru ;
+	doap:license <http://opensource.org/licenses/isc> ;
+	lv2:optionalFeature lv2:hardRTCapable ;
+	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.
+# This port is a lv2:ControlPort, which means it contains a single float.
+		a lv2:InputPort ,
+			lv2:ControlPort ;
+		lv2:index 0 ;
+		lv2:symbol "gain" ;
+		lv2:name "Gain" ,
+			"收益"@ch ,
+			"Gewinn"@de ,
+			"Gain"@en-gb ,
+			"Aumento"@es ,
+			"Gain"@fr ,
+			"Guadagno"@it ,
+			"利益"@jp ,
+			"Увеличение"@ru ;
+# An lv2:ControlPort should always describe its default value, and usually a
+# minimum and maximum value.  Defining a range is not strictly required, but
+# should be done wherever possible to aid host support, particularly for UIs.
+		lv2:default 0.0 ;
+		lv2:minimum -90.0 ;
+		lv2:maximum 24.0 ;
+		lv2:scalePoint [
+			rdfs:label "+5" ;
+			rdf:value 5.0
+		] , [
+			rdfs:label "0" ;
+			rdf:value 0.0
+		] , [
+			rdfs:label "-5" ;
+			rdf:value -5.0
+		] , [
+			rdfs:label "-10" ;
+			rdf:value -10.0
+		]
+	] , [
+		a lv2:AudioPort ,
+			lv2:InputPort ;
+		lv2:index 1 ;
+		lv2:symbol "in" ;
+		lv2:name "In"
+	] , [
+		a lv2:AudioPort ,
+			lv2:OutputPort ;
+		lv2:index 2 ;
+		lv2:symbol "out" ;
+		lv2:name "Out"
+	] .
diff --git a/plugins/eg01-amp.lv2/manifest.ttl.in b/plugins/eg01-amp.lv2/manifest.ttl.in
new file mode 100644
index 0000000..0da78b0
--- /dev/null
+++ b/plugins/eg01-amp.lv2/manifest.ttl.in
@@ -0,0 +1,101 @@
+# LV2 Bundle Manifest
+#
+# All LV2 plugins are installed as "bundles", a directory with a particular
+# format.  Inside the bundle, the entry point is a file called "manifest.ttl".
+# This file lists what plugins are in this bundle, and which files are (.so,
+# .ttl, etc.) are associated with those plugins.
+#
+# Hosts read bundles' manifest.ttl to discover what plugins (and other
+# resources) are available.  Manifest files should be as small as possible for
+# performance reasons.
+#
+#
+# ==== Namespace Prefixes ====
+#
+# Turtle files contain many URIs.  To make this more readable, prefixes
+# can be defined.  For example, with the `lv2:` prefix below, instead of
+# <http://lv2plug.in/ns/lv2core#Plugin> the shorter form `lv2:Plugin` can be
+# used.  This is just a shorthand for URIs within a file, the prefixes are not
+# significant otherwise.
+
+@prefix lv2:  <http://lv2plug.in/ns/lv2core#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+# ==== Data ====
+
+<http://lv2plug.in/plugins/eg-amp>
+	a lv2:Plugin ;
+	lv2:binary <amp@LIB_EXT@>  ;
+	rdfs:seeAlso <amp.ttl> .
+
+# The token `@LIB_EXT@` above is replaced by the build system with the
+# appropriate extension for the current platform (e.g. .so, .dylib, .dll).
+# This file is called called `manifest.ttl.in` rather than `manifest.ttl`
+# to indicate that it is not the final file to be installed.
+# This is not necessary, but is a good idea for portable plugins.
+# For reability, the following text will assume `.so` is the extension used.
+#
+# In short, this declares that the resource with URI
+# "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.
+#
+# There are 3 statements in this description:
+# |================================================================
+# | Subject                             | Predicate    | Object
+# | <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>
+# |================================================================
+#
+# 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> .
+
+# (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 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
+# address if possible, since it can be used to easily access documentation,
+# downloads, etc.  Note there are compatibility rules for when the URI of a
+# plugin must be changed, see the http://lv2plug.in/ns/lv2core[LV2 specification]
+# 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 no actual documents are currently hosted there.
+# If this is truly impossible, use a URN, e.g. urn:myplugs:superamp.
+#
+# A detailed explanation of each statement follows.
+
+<http://lv2plug.in/plugins/eg-amp> a lv2:Plugin .
+
+# The `a`, as in ``is a'', is a Turtle shortcut for `rdf:type`.
+# `lv2:Plugin` expands to <http://lv2plug.in/ns/lv2core#Plugin> (using the
+# `lv2:` prefix above) which is the type of all LV2 plugins.
+# This statement means ``<http://lv2plug.in/plugins/eg-amp> is an LV2 plugin''.
+
+<http://lv2plug.in/plugins/eg-amp> lv2:binary <amp@LIB_EXT@> .
+
+# This says "this plugin has executable code ("binary") in the file
+# named "amp.so", which is located in this bundle.  The LV2 specification
+# defines that all relative URIs in manifest files are relative to the bundle
+# directory, so this refers to the file amp.so in the same directory as this
+# manifest.ttl file.
+
+<http://lv2plug.in/plugins/eg-amp> rdfs:seeAlso <amp.ttl> .
+
+# This says ``there is more information about this plugin located in the file
+# `amp.ttl`''.  The host will look at all such files when it needs to actually
+# use or investigate the plugin.
diff --git a/plugins/eg01-amp.lv2/waf b/plugins/eg01-amp.lv2/waf
new file mode 120000
index 0000000..59a1ac9
--- /dev/null
+++ b/plugins/eg01-amp.lv2/waf
@@ -0,0 +1 @@
+../../waf
\ No newline at end of file
diff --git a/plugins/eg01-amp.lv2/wscript b/plugins/eg01-amp.lv2/wscript
new file mode 100644
index 0000000..d4295ff
--- /dev/null
+++ b/plugins/eg01-amp.lv2/wscript
@@ -0,0 +1,67 @@
+#!/usr/bin/env python
+from waflib.extras import autowaf as autowaf
+import re
+
+# Variables for 'waf dist'
+APPNAME = 'eg-amp.lv2'
+VERSION = '1.0.0'
+
+# Mandatory variables
+top = '.'
+out = 'build'
+
+def options(opt):
+    opt.load('compiler_c')
+    autowaf.set_options(opt)
+
+def configure(conf):
+    conf.load('compiler_c')
+    autowaf.configure(conf)
+    autowaf.set_c99_mode(conf)
+    autowaf.display_header('Amp Configuration')
+
+    if not autowaf.is_child():
+        autowaf.check_pkg(conf, 'lv2', uselib_store='LV2')
+        
+    conf.check(features='c cprogram', lib='m', uselib_store='M', mandatory=False) 
+
+    autowaf.display_msg(conf, 'LV2 bundle directory', conf.env.LV2DIR)
+    print('')
+
+def build(bld):
+    bundle = 'eg-amp.lv2'
+
+    # Make a pattern for shared objects without the 'lib' prefix
+    module_pat = re.sub('^lib', '', bld.env.cshlib_PATTERN)
+    module_ext = module_pat[module_pat.rfind('.'):]
+
+    # Build manifest.ttl by substitution (for portable lib extension)
+    bld(features     = 'subst',
+        source       = 'manifest.ttl.in',
+        target       = '%s/%s' % (bundle, 'manifest.ttl'),
+        install_path = '${LV2DIR}/%s' % bundle,
+        LIB_EXT      = module_ext)
+
+    # Copy other data files to build bundle (build/eg-amp.lv2)
+    for i in ['amp.ttl']:
+        bld(features     = 'subst',
+            is_copy      = True,
+            source       = i,
+            target       = '%s/%s' % (bundle, i),
+            install_path = '${LV2DIR}/%s' % bundle)
+
+    # Use LV2 headers from parent directory if building as a sub-project
+    includes = None
+    if autowaf.is_child:
+        includes = '../..'
+
+    # Build plugin library
+    obj = bld(features     = 'c cshlib',
+              source       = 'amp.c',
+              name         = 'amp',
+              target       = '%s/amp' % bundle,
+              install_path = '${LV2DIR}/%s' % bundle,
+              uselib       = 'M LV2',
+              includes     = includes)
+    obj.env.cshlib_PATTERN = module_pat
+