aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/options
diff options
context:
space:
mode:
Diffstat (limited to 'lv2/options')
-rw-r--r--lv2/options/manifest.ttl9
-rw-r--r--lv2/options/options.h146
-rw-r--r--lv2/options/options.meta.ttl129
-rw-r--r--lv2/options/options.ttl44
4 files changed, 328 insertions, 0 deletions
diff --git a/lv2/options/manifest.ttl b/lv2/options/manifest.ttl
new file mode 100644
index 0000000..18db448
--- /dev/null
+++ b/lv2/options/manifest.ttl
@@ -0,0 +1,9 @@
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+<http://lv2plug.in/ns/ext/options>
+ a lv2:Specification ;
+ lv2:minorVersion 1 ;
+ lv2:microVersion 4 ;
+ rdfs:seeAlso <options.ttl> .
+
diff --git a/lv2/options/options.h b/lv2/options/options.h
new file mode 100644
index 0000000..2ed9f8a
--- /dev/null
+++ b/lv2/options/options.h
@@ -0,0 +1,146 @@
+/*
+ Copyright 2012-2016 David Robillard <http://drobilla.net>
+
+ Permission to use, copy, modify, and/or distribute this software for any
+ purpose with or without fee is hereby granted, provided that the above
+ copyright notice and this permission notice appear in all copies.
+
+ THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+*/
+
+/**
+ @defgroup options Options
+ @ingroup lv2
+
+ Instantiation time options, see <http://lv2plug.in/ns/ext/options> for
+ details.
+
+ @{
+*/
+
+#ifndef LV2_OPTIONS_H
+#define LV2_OPTIONS_H
+
+#include "lv2/core/lv2.h"
+#include "lv2/urid/urid.h"
+
+#include <stdint.h>
+
+#define LV2_OPTIONS_URI "http://lv2plug.in/ns/ext/options" ///< http://lv2plug.in/ns/ext/options
+#define LV2_OPTIONS_PREFIX LV2_OPTIONS_URI "#" ///< http://lv2plug.in/ns/ext/options#
+
+#define LV2_OPTIONS__Option LV2_OPTIONS_PREFIX "Option" ///< http://lv2plug.in/ns/ext/options#Option
+#define LV2_OPTIONS__interface LV2_OPTIONS_PREFIX "interface" ///< http://lv2plug.in/ns/ext/options#interface
+#define LV2_OPTIONS__options LV2_OPTIONS_PREFIX "options" ///< http://lv2plug.in/ns/ext/options#options
+#define LV2_OPTIONS__requiredOption LV2_OPTIONS_PREFIX "requiredOption" ///< http://lv2plug.in/ns/ext/options#requiredOption
+#define LV2_OPTIONS__supportedOption LV2_OPTIONS_PREFIX "supportedOption" ///< http://lv2plug.in/ns/ext/options#supportedOption
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ The context of an Option, which defines the subject it applies to.
+*/
+typedef enum {
+ /**
+ This option applies to the instance itself. The subject must be
+ ignored.
+ */
+ LV2_OPTIONS_INSTANCE,
+
+ /**
+ This option applies to some named resource. The subject is a URI mapped
+ to an integer (a LV2_URID, like the key)
+ */
+ LV2_OPTIONS_RESOURCE,
+
+ /**
+ This option applies to some blank node. The subject is a blank node
+ identifier, which is valid only within the current local scope.
+ */
+ LV2_OPTIONS_BLANK,
+
+ /**
+ This option applies to a port on the instance. The subject is the
+ port's index.
+ */
+ LV2_OPTIONS_PORT
+} LV2_Options_Context;
+
+/**
+ An option.
+
+ This is a property with a subject, also known as a triple or statement.
+
+ This struct is useful anywhere a statement needs to be passed where no
+ memory ownership issues are present (since the value is a const pointer).
+
+ Options can be passed to an instance via the feature LV2_OPTIONS__options
+ with data pointed to an array of options terminated by a zeroed option, or
+ accessed/manipulated using LV2_Options_Interface.
+*/
+typedef struct {
+ LV2_Options_Context context; /**< Context (type of subject). */
+ uint32_t subject; /**< Subject. */
+ LV2_URID key; /**< Key (property). */
+ uint32_t size; /**< Size of value in bytes. */
+ LV2_URID type; /**< Type of value (datatype). */
+ const void* value; /**< Pointer to value (object). */
+} LV2_Options_Option;
+
+/** A status code for option functions. */
+typedef enum {
+ LV2_OPTIONS_SUCCESS = 0, /**< Completed successfully. */
+ LV2_OPTIONS_ERR_UNKNOWN = 1, /**< Unknown error. */
+ LV2_OPTIONS_ERR_BAD_SUBJECT = 1 << 1, /**< Invalid/unsupported subject. */
+ LV2_OPTIONS_ERR_BAD_KEY = 1 << 2, /**< Invalid/unsupported key. */
+ LV2_OPTIONS_ERR_BAD_VALUE = 1 << 3 /**< Invalid/unsupported value. */
+} LV2_Options_Status;
+
+/**
+ Interface for dynamically setting options (LV2_OPTIONS__interface).
+*/
+typedef struct {
+ /**
+ Get the given options.
+
+ Each element of the passed options array MUST have type, subject, and
+ key set. All other fields (size, type, value) MUST be initialised to
+ zero, and are set to the option value if such an option is found.
+
+ This function is in the "instantiation" LV2 threading class, so no other
+ instance functions may be called concurrently.
+
+ @return Bitwise OR of LV2_Options_Status values.
+ */
+ uint32_t (*get)(LV2_Handle instance,
+ LV2_Options_Option* options);
+
+ /**
+ Set the given options.
+
+ This function is in the "instantiation" LV2 threading class, so no other
+ instance functions may be called concurrently.
+
+ @return Bitwise OR of LV2_Options_Status values.
+ */
+ uint32_t (*set)(LV2_Handle instance,
+ const LV2_Options_Option* options);
+} LV2_Options_Interface;
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* LV2_OPTIONS_H */
+
+/**
+ @}
+*/
diff --git a/lv2/options/options.meta.ttl b/lv2/options/options.meta.ttl
new file mode 100644
index 0000000..d545f95
--- /dev/null
+++ b/lv2/options/options.meta.ttl
@@ -0,0 +1,129 @@
+@prefix dcs: <http://ontologi.es/doap-changeset#> .
+@prefix doap: <http://usefulinc.com/ns/doap#> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix opts: <http://lv2plug.in/ns/ext/options#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+<http://lv2plug.in/ns/ext/options>
+ a doap:Project ;
+ doap:name "LV2 Options" ;
+ doap:shortdesc "Runtime options for LV2 plugins and UIs." ;
+ doap:created "2012-08-20" ;
+ doap:developer <http://drobilla.net/drobilla#me> ;
+ doap:release [
+ doap:revision "1.4" ;
+ doap:created "2019-02-03" ;
+ doap:file-release <http://lv2plug.in/spec/lv2-1.16.0.tar.bz2> ;
+ dcs:blame <http://drobilla.net/drobilla#me> ;
+ dcs:changeset [
+ dcs:item [
+ rdfs:label "Relax range of opts:requiredOption and opts:supportedOption"
+ ]
+ ]
+ ] , [
+ doap:revision "1.2" ;
+ doap:created "2013-01-10" ;
+ doap:file-release <http://lv2plug.in/spec/lv2-1.4.0.tar.bz2> ;
+ dcs:blame <http://drobilla.net/drobilla#me> ;
+ dcs:changeset [
+ dcs:item [
+ rdfs:label "Set the range of opts:requiredOption and opts:supportedOption to opts:Option."
+ ]
+ ]
+ ] , [
+ doap:revision "1.0" ;
+ doap:created "2012-10-14" ;
+ doap:file-release <http://lv2plug.in/spec/lv2-1.2.0.tar.bz2> ;
+ dcs:blame <http://drobilla.net/drobilla#me> ;
+ dcs:changeset [
+ dcs:item [
+ rdfs:label "Initial release."
+ ]
+ ]
+ ] ;
+ lv2:documentation """
+
+This extension defines a facility for <q>options</q>, which are values the host
+passes to a plugin or UI at run time.
+
+There are two facilities for passing options to an instance: opts:options
+allows passing options at instantiation time, and the opts:interface interface
+allows options to be dynamically set and retrieved after instantiation.
+
+Note that this extension is only for allowing hosts to configure plugins, and
+is not a <q>live</q> control mechanism. For real-time control, use event-based
+control via an atom:AtomPort with an atom:Sequence buffer.
+
+Instances may indicate they require an option with the opts:requiredOption
+property, or that they optionally support an option with the
+opts:supportedOption property.
+
+"""^^lv2:Markdown .
+
+opts:Option
+ lv2:documentation """
+
+It is not required for a property to explicitly be an Option in order to be
+used as such. However, properties which are primarily intended for use as
+options, or are at least particularly useful as options, should be explicitly
+given this type for documentation purposes, and to assist hosts in discovering
+option definitions.
+
+"""^^lv2:Markdown .
+
+opts:interface
+ lv2:documentation """
+
+An interface (LV2_Options_Interface) for dynamically setting and getting
+options. Note that this is intended for use by the host for configuring
+plugins only, and is not a <q>live</q> plugin control mechanism.
+
+The plugin data file should advertise this interface like so:
+
+ :::turtle
+ @prefix opts: &lt;http://lv2plug.in/ns/ext/options#&gt; .
+
+ &lt;plugin&gt;
+ a lv2:Plugin ;
+ lv2:extensionData opts:interface .
+
+"""^^lv2:Markdown .
+
+opts:options
+ lv2:documentation """
+
+To implement this feature, hosts MUST pass an LV2_Feature to the appropriate
+instantiate method with this URI and data pointed to an array of
+LV2_Options_Option terminated by an element with both key and value set to
+zero. The instance should cast this data pointer to `const
+LV2_Options_Option*` and scan the array for any options of interest. The
+instance MUST NOT modify the options array in any way.
+
+Note that requiring this feature may reduce the number of compatible hosts.
+Unless some options are strictly required by the instance, this feature SHOULD
+be listed as an lv2:optionalFeature.
+
+"""^^lv2:Markdown .
+
+opts:requiredOption
+ lv2:documentation """
+
+The host MUST pass a value for the specified option via opts:options during
+instantiation.
+
+Note that use of this property may reduce the number of compatible hosts.
+Wherever possible, it is better to list options with opts:supportedOption and
+fall back to a reasonable default value if it is not provided.
+
+"""^^lv2:Markdown .
+
+opts:supportedOption
+ lv2:documentation """
+
+The host SHOULD provide a value for the specified option if one is known, or
+provide the user an opportunity to specify one if possible.
+
+"""^^lv2:Markdown .
+
diff --git a/lv2/options/options.ttl b/lv2/options/options.ttl
new file mode 100644
index 0000000..f8388da
--- /dev/null
+++ b/lv2/options/options.ttl
@@ -0,0 +1,44 @@
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix opts: <http://lv2plug.in/ns/ext/options#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@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#> .
+
+<http://lv2plug.in/ns/ext/options>
+ a owl:Ontology ;
+ rdfs:label "LV2 Options" ;
+ rdfs:comment "Runtime options for LV2 plugins and UIs." ;
+ rdfs:seeAlso <options.h> ,
+ <options.meta.ttl> .
+
+opts:Option
+ a rdfs:Class ;
+ rdfs:label "Option" ;
+ rdfs:subClassOf rdf:Property ;
+ rdfs:comment "A value for a static option passed to an instance." .
+
+opts:interface
+ a lv2:ExtensionData ;
+ rdfs:label "interface" ;
+ rdfs:comment "An interface for dynamically setting and getting options." .
+
+opts:options
+ a lv2:Feature ;
+ rdfs:label "options" ;
+ rdfs:comment "The feature used to provide options to an instance." .
+
+opts:requiredOption
+ a rdf:Property ,
+ owl:ObjectProperty ;
+ rdfs:range rdf:Property ;
+ rdfs:label "required option" ;
+ rdfs:comment "An option required by the instance to function at all." .
+
+opts:supportedOption
+ a rdf:Property ,
+ owl:ObjectProperty ;
+ rdfs:range rdf:Property ;
+ rdfs:label "supported option" ;
+ rdfs:comment "An option supported or by the instance." .
+
generated by cgit v1.2.1 (git 2.18.0) at 2026-03-15 07:22:23 +0000