commit 63579c8dc25aef90232022a2bce4c6add7d5e0e0
parent c7c1a4168e6d2b3a5d81b7660092c52dbbabfdb3
Author: Paul Walker <paul@pwjw.com>
Date: Mon, 18 Nov 2024 22:37:29 -0500
Add some of the feedback from the Auburn/DPlug port
basically expand some comments around ranges, meaning, and so on.
Diffstat:
3 files changed, 24 insertions(+), 6 deletions(-)
diff --git a/include/clap/events.h b/include/clap/events.h
@@ -9,7 +9,12 @@ extern "C" {
#endif
// event header
-// must be the first attribute of the event
+// All clap events start with an event header to determine the overall
+// size of the event and its type and space (a namespacing for types).
+// clap_event objects are contiguous regions of memory which can be copied
+// with a memcpy of `size` bytes starting at the top of the header. As
+// such, be very careful when desiginig clap events with internal pointers
+// and other non-value-types to consider the lifetime of those members.
typedef struct clap_event_header {
uint32_t size; // event size including this header, eg: sizeof (clap_event_note)
uint32_t time; // sample offset within the buffer for this event
@@ -266,6 +271,12 @@ enum clap_transport_flags {
CLAP_TRANSPORT_IS_WITHIN_PRE_ROLL = 1 << 7,
};
+// clap_event_transport provides song position, tempo, and similar information
+// from the host to the plugin. There are two ways a host communicates these values.
+// In the `clap_process` structure sent to each processing block, the host may
+// provide a transport structure which indicates the available information at the
+// start of the block. If the host provides sample-accurate tempo or transport changes,
+// it can also provide subsequent inter-block transport updates by delivering a new event.
typedef struct clap_event_transport {
clap_event_header_t header;
diff --git a/include/clap/ext/gui.h b/include/clap/ext/gui.h
@@ -13,6 +13,9 @@
/// Embedding the window gives more control to the host, and feels more integrated.
/// Floating window are sometimes the only option due to technical limitations.
///
+/// The Embedding protocol is by far the most common, supported by all hosts to date,
+/// and a plugin author should support at least that case.
+///
/// Showing the GUI works as follow:
/// 1. clap_plugin_gui->is_api_supported(), check what can work
/// 2. clap_plugin_gui->create(), allocates gui resources
@@ -85,7 +88,10 @@ typedef struct clap_gui_resize_hints {
bool can_resize_horizontally;
bool can_resize_vertically;
- // only if can resize horizontally and vertically
+ // if both horizontal and vertical resize are available, do we preserve the
+ // aspect ratio, and if so, what is the width x height aspect ratio to preserve.
+ // These flags are unused if can_resize_horizontally or vertically are false,
+ // and ratios are unused if preserve is false.
bool preserve_aspect_ratio;
uint32_t aspect_ratio_width;
uint32_t aspect_ratio_height;
@@ -94,7 +100,8 @@ typedef struct clap_gui_resize_hints {
// Size (width, height) is in pixels; the corresponding windowing system extension is
// responsible for defining if it is physical pixels or logical pixels.
typedef struct clap_plugin_gui {
- // Returns true if the requested gui api is supported
+ // Returns true if the requested gui api is supported, either in floating (plugin-created)
+ // or non-floating (embedded) mode.
// [main-thread]
bool(CLAP_ABI *is_api_supported)(const clap_plugin_t *plugin, const char *api, bool is_floating);
diff --git a/include/clap/ext/params.h b/include/clap/ext/params.h
@@ -246,9 +246,9 @@ typedef struct clap_param_info {
// '/' will be used as a separator to show a tree-like structure.
char module[CLAP_PATH_SIZE];
- double min_value; // Minimum plain value
- double max_value; // Maximum plain value
- double default_value; // Default plain value
+ double min_value; // Minimum plain value. Must be finite (`std::isfinite` true)
+ double max_value; // Maximum plain value. Must be finite
+ double default_value; // Default plain value. Must be in [min, max] range.
} clap_param_info_t;
typedef struct clap_plugin_params {
