aboutsummaryrefslogtreecommitdiffstats
path: root/ext/atom.lv2/atom.h
diff options
context:
space:
mode:
Diffstat (limited to 'ext/atom.lv2/atom.h')
-rw-r--r--ext/atom.lv2/atom.h232
1 files changed, 232 insertions, 0 deletions
diff --git a/ext/atom.lv2/atom.h b/ext/atom.lv2/atom.h
new file mode 100644
index 0000000..fe7a373
--- /dev/null
+++ b/ext/atom.lv2/atom.h
@@ -0,0 +1,232 @@
+/* lv2_atom.h - C header file for the LV2 Atom extension.
+ * Copyright (C) 2008-2009 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 Atom extension <http://lv2plug.in/ns/ext/atom>.
+ * This extension defines convenience structs that
+ * should match the definition of the built-in types of the atom extension.
+ * The layout of atoms in this header must match the description in RDF.
+ * The RDF description of an atom type should be considered normative.
+ * This header is a non-normative (but hopefully accurate) implementation
+ * of that specification.
+ */
+
+#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_REFERENCE_TYPE 0
+
+#include <stdint.h>
+#include <stddef.h>
+
+#define LV2_ATOM_FROM_EVENT(ev) ((LV2_Atom*)&((LV2_Event*)ev)->type)
+
+/** An LV2 Atom.
+ *
+ * An "Atom" is a generic chunk of memory with a given type and size.
+ * The type field defines how to interpret an atom.
+ *
+ * All atoms are by definition Plain Old Data (POD) and may be safely
+ * copied (e.g. with memcpy) using the size field, except atoms with type 0.
+ * An atom with type 0 is a reference, and may only be used via the functions
+ * provided in LV2_Blob_Support (e.g. it MUST NOT be manually copied).
+ *
+ * Note that an LV2_Atom is the latter two fields of an LV2_Event as defined
+ * by the <a href="http://lv2plug.in/ns/ext/event">LV2 events extension</a>.
+ * The host MAY marshal an Event to an Atom simply by pointing to the offset
+ * of the 'type' field of the LV2_Event, which is also the type field (i.e. start)
+ * of a valid LV2_Atom. The macro LV2_ATOM_FROM_EVENT is provided in this
+ * header for this purpose.
+ */
+typedef struct _LV2_Atom {
+
+ /** The type of this atom. This number represents a URI, mapped to an
+ * integer using the extension <http://lv2plug.in/ns/ext/uri-map>
+ * with "http://lv2plug.in/ns/ext/atom" as the 'map' argument.
+ * Type 0 is a special case which indicates this atom
+ * is a reference and MUST NOT be copied manually.
+ */
+ uint16_t type;
+
+ /** The size of this atom, not including this header, in bytes. */
+ uint16_t size;
+
+ /** Size bytes of data follow here */
+ uint8_t body[];
+
+} 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;
+
+
+/** 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:Message
+ */
+typedef struct _LV2_Message_Body {
+ uint32_t selector; /***< Selector URI mapped to integer */
+ LV2_Atom triples; /***< Always an atom:Triples */
+} LV2_Message_Body;
+
+
+/* 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.
+ */
+
+
+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
+ * 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.
+ */
+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.
+ */
+ LV2_Blob_Data data;
+
+ /** Get blob's type as a URI mapped to an integer.
+ *
+ * The return value may be any type URI, mapped to an integer with the
+ * URI Map extension. If this type is an LV2_Atom type, get returns
+ * a pointer to the LV2_Atom header (e.g. a blob with type atom:Int32
+ * does NOT return a pointer to a int32_t).
+ */
+ uint32_t (*type)(struct _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* (*get)(struct _LV2_Blob* blob);
+
+} LV2_Blob;
+
+
+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.
+ *
+ * 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).
+ */
+typedef struct {
+
+ /** Pointer to opaque data.
+ *
+ * The plugin MUST pass this to any call to functions in this struct.
+ * Otherwise, it must not be interpreted 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.
+ */
+ size_t reference_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
+ * MUST clean up any resources contained in the blob, but MUST NOT
+ * attempt to free the memory pointed to by its LV2_Blob* parameter.
+ * @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);
+
+ /** 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);
+
+ /** 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);
+
+ /** 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).
+ */
+ void (*lv2_reference_reset)(LV2_Blob_Support_Data data,
+ LV2_Reference* ref);
+
+} LV2_Blob_Support;
+
+
+#endif /* LV2_ATOM_H */
+