aboutsummaryrefslogtreecommitdiffstats
path: root/ext/variables.lv2/variables.h
diff options
context:
space:
mode:
Diffstat (limited to 'ext/variables.lv2/variables.h')
-rw-r--r--ext/variables.lv2/variables.h144
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 */
+