aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2010-10-17 01:08:23 +0000
committerDavid Robillard <d@drobilla.net>2010-10-17 01:08:23 +0000
commit591d09e1923164220485e843ae3161090d5dc0ec (patch)
tree1a1adcd5e0e37e28b2570fee5ac47508ca403000
parent1bde548b3c2c0ae5ce5a8f849ada96c2e8735217 (diff)
downloadlv2-591d09e1923164220485e843ae3161090d5dc0ec.tar.xz
Create new Message extension, and remove message type definition from Atom extension.
Clean up Atom extension and define more struct types in header.
-rw-r--r--ext/atom.lv2/atom.h137
-rw-r--r--ext/atom.lv2/atom.ttl39
-rw-r--r--ext/message.lv2/manifest.ttl7
-rw-r--r--ext/message.lv2/message.h46
-rw-r--r--ext/message.lv2/message.ttl83
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.
+""" .