diff options
| -rw-r--r-- | ext/atom.lv2/atom.h | 137 | ||||
| -rw-r--r-- | ext/atom.lv2/atom.ttl | 85 | ||||
| -rw-r--r-- | ext/reference.lv2/manifest.ttl | 9 | ||||
| -rw-r--r-- | ext/reference.lv2/reference.h | 157 | ||||
| -rw-r--r-- | ext/reference.lv2/reference.ttl | 84 | ||||
| -rw-r--r-- | wscript | 1 |
6 files changed, 273 insertions, 200 deletions
diff --git a/ext/atom.lv2/atom.h b/ext/atom.lv2/atom.h index 2895efd..d69c547 100644 --- a/ext/atom.lv2/atom.h +++ b/ext/atom.lv2/atom.h @@ -28,8 +28,7 @@ #ifndef LV2_ATOM_H #define LV2_ATOM_H -#define LV2_ATOM_URI "http://lv2plug.in/ns/ext/atom" -#define LV2_BLOB_SUPPORT_URI "http://lv2plug.in/ns/ext/atom#blobSupport" +#define LV2_ATOM_URI "http://lv2plug.in/ns/ext/atom" #define LV2_ATOM_REFERENCE_TYPE 0 @@ -81,11 +80,6 @@ typedef struct _LV2_Atom { } LV2_Atom; /** - Reference, an LV2_Atom with type 0. -*/ -typedef LV2_Atom LV2_Atom_Reference; - -/** The body of an atom:Literal. */ typedef struct _LV2_Atom_Literal { @@ -120,133 +114,4 @@ typedef struct _LV2_Object { uint8_t properties[]; /**< Sequence of LV2_Atom_Property */ } LV2_Object; -/* Optional Blob Support */ - -/** - Dynamically Allocated LV2 Blob. - - This is an opaque blob of data of any type, dynamically allocated in memory. - 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 copy or destroy a Blob. - - 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 atom:BlobSupport. - - A host which supports blobs must pass an LV2_Feature to the plugin's - instantiate method with 'URI' = "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 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_Atom - with type atom:Reference, hence ref_size is a uint16, like - LV2_Atom.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_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 (*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. 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 (*ref_reset)(LV2_Blob_Support_Data data, - LV2_Atom_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_Atom_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_ATOM_H */ diff --git a/ext/atom.lv2/atom.ttl b/ext/atom.lv2/atom.ttl index 25318d9..2043fbd 100644 --- a/ext/atom.lv2/atom.ttl +++ b/ext/atom.lv2/atom.ttl @@ -1,23 +1,17 @@ # LV2 Atom Extension -# Copyright (C) 2007-2011 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. +# 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#> . @@ -63,14 +57,6 @@ implementations to be polymorphic and extensible.</p> <p>Atoms (the start of the LV2_Atom header) MUST be 32-bit aligned.</p> -<p>Optionally, the host MAY implement <a href="#blobSupport">blob support</a>. -A <a href="#Blob">Blob</a> is a dynamically allocated chunk of memory -that (unlike an Atom) is 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> - <p>Atoms can be communicated in many ways. Since an Atom is the payload of an Event, an <a href="http://lv2plug.in/ns/ext/event#EventPort">EventPort</a> can be used for communicating Atoms in realtime with sub-sample time stamp @@ -100,27 +86,14 @@ extension's <a href="urn:struct:LV2_URI_Map_Feature" >LV2_URI_Map_Feature</a>::uri_to_id with <code>map = "http://lv2plug.in/ns/ext/event"</code>. If a plugin or host does not understand <code>type</code>, that atom SHOULD be gracefully ignored -(or copied if it is not a <a href="#Reference">Reference</a>).</p> - -<p>All atoms are POD by definition except references, which have -<code>type = 0</code>. An Atom MUST NOT contain a Reference. It is safe -to copy any non-reference Atom with a simple <code>memcpy</code>, even if -the implementation does not understand <code>type</code>.</p> -""" . - - -atom: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> +(or copied if it does not have type 0).</p> + +<p>All atoms are POD by definition except references, which as a special case +have <code>type = 0</code>. An Atom MUST NOT contain a Reference. It is safe +to copy any non-reference Atom with a simple <code>memcpy</code>, even if the +implementation does not understand <code>type</code>. Though this extension reserves +the type 0 for references, actual specification of how references are used is left +to another extension.</p> """ . @@ -362,22 +335,6 @@ and <code>data</code> pointing to a <a href="urn:struct:LV2_Blob_Support" """ . -atom: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> -""" . - - atom:AtomPort a rdfs:Class ; rdfs:subClassOf lv2:Port ; rdfs:label "Atom Port" ; 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> +""" . @@ -65,6 +65,7 @@ def build(bld): pui pui-event pui-gtk + reference resize-port string-port uri-map |