From 233fda99dd3fab70b90ca73fe52bec9cebff95b0 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Mon, 10 Oct 2011 04:12:12 +0000
Subject: Add event type to atom extension (towards replacing event extension).

---
 ext/atom.lv2/atom.h   | 105 ++++++++++++++++++++++++++++++++++++++++++++++++--
 ext/atom.lv2/atom.ttl |  22 +++++++++++
 2 files changed, 123 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 */
diff --git a/ext/atom.lv2/atom.ttl b/ext/atom.lv2/atom.ttl
index 9ed95c3..64c2ae7 100644
--- a/ext/atom.lv2/atom.ttl
+++ b/ext/atom.lv2/atom.ttl
@@ -295,6 +295,15 @@ A description of a set of <a href="#Object">objects</a>.  In memory, a Model is
 simply a sequence of objects.
 """ .
 
+atom:Event
+	a rdfs:Class ;
+	rdfs:subClassOf atom:Atom ;
+	rdfs:label "Event" ;
+	lv2:documentation """
+An atom with a time stamp header prepended, typically for sample accurate
+transmission via LV2 ports.  See struct LV2_Atom_Event.
+""" .
+
 atom:Bang
 	a rdfs:Class ;
 	rdfs:subClassOf atom:Atom ;
@@ -397,6 +406,19 @@ Intuitively, a MessagePort contains a "message" or "command" or "event"
 which is reacted to, NOT a "value" or "signal" (which is computed with).
 """ .
 
+atom:EventPort
+	a rdfs:Class ;
+	rdfs:label "Event port" ;
+	rdfs:subClassOf lv2:Port ;
+	lv2:documentation """
+Ports of this type will be connected to an LV2_Atom_Event_Buffer.  These ports
+contain a sequence of atom:Event (i.e. time stamped atoms).  These ports are
+used to send and receive atoms in the audio context
+(i.e. LV2_Descriptor::run()), and are intended as a simpler, more generic, and
+atom compatible successor to <a
+href="http://lv2plug.in/ns/ext/event#EventPort">ev:EventPort</a>.
+""" .
+
 atom:supports
 	a rdf:Property ;
 	rdfs:domain lv2:Port ;
-- 
cgit v1.2.1