diff options
Diffstat (limited to 'lv2/lv2plug.in/ns/ext/options')
| -rw-r--r-- | lv2/lv2plug.in/ns/ext/options/options.h | 95 | ||||
| -rw-r--r-- | lv2/lv2plug.in/ns/ext/options/options.ttl | 36 |
2 files changed, 113 insertions, 18 deletions
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 <stdint.h> #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-options.doap.ttl> ; lv2:documentation """ -<p>This extension defines a facility for <q>options</q>, which are parameters -passed to a plugin, UI, or other instance at instantiation time. Like the -command-line <em>options</em> of a program, options do not change over the -lifetime of an instance.</p> -<p>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.</p> +<p>This extension defines a facility for <q>options</q>, which are dynamic +properties that may be changed at run time.</p> -<p>Options are provided to instances by the host via the opts:options -feature.</p> +<p>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.</p> + +<p>Note that this extension is only for allowing hosts to configure plugins, +and is not a <q>live</q> control mechanism. For real-time control, use +event-based control via an atom:AtomPort with an atom:Sequence buffer.</p> <p>Instances may indicate they <q>require</q> an option with the opts:requiredOption property, or that they optionally <q>support</q> an option @@ -43,6 +42,23 @@ given this type for documentation purposes, and to assist hosts in discovering option definitions.</p> """ . +opts:interface + a lv2:ExtensionData ; + lv2:documentation """ +<p>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 <em>not</em> a <q>live</q> plugin control mechanism.</p> + +<p>The plugin data file should describe this like so:</p> +<pre class="turtle-code"> +@prefix opts: <http://lv2plug.in/ns/ext/options#> . + +<plugin> + a lv2:Plugin ; + lv2:extensionData opts:interface . +</pre> +""" . + opts:options a lv2:Feature ; rdfs:label "options" ; |