aboutsummaryrefslogtreecommitdiffstats
path: root/ext/reference.lv2
diff options
context:
space:
mode:
Diffstat (limited to 'ext/reference.lv2')
-rw-r--r--ext/reference.lv2/manifest.ttl9
-rw-r--r--ext/reference.lv2/reference.h157
-rw-r--r--ext/reference.lv2/reference.ttl84
3 files changed, 250 insertions, 0 deletions
diff --git a/ext/reference.lv2/manifest.ttl b/ext/reference.lv2/manifest.ttl
new file mode 100644
index 0000000..e25c54d
--- /dev/null
+++ b/ext/reference.lv2/manifest.ttl
@@ -0,0 +1,9 @@
+@prefix lv2: <http://lv2plug.in/ns/lv2core#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+<http://lv2plug.in/ns/ext/reference>
+ a lv2:Specification ;
+ lv2:minorVersion 0 ;
+ lv2:microVersion 1 ;
+ rdfs:seeAlso <reference.ttl> .
+
diff --git a/ext/reference.lv2/reference.h b/ext/reference.lv2/reference.h
new file mode 100644
index 0000000..043d3c2
--- /dev/null
+++ b/ext/reference.lv2/reference.h
@@ -0,0 +1,157 @@
+/*
+ Copyright 2008-2011 David Robillard <http://drobilla.net>
+
+ 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.
+*/
+
+/**
+ @file reference.h C header for the LV2 Reference extension
+ <http://lv2plug.in/ns/ext/reference>.
+*/
+
+#ifndef LV2_REFERENCE_H
+#define LV2_REFERENCE_H
+
+#define LV2_REFERENCE_URI "http://lv2plug.in/ns/ext/reference"
+#define LV2_REFERENCE_BLOB_SUPPORT_URI LV2_REFERENCE_URI "#blobSupport"
+
+#include <stdint.h>
+#include <stddef.h>
+
+/**
+ Dynamically Allocated Data.
+
+ This is an opaque piece of data of any type, dynamically allocated in memory.
+ Unlike an "atom", a "blob" is not necessarily POD. Non-POD data is referred
+ to by a "reference (a special case of atom with type 0).
+
+ This is a pointer to host data which is opaque to the plugin. Plugins MUST
+ NOT interpret this data in any way, except via host-provided functions in
+ LV2_Blob_Support.
+*/
+typedef void* LV2_Blob;
+
+typedef void* LV2_Blob_Support_Data;
+
+typedef void (*LV2_Blob_Destroy)(LV2_Blob* blob);
+
+/**
+ The data field of the LV2_Feature for reference:blobSupport.
+
+ A host which supports blobs must pass an LV2_Feature to the plugin's
+ instantiate method with 'URI' = "http://lv2plug.in/ns/ext/reference#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 host data.
+
+ The plugin MUST pass this to any call to functions in this struct.
+ 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. Note a reference is an LV2_Reference
+ with type reference:Reference, hence ref_size is a uint16, like
+ LV2_Reference.size.
+ */
+ uint16_t ref_size;
+
+ /**
+ Return 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_Support (e.g. it MUST NOT be directly
+ accessed, copied, or destroyed). The actual payload of the blob can
+ be accessed with LV2_Blob_Support.blob_get.
+ */
+ LV2_Blob (*ref_get)(LV2_Blob_Support_Data data,
+ LV2_Reference_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 (*ref_copy)(LV2_Blob_Support_Data data,
+ LV2_Reference_Reference* dst,
+ LV2_Reference_Reference* src);
+
+ /**
+ Reset (release) a reference.
+ 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 references. 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 (*ref_reset)(LV2_Blob_Support_Data data,
+ LV2_Reference_Reference* ref);
+
+ /**
+ Initialize a reference to point to a newly allocated Blob.
+
+ @param data Must be the data member of this struct.
+ @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 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
+ (since this is allocated by the host).
+ @param type ID of type of blob to allocate.
+ @param size Size of blob to allocate in bytes.
+ */
+ void (*blob_new)(LV2_Blob_Support_Data data,
+ LV2_Reference_Reference* ref,
+ LV2_Blob_Destroy destroy,
+ uint32_t type,
+ size_t size);
+
+ /**
+ Get blob's type as an ID.
+
+ The return value may be any type URI, mapped to an integer with the
+ URI Map extension with <code>context = NULL</code>.
+ */
+ uint32_t (*blob_type)(LV2_Blob blob);
+
+ /**
+ Get blob's body.
+
+ Returns a pointer to the start of the blob data. The format of this
+ data is defined by the return value of the type method. It MUST NOT
+ be used in any way by code which does not understand that type.
+ */
+ void* (*blob_data)(LV2_Blob blob);
+
+} LV2_Blob_Support;
+
+#endif /* LV2_REFERENCE_H */
diff --git a/ext/reference.lv2/reference.ttl b/ext/reference.lv2/reference.ttl
new file mode 100644
index 0000000..8c8281f
--- /dev/null
+++ b/ext/reference.lv2/reference.ttl
@@ -0,0 +1,84 @@
+# LV2 Reference Extension
+# Copyright 2007-2011 David Robillard <d@drobilla.net>
+#
+# 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.
+
+@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 reference: <http://lv2plug.in/ns/ext/reference#> .
+
+<http://lv2plug.in/ns/ext/reference>
+ a lv2:Specification ;
+ doap:name "LV2 Reference" ;
+ doap:release [
+ doap:revision "0.1" ;
+ doap:created "2011-07-22"
+ ] ;
+ doap:maintainer [
+ a foaf:Person ;
+ foaf:name "David Robillard" ;
+ foaf:homepage <http://drobilla.net/> ;
+ rdfs:seeAlso <http://drobilla.net/drobilla.rdf>
+ ] ;
+ lv2:documentation """
+<p>This extension defines a mechanism for working with generic/opaque
+dynamically allocated memory, called a <a href="#Blob">"Blob"</a>, which is
+(unlike an Atom) not necessarily POD. Blobs are accessed via a <a
+href="#Reference">Reference</a>, which is a special case of Atom that always
+has <code>type = 0</code>, is not POD, and can only be copied using host
+provided functions. This allows plugins and hosts to work with data of any
+type at all.</p>
+""" .
+
+reference:Reference a rdfs:Class ;
+ rdfs:subClassOf atom:Atom ;
+ rdfs:label "Reference" ;
+ lv2:documentation """
+<p>Reference to a <a href="#Blob">Blob</a>. The actual contents of a Reference
+are opaque and host specific, and must not be copied, serialized, or otherwise
+interpreted by a plugin, except via functions provided by the host in
+<a href="urn:struct:LV2_Blob_Support">LV2_Blob_Support</a>.</p>
+
+<p>A Reference is a special case of Atom with <code>type = 0</code>.
+"Null" is the unique Atom with <code>type = 0</code> and
+<code>size = 0</code>.</p>
+""" .
+
+reference:blobSupport a lv2:Feature ;
+ rdfs:label "Blob support" ;
+ lv2:documentation """
+Support for dynamically allocated blobs. If a host supports this feature, it
+MUST pass a <a href="urn:struct:LV2_Feature">LV2_Feature</a> with
+<code>URI</code> http://lv2plug.in/ns/ext/atom#blobSupport
+and <code>data</code> pointing to a <a href="urn:struct:LV2_Blob_Support"
+>LV2_Blob_Support</a>.
+""" .
+
+reference:Blob a rdfs:Class ;
+ rdfs:label "Blob" ;
+ lv2:documentation """
+<p>Base class for all dynamically allocated blobs. An <a
+href="urn:struct:LV2_Blob" >LV2_Blob</a> ia an opaque pointer to host
+data. The type and data of a blob can be accessed via host-provided
+functions in <a href="urn:struct:LV2_Blob_Support">LV2_Blob_Support</a>.
+The type of a blob can be any URI that describes a data format. Blobs are
+always allocated by the host, and unlike atoms are not necessarily POD.</p>
+
+<p>Blob data MUST NOT be used in any way by an implementation that does not
+understand that blob type (unlike Atoms, meaningful type-oblivious use
+of a Blob is impossible).</p>
+""" .