aboutsummaryrefslogtreecommitdiffstats
path: root/ext/variables.lv2
diff options
context:
space:
mode:
Diffstat (limited to 'ext/variables.lv2')
-rw-r--r--ext/variables.lv2/manifest.ttl7
-rw-r--r--ext/variables.lv2/variables-private.h48
-rw-r--r--ext/variables.lv2/variables.h144
-rw-r--r--ext/variables.lv2/variables.ttl118
4 files changed, 317 insertions, 0 deletions
diff --git a/ext/variables.lv2/manifest.ttl b/ext/variables.lv2/manifest.ttl
new file mode 100644
index 0000000..a8e3306
--- /dev/null
+++ b/ext/variables.lv2/manifest.ttl
@@ -0,0 +1,7 @@
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+<http://lv2plug.in/ns/ext/variables>
+ a lv2:Specification ;
+ rdfs:seeAlso <variables.ttl> .
+
diff --git a/ext/variables.lv2/variables-private.h b/ext/variables.lv2/variables-private.h
new file mode 100644
index 0000000..451aeb2
--- /dev/null
+++ b/ext/variables.lv2/variables-private.h
@@ -0,0 +1,48 @@
+/* LV2 Plugin Variables Extension (Private Implementation)
+ * Copyright (C) 2007-2009 David Robillard <http://drobilla.net>
+ *
+ * This header is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This header is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#include "lv2_variables.h"
+
+/** An LV2 Plugin Variable (Private) */
+struct _LV2Var_Variable {
+ char* key; /**< Lookup key of variable, full URI */
+ char* type; /**< Type of value, full URI, may be NULL */
+ char* value; /**< Variable value (string literal or URI) */
+};
+
+
+static const char*
+lv2var_variable_key(const LV2Var_Variable var)
+{
+ return var->key;
+}
+
+
+static const char*
+lv2var_variable_type(const LV2Var_Variable var)
+{
+ return var->type;
+}
+
+
+static const char*
+lv2var_variable_value(const LV2Var_Variable var)
+{
+ return var->value;
+}
+
diff --git a/ext/variables.lv2/variables.h b/ext/variables.lv2/variables.h
new file mode 100644
index 0000000..5c51be7
--- /dev/null
+++ b/ext/variables.lv2/variables.h
@@ -0,0 +1,144 @@
+/* LV2 Plugin Variables Extension
+ * Copyright (C) 2007-2009 David Robillard <http://drobilla.net>
+ *
+ * This header is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This header is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+#ifndef LV2_VARIABLES_H
+#define LV2_VARIABLES_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+
+/** @file
+ * This is an LV2 extension allowing plugin instances to have a set of
+ * dynamic named/typed variables (ie key/value metadata).
+ *
+ * Plugin variable values are always in string form (if numeric
+ * variable values are requires in realtime run callbacks, it is assumed
+ * the plugin will cache the converted value).
+ *
+ * Keys are strings, either free-form locally unique strings, or URIs.
+ * Types are URIs (corresponding to some type defined somewhere, e.g. in an
+ * XML namespace or RDF ontology).
+ *
+ * The goal is to provide a powerful key/value system for plugins, which is
+ * useful for setting run-time values (analogous to DSSI's "configure" calls)
+ * which is typed and ideal for serializing to RDF (which means variable
+ * values can be stored in the same file as the plugin's definition) or
+ * network transmission/control.
+ */
+
+
+/** An LV2 Plugin Variable */
+typedef struct _LV2Var_Variable* LV2Var_Variable;
+
+static const char* lv2var_variable_key(const LV2Var_Variable var);
+static const char* lv2var_variable_type(const LV2Var_Variable var);
+static const char* lv2var_variable_value(const LV2Var_Variable var);
+
+
+
+/** Plugin extension data for plugin variables.
+ *
+ * The extension_data function on a plugin (which supports this extension)
+ * will return a pointer to a struct of this type, when called with the URI
+ * http://drobilla.net/ns/lv2/variables
+ */
+typedef struct _LV2Var_Descriptor {
+
+ /** Get the value of a plugin variable (O(log(n), non-blocking).
+ *
+ * @param key_uri Key of variable to look up
+ * @param type_uri Output, set to (shared) type of value (full URI, may be NULL)
+ * @param value Output, set to (shared) value of variable
+ *
+ * @return 0 if variable was found and type, value have been set accordingly,
+ * otherwise non-zero.
+ */
+ int32_t (*get_value)(const char* key_uri,
+ const char** type_uri,
+ const char** value);
+
+
+ /** Set a plugin variable to a typed literal value (O(log(n), allocates memory).
+ *
+ * Note that this function is NOT realtime safe.
+ *
+ * String parameters are copied. The key is the sole unique identifier
+ * for variables; if a variable exists with the given key, it will be
+ * overwritten with the new type and value.
+ *
+ * To set a variable's value to a URI, use rdfs:Resource
+ * (http://www.w3.org/2000/01/rdf-schema#Resource) for the value type.
+ *
+ * @param key_uri Key of variable to set (MUST be a full URI)
+ * @param type_uri Type of value (MUST be a full URI, may be NULL)
+ * @param value Value of variable to set
+ */
+ void (*set_value)(const char* key_uri,
+ const char* type_uri,
+ const char* value);
+
+
+ /** Unset (erase) a variable (O(log(n), deallocates memory).
+ *
+ * Note that this function is NOT realtime safe.
+ *
+ * @param key Key of variable to erase
+ */
+ void (*unset)(const char* key_uri);
+
+
+ /** Clear (erase) all set variables (O(1), deallocates memory).
+ *
+ * Note that this function is NOT realtime safe.
+ */
+ void (*clear)();
+
+
+ /** Get all variables of a plugin (O(log(n), allocates memory).
+ *
+ * @param variables Output, set to a shared array of all set variables
+ *
+ * @return The number of variables found
+ */
+ uint32_t (*get_all_variables)(const LV2Var_Variable** variables);
+
+
+ /** Get the value of a plugin variable (O(log(n), non-blocking).
+ *
+ * @param key_uri Key of variable to look up
+ * @param variable Output, set to point at (shared) variable
+ *
+ * @return 0 if variable was found and variable has been set accordingly,
+ * otherwise non-zero.
+ */
+ int32_t (*get_variable)(const char* key_uri,
+ const LV2Var_Variable** variable);
+
+} LV2Var_Descriptor;
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* LV2_VARIABLES_H */
+
diff --git a/ext/variables.lv2/variables.ttl b/ext/variables.lv2/variables.ttl
new file mode 100644
index 0000000..b7d1b8c
--- /dev/null
+++ b/ext/variables.lv2/variables.ttl
@@ -0,0 +1,118 @@
+# LV2 Variables Extension
+# Copyright (C) 2008 David Robillard
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
+@prefix var: <http://lv2plug.in/ns/ext/instance-var#> .
+@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#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema> .
+@prefix doap: <http://usefulinc.com/ns/doap#> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+
+<http://lv2plug.in/ns/ext/instance-var> a lv2:Specification ;
+ doap:license <http://usefulinc.com/doap/licenses/mit> ;
+ doap:name "LV2 Instance Variables" ;
+ doap:created "2008-08-18" ;
+ doap:maintainer [
+ a foaf:Person ;
+ foaf:name "David Robillard" ;
+ foaf:homepage <http://drobilla.net/> ;
+ rdfs:seeAlso <http://drobilla.net/drobilla.rdf>
+ ] ;
+ rdfs:comment """
+An extension for setting named/typed variables on an instance of an
+LV2 Plugin (or anything else). A "variable" is really just a (reified)
+RDF statement with an implicit subject (e.g. the plugin instance).
+
+Variables serve as a portable, network transparent, and serialisable
+mechanism for clients (e.g. user interfaces, programs) to control any
+parameter of a running plugin instance. Because variables are 'keyed'
+by URI (the predicate), future extensions can define variables with
+specific meanings or restricted/extended types.
+The value (rdf:value) of a variable may be anything, but hosts or plugins
+aren't guaranteed to support anything other than simple typed literals.
+Serialisation and code access to complex variables is considered outside
+the scope of this extension.
+
+Hosts and plugins SHOULD use the following types for appropriate values:
+
+<table>
+<tr><th>RDF Type</th><th>Data Type</th></tr>
+<tr><td>xsd:string</td><td>string</td></tr>
+<tr><td>xsd:decimal</td><td>floating point number</td></tr>
+<tr><td>xsd:integer</td><td>integer number</td></tr>
+<tr><td>xsd:boolean</td><td>boolean value</td></tr>
+</table>
+
+This extension does not currently define a code mechanism for access
+to variables. A future revision, or a different extension, may.
+
+An example of a plugin with several variables:
+<pre>
+&lt;http://example.org/plugin&gt; a lv2:Plugin ;
+ lv2var:variable [
+ rdf:predicate &lt;http://example.org/greetingology#Greeting&gt; ;
+ rdf:value "Hello, cruel world."
+ ] , [
+ rdf:predicate &lt;http://example.org/matheybits#Coeff&gt; ;
+ rdf:value 1.23456
+ ] , [
+ rdf:predicate &lt;http://example.org/databits#BigValue&gt; ;
+ rdf:value [
+ a somext:Something ;
+ someext:foo "Foo?" ;
+ someext:bar "Bar." ;
+ someext:baz 1234.0
+ ]
+ ] .
+</pre>
+""" .
+
+
+var:Variable a rdfs:Class ;
+ rdfs:label "LV2 Variable" ;
+ rdfs:comment "A typed instance variable." ;
+
+ rdfs:subClassOf [
+ a owl:Restriction ;
+ rdfs:comment "Must have exactly one rdf:predicate which is a resource" ;
+ owl:onProperty rdf:predicate ;
+ owl:cardinality 1 ;
+ owl:allValuesFrom rdfs:Resource
+ ], [
+ a owl:Restriction ;
+ rdfs:comment "Must have exactly one rdf:value (of any type)" ;
+ owl:onProperty rdf:value ;
+ owl:cardinality 1
+ ] .
+
+
+var:variable a owl:ObjectProperty ;
+ rdfs:label "Has a Variable" ;
+ rdfs:range var:Variable ;
+ rdfs:comment """
+Relates an LV2 Variable to some Resource, usually a plugin instance.
+The domain of this property is not restricted, it may be used for anything.
+The range is implicitly an lv2var:Variable, the 'a lv2var:Variable' triple
+is not mandatory.
+""" .
+