From 4db67120efca2d4c200d2e1ba5cf3d7b97cab97e Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sat, 22 Sep 2018 20:38:01 +0200 Subject: Install standard headers to simpler include paths --- lv2/options/lv2-options.doap.ttl | 32 +++++++++ lv2/options/manifest.ttl | 8 +++ lv2/options/options.h | 145 +++++++++++++++++++++++++++++++++++++++ lv2/options/options.ttl | 104 ++++++++++++++++++++++++++++ 4 files changed, 289 insertions(+) create mode 100644 lv2/options/lv2-options.doap.ttl create mode 100644 lv2/options/manifest.ttl create mode 100644 lv2/options/options.h create mode 100644 lv2/options/options.ttl (limited to 'lv2/options') diff --git a/lv2/options/lv2-options.doap.ttl b/lv2/options/lv2-options.doap.ttl new file mode 100644 index 0000000..d828360 --- /dev/null +++ b/lv2/options/lv2-options.doap.ttl @@ -0,0 +1,32 @@ +@prefix dcs: . +@prefix doap: . +@prefix foaf: . +@prefix rdfs: . + + + a doap:Project ; + doap:name "LV2 Options" ; + doap:shortdesc "Instantiation time options." ; + doap:created "2012-08-20" ; + doap:developer ; + doap:release [ + doap:revision "1.2" ; + doap:created "2013-01-10" ; + doap:file-release ; + dcs:blame ; + dcs:changeset [ + dcs:item [ + rdfs:label "Set the range of opts:requiredOption and opts:supportedOption to opts:Option." + ] + ] + ] , [ + doap:revision "1.0" ; + doap:created "2012-10-14" ; + doap:file-release ; + dcs:blame ; + dcs:changeset [ + dcs:item [ + rdfs:label "Initial release." + ] + ] + ] . diff --git a/lv2/options/manifest.ttl b/lv2/options/manifest.ttl new file mode 100644 index 0000000..c0c3315 --- /dev/null +++ b/lv2/options/manifest.ttl @@ -0,0 +1,8 @@ +@prefix lv2: . +@prefix rdfs: . + + + a lv2:Specification ; + lv2:minorVersion 1 ; + lv2:microVersion 2 ; + rdfs:seeAlso . diff --git a/lv2/options/options.h b/lv2/options/options.h new file mode 100644 index 0000000..c1dad83 --- /dev/null +++ b/lv2/options/options.h @@ -0,0 +1,145 @@ +/* + Copyright 2012-2016 David Robillard + + Permission to use, copy, modify, and/or distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +*/ + +/** + @defgroup options Options + + Instantiation time options, see for + details. + + @{ +*/ + +#ifndef LV2_OPTIONS_H +#define LV2_OPTIONS_H + +#include + +#include "lv2/core/lv2.h" +#include "lv2/urid/urid.h" + +#define LV2_OPTIONS_URI "http://lv2plug.in/ns/ext/options" ///< http://lv2plug.in/ns/ext/options +#define LV2_OPTIONS_PREFIX LV2_OPTIONS_URI "#" ///< http://lv2plug.in/ns/ext/options# + +#define LV2_OPTIONS__Option LV2_OPTIONS_PREFIX "Option" ///< http://lv2plug.in/ns/ext/options#Option +#define LV2_OPTIONS__interface LV2_OPTIONS_PREFIX "interface" ///< http://lv2plug.in/ns/ext/options#interface +#define LV2_OPTIONS__options LV2_OPTIONS_PREFIX "options" ///< http://lv2plug.in/ns/ext/options#options +#define LV2_OPTIONS__requiredOption LV2_OPTIONS_PREFIX "requiredOption" ///< http://lv2plug.in/ns/ext/options#requiredOption +#define LV2_OPTIONS__supportedOption LV2_OPTIONS_PREFIX "supportedOption" ///< http://lv2plug.in/ns/ext/options#supportedOption + +#ifdef __cplusplus +extern "C" { +#endif + +/** + 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, + + /** + 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_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 + +#endif /* LV2_OPTIONS_H */ + +/** + @} +*/ diff --git a/lv2/options/options.ttl b/lv2/options/options.ttl new file mode 100644 index 0000000..b0f752c --- /dev/null +++ b/lv2/options/options.ttl @@ -0,0 +1,104 @@ +@prefix lv2: . +@prefix opts: . +@prefix owl: . +@prefix rdf: . +@prefix rdfs: . +@prefix xsd: . + + + a owl:Ontology ; + rdfs:seeAlso , + ; + lv2:documentation """ + +

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

+ +

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 +with the opts:supportedOption property.

+""" . + +opts:Option + a rdfs:Class ; + rdfs:label "Option" ; + rdfs:subClassOf rdf:Property ; + lv2:documentation """ +

A property intended to be used as a static option for an instance.

+ +

It is not required for a property to explicitly be an Option in order to be +used as such. However, properties which are primarily intended for use as +options, or are at least particularly useful as options, should be explicitly +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" ; + lv2:documentation """ +

The feature used to provide options to an instance.

+ +

To implement this feature, hosts MUST pass an LV2_Feature to the appropriate +instantiate method with this URI and data pointed to an array of +LV2_Options_Option terminated by an element with both key and value set to +zero. The instance should cast this data pointer to const +LV2_Options_Option* and scan the array for any options of interest. The +instance MUST NOT modify the options array in any way.

+ +

Note that requiring this feature may reduce the number of compatible hosts. +Unless some options are strictly required by the instance, this feature SHOULD +be listed as a lv2:optionalFeature.

+""" . + +opts:requiredOption + a rdf:Property , + owl:ObjectProperty ; + rdfs:range opts:Option ; + rdfs:label "required option" ; + lv2:documentation """ +

An option required by the instance to function at all. The host MUST pass a +value for the specified option via opts:options in order to create an +instance.

+ +

Note that use of this property may reduce the number of compatible hosts. +Wherever possible, it is better to list options with opts:supportedOption and +fall back to a reasonable default value if it is not provided.

+""" . + +opts:supportedOption + a rdf:Property , + owl:ObjectProperty ; + rdfs:range opts:Option ; + rdfs:label "supported option" ; + lv2:documentation """ +

An option supported or understood by the instance. The host SHOULD +provide a value for the specified option if one is known, or provide the user +an opportunity to specify one if one is Indicates that the instance host MUST +pass a value for the specified option in order to instantiate the instance.

+""" . -- cgit v1.2.1