diff options
Diffstat (limited to 'extensions/ui.lv2/ui.ttl')
-rw-r--r-- | extensions/ui.lv2/ui.ttl | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/extensions/ui.lv2/ui.ttl b/extensions/ui.lv2/ui.ttl new file mode 100644 index 0000000..496b625 --- /dev/null +++ b/extensions/ui.lv2/ui.ttl @@ -0,0 +1,217 @@ +# LV2 UI Extension +# Copyright (C) 2006-2008 Lars Luthman <lars.luthman@gmail.com> +# Copyright (C) 2009-2010 David Robillard <d@drobilla.net> +# +# 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 ui: <http://lv2plug.in/ns/extensions/ui#> . +@prefix lv2: <http://lv2plug.in/ns/lv2core#> . +@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . +@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . +@prefix owl: <http://www.w3.org/2002/07/owl#> . +@prefix xsd: <http://www.w3.org/2001/XMLSchema#> . +@prefix doap: <http://usefulinc.com/ns/doap#> . +@prefix foaf: <http://xmlns.com/foaf/0.1/> . + +<http://lv2plug.in/ns/extensions/ui> a lv2:Specification ; + doap:license <http://usefulinc.com/doap/licenses/mit> ; + doap:name "LV2 UI" ; + doap:release [ + doap:revision "2pre" ; + doap:created "2010-05-10" + ] ; + doap:maintainer [ + a foaf:Person ; + foaf:name "Lars Luthman" ; + foaf:mbox <mailto:lars.luthman@gmail.com> + ] , [ + a foaf:Person ; + foaf:name "David Robillard" ; + foaf:homepage <http://drobilla.net/> ; + rdfs:seeAlso <http://drobilla.net/drobilla.rdf> + ] ; + rdfs:comment """ +This extension defines an interface that can be used in LV2 plugins and hosts +to create UIs for plugins. The UIs are similar to plugins and reside in shared object +files in an LV2 bundle. UIs are associated with a plugin in RDF using the triples +<pre> +@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> +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. + +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. + +(Note: the prefix above is used throughout this file for the same URI) + +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. + +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 can +<b>not</b> 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). + +Since the LV2 specification itself allows for extensions that may add new +functionality that could be useful to control with a UI, this extension +allows for meta-extensions that can extend the interface between the UI and +the host. These extensions mirror the extensions used for plugins - there are +required and optional "features" that you declare in the RDF data for the UI as +<pre> +<http://my.pluginui> lv2:requiredFeature <http://my.feature> . +<http://my.pluginui> lv2:optionalFeature <http://my.feature> . +</pre> +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. These features may be used to specify how to pass +specific types of data between the UI and the plugin port buffers +(see LV2UI_Write_Function for details). + +UIs written to this specification do not need to be threadsafe - the +functions defined below may only be called in the same thread the UI +main loop is running in. + +Note that this UI extension is NOT a lv2:Feature. There is no way for a +plugin to know whether the host that loads it supports UIs or not, and +the plugin must always work without the UI (although it may be rather +useless unless it has been configured using the UI in a previous session). +From the plugin perspective, control from a UI is the same as control +from anywhere else (e.g. the host, the user): via ports. + +A UI does not have to be a graphical widget, it could just as well be a +server listening for OSC input or an interface to some sort of hardware +device, depending on the RDF class of the UI. +""" . + + +ui:UI a rdfs:Class ; + rdfs:subClassOf lv2:Resource ; + rdfs:label "LV2 UI" ; + rdfs:comment "A UI for an LV2 plugin" . + +ui:GtkUI a rdfs:Class ; + rdfs:subClassOf ui: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 an UI of this type is instantiated.""" . + +ui:makeSONameResident a lv2:Feature ; + rdfs:comment """ +This feature is ELF specific - it should only be used by UIs that +use the ELF file format for the UI shared object files (e.g. on Linux). +If it is required by an UI the UI should also list a number of SO names +(shared object names) for libraries that the UI shared object +depends on and that may not be unloaded during the lifetime of the host +process, using the predicate @c ui:residentSONames, like this: +<pre> +<http://my.pluginui> ui:residentSONames "libgtkmm-2.4.so.1", "libfoo.so.0" +</pre> +The host MUST then make sure that the shared libraries with the given ELF +SO names are not unloaded when the plugin UI is, but stay loaded during +the entire lifetime of the host process. On Linux this can be accomplished +by calling dlopen() on the shared library file with that SO name and never +calling a matching dlclose(). However, if a plugin UI requires the +@c ui:makeSONameResident feature, it MUST ALWAYS be safe for the host to +just never unload the shared object containing the UI implementation, i.e. +act as if the UI required the @c ui:makeResident feature instead. Thus +the host only needs to find the shared library files corresponding to the +given SO names if it wants to save RAM by unloading the UI shared object +file when it is no longer needed. The data pointer for the LV2_Feature for +this feature should always be set to NULL. +"""^^lv2:basicXHTML . + +ui:noUserResize a lv2:Feature ; + rdfs:comment """ +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. +""" . + +ui:fixedSize a lv2:Feature ; + rdfs:comment """ +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. +""" . + +ui:PortNotification a rdfs:Class ; + rdfs:subClassOf [ + a owl:Restriction ; + owl:onProperty ui:plugin ; + owl:someValuesFrom lv2:Plugin ; + owl:cardinality 1 ; + rdfs:comment """ +A PortNotification MUST have exactly one ui:plugin which is a lv2:Plugin. +""" ] , [ + a owl:Restriction ; + owl:onProperty ui:portIndex ; + owl:someValuesFrom xsd:decimal ; + owl:cardinality 1 ; + rdfs:comment """ +A PortNotification MUST have exactly one ui:portIndex which is an xsd:decimal. +""" ] ; + rdfs:comment "Port Notification" . + +ui:portNotification a rdf:Property ; + rdfs:domain ui:UI ; + rdfs:range ui:PortNotification ; + rdfs:comment """ +Indicates that a UI should receive notification (via port_event on +LV2UI_Descriptor) when a particular port's value changes. +""" . + +ui:plugin a rdf:Property ; + rdfs:domain ui:PortNotification ; + rdfs:range lv2:Plugin ; + rdfs:comment """ +The plugin a portNotification applies to. +""" . + +ui:portIndex a rdf:Property ; + rdfs:domain ui:PortNotification ; + rdfs:range xsd:decimal ; + rdfs:comment """ +The index of the port a portNotification applies to. +""" . + |