From cef9811dac46a9d54dab0f0d82ce5c3ae032fc7c Mon Sep 17 00:00:00 2001 From: David Robillard Date: Mon, 4 Oct 2010 18:21:08 +0000 Subject: Initial import of lv2plug.in universe. --- ext/variables.lv2/manifest.ttl | 7 ++ ext/variables.lv2/variables-private.h | 48 ++++++++++++ ext/variables.lv2/variables.h | 144 ++++++++++++++++++++++++++++++++++ ext/variables.lv2/variables.ttl | 118 ++++++++++++++++++++++++++++ 4 files changed, 317 insertions(+) create mode 100644 ext/variables.lv2/manifest.ttl create mode 100644 ext/variables.lv2/variables-private.h create mode 100644 ext/variables.lv2/variables.h create mode 100644 ext/variables.lv2/variables.ttl (limited to 'ext/variables.lv2') 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: . +@prefix rdfs: . + + + a lv2:Specification ; + rdfs:seeAlso . + 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 + * + * 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 + * + * 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 + +#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: . +@prefix lv2: . +@prefix rdf: . +@prefix rdfs: . +@prefix xsd: . +@prefix doap: . +@prefix foaf: . +@prefix owl: . + + a lv2:Specification ; + doap:license ; + doap:name "LV2 Instance Variables" ; + doap:created "2008-08-18" ; + doap:maintainer [ + a foaf:Person ; + foaf:name "David Robillard" ; + foaf:homepage ; + rdfs:seeAlso + ] ; + 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: + + + + + + + +
RDF TypeData Type
xsd:stringstring
xsd:decimalfloating point number
xsd:integerinteger number
xsd:booleanboolean value
+ +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: +
+<http://example.org/plugin> a lv2:Plugin ;
+	lv2var:variable [
+		rdf:predicate <http://example.org/greetingology#Greeting> ;
+		rdf:value "Hello, cruel world."
+	] , [
+		rdf:predicate <http://example.org/matheybits#Coeff> ;
+		rdf:value 1.23456
+	] , [
+		rdf:predicate <http://example.org/databits#BigValue> ;
+		rdf:value [
+			a somext:Something ;
+			someext:foo "Foo?" ;
+			someext:bar "Bar." ;
+			someext:baz 1234.0
+		]
+	] .
+
+""" . + + +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. +""" . + -- cgit v1.2.1