diff options
Diffstat (limited to 'ext/atom.lv2/atom.h')
| -rw-r--r-- | ext/atom.lv2/atom.h | 159 |
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; |