aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/options/options.meta.ttl
blob: 838b0b94b94f7c1829a720a45a05af756fee9918 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
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: <http://lv2plug.in/ns/ext/options#> .

    <plugin>
        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 .