Added pui:floatPeakRMS

2 files changed, 80 insertions, 1 deletions

diff --git a/ext/pui.lv2/pui.h b/ext/pui.lv2/pui.h
index 6af445b..f6ec303 100644
--- a/ext/pui.lv2/pui.h
+++ b/ext/pui.lv2/pui.h
@@ -55,10 +55,53 @@
 /** The full URI for the pui:floatControl PortProtocol. */
 #define LV2_PUI_FLOAT_CONTROL_URI "http://lv2plug.in/ns/ext/pui#floatControl"
 
+/** The full URI for the pui:floatPeakRMS PortProtocol. */
+#define LV2_PUI_FLOAT_PEAK_RMS_URI "http://lv2plug.in/ns/ext/pui#floatPeakRMS"
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/** 
+   A data type that is used to pass peak and RMS values for a period of
+   audio data at an input or output port to an UI, using port_event. See the
+   documentation for pui:floatPeakRMS for details about how and when this
+   should be done.
+*/
+typedef struct _LV2_PUI_Peak_RMS_Data {
+  
+  /**
+     The start of the measurement period. This is just a running counter that
+     must not be interpreted as any sort of global frame position. It should
+     only be interpreted relative to the starts of other measurement periods
+     in port_event() calls to the same plugin instance.
+     
+     This counter is allowed to overflow, in which case it should just wrap
+     around.
+  */
+  uint32_t period_start;
+  
+  /**
+     The size of the measurement period, in the same units as period_start.
+  */
+  uint32_t period_size;
+  
+  /**
+     The peak value for the measurement period. This should be the maximal
+     value for abs(sample) over all the samples in the period.
+  */
+  float peak;
+  
+  /**
+     The RMS value for the measurement period. This should be the root mean
+     square value of the samples in the period, equivalent to
+     sqrt((pow(sample1, 2) + pow(sample2, 2) + ... + pow(sampleN, 2)) / N)
+     where N is period_size.
+  */
+  float rms;
+
+} LV2_PUI_Peak_RMS_Data;
+
 /**
    A pointer to a widget or other type of UI.
    The actual type is defined by the type of the UI defined in the RDF data.
diff --git a/ext/pui.lv2/pui.ttl b/ext/pui.lv2/pui.ttl
index 425047d..20c9ee8 100644
--- a/ext/pui.lv2/pui.ttl
+++ b/ext/pui.lv2/pui.ttl
@@ -156,7 +156,7 @@ those extensions MUST specify:
 <li>What data (if any) should be passed in the LV2_Feature data pointer. </li>
 </ol></p>
 
-<p>For an example, see pui:floatControl.
+<p>For an example, see pui:floatControl or pui:floatPeakRMS.
 </p>
 
 <p>PortProtocol is a subclass of lv2:Feature, so UIs use lv2:optionalFeature and
@@ -185,3 +185,39 @@ pui:floatControl a pui:PortProtocol;
     NULL.</li>
 </ol>
 """.
+
+pui:floatPeakRMS a pui:PortProtocol;
+	rdfs:label "Peak and RMS for a period of audio data";
+	lv2:documentation """
+<p>This port protocol defines a way for the host to send continuous peak
+and RMS measurements of the audio signal at a certain port to the UI. The
+intended use is visualisation, e.g. an animated meter widget that shows
+the level of the audio input or output.</p>
+
+<p>A contiguous sequence of audio samples for which a single peak value
+and a single RMS value have been computed is called a <em>measurement
+period</em>.</p>
+
+<p>The rules (see pui:PortProtocol) for this port protocol are:</p>
+<ol>
+<li>This PortProtocol is valid for ports with the type lv2:AudioPort.</li>
+<li>The host SHOULD call port_event() at regular intervals. The measurement
+    periods used for calls to port_event() for the same port SHOULD be
+    contiguous (i.e. the measurement period for one call should begin right
+    after the end of the measurement period for the previous call ends) unless
+    the UI has removed and re-added the port subscription between those calls.
+    However, UIs MUST NOT depend on either the regularity of the calls or the
+    contiguity of the measurement periods; hosts may change the call rate
+    or skip calls for performance or other reasons. Measurement periods for
+    different calls to port_event() for the same port MUST NOT overlap. 
+<li>The format of the data in the buffer passed to port_event() is a single
+    LV2_PUI_Peak_RMS_Data object, and the buffer size is
+    sizeof(LV2_PUI_Peak_RMS_Data).</li>
+<li>The UI MUST NOT call write_port() with the ID for this port protocol as
+    the port_protocol parameter.</li>
+<li>The host MUST ignore any write_port() calls with the ID for this port
+    protocol as the port_protocol parameter.</li>
+<li>The data pointer in the LV2_Feature object for this feature should be
+    NULL.</li>
+</ol>
+""".