aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/ui/ui.meta.ttl
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2020-03-22 16:36:44 +0100
committerDavid Robillard <d@drobilla.net>2020-04-10 19:46:04 +0200
commit430284545345539c9ffb31df889debac1d3888b5 (patch)
treedc9bb1f32f0d6fe34a7339221389048e199f14a5 /lv2/ui/ui.meta.ttl
parentc4514483da1ab4f49148f9c4fe4ff5b559323217 (diff)
downloadlv2-430284545345539c9ffb31df889debac1d3888b5.tar.xz
Move documentation to metadata files and convert it to Markdown
Diffstat (limited to 'lv2/ui/ui.meta.ttl')
-rw-r--r--lv2/ui/ui.meta.ttl472
1 files changed, 470 insertions, 2 deletions
diff --git a/lv2/ui/ui.meta.ttl b/lv2/ui/ui.meta.ttl
index b83a730..59d5ac6 100644
--- a/lv2/ui/ui.meta.ttl
+++ b/lv2/ui/ui.meta.ttl
@@ -1,13 +1,16 @@
@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 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#> .
<http://lv2plug.in/ns/extensions/ui>
a doap:Project ;
doap:license <http://opensource.org/licenses/isc> ;
doap:name "LV2 UI" ;
- doap:shortdesc "LV2 plugin UIs of any type." ;
+ doap:shortdesc "User interfaces for LV2 plugins." ;
doap:created "2006-00-00" ;
doap:developer <http://lv2plug.in/ns/meta#larsl> ;
doap:maintainer <http://drobilla.net/drobilla#me> ;
@@ -20,6 +23,8 @@
rdfs:label "Add ui:requestValue feature."
] , [
rdfs:label "Add ui:scaleFactor, ui:foregroundColor, and ui:backgroundColor properties."
+ ] , [
+ rdfs:label "Deprecate ui:binary."
]
]
] , [
@@ -154,5 +159,468 @@
rdfs:label "Initial release."
]
]
- ] .
+ ] ;
+ lv2:documentation """
+
+This extension makes it possible to create user interfaces for LV2 plugins.
+
+UIs are implemented as an LV2UI_Descriptor loaded via lv2ui_descriptor() in a
+shared library, and are distributed in bundles just like plugins.
+
+UIs are associated with plugins in data:
+
+ :::turtle
+ @prefix ui: <http://lv2plug.in/ns/extensions/ui#> .
+
+ <http://my.plugin> ui:ui <http://my.pluginui> .
+ <http://my.pluginui> a ui:X11UI ;
+ lv2:binary <myui.so> .
+
+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 a good idea to keep them separate so that hosts can avoid
+loading the UI code if they do not need it. A UI MUST specify its class in the
+RDF data (`ui:X11UI` in the above example). The class defines what type the UI
+is, for example what graphics toolkit it uses. Any type of UI class can be
+defined separately from this extension.
+
+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 allows plugin UIs
+to be written independently.
+
+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).
+
+UI functionality may be extended via features, much like plugins:
+
+ :::turtle
+ <http://my.pluginui> lv2:requiredFeature <http://my.feature> .
+ <http://my.pluginui> lv2:optionalFeature <http://my.feature> .
+
+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.
+
+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.
+
+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.
+
+"""^^lv2:Markdown .
+
+ui:GtkUI
+ lv2:documentation """
+
+The host must guarantee that the Gtk+ 2 library has been initialised and the
+Glib main loop is running before the UI is instantiated. Note that this UI
+type is not suitable for binary distribution since multiple versions of Gtk can
+not be used in the same process.
+
+"""^^lv2:Markdown .
+
+ui:Gtk3UI
+ lv2:documentation """
+
+The host must guarantee that the Gtk+ 3 library has been initialised and the
+Glib main loop is running before the UI is instantiated. Note that this UI
+type is not suitable for binary distribution since multiple versions of Gtk can
+not be used in the same process.
+
+"""^^lv2:Markdown .
+
+ui:Qt4UI
+ lv2:documentation """
+
+The host must guarantee that the Qt4 library has been initialised and the Qt4
+main loop is running before the UI is instantiated. Note that this UI type is
+not suitable for binary distribution since multiple versions of Qt can not be
+used in the same process.
+
+"""^^lv2:Markdown .
+
+ui:Qt5UI
+ lv2:documentation """
+
+The host must guarantee that the Qt5 library has been initialised and the Qt5
+main loop is running before the UI is instantiated. Note that this UI type is
+not suitable for binary distribution since multiple versions of Qt can not be
+used in the same process.
+
+"""^^lv2:Markdown .
+
+ui:X11UI
+ lv2:documentation """
+
+Note that the LV2UI_Widget for this type of UI is not a pointer, but should be
+interpreted directly as an X11 `Window` ID. This is the native UI type on most
+POSIX systems.
+
+"""^^lv2:Markdown .
+
+ui:WindowsUI
+ lv2:documentation """
+
+Note that the LV2UI_Widget for this type of UI is not a pointer, but should be
+interpreted directly as a `HWND`. This is the native UI type on Microsoft
+Windows.
+
+"""^^lv2:Markdown .
+
+ui:CocoaUI
+ lv2:documentation """
+
+This is the native UI type on Mac OS X.
+
+"""^^lv2:Markdown .
+
+ui:binary
+ lv2:documentation """
+
+This property is redundant and deprecated: new UIs should use lv2:binary
+instead, however hosts must still support ui:binary.
+
+"""^^lv2:Markdown .
+
+ui:makeSONameResident
+ lv2:documentation """
+
+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, for example `gcc
+-Wl,-z,nodelete`.
+
+"""^^lv2:Markdown .
+
+ui:noUserResize
+ lv2:documentation """
+
+If a UI has 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 this feature should
+always be set to NULL.
+
+"""^^lv2:Markdown .
+
+ui:fixedSize
+ lv2:documentation """
+
+If a UI has this feature, it indicates the same thing as ui:noUserResize, and
+additionally that the UI will not resize itself on its own. That is, the UI
+will always remain the same size. This feature may not make sense for all UI
+types. The data pointer for this feature should always be set to NULL.
+
+"""^^lv2:Markdown .
+
+ui:scaleFactor
+ lv2:documentation """
+
+HiDPI (High Dots Per Inch) displays have a high resolution on a relatively
+small form factor. Many systems use a scale factor to compensate for this, so
+for example, a scale factor of 2 means things are drawn twice as large as
+normal.
+
+Hosts can pass this as an option to UIs to communicate this information, so
+that the UI can draw at an appropriate scale.
+
+"""^^lv2:Markdown .
+
+ui:backgroundColor
+ lv2:documentation """
+
+The background color of the host's UI. The host can pass this as an option so
+that UIs can integrate nicely with the host window around it.
+
+Hosts should pass this as an option to UIs with an integer RGBA32 color value.
+If the value is a 32-bit integer, it is guaranteed to be in RGBA32 format, but
+the UI must check the value type and not assume this, to allow for other types
+of color in the future.
+
+"""^^lv2:Markdown .
+
+ui:foregroundColor
+ lv2:documentation """
+
+The foreground color of the host's UI. The host can pass this as an option so
+that UIs can integrate nicely with the host window around it.
+
+Hosts should pass this as an option to UIs with an integer RGBA32 color value.
+If the value is a 32-bit integer, it is guaranteed to be in RGBA32 format, but
+the UI must check the value type and not assume this, to allow for other types
+of color in the future.
+
+"""^^lv2:Markdown .
+
+ui:parent
+ lv2:documentation """
+
+This feature can be used to pass a parent that 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 LV2UI_Widget that the UI would return. For
+example, for a ui:X11UI, the parent should be a `Window`. This is particularly
+useful for 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 necessary for them to work
+at all, but hosts should provide it whenever possible.
+
+"""^^lv2:Markdown .
+
+ui:PortNotification
+ lv2:documentation """
+
+This describes which ports the host must send notifications to the UI about.
+The port must be specific either by index, using the ui:portIndex property, or
+symbol, using the lv2:symbol property. Since port indices are not guaranteed
+to be stable, using the symbol is recommended, and the inde MUST NOT be used
+except by UIs that are shipped in the same bundle as the corresponding plugin.
+
+"""^^lv2:Markdown .
+
+ui:portNotification
+ lv2:documentation """
+
+Specifies that a UI should receive notifications about changes to a particular
+port's value via LV2UI_Descriptor::port_event().
+
+For example:
+
+ :::turtle
+ eg:ui
+ a ui:X11UI ;
+ ui:portNotification [
+ ui:plugin eg:plugin ;
+ lv2:symbol "gain" ;
+ ui:protocol ui:floatProtocol
+ ] .
+
+"""^^lv2:Markdown .
+
+ui:notifyType
+ lv2:documentation """
+
+Specifies a particular type that the UI should be notified of.
+
+This is useful for message-based ports where several types of data can be
+present, but only some are interesting to the UI. For example, if UI control
+is multiplexed in the same port as MIDI, this property can be used to ensure
+that only the relevant events are forwarded to the UI, and not potentially high
+frequency MIDI data.
+
+"""^^lv2:Markdown .
+
+ui:resize
+ lv2:documentation """
+
+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.
+
+"""^^lv2:Markdown .
+
+ui:portMap
+ lv2:documentation """
+
+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.
+
+"""^^lv2:Markdown .
+
+ui:portSubscribe
+ lv2:documentation """
+
+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.
+
+"""^^lv2:Markdown .
+
+ui:touch
+ lv2:documentation """
+
+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 motorised 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.
+
+"""^^lv2:Markdown .
+
+ui:requestValue
+ lv2:documentation """
+
+This allows a plugin UI to request a new parameter value using the host's UI,
+for example by showing a dialog or integrating with the host's built-in content
+browser. This should only be used for complex parameter types where the plugin
+UI is not capable of showing the expected native platform or host interface to
+choose a value, such as file path parameters.
+
+This feature corresponds to the LV2UI_Request_Value struct, which should be
+passed with the URI LV2_UI__requestValue.
+
+"""^^lv2:Markdown .
+
+ui:idleInterface
+ lv2:documentation """
+
+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.
+
+To indicate support, the host should pass a feature to instantiate() with this
+URI, with NULL for data.
+
+"""^^lv2:Markdown .
+
+ui:showInterface
+ lv2:documentation """
+
+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.
+
+"""^^lv2:Markdown .
+
+ui:PortProtocol
+ lv2:documentation """
+
+A PortProtocol MUST define:
+
+Port Type
+: Which plugin port types the buffer type is valid for.
+
+Feature Data
+: What data (if any) should be passed in the LV2_Feature.
+
+A PortProtocol for an output port MUST define:
+
+Update Frequency
+: When the host should call port_event().
+
+Update Format
+: The format of the data in the buffer passed to port_event().
+
+Options
+: The format of the options passed to subscribe() and unsubscribe().
+
+A PortProtocol for an input port MUST define:
+
+Write Format
+: The format of the data in the buffer passed to write_port().
+
+Write Effect
+: What happens when the UI calls write_port().
+
+For an example, see ui:floatProtocol or ui:peakProtocol.
+
+PortProtocol is a subclass of lv2:Feature, so UIs use lv2:optionalFeature and
+lv2:requiredFeature to specify which PortProtocols they want to use.
+
+"""^^lv2:Markdown .
+
+ui:floatProtocol
+ lv2:documentation """
+
+A protocol for transferring single floating point values. The rules for this
+protocol are:
+
+Port Type
+: lv2:ControlPort
+
+Feature Data
+: None.
+
+Update Frequency
+: The host SHOULD call port_event() as soon as possible when the port value has
+ changed, but there are no timing guarantees.
+
+Update Format
+: A single <code>float</code>.
+
+Options
+: None.
+
+Write Format
+: A single <code>float</code>.
+
+Write Effect
+: 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.
+
+"""^^lv2:Markdown .
+
+ui:peakProtocol
+ lv2:documentation """
+
+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, for example an animated meter widget that shows the level of
+the audio input or output.
+
+A contiguous sequence of audio samples for which a peak value has been computed
+is called a _measurement period_.
+
+The rules for this protocol are:
+
+Port Type
+: lv2:AudioPort
+
+Feature Data
+: None.
+
+Update Frequency
+: 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.
+
+Update Format
+: A single LV2UI_Peak_Data object.
+
+Options
+: None.
+
+Write Format
+: None.
+
+Write Effect
+: None.
+
+"""^^lv2:Markdown .