diff options
| -rw-r--r-- | ext/atom.lv2/atom.h | 137 | ||||
| -rw-r--r-- | ext/atom.lv2/atom.ttl | 39 | ||||
| -rw-r--r-- | ext/message.lv2/manifest.ttl | 7 | ||||
| -rw-r--r-- | ext/message.lv2/message.h | 46 | ||||
| -rw-r--r-- | ext/message.lv2/message.ttl | 83 |
5 files changed, 223 insertions, 89 deletions
diff --git a/ext/atom.lv2/atom.h b/ext/atom.lv2/atom.h index 51fb817..e5990c9 100644 --- a/ext/atom.lv2/atom.h +++ b/ext/atom.lv2/atom.h @@ -75,46 +75,29 @@ typedef struct _LV2_Atom { } LV2_Atom; /** Reference, an LV2_Atom with type 0 */ -typedef LV2_Atom LV2_Reference; - -/** The body of an LV2_Atom with type atom:Vector - */ -typedef struct _LV2_Vector_Body { - - /** The size of each element in the vector */ - uint16_t elem_count; - - /** The type of each element in the vector */ - uint16_t elem_type; - - /** Elements follow here */ - uint8_t elems[]; - -} LV2_Vector_Body; +typedef LV2_Atom LV2_Atom_Reference; +/** The body of an LV2_Atom with type atom:Vector */ +typedef struct _LV2_Atom_Vector { + uint16_t elem_count; /**< The size of each element in the vector */ + uint16_t elem_type; /**< The type of each element in the vector */ + uint8_t elems[]; /**< Elements follow here */ +} LV2_Atom_Vector; -/** The body of an LV2_Atom with type atom:Triple - */ -typedef struct _LV2_Triple_Body { - uint32_t subject; - uint32_t predicate; - LV2_Atom object; -} LV2_Triple_Body; - +/** The body of an LV2_Atom with type atom:Property */ +typedef struct _LV2_Atom_Property { + uint32_t predicate; /**< Predicate (key) of RDF triple (URI mapped int) */ + LV2_Atom object; /**< Object (value) of RDF triple */ +} LV2_Atom_Property; -/** The body of an LV2_Atom with type atom:Message - */ -typedef struct _LV2_Message_Body { - uint32_t selector; /***< Selector URI mapped to integer */ - LV2_Atom triples; /***< Always an atom:Triples */ -} LV2_Message_Body; +/** The body of an LV2_Atom with type atom:Triple */ +typedef struct _LV2_Atom_Triple { + uint32_t subject; /**< Subject of RDF triple (URI mapped integer) */ + LV2_Atom_Property property; /** Property (predicate and object) of subject */ +} LV2_Atom_Triple; -/* Everything below here is related to blobs, which are dynamically allocated - * atoms that are not necessarily POD. This functionality is optional, - * hosts may support atoms without implementing blob support. - * Blob support is an LV2 Feature. - */ +/* Optional Blob Support */ typedef void* LV2_Blob_Data; @@ -122,16 +105,16 @@ typedef void* LV2_Blob_Data; /** Dynamically Allocated LV2 Blob. * * This is a blob of data of any type, dynamically allocated in memory. - * Unlike an LV2_Atom, a blob is not necessarily POD. Plugins may only + * Unlike an LV2_Atom, a blob is not necessarily POD. Plugins MUST only * refer to blobs via a Reference (an LV2_Atom with type 0), there is no - * way for a plugin to directly create, copy, or destroy a Blob. + * way for a plugin to directly copy or destroy a Blob. */ typedef struct _LV2_Blob { /** Pointer to opaque data. * * Plugins MUST NOT interpret this data in any way. Hosts may store - * whatever information they need to associate with references here. + * whatever information they need to associate with blobs here. */ LV2_Blob_Data data; @@ -159,72 +142,88 @@ typedef void* LV2_Blob_Support_Data; typedef void (*LV2_Blob_Destroy)(LV2_Blob* blob); -/** The data field of the LV2_Feature for the LV2 Atom extension. +/** The data field of the LV2_Feature for atom:BlobSupport. * - * A host which supports this extension must pass an LV2_Feature struct to the - * plugin's instantiate method with 'URI' "http://lv2plug.in/ns/ext/atom" and - * 'data' pointing to an instance of this struct. All fields of this struct, - * MUST be set to non-NULL values by the host (except possibly data). + * A host which supports blobs must pass an LV2_Feature struct to the + * plugin's instantiate method with 'URI' equal to + * "http://lv2plug.in/ns/ext/atom#BlobSupport" and 'data' pointing to an + * instance of this struct. All fields of this struct MUST be set to + * non-NULL values by the host, except possibly 'data'. */ typedef struct { - /** Pointer to opaque data. + /** Pointer to opaque host data. * * The plugin MUST pass this to any call to functions in this struct. - * Otherwise, it must not be interpreted in any way. + * Otherwise, the plugin MUST NOT interpret this value in any way. */ LV2_Blob_Support_Data data; /** The size of a reference, in bytes. * * This value is provided by the host so plugins can allocate large - * enough chunks of memory to store references. + * enough chunks of memory to store references. Note a reference is + * an LV2_Atom with type atom:Reference, hence ref_size is a + * uint16, like LV2_Atom.size. */ - size_t reference_size; + uint16_t ref_size; /** Initialize a reference to point to a newly allocated Blob. * * @param data Must be the data member of this struct. - * @param reference Pointer to an area of memory at least as large as - * the reference_size field of this struct. On return, this will - * be the unique reference to the new blob which is owned by the - * caller. Caller MUST NOT pass a valid reference. - * @param destroy Function to destroy a blob of this type. This function + * @param ref Pointer to an area of memory at least as large as + * the ref_size field of this struct. On return, this will + * be the unique reference to the new blob, which is owned by the + * caller. Assumed to be uninitialised, i.e. the caller MUST NOT + * pass a valid (owned) reference since this could cause a memory leak. + * @param destroy Function to destroy this blob. This function * MUST clean up any resources contained in the blob, but MUST NOT - * attempt to free the memory pointed to by its LV2_Blob* parameter. + * attempt to free the memory pointed to by its LV2_Blob* parameter + * (since this is allocated by the host). * @param type Type of blob to allocate (URI mapped integer). * @param size Size of blob to allocate in bytes. */ - void (*lv2_blob_new)(LV2_Blob_Support_Data data, - LV2_Reference* reference, - LV2_Blob_Destroy destroy_func, - uint32_t type, - size_t size); + void (*blob_new)(LV2_Blob_Support_Data data, + LV2_Atom_Reference* ref, + LV2_Blob_Destroy destroy, + uint32_t type, + size_t size); /** Return a pointer to the Blob referred to by @a ref. * * The returned value MUST NOT be used in any way other than by calling * methods defined in LV2_Blob (e.g. it MUST NOT be copied or destroyed). */ - LV2_Blob* (*lv2_reference_get)(LV2_Blob_Support_Data data, - LV2_Reference* ref); + LV2_Blob* (*ref_get)(LV2_Blob_Support_Data data, + LV2_Atom_Reference* ref); /** Copy a reference. * This copies a reference but not the blob it refers to, * i.e. after this call @a dst and @a src refer to the same LV2_Blob. */ - void (*lv2_reference_copy)(LV2_Blob_Support_Data data, - LV2_Reference* dst, - LV2_Reference* src); + void (*ref_copy)(LV2_Blob_Support_Data data, + LV2_Atom_Reference* dst, + LV2_Atom_Reference* src); /** Reset (release) a reference. - * After this call, @a ref is invalid. Use of this function is only - * necessary if a plugin makes a copy of a reference it does not later - * send to an output (which transfers ownership to the host). + * After this call, @a ref is invalid. Implementations must be sure to + * call this function when necessary, or memory leaks will result. The + * specific times this is necessary MUST be defined by any extensions that + * define a mechanism for transporting atoms. The standard semantics are: + * <ul><li>Whenever passed a Reference (e.g. via a Port) and run, the + * plugin owns that reference.</li> + * <li>The plugin owns any reference it creates (e.g. by using blob_new or + * ref_copy).</li> + * <li>For any reference it owns, the plugin MUST either: + * <ul><li>Copy the reference and store it (to be used in future runs and + * released later).</li> + * <li>Copy the reference to an output port exactly once.</li> + * <li>Release it with ref_reset.</li></ul></li> + * </ul> */ - void (*lv2_reference_reset)(LV2_Blob_Support_Data data, - LV2_Reference* ref); - + void (*ref_reset)(LV2_Blob_Support_Data data, + LV2_Atom_Reference* ref); + } LV2_Blob_Support; diff --git a/ext/atom.lv2/atom.ttl b/ext/atom.lv2/atom.ttl index 0173d51..e6ed6b9 100644 --- a/ext/atom.lv2/atom.ttl +++ b/ext/atom.lv2/atom.ttl @@ -1,3 +1,4 @@ + # LV2 Atom Extension # Copyright (C) 2007-2010 David Robillard <d@drobilla.net> # @@ -122,23 +123,6 @@ always 4. """ . -atom:Message a atom:AtomType ; - rdfs:label "Message" ; - rdfs:comment """ -A message is a communication from one component to another. Messages -consist of a selector URI, and a set of RDF triples. The selector URI -dictates how the triples are to be interpreted (e.g. the selector can -be used as a "verb" to build commands). - -The payload of a message is always an atom:Triples so hosts and plugins can -always work with message data (e.g. to serialise for saved state or an undo -stack), even if they do not specifically understand a particular message. - -In memory, a Message is simply a uint32_t selector (a URI mapped integer) -followed by an atom:Triples. -""" . - - atom:Vector a atom:AtomType ; rdfs:label "Vector" ; rdfs:comment """ @@ -171,14 +155,28 @@ int32_t contents[42] = ... """ . +atom:Property a atom:AtomType ; + rdfs:label "RDF property of some object" ; + rdfs:comment """ +A description in RDF of a single property for some object (i.e. an RDF +statement with only predicate and object defined). +<pre> +uint32_t predicate; +LV2_Atom object; +</pre> +""" . + + atom:Triple a atom:AtomType ; rdfs:label "RDF triple" ; rdfs:comment """ A single RDF triple. -The subject and predicate of an RDF triple are implicitly URIs, thus in an -atom:Triple they are stored as URI mapped integers with type tags and sizes -omitted. +The subject and predicate of a Triple are implicitly URIs, thus they are stored +as URI mapped integers with type and size ommitted (i.e. a single uint32_t). + +An atom:Triple is memory is a uint32_t subject immediately followed by the +body of an atom:Property. An atom:Triple in memory is two uint32_t's followed by an LV2_Atom: <pre> @@ -247,6 +245,7 @@ atom:Float64 a atom:AtomType ; rdfs:label "64-bit Floating Point Number" . atom:blobSupport a lv2:Feature ; rdfs:label "Blob support" ; rdfs:comment """ + Support for dynamically allocated blobs. If a host supports this feature, it MUST pass an LV2_Feature with URI http://lv2plug.in/ns/ext/atom#blobSupport and a pointer to LV2_Blob_Support as data to the plugin's instantiate method. diff --git a/ext/message.lv2/manifest.ttl b/ext/message.lv2/manifest.ttl new file mode 100644 index 0000000..2e0704a --- /dev/null +++ b/ext/message.lv2/manifest.ttl @@ -0,0 +1,7 @@ +@prefix lv2: <http://lv2plug.in/ns/lv2core#> . +@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . + +<http://lv2plug.in/ns/ext/message> + a lv2:Specification ; + rdfs:seeAlso <message.ttl> . + diff --git a/ext/message.lv2/message.h b/ext/message.lv2/message.h new file mode 100644 index 0000000..45391c3 --- /dev/null +++ b/ext/message.lv2/message.h @@ -0,0 +1,46 @@ +/* lv2_message.h - C header file for the LV2 Message extension. + * Copyright (C) 2010 David Robillard <http://drobilla.net> + * + * This header is free software; you can redistribute it and/or modify it + * under the terms of the GNU Lesser General Public License as published + * by the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This header is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public + * License for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this header; if not, write to the Free Software Foundation, + * Inc., 59 Temple Place, Suite 330, Boston, MA 01222-1307 USA + */ + +/** @file + * C header for the LV2 Message extension <http://lv2plug.in/ns/ext/message>. + */ + +#ifndef LV2_MESSAGE_H +#define LV2_MESSAGE_H + +#define LV2_MESSAGE_URI "http://lv2plug.in/ns/ext/message" + +#include <stdint.h> +#include <stddef.h> + +#include "lv2/http/lv2plug.in/ns/ext/atom/atom.h" + +/** An LV2 Message. + * + * A "Message" is an Atom of type message:Message. The payload of a Message + * is a key/value dictionary with URI mapped integer keys (uint32_t), followed + * by a key/value dictionary with URI mapped integer keys and Atom values + * (atom:Blank, i.e. LV2_). + */ +typedef struct _LV2_Message_Message { + uint32_t selector; /***< Selector URI mapped to integer */ + LV2_Atom triples; /***< Always an atom:Triples */ +} LV2_Message_Message; + +#endif /* LV2_MESSAGE_H */ + diff --git a/ext/message.lv2/message.ttl b/ext/message.lv2/message.ttl new file mode 100644 index 0000000..03072f3 --- /dev/null +++ b/ext/message.lv2/message.ttl @@ -0,0 +1,83 @@ +# LV2 Message Extension +# Copyright (C) 2007-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 message: <http://lv2plug.in/ns/ext/message#> . +@prefix atom: <http://lv2plug.in/ns/ext/atom#> . +@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 xsd: <http://www.w3.org/2001/XMLSchema> . + +<http://lv2plug.in/ns/ext/message> + a lv2:Specification ; + doap:name "LV2 Message" ; + doap:maintainer [ + a foaf:Person ; + foaf:name "David Robillard" ; + foaf:homepage <http://drobilla.net/> ; + rdfs:seeAlso <http://drobilla.net/drobilla.rdf> + ] ; + rdfs:comment """ +This extension defines the format for "messages" which can be used to +dynamically control an LV2 plugin instance at runtime. Messages are useful +for any kind of plugin control that does not fit well with control ports. +Plugins can both receive and send messages (and thus send messages to each +other) via any mechanism. + +This extension requires the host to support the <a +href="http://lv2plug.in/ns/ext/uri-map">LV2 URI Map</a> extension, and the +<a href="http://lv2plug.in/ns/ext/atom">LV2 Atom</a> extension. +""" . + + +message:MessageType a rdfs:Class ; + rdfs:label "LV2 Message Type" ; + rdfs:comment """ +Base class for all types of LV2 Message. + +A type of message, which must be a resource (i.e. have a URI). This URI +is used as the selector component of a Message and is used by receivers +to interpret the meaning of messages (e.g. which components are present). +""" . + +message:Message a atom:AtomType ; + rdfs:label "Message" ; + rdfs:comment """ +A message is a communication from one component to another. Messages consist +of a selector URI, and a key/value dictionary. Keys in the dictionary are +URI mapped integers, and values are Atoms. The selector URI dictates how +the message is to be interpreted (e.g. the selector can be used as a "verb" +to build commands). + +Messages are simple to serialise in many different formats (e.g. any RDF +serialisation including LV2 Turtle files, JSON, XML, etc) making network +transparency and persistence simple, assuming the implementation can +serialise Atoms. + +Because all messages have a standard format, plugins and hosts can store, +communicate, or otherwise work with messages even if they do not understand +that particular message's selector. + +In memory, a Message is simply a uint32_t selector (a URI mapped integer) +followed by an atom:Blank. +""" . |