aboutsummaryrefslogtreecommitdiffstats
path: root/lv2/ns/ext/atom/atom.h
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2012-02-08 01:38:38 +0000
committerDavid Robillard <d@drobilla.net>2012-02-08 01:38:38 +0000
commit046c0a8bbffb572df1c6376d3bf525aac9b3a9fa (patch)
tree1299f3ed06b43031060673fefc32bc2f29587638 /lv2/ns/ext/atom/atom.h
parent0ad020578277f8aade6b2df90385b911775ead18 (diff)
downloadlv2-046c0a8bbffb572df1c6376d3bf525aac9b3a9fa.tar.xz
Heavily revise atom extension into a release candidate.
Diffstat (limited to 'lv2/ns/ext/atom/atom.h')
-rw-r--r--lv2/ns/ext/atom/atom.h279
1 files changed, 117 insertions, 162 deletions
diff --git a/lv2/ns/ext/atom/atom.h b/lv2/ns/ext/atom/atom.h
index 569ab49..7a29dae 100644
--- a/lv2/ns/ext/atom/atom.h
+++ b/lv2/ns/ext/atom/atom.h
@@ -1,5 +1,5 @@
/*
- Copyright 2008-2011 David Robillard <http://drobilla.net>
+ Copyright 2008-2012 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
@@ -36,148 +36,152 @@
extern "C" {
#endif
+/** This expression will fail to compile if double does not fit in 64 bits. */
+typedef char lv2_atom_assert_double_fits_in_64_bits[
+ ((sizeof(double) <= sizeof(uint64_t)) * 2) - 1];
+
/**
- An LV2 Atom.
+ Return a pointer to the contents of a variable-sized atom.
+ @param type The type of the atom, e.g. LV2_Atom_String.
+ @param atom A variable-sized atom.
+*/
+#define LV2_ATOM_CONTENTS(type, atom) \
+ ((void*)((uint8_t*)(atom) + sizeof(type)))
- An "Atom" is a generic chunk of memory with a given type and size.
- The type field defines how to interpret an atom.
+/** Return a pointer to the body of @p atom (just past the LV2_Atom head). */
+#define LV2_ATOM_BODY(atom) LV2_ATOM_CONTENTS(LV2_Atom, 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).
-*/
+/** The header of an atom:Atom. */
typedef struct {
- uint32_t type; /**< Type of this atom (mapped URI). */
- uint32_t size; /**< Size in bytes, not including type and size. */
- uint8_t body[]; /**< Body of length @ref size bytes. */
+ uint32_t type; /**< Type of this atom (mapped URI). */
+ uint32_t size; /**< Size in bytes, not including type and size. */
} LV2_Atom;
-/**
- An atom:String.
- May be cast to LV2_Atom.
-*/
+/** An atom:Int32 or atom:Bool. May be cast to LV2_Atom. */
+typedef struct {
+ LV2_Atom atom;
+ int32_t value;
+} LV2_Atom_Int32;
+
+/** An atom:Int64. May be cast to LV2_Atom. */
typedef struct {
- uint32_t type; /**< Type of this atom (mapped URI). */
- uint32_t size; /**< Size in bytes, not including type and size. */
- uint8_t str[]; /**< Null-terminated string data in UTF-8 encoding. */
+ LV2_Atom atom;
+ int64_t value;
+} LV2_Atom_Int64;
+
+/** An atom:Float. May be cast to LV2_Atom. */
+typedef struct {
+ LV2_Atom atom;
+ float value;
+} LV2_Atom_Float;
+
+/** An atom:Double. May be cast to LV2_Atom. */
+typedef struct {
+ LV2_Atom atom;
+ double value;
+} LV2_Atom_Double;
+
+/** An atom:Bool. May be cast to LV2_Atom. */
+typedef LV2_Atom_Int32 LV2_Atom_Bool;
+
+/** An atom:URID. May be cast to LV2_Atom. */
+typedef struct {
+ LV2_Atom atom; /**< Atom header. */
+ uint32_t id; /**< URID. */
+} LV2_Atom_URID;
+
+/** The complete header of an atom:String. */
+typedef struct {
+ LV2_Atom atom; /**< Atom header. */
+ /* Contents (a null-terminated UTF-8 string) follow here. */
} LV2_Atom_String;
-/**
- An atom:Literal.
- May be cast to LV2_Atom.
-*/
+/** The header of an atom:Literal body. */
typedef struct {
- uint32_t type; /**< Type of this atom (mapped URI). */
- uint32_t size; /**< Size in bytes, not including type and size. */
uint32_t datatype; /**< The ID of the datatype of this literal. */
uint32_t lang; /**< The ID of the language of this literal. */
- uint8_t str[]; /**< Null-terminated string data in UTF-8 encoding. */
+} LV2_Atom_Literal_Head;
+
+/** The complete header of an atom:Literal. */
+typedef struct {
+ LV2_Atom atom; /**< Atom header. */
+ LV2_Atom_Literal_Head literal; /**< Literal body header. */
+ /* Contents (a null-terminated UTF-8 string) follow here. */
} LV2_Atom_Literal;
-/**
- An atom:URID or atom:BlankID.
- May be cast to LV2_Atom.
-*/
+/** The complete header of an atom:Tuple. */
typedef struct {
- uint32_t type; /**< Type of this atom (mapped URI). */
- uint32_t size; /**< Size in bytes, not including type and size. */
- uint32_t id; /**< URID (integer mapped URI) or blank node ID. */
-} LV2_Atom_URID;
+ LV2_Atom atom; /**< Atom header. */
+ /* Contents (a series of complete atoms) follow here. */
+} LV2_Atom_Tuple;
-/**
- An atom:Vector.
- May be cast to LV2_Atom.
-*/
+/** The complete header of an atom:Vector. */
typedef struct {
- uint32_t type; /**< Type of this atom (mapped URI). */
- uint32_t size; /**< Size in bytes, not including type and size. */
+ LV2_Atom atom; /**< Atom header. */
uint32_t elem_count; /**< The number of elements in the vector */
uint32_t elem_type; /**< The type of each element in the vector */
- uint8_t elems[]; /**< Sequence of element bodies */
+ /* Contents (a series of packed atom bodies) follow here. */
} LV2_Atom_Vector;
-/**
- The body of an atom:Property.
- Note this type is not an LV2_Atom.
-*/
-typedef struct _LV2_Atom_Property {
- uint32_t key; /**< Key (predicate) (mapped URI). */
- LV2_Atom value; /**< Value (object) */
-} LV2_Atom_Property;
-
-/**
- An atom:Thing (Resource, Blank, or Message).
- May be cast to LV2_Atom.
-*/
+/** The header of an atom:Property body (e.g. in an atom:Object). */
typedef struct {
- uint32_t type; /**< Type of this atom (mapped URI). */
- uint32_t size; /**< Size in bytes, not including type and size. */
- uint32_t context; /**< ID of context graph, or 0 for default */
- uint32_t id; /**< URID (for Resource) or blank ID (for Blank) */
- uint8_t properties[]; /**< Sequence of LV2_Atom_Property */
-} LV2_Thing;
+ uint32_t key; /**< Key (predicate) (mapped URI). */
+ uint32_t context; /**< Context URID (may be, and generally is, 0). */
+ LV2_Atom value; /**< Value atom header. */
+} LV2_Atom_Property_Body;
-/**
- An atom:Event, a timestamped Atom.
- Note this type is not an LV2_Atom, but contains an Atom as payload.
-*/
+/** The complete header of an atom:Property. */
typedef struct {
- uint32_t frames; /**< Time in frames relative to this block. */
- uint32_t subframes; /**< Fractional time in 1/(2^32)ths of a frame. */
- LV2_Atom body; /**< Event body. */
-} LV2_Atom_Event;
+ LV2_Atom atom; /**< Atom header. */
+ uint32_t key; /**< Key (predicate) (mapped URI). */
+ uint32_t context; /**< Context URID (may be, and generally is, 0). */
+ LV2_Atom value; /**< Value atom header. */
+ /* Value atom body follows here. */
+} LV2_Atom_Property;
-/**
- An atom:Int32, a signed 32-bit integer.
- May be cast to LV2_Atom.
-*/
+/** The complete header of an atom:Object. */
typedef struct {
- uint32_t type;
- uint32_t size;
- int32_t value;
-} LV2_Atom_Int32;
+ LV2_Atom atom; /**< Atom header. */
+ uint32_t id; /**< URID for atom:Resource, or blank ID for atom:Blank. */
+ uint32_t type; /**< Type URID (same as rdf:type, for fast dispatch). */
+ /* Contents (a series of property bodies) follow here. */
+} LV2_Atom_Object;
-/**
- An atom:Int64, a signed 64-bit integer.
- May be cast to LV2_Atom.
-*/
+/** The complete header of an atom:Response. */
typedef struct {
- uint32_t type;
- uint32_t size;
- int64_t value;
-} LV2_Atom_Int64;
-
-/**
- An atom:Float, a 32-bit IEEE-754 floating point number.
- May be cast to LV2_Atom.
-*/
+ LV2_Atom atom; /**< Atom header. */
+ uint32_t source; /**< ID of message this is a response to (may be 0). */
+ uint32_t type; /**< Specific response type URID (may be 0). */
+ uint32_t seq; /**< Response sequence number, 0 for end. */
+ LV2_Atom body; /**< Body atom header (may be empty). */
+ /* Body optionally follows here. */
+} LV2_Atom_Response;
+
+/** A time stamp in frames. Note this type is NOT an LV2_Atom. */
typedef struct {
- uint32_t type;
- uint32_t size;
- float value;
-} LV2_Atom_Float;
+ uint32_t frames; /**< Time in frames relative to this block. */
+ uint32_t subframes; /**< Fractional time in 1/(2^32)ths of a frame. */
+} LV2_Atom_Audio_Time;
-/**
- An atom:Double, a 64-bit IEEE-754 floating point number.
- May be cast to LV2_Atom.
-*/
+/** The header of an atom:Event. Note this type is NOT an LV2_Atom. */
typedef struct {
- uint32_t type;
- uint32_t size;
- double value;
-} LV2_Atom_Double;
+ /** Time stamp. Which type is valid is determined by context. */
+ union {
+ LV2_Atom_Audio_Time audio; /**< Time in audio frames. */
+ double beats; /**< Time in beats. */
+ } time;
+ LV2_Atom body; /**< Event body atom header. */
+ /* Body atom contents follow here. */
+} LV2_Atom_Event;
/**
- A buffer of events (the contents of an atom:EventPort).
+ A sequence of events (time-stamped atoms).
- The host MAY elect to allocate buffers as a single chunk of POD by using
- this struct as a header much like LV2_Atom, or it may choose to point to
- a fragment of a buffer elsewhere. In either case, @ref data points to the
- start of the data contained in this buffer.
+ This is used as the contents of an atom:EventPort, but is a generic Atom
+ type which can be used anywhere.
- The buffer at @ref data contains a sequence of LV2_Atom_Event padded such
- that the start of each event is aligned to 64 bits, e.g.:
+ The contents of a sequence is a series of LV2_Atom_Event, each aligned
+ to 64-bits, e.g.:
<pre>
| Event 1 (size 6) | Event 2
| | | | | | | | |
@@ -186,60 +190,11 @@ typedef struct {
</pre>
*/
typedef struct {
-
- /**
- The contents of the event buffer. This may or may not reside in the
- same block of memory as this header, plugins must not assume either.
- The host guarantees this points to at least capacity bytes of allocated
- memory (though only size bytes of that are valid events).
- */
- uint8_t* data;
-
- /**
- The number of events in this buffer.
-
- INPUTS: The host must set this field to the number of events contained
- in the data buffer before calling run(). The plugin must not change
- this field.
-
- OUTPUTS: The plugin must set this field to the number of events it has
- written to the buffer before returning from run(). Any initial value
- should be ignored by the plugin.
- */
- uint32_t event_count;
-
- /**
- The capacity of the data buffer in bytes.
- This is set by the host and must not be changed by the plugin.
- The host is allowed to change this between run() calls.
- */
- uint32_t capacity;
-
- /**
- The size of the initial portion of the data buffer containing data.
-
- INPUTS: The host must set this field to the number of bytes used
- by all events it has written to the buffer (including headers)
- before calling the plugin's run().
- The plugin must not change this field.
-
- OUTPUTS: The plugin must set this field to the number of bytes
- used by all events it has written to the buffer (including headers)
- before returning from run().
- Any initial value should be ignored by the plugin.
- */
- uint32_t size;
-
-} LV2_Atom_Buffer;
-
-/**
- Pad a size to 64 bits.
-*/
-static inline uint32_t
-lv2_atom_pad_size(uint32_t size)
-{
- return (size + 7) & (~7);
-}
+ LV2_Atom atom; /**< Atom header. */
+ uint32_t capacity; /**< Maximum size of contents. */
+ uint32_t pad;
+ /* Contents (a series of events) follow here. */
+} LV2_Atom_Sequence;
#ifdef __cplusplus
} /* extern "C" */