CLAP 1.2.6

ChangeLog.md

@@ -1,3 +1,7 @@
+# Changes in 1.2.6
+
+* [mini-curve-display.h](include/clap/ext/draft/mini-curve-display.h): third iteration, added curve stacking, curve kind and curve hints.
+
 # Changes in 1.2.5
 
 * [mini-curve-display.h](include/clap/ext/draft/mini-curve-display.h): second iteration, remove `host->cuve_changed()` and improve documentation

include/clap/ext/draft/mini-curve-display.h

@@ -5,24 +5,99 @@
 // This extension allows a host to render a small curve provided by the plugin.
 // A useful application is to render an EQ frequency response in the DAW mixer view.
 
-static CLAP_CONSTEXPR const char CLAP_EXT_MINI_CURVE_DISPLAY[] = "clap.mini-curve-display/2";
+static CLAP_CONSTEXPR const char CLAP_EXT_MINI_CURVE_DISPLAY[] = "clap.mini-curve-display/3";
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+enum clap_mini_curve_display_curve_kind {
+   // If the curve's kind doesn't fit in any proposed kind, use this one
+   // and perhaps, make a pull request to extend the list.
+   CLAP_MINI_CURVE_DISPLAY_CURVE_KIND_UNSPECIFIED = 0,
+
+   // The mini curve is intended to draw the total gain response of the plugin.
+   // In this case the y values are in dB and the x values are in Hz (logarithmic).
+   // This would be useful in for example an equalizer.
+   CLAP_MINI_CURVE_DISPLAY_CURVE_KIND_GAIN_RESPONSE = 1,
+
+   // The mini curve is intended to draw the total phase response of the plugin.
+   // In this case the y values are in radians and the x values are in Hz (logarithmic).
+   // This would be useful in for example an equalizer.
+   CLAP_MINI_CURVE_DISPLAY_CURVE_KIND_PHASE_RESPONSE = 2,
+
+   // The mini curve is intended to draw the transfer curve of the plugin.
+   // In this case the both x and y values are in dB.
+   // This would be useful in for example a compressor or distortion plugin.
+   CLAP_MINI_CURVE_DISPLAY_CURVE_KIND_TRANSFER_CURVE = 3,
+
+   // This mini curve is intended to draw gain reduction over time. In this case
+   // x refers to the window in seconds and y refers to level in dB, x_min is
+   // always 0, and x_max would be the duration of the window.
+   // This would be useful in for example a compressor or limiter.
+   CLAP_MINI_CURVE_DISPLAY_CURVE_KIND_GAIN_REDUCTION = 4,
+
+   // This curve is intended as a generic time series plot. In this case
+   // x refers to the window in seconds. x_min is always 0, and x_max would be the duration of the
+   // window.
+   // Y is not specified and up to the plugin.
+   CLAP_MINI_CURVE_DISPLAY_CURVE_KIND_TIME_SERIES = 5,
+
+   // Note: more entries could be added here in the future
+};
+
+typedef struct clap_mini_curve_display_curve_hints {
+
+   // Range for the x axis.
+   double x_min;
+   double x_max;
+
+   // Range for the y axis.
+   double y_min;
+   double y_max;
+
+} clap_mini_curve_display_curve_hints_t;
+
+// A set of points representing the curve to be painted.
+typedef struct clap_mini_curve_display_curve_data {
+   // Indicates the kind of curve those values represent, the host can use this
+   // information to paint the curve using a meaningful color.
+   int32_t curve_kind;
+
+   // values[0] will be the leftmost value and values[data_size -1] will be the rightmost
+   // value.
+   //
+   // The value 0 and UINT16_MAX won't be painted.
+   // The value 1 will be at the bottom of the curve and UINT16_MAX - 1 will be at the top.
+   uint16_t *values;
+   uint32_t  values_count;
+} clap_mini_curve_display_curve_data_t;
+
 typedef struct clap_plugin_mini_curve_display {
-   // Renders the curve into the data buffer.
-   // The value 0 will be at the bottom of the curve and UINT16_MAX will be at the top.
-   // The value at index 0 will be the leftmost and the value at index data_size -1 will be the
-   // rightmost.
+   // Returns the number of curves the plugin wants to paint.
+   // Be aware that the space to display those curves will be small, and too much data will make
+   // the output hard to read.
+   uint32_t(CLAP_ABI *get_curve_count)(const clap_plugin_t *plugin);
+
+   // Renders the curve into each the curves buffer.
+   //
+   // curves is an array, and each entries (up to curves_size) contains pre-allocated
+   // values buffer that must be filled by the plugin.
+   //
+   // The host will "stack" the curves, from the first one to the last one.
+   // curves[0] is the first curve to be painted.
+   // curves[n + 1] will be painted over curves[n].
+   //
+   // Returns the number of curves rendered.
    // [main-thread]
-   bool(CLAP_ABI *render)(const clap_plugin_t *plugin, uint16_t *data, uint32_t data_size);
+   uint32_t(CLAP_ABI *render)(const clap_plugin_t                  *plugin,
+                              clap_mini_curve_display_curve_data_t *curves,
+                              uint32_t                              curves_size);
 
    // Tells the plugin if the curve is currently observed or not.
    // When it isn't observed render() can't be called.
    //
-   // When is_obseverd becomes true, the curve content and axis name are implicitely invalidated. So
+   // When is_obseverd becomes true, the curve content and axis name are implicitly invalidated. So
    // the plugin don't need to call host->changed.
    //
    // [main-thread]
@@ -33,6 +108,7 @@ typedef struct clap_plugin_mini_curve_display {
    // Returns true on success, if the name capacity was sufficient.
    // [main-thread]
    bool(CLAP_ABI *get_axis_name)(const clap_plugin_t *plugin,
+                                 uint32_t             curve_index,
                                  char                *x_name,
                                  char                *y_name,
                                  uint32_t             name_capacity);
@@ -49,6 +125,13 @@ enum clap_mini_curve_display_change_flags {
 };
 
 typedef struct clap_host_mini_curve_display {
+   // Fills in the given clap_mini_display_curve_hints_t structure and returns
+   // true if successful. If not, return false.
+   // [main-thread]
+   bool(CLAP_ABI *get_hints)(const clap_host_t                     *host,
+                             uint32_t                               kind,
+                             clap_mini_curve_display_curve_hints_t *hints);
+
    // Mark the curve as being static or dynamic.
    // The curve is initially considered as static, though the plugin should explicitely
    // initialize this state.

include/clap/version.h

@@ -22,7 +22,7 @@ typedef struct clap_version {
 
 #define CLAP_VERSION_MAJOR 1
 #define CLAP_VERSION_MINOR 2
-#define CLAP_VERSION_REVISION 5
+#define CLAP_VERSION_REVISION 6
 
 #define CLAP_VERSION_INIT                                                                          \
    { (uint32_t)CLAP_VERSION_MAJOR, (uint32_t)CLAP_VERSION_MINOR, (uint32_t)CLAP_VERSION_REVISION }