From fd74305f08c85ad62201de8d51d71a3f1d86cd54 Mon Sep 17 00:00:00 2001 From: David Robillard 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: . +@prefix doap: . +@prefix foaf: . +@prefix rdfs: . + + + a doap:Project ; + rdfs:seeAlso <../../meta/meta.ttl> ; + doap:name "LV2 Options" ; + doap:shortdesc "Instantiation time options" ; + doap:created "2012-08-20" ; + doap:developer ; + doap:release [ + doap:revision "0.1" ; + dcs:blame ; + 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: . +@prefix rdfs: . + + + a lv2:Specification ; + lv2:minorVersion 0 ; + lv2:microVersion 0 ; + rdfs:seeAlso . 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 + + 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 + +#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: . +@prefix opts: . +@prefix owl: . +@prefix rdf: . +@prefix rdfs: . +@prefix xsd: . + + + a owl:Ontology ; + rdfs:seeAlso , + <../../meta/meta.ttl> , + ; + lv2:documentation """ +

This extension defines a facility for options, which are parameters +passed to a plugin, UI, or other instance at instantiation time. Like the +command-line options of a program, options do not change over the +lifetime of an instance.

+ +

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.

+ +

Options are provided to instances by the host via the opts:options +feature.

+ +

Instances may indicate they require an option with the +opts:requiredOption property, or that they optionally support an option +with the opts:supportedOption property.

+""" . + +opts:options + a lv2:Feature ; + rdfs:label "options" ; + lv2:documentation """ +

The feature used to provide options to an instance.

+ +

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 a lv2:optionalFeature.

+""" . + +opts:requiredOption + a rdf:Property , + owl:ObjectProperty ; + rdfs:label "required option" ; + lv2:documentation """ +

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.

+ +

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.

+""" . + +opts:supportedOption + a rdf:Property , + owl:ObjectProperty ; + rdfs:label "supported option" ; + lv2:documentation """ +

An option supported or understood 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.

+""" . -- cgit v1.2.1