diff options
Diffstat (limited to 'ext/variables.lv2/variables.h')
| -rw-r--r-- | ext/variables.lv2/variables.h | 144 |
1 files changed, 144 insertions, 0 deletions
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 */ + |