From fd74305f08c85ad62201de8d51d71a3f1d86cd54 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Tue, 21 Aug 2012 04:34:49 +0000
Subject: Add options extension.
---
doc/reference.doxygen.in | 1 +
lv2/lv2plug.in/ns/ext/options/lv2-options.doap.ttl | 21 +++++++
lv2/lv2plug.in/ns/ext/options/manifest.ttl | 8 +++
lv2/lv2plug.in/ns/ext/options/options.h | 48 ++++++++++++++
lv2/lv2plug.in/ns/ext/options/options.ttl | 73 ++++++++++++++++++++++
5 files changed, 151 insertions(+)
create mode 100644 lv2/lv2plug.in/ns/ext/options/lv2-options.doap.ttl
create mode 100644 lv2/lv2plug.in/ns/ext/options/manifest.ttl
create mode 100644 lv2/lv2plug.in/ns/ext/options/options.h
create mode 100644 lv2/lv2plug.in/ns/ext/options/options.ttl
diff --git a/doc/reference.doxygen.in b/doc/reference.doxygen.in
index 958ad7b..8db28a0 100644
--- a/doc/reference.doxygen.in
+++ b/doc/reference.doxygen.in
@@ -667,6 +667,7 @@ INPUT = @LV2_SRCDIR@/doc/mainpage.dox \
lv2/lv2plug.in/ns/ext/instance-access/instance-access.h \
lv2/lv2plug.in/ns/ext/log/log.h \
lv2/lv2plug.in/ns/ext/morph/morph.h \
+ lv2/lv2plug.in/ns/ext/options/options.h \
lv2/lv2plug.in/ns/ext/patch/patch.h \
lv2/lv2plug.in/ns/ext/port-groups/port-groups.h \
lv2/lv2plug.in/ns/ext/resize-port/resize-port.h \
diff --git a/lv2/lv2plug.in/ns/ext/options/lv2-options.doap.ttl b/lv2/lv2plug.in/ns/ext/options/lv2-options.doap.ttl
new file mode 100644
index 0000000..05e9c87
--- /dev/null
+++ b/lv2/lv2plug.in/ns/ext/options/lv2-options.doap.ttl
@@ -0,0 +1,21 @@
+@prefix dcs: <http://ontologi.es/doap-changeset#> .
+@prefix doap: <http://usefulinc.com/ns/doap#> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+<http://lv2plug.in/ns/ext/options>
+ a doap:Project ;
+ rdfs:seeAlso <../../meta/meta.ttl> ;
+ doap:name "LV2 Options" ;
+ doap:shortdesc "Instantiation time options" ;
+ doap:created "2012-08-20" ;
+ doap:developer <http://drobilla.net/drobilla#me> ;
+ doap:release [
+ doap:revision "0.1" ;
+ dcs:blame <http://drobilla.net/drobilla#me> ;
+ dcs:changeset [
+ dcs:item [
+ rdfs:label "Initial release."
+ ]
+ ]
+ ] .
diff --git a/lv2/lv2plug.in/ns/ext/options/manifest.ttl b/lv2/lv2plug.in/ns/ext/options/manifest.ttl
new file mode 100644
index 0000000..6a1dd0b
--- /dev/null
+++ b/lv2/lv2plug.in/ns/ext/options/manifest.ttl
@@ -0,0 +1,8 @@
+@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 0 ;
+ lv2:microVersion 0 ;
+ rdfs:seeAlso <options.ttl> .
diff --git a/lv2/lv2plug.in/ns/ext/options/options.h b/lv2/lv2plug.in/ns/ext/options/options.h
new file mode 100644
index 0000000..fa4ba48
--- /dev/null
+++ b/lv2/lv2plug.in/ns/ext/options/options.h
@@ -0,0 +1,48 @@
+/*
+ Copyright 2012 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.
+*/
+
+#ifndef LV2_OPTIONS_H
+#define LV2_OPTIONS_H
+
+#include <stdint.h>
+
+#include "lv2/lv2plug.in/ns/ext/atom/atom.h"
+
+#define LV2_OPTIONS_URI "http://lv2plug.in/ns/ext/options"
+#define LV2_OPTIONS_PREFIX LV2_OPTIONS_URI "#"
+
+#define LV2_OPTIONS__options LV2_OPTIONS_PREFIX "options"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ An instantiation time option.
+
+ An array of these is passed to the instantiate method in a Feature with URI
+ LV2_OPTIONS__options .
+*/
+typedef struct {
+ LV2_URID key; /**< Key (a property URID). */
+ const LV2_Atom* value; /**< Value (an atom of appropriate type). */
+} LV2_Options_Option;
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* LV2_OPTIONS_H */
diff --git a/lv2/lv2plug.in/ns/ext/options/options.ttl b/lv2/lv2plug.in/ns/ext/options/options.ttl
new file mode 100644
index 0000000..564dfea
--- /dev/null
+++ b/lv2/lv2plug.in/ns/ext/options/options.ttl
@@ -0,0 +1,73 @@
+@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:seeAlso <options.h> ,
+ <../../meta/meta.ttl> ,
+ <lv2-options.doap.ttl> ;
+ lv2:documentation """
+<p>This extension defines a facility for <q>options</q>, which are parameters
+passed to a plugin, UI, or other instance at instantiation time. Like the
+command-line <em>options</em> of a program, options do not change over the
+lifetime of an instance.</p>
+
+<p>Because they are available at instantiation time, options are useful for
+adding parameters which are not suitable for dynamic control, such as those
+that require expensive pre-computation. They are also useful for providing
+information which would not otherwise be available.</p>
+
+<p>Options are provided to instances by the host via the opts:options
+feature.</p>
+
+<p>Instances may indicate they <q>require</q> an option with the
+opts:requiredOption property, or that they optionally <q>support</q> an option
+with the opts:supportedOption property.</p>
+""" .
+
+opts:options
+ a lv2:Feature ;
+ rdfs:label "options" ;
+ lv2:documentation """
+<p>The feature used to provide options to an instance.</p>
+
+<p>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 <code>const
+LV2_Options_Option*</code> and scan the array for any options of interest. The
+instance MUST NOT modify the options array in any way.</p>
+
+<p>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 a lv2:optionalFeature.</p>
+""" .
+
+opts:requiredOption
+ a rdf:Property ,
+ owl:ObjectProperty ;
+ rdfs:label "required option" ;
+ lv2:documentation """
+<p>An option required by the instance to function at all. The host MUST pass a
+value for the specified option via opts:options in order to create an
+instance.</p>
+
+<p>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.</p>
+""" .
+
+opts:supportedOption
+ a rdf:Property ,
+ owl:ObjectProperty ;
+ rdfs:label "supported option" ;
+ lv2:documentation """
+<p>An option supported or <q>understood</q> by the instance. The host SHOULD
+provide a value for the specified option if one is known, or provide the user
+an opportunity to specify one if one is Indicates that the instance host MUST
+pass a value for the specified option in order to instantiate the instance.</p>
+""" .
--
cgit v1.2.1