diff options
Diffstat (limited to 'ext')
| -rw-r--r-- | ext/atom.lv2/atom.h | 311 |
1 files changed, 168 insertions, 143 deletions
diff --git a/ext/atom.lv2/atom.h b/ext/atom.lv2/atom.h index a15000a..b39844b 100644 --- a/ext/atom.lv2/atom.h +++ b/ext/atom.lv2/atom.h @@ -1,30 +1,31 @@ -/* 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. - */ +/* + Copyright (C) 2008-2011 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 atom.h 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 @@ -39,190 +40,214 @@ #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 <a href="urn:struct:LV2_Event">LV2_Event</a> to - * an <a href="urn:struct:LV2_Atom">LV2_Atom</a> by simply pointing to the - * offset of <code>type</code>. The macro LV2_ATOM_FROM_EVENT is provided - * in this header for this purpose. - */ +/** + 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 <a href="urn:struct:LV2_Event">LV2_Event</a> to an <a + href="urn:struct:LV2_Atom">LV2_Atom</a> by simply pointing to the offset of + <code>type</code>. 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 is mapped from a URI using - * the extension <http://lv2plug.in/ns/ext/uri-map> - * with 'map' = "http://lv2plug.in/ns/ext/atom". - * Type 0 is a special case which indicates this atom - * is a reference and MUST NOT be copied manually. - */ + /** + The type of this atom. + + This number is mapped from a URI using the extension + <http://lv2plug.in/ns/ext/uri-map> with 'map' = + "http://lv2plug.in/ns/ext/atom". 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. */ + /** + The size of this atom, not including this header, in bytes. + */ uint16_t size; - /** Size bytes of data follow here */ + /** + Size bytes of data follow here. + */ uint8_t body[]; } LV2_Atom; -/** Reference, an LV2_Atom with type 0 */ +/** + Reference, an LV2_Atom with type 0. +*/ typedef LV2_Atom LV2_Atom_Reference; -/** The body of an atom:String */ +/** + The body of an atom:String. +*/ typedef struct _LV2_Atom_String { uint32_t lang; /**< The ID of the language of this string */ uint8_t str[]; /**< Null-terminated string data in UTF-8 encoding */ } LV2_Atom_String; -/** The body of an atom:Vector */ +/** + The body of an atom:Vector. +*/ typedef struct _LV2_Atom_Vector { uint16_t elem_count; /**< The number of elements in the vector */ uint16_t elem_type; /**< The type of each element in the vector */ uint8_t elems[]; /**< Sequence of element bodies */ } LV2_Atom_Vector; -/** The body of an atom:Property */ +/** + The body of an atom:Property. +*/ typedef struct _LV2_Atom_Property { uint32_t key; /**< ID of key (predicate) */ LV2_Atom value; /**< Value (object) */ } LV2_Atom_Property; -/** The body of an atom:Resource or atom:Blank */ +/** + The body of an atom:Resource or atom:Blank. +*/ typedef struct _LV2_Object { uint32_t context; /**< ID of context graph, or 0 for the default context */ uint32_t id; /**< ID for atom:Resource or blank ID for atom:Blank */ 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. - */ +/** + 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'. - */ +/** + 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. - */ + /** + 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. - */ + /** + 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. - */ + /** + 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. - */ + /** + 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> - */ + /** + 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. - */ + /** + 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>. - */ + /** + 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. - */ + /** + 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 */ - |