From 3bbce7c5437aea1243bcd556f6b2232564cb3ab3 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sun, 16 Sep 2012 16:55:52 +0000 Subject: Replace LV2_Morph_Interface with more general LV2_Options_Interface. --- lv2/lv2plug.in/ns/ext/morph/morph.h | 84 +-------------------------- lv2/lv2plug.in/ns/ext/morph/morph.ttl | 60 ++++++++++--------- lv2/lv2plug.in/ns/ext/options/options.h | 95 ++++++++++++++++++++++++++++--- lv2/lv2plug.in/ns/ext/options/options.ttl | 36 ++++++++---- 4 files changed, 148 insertions(+), 127 deletions(-) (limited to 'lv2/lv2plug.in/ns/ext') diff --git a/lv2/lv2plug.in/ns/ext/morph/morph.h b/lv2/lv2plug.in/ns/ext/morph/morph.h index 3c8ec46..6739d39 100644 --- a/lv2/lv2plug.in/ns/ext/morph/morph.h +++ b/lv2/lv2plug.in/ns/ext/morph/morph.h @@ -29,88 +29,6 @@ #define LV2_MORPH__MorphPort LV2_MORPH_PREFIX "MorphPort" #define LV2_MORPH__interface LV2_MORPH_PREFIX "interface" #define LV2_MORPH__supportsType LV2_MORPH_PREFIX "supportsType" - -#ifdef __cplusplus -extern "C" { -#endif - -typedef enum { - LV2_MORPH_SUCCESS = 0, /**< Completed successfully. */ - LV2_MORPH_ERR_UNKNOWN = 1, /**< Unknown error. */ - LV2_MORPH_ERR_BAD_TYPE = 2, /**< Unsupported type. */ - LV2_MORPH_ERR_BAD_PORT = 3 /**< Port is not morphable. */ -} LV2_Morph_Status; - -/** A port property. */ -typedef struct { - LV2_URID key; /**< Key (predicate) */ - uint32_t size; /**< Value size */ - LV2_URID type; /**< Value type */ - const void* value; /**< Value (object) */ -} LV2_Morph_Property; - -/** The interface provided by a plugin to support morph ports. */ -typedef struct { - /** - Morph a port to a different type. - - This function is in the audio threading class. - - This function MAY return an error, in which case the port's type was not - changed. If the type was changed and the plugin has AutoMorphPort - ports, the host MUST check the type of every AutoMorphPort using the - port_type() function since they may have changed. - - This function MUST gracefully handle being called for ports that are not - MorpPorts by ignoring the request and returning LV2_MORPH_ERR_BAD_PORT. - - A NULL-terminated array of additional properties to set on the port may - be passed via @p properties. These properties and their values are - owned by the caller and valid only for the duration of the call. - - @param instance The plugin instance. - @param port The index of the port to change the type of. - @param type The new port type URID. - @param properties Additional properties to set, or NULL. - */ - LV2_Morph_Status (*morph_port)(LV2_Handle instance, - uint32_t port, - LV2_URID type, - const LV2_Morph_Property*const* properties); - - /** - Get the type of an AutoMorphPort. - - This function is in the audio threading class. - - If the plugin has no auto morph ports, this field may be NULL. This - function may only be called for ports which are AutoMorphPorts. - - This function MAY return 0, which indicates that the current - configuration of MorphPort types is invalid and the port is - non-functional. If the port is not lv2:connectionOptional, then the - plugin MUST NOT be used. - - The @p properties parameter may be used to get additional properties of - the port. To do so, the host passes a NULL-terminated property array - with keys set to the desired properties and all other fields zeroed. - The plugin sets these fields appropriately if possible. The data - pointed to is owned by the plugin and only valid until the next call to - a method on this plugin (this mechanism is only meant for accessing - simple properties, such as buffer size). - - @param instance The plugin instance. - @param port The index of the port to return the type of. - @param properties Additional properties to get, or NULL. - @return The current type of the port. - */ - LV2_URID (*port_type)(LV2_Handle instance, - uint32_t port, - LV2_Morph_Property*const* properties); -} LV2_Morph_Interface; - -#ifdef __cplusplus -} /* extern "C" */ -#endif +#define LV2_MORPH__currentType LV2_MORPH_PREFIX "currentType" #endif /* LV2_MORPH_H */ diff --git a/lv2/lv2plug.in/ns/ext/morph/morph.ttl b/lv2/lv2plug.in/ns/ext/morph/morph.ttl index 09351b1..9457089 100644 --- a/lv2/lv2plug.in/ns/ext/morph/morph.ttl +++ b/lv2/lv2plug.in/ns/ext/morph/morph.ttl @@ -1,10 +1,11 @@ @prefix doap: . @prefix foaf: . @prefix lv2: . +@prefix morph: . +@prefix opts: . @prefix owl: . @prefix rdf: . @prefix rdfs: . -@prefix morph: . @prefix xsd: . @@ -15,11 +16,14 @@ lv2:documentation """

This extension defines two port types: morph:MorphPort, which has a host-configurable type, and morph:AutoMorphPort, which may automatically change -type when a MorphPort type is changed. These ports always have a default type -and work normally work in hosts that are unaware of this extension. Thus, this -extension provides a backwards compatibility mechanism which allows plugins to -use new port types but gracefully fall back to a default type in hosts that do -not support them.

+type when a MorphPort's type is changed. These ports always have a default +type and work normally work in hosts that are unaware of this extension. Thus, +this extension provides a backwards compatibility mechanism which allows +plugins to use new port types but gracefully fall back to a default type in +hosts that do not support them.

+ +

This extension only defines port types and properties for describing morph +ports. The actual run-time switching is done via the opts:interface API.

""" . morph:MorphPort @@ -30,13 +34,12 @@ morph:MorphPort lv2:documentation """

Ports of this type MUST have another type which defines the default buffer format (e.g. lv2:ControlPort) but can be dynamically changed to a different -type in hosts that support morph:interface.

+type in hosts that support opts:interface.

-

The host may change the type of a MorphPort by calling -LV2_Morph_Interface::morph_port(). If the plugin has any morph:AutoMorphPort +

The host may change the type of a MorphPort by setting its morph:currentType +with LV2_Options_Interface::set(). If the plugin has any morph:AutoMorphPort ports, the host MUST check their types after changing any port type since they -may have changed.

-""" . +may have changed.

""" . morph:AutoMorphPort a rdfs:Class , @@ -48,31 +51,36 @@ morph:AutoMorphPort format (e.g. lv2:ControlPort) but may dynamically change types based on the configured types of any morph:MorphPort ports on the same plugin instance.

-

The type of a port may only change in response to a call to -LV2_Morph_Interface::morph_port(), i.e. ports can only change type as a result -of an explicit host request. Whenever any port type on the instance changes, -the host MUST check the type of all morph:AutoMorphPort ports on the instance -before calling run() again, since they may have changed.

+

The type of a port may only change in response to a host call to +LV2_Options_Interface::set(). Whenever any port type on the instance changes, +the host MUST check the type of all morph:AutoMorphPort ports with +LV2_Options_Interface::get() before calling run() again, since they may have +changed. If the type of any port is zero, it means the current configuration +is invalid and the plugin may not be run (unless that port is +lv2:connectionOptional and connected to NULL).

This is mainly useful for outputs whose type depends on the type of corresponding inputs.

""" . -morph:interface - a lv2:ExtensionData ; +morph:supportsType + a rdf:Property , + owl:ObjectProperty ; + rdfs:domain morph:MorphPort ; + rdfs:label "supports type" ; lv2:documentation """ -

The interface provided by the plugin to support morph ports. To support -this extension, the plugin must return a LV2_Morph_Interface from -LV2_Descriptor::extension_data() when it is called with this URI -(LV2_MORPH__interface).

+

Indicates that a port supports being switched to a certain type. A +MorphPort MUST list each type it supports being switched to in the plugin data +using this property.

""" . -morph:supportsType +morph:currentType a rdf:Property , + opts:Option , owl:ObjectProperty ; rdfs:domain morph:MorphPort ; - rdfs:label "supports type" ; + rdfs:label "current type" ; lv2:documentation """ -

Indicates that a port supports being switched to a certain type via -morph:interface.

+

The currently active type of the port. This is for dynamic use as an option +and SHOULD NOT be listed in the static plugin data.

""" . diff --git a/lv2/lv2plug.in/ns/ext/options/options.h b/lv2/lv2plug.in/ns/ext/options/options.h index 089464a..1a71a3e 100644 --- a/lv2/lv2plug.in/ns/ext/options/options.h +++ b/lv2/lv2plug.in/ns/ext/options/options.h @@ -20,11 +20,13 @@ #include #include "lv2/lv2plug.in/ns/ext/urid/urid.h" +#include "lv2/lv2plug.in/ns/lv2core/lv2.h" #define LV2_OPTIONS_URI "http://lv2plug.in/ns/ext/options" #define LV2_OPTIONS_PREFIX LV2_OPTIONS_URI "#" #define LV2_OPTIONS__Option LV2_OPTIONS_PREFIX "Option" +#define LV2_OPTIONS__interface LV2_OPTIONS_PREFIX "interface" #define LV2_OPTIONS__options LV2_OPTIONS_PREFIX "options" #define LV2_OPTIONS__requiredOption LV2_OPTIONS_PREFIX "requiredOption" #define LV2_OPTIONS__supportedOption LV2_OPTIONS_PREFIX "supportedOption" @@ -34,18 +36,95 @@ extern "C" { #endif /** - An instantiation time option. + The context of an Option, which defines the subject it applies to. +*/ +typedef enum { + /** + This option applies to the instance itself. The subject must be + ignored. + */ + LV2_OPTIONS_INSTANCE, + + /** + This option applies to some named resource. The subject is a URI mapped + to an integer (a LV2_URID, like the key) + */ + LV2_OPTIONS_RESOURCE, + + /** + This option applies to some blank node. The subject is a blank node + identifier, which is valid only within the current local scope. + */ + LV2_OPTIONS_BLANK, - An array of these is passed to the instantiate method in a Feature with URI - LV2_OPTIONS__options . + /** + This option applies to a port on the instance. The subject is the + port's index. + */ + LV2_OPTIONS_PORT +} LV2_Options_Context; + +/** + An option. + + This is a property with a subject, also known as a triple or statement. + + This struct is useful anywhere a statement needs to be passed where no + memory ownership issues are present (since the value is a const pointer). + + Options can be passed to an instance via the feature LV2_OPTIONS__options + with data pointed to an array of options terminated by a zeroed option, or + accessed/manipulated using LV2_Options_Interface. */ -typedef struct { - LV2_URID key; /**< Key (a property URID). */ - uint32_t size; /**< Size of value in bytes. */ - LV2_URID type; /**< Type of value (a datatype URID). */ - const void* value; /**< Pointer to value. */ +typedef struct _LV2_Options_Option { + LV2_Options_Context context; /**< Context (type of subject). */ + uint32_t subject; /**< Subject. */ + LV2_URID key; /**< Key (property). */ + uint32_t size; /**< Size of value in bytes. */ + LV2_URID type; /**< Type of value (datatype). */ + const void* value; /**< Pointer to value (object). */ } LV2_Options_Option; +/** A status code for option functions. */ +typedef enum { + LV2_OPTIONS_SUCCESS = 0, /**< Completed successfully. */ + LV2_OPTIONS_ERR_UNKNOWN = 1, /**< Unknown error. */ + LV2_OPTIONS_ERR_BAD_SUBJECT = 1 << 1, /**< Invalid/unsupported subject. */ + LV2_OPTIONS_ERR_BAD_KEY = 1 << 2, /**< Invalid/unsupported key. */ + LV2_OPTIONS_ERR_BAD_VALUE = 1 << 3 /**< Invalid/unsupported value. */ +} LV2_Options_Status; + +/** + Interface for dynamically setting options (LV2_OPTIONS__interface). +*/ +typedef struct _LV2_Options_Interface { + /** + Get the given options. + + Each element of the passed options array MUST have type, subject, and + key set. All other fields (size, type, value) MUST be initialised to + zero, and are set to the option value if such an option is found. + + This function is in the "instantiation" LV2 threading class, so no other + instance functions may be called concurrently. + + @return Bitwise OR of LV2_Options_Status values. + */ + uint32_t (*get)(LV2_Handle instance, + LV2_Options_Option* options); + + /** + Set the given options. + + This function is in the "instantiation" LV2 threading class, so no other + instance functions may be called concurrently. + + @return Bitwise OR of LV2_Options_Status values. + */ + uint32_t (*set)(LV2_Handle instance, + const LV2_Options_Option* options); +} LV2_Options_Interface; + #ifdef __cplusplus } /* extern "C" */ #endif diff --git a/lv2/lv2plug.in/ns/ext/options/options.ttl b/lv2/lv2plug.in/ns/ext/options/options.ttl index c66aff3..12ac4aa 100644 --- a/lv2/lv2plug.in/ns/ext/options/options.ttl +++ b/lv2/lv2plug.in/ns/ext/options/options.ttl @@ -11,18 +11,17 @@ <../../meta/meta.ttl> , ; lv2:documentation """ -

This extension defines a facility for options, which are parameters -passed to a plugin, UI, or other instance at instantiation time. Like the -command-line options of a program, options do not change over the -lifetime of an instance.

-

Because they are available at instantiation time, options are useful for -adding parameters which are not suitable for dynamic control, such as those -that require expensive pre-computation. They are also useful for providing -information which would not otherwise be available.

+

This extension defines a facility for options, which are dynamic +properties that may be changed at run time.

-

Options are provided to instances by the host via the opts:options -feature.

+

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 live 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 @@ -43,6 +42,23 @@ given this type for documentation purposes, and to assist hosts in discovering option definitions.

""" . +opts:interface + a lv2:ExtensionData ; + lv2:documentation """ +

An interface (LV2_Options_Interface) for dynamically setting and getting +options. Note this is intended for use by the host for configuring plugins +only, and and is not a live plugin control mechanism.

+ +

The plugin data file should describe this like so:

+
+@prefix opts: <http://lv2plug.in/ns/ext/options#> .
+
+<plugin>
+    a lv2:Plugin ;
+    lv2:extensionData opts:interface .
+
+""" . + opts:options a lv2:Feature ; rdfs:label "options" ; -- cgit v1.2.1