aboutsummaryrefslogtreecommitdiffstats
path: root/ext/atom.lv2/atom.h
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2010-10-25 04:05:28 +0000
committerDavid Robillard <d@drobilla.net>2010-10-25 04:05:28 +0000
commitc6883595c3a4a34bf1a459c3bc1fba91d27f18f8 (patch)
treec2724fd9bd34544a5158546b2228b7bf2da3da9c /ext/atom.lv2/atom.h
parente45e55acbfc5e3675380fe05a2b26425d6015df9 (diff)
downloadlv2-c6883595c3a4a34bf1a459c3bc1fba91d27f18f8.tar.xz
Simplify and improve atom extension.
Merge atom-port extension into atom extension. Link to code documentation from atom HTML documentation.
Diffstat (limited to 'ext/atom.lv2/atom.h')
-rw-r--r--ext/atom.lv2/atom.h159
1 files changed, 78 insertions, 81 deletions
diff --git a/ext/atom.lv2/atom.h b/ext/atom.lv2/atom.h
index df73504..f547e80 100644
--- a/ext/atom.lv2/atom.h
+++ b/ext/atom.lv2/atom.h
@@ -51,16 +51,16 @@
*
* 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.
+ * 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 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.
+ /** 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.
*/
@@ -77,66 +77,47 @@ typedef struct _LV2_Atom {
/** Reference, an LV2_Atom with type 0 */
typedef LV2_Atom LV2_Atom_Reference;
-/** The body of an LV2_Atom with type atom:Vector */
+/** The body of an atom:String */
+typedef struct _LV2_Atom_String {
+ uint32_t lang; /**< The ID of the language of this string */
+ char* str; /**< Null-terminated string data in UTF-8 encoding */
+} LV2_Atom_String;
+
+/** The body of an atom:Vector */
typedef struct _LV2_Atom_Vector {
- uint16_t elem_count; /**< The size of each element in the 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[]; /**< Elements follow here */
+ uint8_t elems[]; /**< Sequence of element bodies */
} LV2_Atom_Vector;
-/** The body of an LV2_Atom with type atom:Property */
+/** The body of an atom:Property */
typedef struct _LV2_Atom_Property {
- uint32_t key; /**< Key (predicate) of Object or RDF triple (URIInt) */
- LV2_Atom value; /**< Value (object) of Object or RDF triple */
+ uint32_t key; /**< ID of key (predicate) */
+ LV2_Atom value; /**< Value (object) */
} LV2_Atom_Property;
-/** 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;
+/** The body of an atom:Resource or atom:Blank */
+typedef struct _LV2_Atom_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_Atom_Object;
/* Optional Blob Support */
-
-typedef void* LV2_Blob_Data;
-
/** Dynamically Allocated LV2 Blob.
*
- * This is a blob of data of any type, dynamically allocated in memory.
+ * 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 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 blobs 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;
typedef void* LV2_Blob_Support_Data;
@@ -144,11 +125,10 @@ 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 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'.
+ * 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 {
@@ -167,35 +147,16 @@ typedef struct {
* uint16, like LV2_Atom.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 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
- * (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 (*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.
+
+ /** 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 (e.g. it MUST NOT be copied or destroyed).
+ * 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);
+ 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,
@@ -223,6 +184,42 @@ typedef struct {
*/
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;