diff options
Diffstat (limited to 'lv2/ui/ui.ttl')
| -rw-r--r-- | lv2/ui/ui.ttl | 461 |
1 files changed, 461 insertions, 0 deletions
diff --git a/lv2/ui/ui.ttl b/lv2/ui/ui.ttl new file mode 100644 index 0000000..48ac166 --- /dev/null +++ b/lv2/ui/ui.ttl @@ -0,0 +1,461 @@ +@prefix lv2: <http://lv2plug.in/ns/lv2core#> . +@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 ui: <http://lv2plug.in/ns/extensions/ui#> . +@prefix xsd: <http://www.w3.org/2001/XMLSchema#> . + +<http://lv2plug.in/ns/extensions/ui> + a owl:Ontology ; + owl:imports <http://lv2plug.in/ns/lv2core> ; + rdfs:seeAlso <ui.h> , + <lv2-ui.doap.ttl> ; + lv2:documentation """ +<p>This extension is used to create User Interfaces (UIs) for LV2 plugins.</p> + +<p>UIs are implemented as an LV2UI_Descriptor loaded via lv2ui_descriptor() in +a shared library, and are distributed in bundles just like plugins.</p> + +<p>UIs are associated with plugins in data:</p> + +<pre class="turtle-code"> +@prefix ui: <http://lv2plug.in/ns/extensions/ui#> . + +<http://my.plugin> ui:ui <http://my.pluginui> . +<http://my.pluginui> a ui:GtkUI ; + ui:binary <myui.so> . +</pre> + +<p>where <http://my.plugin> is the URI of the plugin, +<http://my.pluginui> is the URI of the plugin UI and <myui.so> is +the relative URI to the shared object file.</p> + +<p>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. A UI MUST specify its class in +the RDF data (ui:GtkUI in the above example). The class defines what type the +UI is, e.g. what graphics toolkit it uses. Any type of UI class can be defined +separately from this extension.</p> + +<p>It is 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.</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 are not necessarily the same process (and not even +necessarily on the same machine). This means that plugin and UI code MUST NOT +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 this header is the only method of communication between UIs and +plugin instances (extensions may define more, though this is discouraged unless +absolutely necessary since the significant benefits of network transparency and +serialisability are lost).</p> + +<p>UI functionality may be extended via features, much like plugins:</p> + +<pre class="turtle-code"> +<http://my.pluginui> lv2:requiredFeature <http://my.feature> . +<http://my.pluginui> lv2:optionalFeature <http://my.feature> . +</pre> + +<p>The rules for a UI with a required or optional feature are identical to +those of lv2:Plugin instances: if a UI declares a feature as required, the host +is NOT allowed to load it unless it supports that feature; and if it does +support a feature, it MUST pass an appropriate LV2_Feature struct to the UI's +instantiate() method. This extension defines several standard features for +common functionality.</p> + +<p>UIs written to this specification do not need to be thread-safe. All +functions may only be called in the <q>UI thread</q>. There is only one UI +thread (for toolkits, the one the UI main loop runs in). There is no +requirement that a <q>UI</q> actually be a graphical widget.</p> + +<p>Note that UIs are completely separate from plugins. From the plugin's +perspective, control from a UI is indistinguishable from any other control, as +it all occcurs via ports.</p> +""" . + +ui:UI + a rdfs:Class , + owl:Class ; + rdfs:label "User Interface" ; + rdfs:comment "A UI for an LV2 plugin" . + +ui:GtkUI + a rdfs:Class , + owl:Class ; + rdfs:subClassOf ui:UI ; + rdfs:label "GTK2 UI" ; + rdfs:comment """A UI where the LV2_Widget is a pointer to a Gtk+ 2.0 compatible GtkWidget, and the host guarantees that the Gtk+ library has been initialised and the Glib main loop is running before a UI of this type is instantiated.""" . + +ui:Gtk3UI + a rdfs:Class , + owl:Class ; + rdfs:subClassOf ui:UI ; + rdfs:label "GTK3 UI" ; + rdfs:comment """A UI where the LV2_Widget is a pointer to a Gtk+ 3.0 compatible GtkWidget, and the host guarantees that the Gtk+ library has been initialised and the Glib main loop is running before a UI of this type is instantiated.""" . + +ui:Qt4UI + a rdfs:Class , + owl:Class ; + rdfs:subClassOf ui:UI ; + rdfs:label "Qt4 UI" ; + rdfs:comment """A UI where the LV2_Widget is a pointer to a Qt4 compatible QWidget, and the host guarantees that the Qt4 library has been initialised and the Qt4 main loop is running before a UI of this type is instantiated.""" . + +ui:Qt5UI + a rdfs:Class , + owl:Class ; + rdfs:subClassOf ui:UI ; + rdfs:label "Qt5 UI" ; + rdfs:comment """A UI where the LV2_Widget is a pointer to a Qt5 compatible QWidget, and the host guarantees that the Qt5 library has been initialised and the Qt5 main loop is running before a UI of this type is instantiated.""" . + +ui:X11UI + a rdfs:Class , + owl:Class ; + rdfs:subClassOf ui:UI ; + rdfs:label "X11 UI" ; + rdfs:comment """A UI where the LV2_Widget is an X11 window ID. Note this is actually an integer, i.e. the LV2_Widget is not a pointer to an X11 window ID, but should be itself taken as an integer value. This is the native UI type on most POSIX systems.""" . + +ui:WindowsUI + a rdfs:Class , + owl:Class ; + rdfs:subClassOf ui:UI ; + rdfs:label "Windows UI" ; + rdfs:comment """A UI where the LV2_Widget is a Windows HWND window ID. Note this is actually an unsigned 32-bit integer, i.e. the LV2_Widget is not a pointer to a HWND but should be interpreted as an HWND itself. This is the native UI type on Microsoft Windows.""" . + +ui:CocoaUI + a rdfs:Class , + owl:Class ; + rdfs:subClassOf ui:UI ; + rdfs:label "Cocoa UI" ; + rdfs:comment """A UI where the LV2_Widget is a pointer to a NSView, the basic view type for the Cocoa API (formerly OpenStep). This is the native UI type on Mac OS X.""" . + +ui:ui + a rdf:Property ; + rdfs:domain lv2:Plugin ; + rdfs:range ui:UI ; + rdfs:label "user interface" ; + rdfs:comment """Relates a plugin to a UI that applies to it.""" . + +ui:binary + a rdf:Property ; + owl:sameAs lv2:binary ; + owl:deprecated "true"^^xsd:boolean ; + rdfs:label "binary" ; + rdfs:comment """The shared library a UI resides in. This property is redundant, new UIs SHOULD use lv2:binary, however hosts MUST still support ui:binary at this time.""" . + +ui:makeSONameResident + a lv2:Feature ; + owl:deprecated "true"^^xsd:boolean ; + lv2:documentation """ +<p>DEPRECATED</p> + +<p>This feature was intended to support UIs that link against toolkit +libraries which may not be unloaded during the lifetime of the host. +This is better achieved by using the appropriate flags when linking the +UI, e.g. <code>gcc -Wl,-z,nodelete</code>.</p> +""" . + +ui:noUserResize + a lv2:Feature ; + lv2:documentation """ +<p>If a UI requires this feature it indicates that it does not make sense +to let the user resize the main widget, and the host should prevent that. +This feature may not make sense for all UI types. The data pointer for the +LV2_Feature for this feature should always be set to NULL.</p> +""" . + +ui:fixedSize + a lv2:Feature ; + lv2:documentation """ +<p>If a UI requires this feature it indicates the same thing as +ui:noUserResize, and additionally it means that the UI will not resize +the main widget on its own - it will always remain the same size (e.g. a +pixmap based GUI). This feature may not make sense for all UI types. +The data pointer for the LV2_Feature for this feature should always be set +to NULL.</p> +""" . + +ui:parent + a lv2:Feature ; + lv2:documentation """ +<p>The parent for the UI.</p> + +<p>This feature can be used to pass a parent (e.g. a widget, container, canvas, +etc.) the UI should be a child of. The format of data pointer of this feature +is determined by the UI type, and is generally the same type as the LV2_Widget +the UI would return (e.g. for a GtkUI the data would be a pointer to a +GtkWidget which is a GtkContainer). This is particularly useful for +cross-toolkit embedding, where the parent often must be known at construction +time for embedding to work correctly. UIs should not require this feature +unless it is absolutely necessary for them to work at all.</p> +""" . + +ui:PortNotification + a rdfs:Class , + owl:Class ; + rdfs:subClassOf [ + a owl:Restriction ; + owl:onProperty ui:plugin ; + owl:cardinality 1 ; + rdfs:comment "A PortNotification MUST have exactly one ui:plugin." ; + ] ; + lv2:documentation """ +<p>A port notification. This describes which ports the host must send +notifications to the UI about. The port can be specific by index, using the +ui:portIndex property, or symbol, using the lv2:symbol property. Since port +indices are not guaranteed to be stable between different revisions (or even +instantiations) of a plugin, symbol is recommended, and index may only be used +by UIs shipped in the same bundle as the plugin.</p> + +<p>A ui:PortNotification MUST have either a ui:portIndex or a lv2:symbol to +indicate which port it refers to.</p> +""" . + +ui:portNotification + a rdf:Property , + owl:ObjectProperty ; + rdfs:domain ui:UI ; + rdfs:range ui:PortNotification ; + rdfs:label "port notification" ; + lv2:documentation """ +<p>Indicates that a UI should receive notification (via +LV2UI_Descriptor::port_event()) when a particular port's value changes.</p> + +<p>For example:</p> +<pre class="turtle-code"> +eg:ui + a ui:GtkUI ; + ui:portNotification [ + ui:plugin eg:plugin ; + lv2:symbol "gain" ; + ui:protocol ui:floatProtocol + ] . +</pre> +""" . + +ui:plugin + a rdf:Property , + owl:ObjectProperty ; + rdfs:domain ui:PortNotification ; + rdfs:range lv2:Plugin ; + rdfs:label "plugin" ; + rdfs:comment "The plugin a portNotification applies to." . + +ui:portIndex + a rdf:Property , + owl:DatatypeProperty ; + rdfs:domain ui:PortNotification ; + rdfs:range xsd:decimal ; + rdfs:label "port index" ; + rdfs:comment "The index of the port a portNotification applies to." . + +ui:notifyType + a rdf:Property ; + rdfs:domain ui:PortNotification ; + rdfs:label "notify type" ; + lv2:documentation """ +<p>Indicates a particular type that the UI should be notified of. In the case +of ports where several types of data can be present (e.g. event ports), this +can be used to indicate that only a particular type of data should cause +notification. This is useful where port traffic is very dense, but only a +certain small number of events are actually of interest to the UI.</p> +""" . + +ui:resize + a lv2:Feature , + lv2:ExtensionData ; + lv2:documentation """ +<p>A feature that allows the UI to notify the host about its current size, or +request a size change. This feature corresponds to the LV2UI_Resize struct, +which should be passed with the URI LV2_UI__resize. This struct may also be +provided by the UI as extension data using the same URI, in which case it is +used by the host to request that the UI change its size.</p> +""" . + +ui:portMap + a lv2:Feature ; + lv2:documentation """ +<p>A feature for accessing the index of a port by symbol. This makes it +possible to implement and distribute UIs separately from the plugin binaries +they control. This feature corresponds to the LV2UI_Port_Index struct, which +should be passed with the URI LV2_UI__portIndex.</p> +""" . + +ui:portSubscribe + a lv2:Feature ; + lv2:documentation """ +<p>A feature for dynamically subscribing to updates from a port. This makes it +possible for a UI to explicitly request a particular style of update from a +port at run-time, in a more flexible and powerful way than listing +subscriptions statically allows. This feature corresponds to the +LV2UI_Port_Subscribe struct, which should be passed with the URI +LV2_UI__portSubscribe.</p> +""" . + +ui:touch + a lv2:Feature ; + lv2:documentation """ +<p>A feature to notify the host that the user has grabbed a particular port +control. This is useful for automation, so the host can allow the user to take +control of a port, even if that port would otherwise be automated (much like +grabbing a physical morotised fader). It can also be used for MIDI learn or in +any other situation where the host needs to do something with a particular +control and it would be convenient for the user to select it directly from the +plugin UI. This feature corresponds to the LV2UI_Touch struct, which +should be passed with the URI LV2_UI__touch.</p> +""" . + +ui:idleInterface + a lv2:Feature , + lv2:ExtensionData ; + lv2:documentation """ +<p>A feature that provides a callback for the host to call rapidly to drive the +UI. To support this feature, the UI should list it as a lv2:optionalFeature or +lv2:requiredFeature in its data, and also as lv2:extensionData. When the UI's +extension_data() is called with this URI (LV2_UI__idleInterface), it should +return a pointer to an LV2UI_Idle_Interface.</p> + +<p>To indicate support, the host should pass a feature to instantiate() with +this URI, with NULL for data.</p> +""" . + +ui:showInterface + a lv2:ExtensionData ; + lv2:documentation """ +<p>An interface for showing and hiding a window for a UI. This allows UIs to +gracefully degrade to separate windows when the host is unable to embed the UI +widget for whatever reason. When the UI's extension_data() is called with this +URI (LV2_UI__showInterface), it should return a pointer to an +LV2UI_Show_Interface.</p> +""" . + +ui:windowTitle + a rdf:Property ; + rdfs:range xsd:string ; + rdfs:label "window title" ; + rdfs:comment "The title for the window shown by LV2UI_Show_Interface." . + +ui:updateRate + a rdf:Property ; + rdfs:range xsd:float ; + rdfs:label "update rate" ; + rdfs:comment "The target rate, in Hz, to send updates to the UI." . + +ui:protocol + a rdf:Property ; + rdfs:domain ui:PortNotification ; + rdfs:range ui:PortProtocol ; + rdfs:label "protocol" ; + rdfs:comment "The protocol to be used for this notification." . + +ui:PortProtocol + a rdfs:Class ; + rdfs:subClassOf lv2:Feature ; + rdfs:label "Port Protocol" ; + lv2:documentation """ +<p>A PortProtocol defines a method to communicate port data between a UI and +plugin.</p> + +<p>Any PortProtocol MUST define:</p> +<table> +<tr><th>Port Type</th> + <td>Which plugin port types the buffer type is valid for.</td></tr> +<tr><th>Feature Data</th> + <td>What data (if any) should be passed in the LV2_Feature.</td></tr> +</table> + +<p>Any PortProtocol for an output port MUST define:</p> +<table> +<tr><th>Update Frequency</th> + <td>When the host should call port_event().</td></tr> +<tr><th>Update Format</th> + <td>The format of the data in the buffer passed to port_event().</td></tr> +<tr><th>Options</th> + <td>The format of the options passed to subscribe() and unsubscribe().</td> +</tr></table> + +<p>Any PortProtocol for an input port MUST define:</p> +<table> +<tr><th>Write Format</th> + <td>The format of the data in the buffer passed to write_port().</td></tr> +<tr><th>Write Effect</th> + <td>What happens when the UI calls write_port().</td></tr> +</table> + +<p>For an example, see ui:floatProtocol or ui:peakProtocol. +</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> +""" . + +ui:floatProtocol + a ui:PortProtocol ; + rdfs:label "floating point value" ; + lv2:documentation """ + +<p>A protocol for transferring single floating point values. The rules for +this protocol are:</p> +<table> +<tr><th>Port Type</th> + <td>lv2:ControlPort</td></tr> +<tr><th>Feature Data</th> + <td>None.</td></tr> +<tr><th>Update Frequency</th> + <td>The host SHOULD call port_event() as soon as possible when the port + value has changed, but there are no timing guarantees.</td></tr> +<tr><th>Update Format</th> + <td>A single <code>float</code>.</td></tr> +<tr><th>Options</th> + <td>None.</td></tr> +<tr><th>Write Format</th> + <td>A single <code>float</code>.</td></tr> +<tr><th>Write Effect</th> + <td>The host SHOULD set the port to the received value as soon as possible, + but there is no guarantee that run() actually sees this value.</td></tr> +</table> +""" . + +ui:peakProtocol + a ui:PortProtocol ; + rdfs:label "peak measurement for a period of audio" ; + lv2:documentation """ +<p>This port protocol defines a way for the host to send continuous peak +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 peak value has been +computed is called a <em>measurement period</em>.</p> + +<p>The rules for this protocol are:</p> +<table> +<tr><th>Port Type</th> + <td>lv2:AudioPort</td></tr> +<tr><th>Feature Data</th> + <td>None.</td></tr> +<tr><th>Update Frequency</th> + <td>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.</td></tr> +<tr><th>Update Format</th> + <td>A single LV2UI_Peak_Data object.</td></tr> +<tr><th>Options</th> + <td>None.</td></tr> +<tr><th>Write Format</th> + <td>None.</td></tr> +<tr><th>Write Effect</th> + <td>None.</td></tr> +</table> +""" . |