Add LV2_Atom_Port_Buffer.

2 files changed, 31 insertions, 3 deletions

diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.h b/lv2/lv2plug.in/ns/ext/atom/atom.h
index fd0279c..66f0490 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom.h
+++ b/lv2/lv2plug.in/ns/ext/atom/atom.h
@@ -196,6 +196,29 @@ typedef struct {
 	/* Contents (a series of events) follow here. */
 } LV2_Atom_Sequence;
 
+/**
+   The contents of an atom:AtomPort buffer.
+
+   This contains a pointer to an Atom, which is the data to be
+   processed/written, as well as additional metadata.  This struct may be
+   augmented in the future to add more metadata fields as they become
+   necessary.  The initial version of this struct contains data, size, and
+   capacity.  Implementations MUST check that any other fields they wish to use
+   are actually present by comparing the size with the offset of that field,
+   e.g.:
+
+   @code
+   if (offsetof(LV2_Atom_Port_Buffer, field) < buf->size) {
+       do_stuff_with(buf->field);
+   }
+   @endcode
+*/
+typedef struct {
+	LV2_Atom* data;      /** Pointer to data. */
+	uint32_t  size;      /** Total size of this struct. */
+	uint32_t  capacity;  /** Available space for data body. */
+} LV2_Atom_Port_Buffer;
+
 #ifdef __cplusplus
 }  /* extern "C" */
 #endif
diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.ttl b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
index b19425f..70a1252 100644
--- a/lv2/lv2plug.in/ns/ext/atom/atom.ttl
+++ b/lv2/lv2plug.in/ns/ext/atom/atom.ttl
@@ -389,9 +389,14 @@ atom:AtomPort
 	rdfs:subClassOf lv2:Port ;
 	rdfs:label "Atom Port" ;
 	lv2:documentation """
-<p>A port which contains an lv2:Atom.  Ports of this type will be connected to
-a 64-bit aligned LV2_Atom immediately followed by <code>size</code> bytes of
-data.</p>
+<p>A port which contains an lv2:Atom.  Ports of this type are connected to an
+LV2_Atom_Port_Buffer, which contains a pointer to the port's Atom contents, as
+well as other metadata (such as capacity, for output ports with variably sized
+types).  The host MUST set all fields of LV2_Atom_Port_Buffer to appropriate
+values before calling the plugin's run method.  LV2_Atom_Port_Buffer::capacity
+must be set to the available space for the <em>body</em> of LV2_Atom_Port_Buffer::data,
+i.e. the maximum possible value for its <code>size</code> field, which does
+not include the LV2_Atom header.</p>
 
 <p>This is an abstract port type with incomplete semantics which can not be
 used directly as a port type.  Atom ports should be either a atom:ValuePort or