commit 69a69252fdd6ac1d06e246d9a04c0a89d9607a17
parent 0b84cc2cccf4cdbaea3719f8d532e4bc002aa2b2
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date: Tue, 11 Mar 2025 09:06:41 +0100
Merge pull request #459 from free-audio/next
CLAP 1.2.6
Diffstat:
3 files changed, 95 insertions(+), 8 deletions(-)
diff --git a/ChangeLog.md b/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
diff --git a/include/clap/ext/draft/mini-curve-display.h b/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.
diff --git a/include/clap/version.h b/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 }
