aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/lv2plug.in/ns/ext/pui/pui.ttl
blob: d30576966b8e5234af517b4aee9d8ed7f2365739 (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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
# LV2 Plugin UI Extension
# Copyright (C) 2010-2011 Lars Luthman <mail@larsluthman.net>
#
# Based on lv2.ttl, which is
# Copyright (C) 2006-2008 Steve Harris, David Robillard
#
# This extension should be considered a replacement for the earlier
# in-process UI extension with the URI <http://lv2plug.in/ns/extensions/ui>.
# Hosts and plugins that used that extension should use this one instead.
# The earlier in-process UI extension is not compatible with LV2 revision 3
# and later and may break in subtle ways.
#
# Permission is hereby granted, free of charge, to any person obtaining a
# copy of this software and associated documentation files (the "Software"),
# to deal in the Software without restriction, including without limitation
# the rights to use, copy, modify, merge, publish, distribute, sublicense,
# and/or sell copies of the Software, and to permit persons to whom the
# Software is furnished to do so, subject to the following conditions:
# 
# The above copyright notice and this permission notice shall be included
# in all copies or substantial portions of the Software.
# 
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
# ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
# OTHER DEALINGS IN THE SOFTWARE.

@prefix doap: <http://usefulinc.com/ns/doap#> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix lv2:  <http://lv2plug.in/ns/lv2core#>.
@prefix pui:  <http://lv2plug.in/ns/ext/pui#>.
@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/pui>
	a lv2:Specification ;
	doap:license <http://usefulinc.com/doap/licenses/mit> ;
	doap:name "LV2 UI" ;
	doap:shortdesc "Generic UI interface for LV2 plugins." ;
	doap:release [
		doap:revision "0.1" ;
		doap:created "2011-03-26"
	] ;
	doap:maintainer [
		a foaf:Person ;
		foaf:name "Lars Luthman" ;
		foaf:mbox <mailto:mail@larsluthman.net>
	] ;
	lv2:documentation """
<p>This extension defines an interface that can be used to create UIs for 
plugins. The UIs are code that reside in shared object files in an LV2
bundle and are referenced in the RDF data using the triples:</p>
<pre class="turtle-code">
@prefix pui: &lt;http://lv2plug.in/ns/ext/pui#&gt; .

&lt;http://example.org/my-ui&gt;
    a             pui:Gtk2UI ;
    lv2:appliesTo &lt;http://example.org/my-plugin&gt; ;
    pui:binary    &lt;my-ui.so&gt; .
</pre>
<p>... where <code>http://example.org/my-plugin</code> is the URI of the plugin,
<code>http://example.org/my-ui</code> is the URI of the plugin UI and
<code>my-ui.so</code> is the relative URI to the shared object file. While it
is possible to have the plugin UI and the plugin in the same shared object file
it is probably a good idea to keep them separate so that hosts that don't want
UIs don't have to load the UI code.</p>

<p>A UI MUST specify its class in the RDF data and the class MUST be a proper
subclass of pui:UI, in this case pui:Gtk2UI. The class defines what type the
UI is, e.g. what graphics toolkit it uses. There are no UI classes defined in
this extension, those are specified separately (and anyone can define their
own).</p>

<p>It's entirely possible to have multiple UIs for the same plugin, or to have
the UI for a plugin in a different bundle from the actual plugin - this way
people other than the plugin author can write plugin UIs independently without
editing the original plugin bundle. It is also possible to have one UI that
works with several different plugins.</p>

<p>UIs should also be written in such a way that the host may load several
instances of an UI, or different UIs, and use them with the same plugin
instance.</p>

<p>Note that the process that loads the shared object file containing the UI
code and the process that loads the shared object file containing the actual
plugin implementation do not have to be the same. There are many valid reasons
for having the plugin and the UI in different processes, or even on different
machines. This means that you can <strong>not</strong> use singletons and
global variables and expect them to refer to the same objects in the UI and the
actual plugin. The function callback interface defined in the header pui.h is
all you can expect to work.</p>
""" .

pui:UI
	a rdfs:Class ;
	rdfs:subClassOf lv2:Feature ;
	rdfs:label "UI" ;
	lv2:documentation """
<p>The class which represents an LV2 plugin UI.
</p>

<p>To be used by a host a UI MUST have at least the following properties:</p>
<ul>
<li>rdf:type (with object a proper subclass of pui:UI)</li>
<li>doap:name (one without language tag)</li>
<li>lv2:binary (with a shared object file as object)</li>
<li>lv2:appliesTo (with a LV2 plugin as object)</li>
</ul>

<p>The rdf:type of an UI is used by the host to decide whether it supports the
UI and how to handle the LV2_PUI_Widget object that is returned by the UIs
get_widget() function. For example, a type of pui:Gtk2UI might tell the
host that LV2_PUI_Widget is a pointer to an object of a type defined in the
Gtk+ library. No UI types are defined in this extension, that is intentionally
left for other extensions.</p>

<p>The doap:name property should be at most a few words in length using title
capitalization, e.g. "Flashy Mixer GUI". Use lv2:documentation for more
detailed descriptions.</p>

<p>UIs may have optional or required features, specified using lv2:optionalFeature
or lv2:requiredFeature. The same rules apply here as for plugins; a host MUST
pass the LV2_Feature objects for all features it supports to the UI's
instantiate() function, a host SHOULD NOT try to instantiate an UI if it
doesn't support all of its required features, and an UI MUST fail to
instantiate if the host doesn't pass all required features to instantiate().
</p>

<p>For details about the C API used to load UIs, see the file pui.h.
</p>
""" .

pui:PortProtocol
	a rdfs:Class ;
	rdfs:subClassOf lv2:Feature ;
	rdfs:label "Port protocol" ;
	lv2:documentation """
<p>A PortProtocol defines a certain way of communicating port data between UI
and plugin. PortProtocols can be specified in additional extensions, and
those extensions MUST specify:
</p>

<ol>
<li>Which plugin port types the buffer type is valid for</li>
<li>When the host should call port_event() in LV2_PUI_Descriptor</li>
<li>The format of the data in the buffer passed to port_event()</li>
<li>The format of the data in the buffer passed to write_port()</li>
<li>What happens when the UI calls write_port() in LV2_PUI_Host_Descriptor</li>
<li>What data (if any) should be passed in the LV2_Feature data pointer. </li>
</ol>

<p>For an example, see pui:floatControl or pui:floatPeakRMS.
</p>

<p>PortProtocol is a subclass of lv2:Feature, so UIs use lv2:optionalFeature and
lv2:requiredFeature to specify which PortProtocols they want to use.
</p>
""" .

pui:floatControl
	a pui:PortProtocol ;
	rdfs:label "Floating point value" ;
	lv2:documentation """
<p>The rules (see pui:PortProtocol) for this port protocol are:</p>
<ol>
<li>This PortProtocol is valid for ports with the type lv2:ControlPort.</li>
<li>The host SHOULD call port_event() as soon as possible when the port value
    has changed, but the plugin MUST NOT depend on a call for every change or
    the timing of the calls. However, the host MUST do the calls in the same
    order that the value changes occur in.</li>
<li>The format of the data in the buffer passed to port_event() is a single
    float, and the buffer size is sizeof(float).</li>
<li>Same as 3.</li>
<li>The host SHOULD change the port value as soon as possible when write_port()
    is called, but the UI MUST NOT depend on a change for every call or the
    timing of the changes. However, the host MUST do the changes in the same
    order that the function calls occur in.</li>
<li>The data pointer in the LV2_Feature object for this feature should be
    NULL.</li>
</ol>
""" .

pui:floatPeakRMS
	a pui:PortProtocol ;
	rdfs:label "Peak and RMS for a period of audio data" ;
	lv2:documentation """
<p>This port protocol defines a way for the host to send continuous peak
and RMS measurements of the audio signal at a certain port to the UI. The
intended use is visualisation, e.g. an animated meter widget that shows
the level of the audio input or output.</p>

<p>A contiguous sequence of audio samples for which a single peak value
and a single RMS value have been computed is called a <em>measurement
period</em>.</p>

<p>The rules (see pui:PortProtocol) for this port protocol are:</p>
<ol>
<li>This PortProtocol is valid for ports with the type lv2:AudioPort.</li>
<li>The host SHOULD call port_event() at regular intervals. The measurement
    periods used for calls to port_event() for the same port SHOULD be
    contiguous (i.e. the measurement period for one call should begin right
    after the end of the measurement period for the previous call ends) unless
    the UI has removed and re-added the port subscription between those calls.
    However, UIs MUST NOT depend on either the regularity of the calls or the
    contiguity of the measurement periods; hosts may change the call rate
    or skip calls for performance or other reasons. Measurement periods for
    different calls to port_event() for the same port MUST NOT overlap.</li>
<li>The format of the data in the buffer passed to port_event() is a single
    LV2_PUI_Peak_RMS_Data object, and the buffer size is
    sizeof(LV2_PUI_Peak_RMS_Data).</li>
<li>The UI MUST NOT call write_port() with the ID for this port protocol as
    the port_protocol parameter.</li>
<li>The host MUST ignore any write_port() calls with the ID for this port
    protocol as the port_protocol parameter.</li>
<li>The data pointer in the LV2_Feature object for this feature should be
    NULL.</li>
</ol>
""" .

pui:events
	a pui:PortProtocol ;
	rdfs:label "Event buffer" ;
	lv2:documentation """
<ol>
<li>This PortProtocol is valid for ports with the type ev:EventPort.</li>
<li>The host MUST call port_event() whenever there is an event in an input port
    prior to the plugin instance's run() function is called, and whenever there
    is an event in an output port after run() has been called. The UI MUST NOT
    depend on the timing of the calls. However, the host MUST do the calls in
    the same order that the events occur in. The host is allowed and encouraged
    to bundle multiple events into a single port_event() call if it improves
    performance.</li>
<li>The data buffer passed to port_event() is an LV2_Event_Buffer, as specified
    in the Event extension. The stamp_type MUST be ignored. The frames and
    subframes fields of every event in the buffer MUST be ignored. Events with
    type 0 (reference counted events) MUST be ignored.</li>
<li>The data buffer passed to write_event() is an LV2_Event_Buffer, as
    specified in the Event extension. The stamp_type MUST be ignored. The
    frames and subframes fields of every event in the buffer MUST be
    ignored. The host MUST NOT pass events with type 0 (references) unless the
    UI supports the feature "http://lv2plug.in/ns/ext/event".</li>
<li>The host MUST pass all the events in the buffer to the plugin instance's
    event port in the same order, but the plugin and the UI MUST NOT depend on
    the timing of the events, or on whether they are all sent to the plugin in
    the same run() call or distributed over multiple calls.</li>
<li>The data pointer in the LV2_Feature object for this feature should be
    NULL.</li>
</ol>
""" .

pui:Gtk2UI
	a rdfs:Class ;
	rdfs:subClassOf pui:UI ;
	rdfs:label "Gtk+ UI" ;
	lv2:documentation """
<p>The class which represents a Gtk+ UI. For a successfully created instance of
an UI of this class, the get_widget() function MUST return a pointer to a valid
GtkWidget object compatible with Gtk+ version 2.0. The host MUST ensure that
the Gtk+ library has been initialised and that the Glib main loop is running
before an UI of this type is instantiated.</p>

<p>Unless otherwise specified by extensions, all function pointers in
LV2_PUI_Descriptor may only be called from the thread that runs the Glib main
loop.</p>
""" .

pui:noHostResize
	a lv2:Feature ;
	rdfs:label "No host resize" ;
	lv2:documentation """
<p>This Feature should only be used with UIs.</p>

<p>When this Feature is active the host SHOULD NOT resize the UI widget to any
other size than its natural size, which the host should be able to determine
via the API of whatever toolkit the UI is implemented in.  However, the UI MUST
NOT break if the widget is resized to another size. This Feature can be used
for example when the widget uses a fixed-size pixmap interface.</p>

<p>The data pointer in the LV2_Feature object for this Feature should be set to
NULL.</p>
""" .