aboutsummaryrefslogtreecommitdiffstats
path: root/ext/atom.lv2/atom.h
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2011-10-10 04:12:12 +0000
committerDavid Robillard <d@drobilla.net>2011-10-10 04:12:12 +0000
commit233fda99dd3fab70b90ca73fe52bec9cebff95b0 (patch)
treeb66fe1a506957567c9ff5c31507371e0cc9463fd /ext/atom.lv2/atom.h
parentbfab1592ec2ac68c1c2ff8d1d7713ebaa81d8839 (diff)
downloadlv2-233fda99dd3fab70b90ca73fe52bec9cebff95b0.tar.xz
Add event type to atom extension (towards replacing event extension).
Diffstat (limited to 'ext/atom.lv2/atom.h')
-rw-r--r--ext/atom.lv2/atom.h105
1 files changed, 101 insertions, 4 deletions
diff --git a/ext/atom.lv2/atom.h b/ext/atom.lv2/atom.h
index d6d2308..1f8c6ac 100644
--- a/ext/atom.lv2/atom.h
+++ b/ext/atom.lv2/atom.h
@@ -17,7 +17,7 @@
/**
@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
@@ -39,15 +39,15 @@
/**
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
@@ -114,4 +114,101 @@ typedef struct _LV2_Object {
uint8_t properties[]; /**< Sequence of LV2_Atom_Property */
} LV2_Object;
+/**
+ An Event (a timestamped Atom).
+
+ Note this struct is different from the other structs in this header in that
+ it does not describe the body of some LV2_Atom, but instead is a "larger"
+ type which contains an LV2_Atom as its payload. This makes it possible for
+ an Event to be interpreted as an Atom in-place by simply pointing at
+ the @ref body field of the Event.
+*/
+typedef struct {
+
+ /**
+ The frames portion of timestamp. The unit of this value may depend on
+ context, but for events processed by LV2_Descriptor::run() the unit is
+ audio frames relative to this block (e.g. frame 0 is the first frame in
+ this call to run())
+ */
+ uint32_t frames;
+
+ /**
+ The sub-frames portion of timestamp. The unit of this value may depend
+ on context, but for events processed by LV2_Descriptor::run() the unit
+ is 1/(2^32) of an audio frame.
+ */
+ uint32_t subframes;
+
+ /**
+ The body of this event.
+ */
+ LV2_Atom body;
+
+} LV2_Atom_Event;
+
+/**
+ A buffer of events (the contents of an atom:EventPort).
+
+ 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.
+
+ 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.:
+ <pre>
+ | Event 1 (size 6) | Event 2
+ | | | | | | | | |
+ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
+ |FRAMES |SUBFRMS|TYPE |SIZE |DATADATADATAPAD|FRAMES |SUBFRMS|...
+ </pre>
+*/
+typedef struct _LV2_Atom_Event_Buffer {
+
+ /**
+ 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_Event_Buffer;
+
#endif /* LV2_ATOM_H */