diff options
Diffstat (limited to 'ext/variables.lv2')
| -rw-r--r-- | ext/variables.lv2/manifest.ttl | 7 | ||||
| -rw-r--r-- | ext/variables.lv2/variables-private.h | 48 | ||||
| -rw-r--r-- | ext/variables.lv2/variables.h | 144 | ||||
| -rw-r--r-- | ext/variables.lv2/variables.ttl | 118 |
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> +<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 + ] + ] . +</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. +""" . + |