From 926d15e02c3a29900c1a4e4219382f0395664682 Mon Sep 17 00:00:00 2001 From: Geraint Luff Date: Thu, 24 Oct 2024 22:48:37 +0100 Subject: [PATCH 1/6] Start `clap.web` draft --- include/clap/all.h | 1 + include/clap/ext/draft/web.h | 52 ++++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+) create mode 100644 include/clap/ext/draft/web.h diff --git a/include/clap/all.h b/include/clap/all.h index 54bbfbc4..b7ba57ac 100644 --- a/include/clap/all.h +++ b/include/clap/all.h @@ -13,3 +13,4 @@ #include "ext/draft/tuning.h" #include "ext/draft/undo.h" #include "ext/draft/scratch-memory.h" +#include "ext/draft/web.h" diff --git a/include/clap/ext/draft/web.h b/include/clap/ext/draft/web.h new file mode 100644 index 00000000..2d294ae6 --- /dev/null +++ b/include/clap/ext/draft/web.h @@ -0,0 +1,52 @@ +#pragma once + +static CLAP_CONSTEXPR const char CLAP_EXT_WEB[] = "clap.web/1"; + +#ifdef __cplusplus +extern "C" { +#endif + +/// @page Web +/// +/// This extension enables the plugin to provide the start-page for a webview UI, and exchange +/// messages back and forth. +/// +/// Messages are received in the webview using a standard MessageEvent, with the data in an +/// ArrayBuffer. They are posted back to the plugin using window.parent.postMessage(), with the +/// data in an ArrayBuffer or TypedArray. + +typedef struct clap_plugin_web { + // Returns the URL for the webview's initial navigation, as a null-terminated UTF-8 string. + // If this URL is relative, it is resolved relative to the plugin (bundle) directory, and + // cannot be outside it. The host may use any protocol to serve this content, and the page + // must not assume that the root of the domain is the root of the bundle. The URL may also be + // absolute, including a `file://` URL. + // Returns true on success. + // [main-thread] + bool(CLAP_ABI *get_start)(const clap_plugin_t *plugin, + char *out_buffer, + uint32_t out_buffer_capacity); + + // Receives a single message from the webview. + // Returns true on success. + // [main-thread] + bool(CLAP_ABI *receive)(const clap_plugin_t *plugin, const void *buffer, uint32_t size); + +} clap_plugin_web_t; + +typedef struct clap_host_web { + // Checks whether the webview is open (and ready to receive messages) + // [thread-safe] + bool(CLAP_ABI *is_open)(const clap_host_t *host); + + // Sends a single message to the webview. + // It must not allocate or block if called from the audio thread. + // Returns true on success. + // [thread-safe] + bool(CLAP_ABI *send)(const clap_host_t *host, const void *buffer, uint32_t size); + +} clap_host_web_t; + +#ifdef __cplusplus +} +#endif From c006cd4d31420bf034826f8c29090f191e1489aa Mon Sep 17 00:00:00 2001 From: Geraint Luff Date: Fri, 25 Oct 2024 12:11:20 +0100 Subject: [PATCH 2/6] Clarified `web_start` URL resolution ("bundle resource" directory depends on package format) --- include/clap/ext/draft/web.h | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/include/clap/ext/draft/web.h b/include/clap/ext/draft/web.h index 2d294ae6..c27e5c02 100644 --- a/include/clap/ext/draft/web.h +++ b/include/clap/ext/draft/web.h @@ -17,9 +17,10 @@ extern "C" { typedef struct clap_plugin_web { // Returns the URL for the webview's initial navigation, as a null-terminated UTF-8 string. - // If this URL is relative, it is resolved relative to the plugin (bundle) directory, and - // cannot be outside it. The host may use any protocol to serve this content, and the page - // must not assume that the root of the domain is the root of the bundle. The URL may also be + // If this URL is relative, it is resolved relative to the plugin (bundle) resource directory. + // The host may assume that no resources outside of that directory are used, and may use any + // protocol to provide this content, following HTTP-like relative URL resolution. The page must + // not assume that the root path of the domain is the root of the bundle. The URL may also be // absolute, including a `file://` URL. // Returns true on success. // [main-thread] From 2d3a4e74f6d3a1581f252ee3a414e69133bcad7e Mon Sep 17 00:00:00 2001 From: Geraint Date: Sun, 24 Nov 2024 21:02:17 +0000 Subject: [PATCH 3/6] `web` -> `webview` --- include/clap/ext/draft/{web.h => webview.h} | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) rename include/clap/ext/draft/{web.h => webview.h} (89%) diff --git a/include/clap/ext/draft/web.h b/include/clap/ext/draft/webview.h similarity index 89% rename from include/clap/ext/draft/web.h rename to include/clap/ext/draft/webview.h index c27e5c02..47ed6818 100644 --- a/include/clap/ext/draft/web.h +++ b/include/clap/ext/draft/webview.h @@ -1,12 +1,12 @@ #pragma once -static CLAP_CONSTEXPR const char CLAP_EXT_WEB[] = "clap.web/1"; +static CLAP_CONSTEXPR const char CLAP_EXT_WEBVIEW[] = "clap.webview/1"; #ifdef __cplusplus extern "C" { #endif -/// @page Web +/// @page Webview /// /// This extension enables the plugin to provide the start-page for a webview UI, and exchange /// messages back and forth. @@ -15,7 +15,7 @@ extern "C" { /// ArrayBuffer. They are posted back to the plugin using window.parent.postMessage(), with the /// data in an ArrayBuffer or TypedArray. -typedef struct clap_plugin_web { +typedef struct clap_plugin_webview { // Returns the URL for the webview's initial navigation, as a null-terminated UTF-8 string. // If this URL is relative, it is resolved relative to the plugin (bundle) resource directory. // The host may assume that no resources outside of that directory are used, and may use any @@ -33,9 +33,9 @@ typedef struct clap_plugin_web { // [main-thread] bool(CLAP_ABI *receive)(const clap_plugin_t *plugin, const void *buffer, uint32_t size); -} clap_plugin_web_t; +} clap_plugin_webview_t; -typedef struct clap_host_web { +typedef struct clap_host_webview { // Checks whether the webview is open (and ready to receive messages) // [thread-safe] bool(CLAP_ABI *is_open)(const clap_host_t *host); @@ -46,7 +46,7 @@ typedef struct clap_host_web { // [thread-safe] bool(CLAP_ABI *send)(const clap_host_t *host, const void *buffer, uint32_t size); -} clap_host_web_t; +} clap_host_webview_t; #ifdef __cplusplus } From 96daf34f3758d65cac07e00179d874820c1b5dde Mon Sep 17 00:00:00 2001 From: Geraint Date: Sun, 24 Nov 2024 21:34:22 +0000 Subject: [PATCH 4/6] Move everything to `[main-thread]` except `is_open()`, add `clap.gui` API constant --- include/clap/ext/draft/webview.h | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/include/clap/ext/draft/webview.h b/include/clap/ext/draft/webview.h index 47ed6818..9bcae6ae 100644 --- a/include/clap/ext/draft/webview.h +++ b/include/clap/ext/draft/webview.h @@ -2,6 +2,10 @@ static CLAP_CONSTEXPR const char CLAP_EXT_WEBVIEW[] = "clap.webview/1"; +// clap.gui API constant. The pointer in clap_window must be NULL, but sizing methods are useful. +// uses logical size, don't call clap_plugin_gui->set_scale() +static const CLAP_CONSTEXPR char CLAP_WINDOW_API_WEBVIEW[] = "webview"; + #ifdef __cplusplus extern "C" { #endif @@ -17,6 +21,7 @@ extern "C" { typedef struct clap_plugin_webview { // Returns the URL for the webview's initial navigation, as a null-terminated UTF-8 string. + // This must be called at least once before any messages are sent (or accepted by the host). // If this URL is relative, it is resolved relative to the plugin (bundle) resource directory. // The host may assume that no resources outside of that directory are used, and may use any // protocol to provide this content, following HTTP-like relative URL resolution. The page must @@ -24,11 +29,11 @@ typedef struct clap_plugin_webview { // absolute, including a `file://` URL. // Returns true on success. // [main-thread] - bool(CLAP_ABI *get_start)(const clap_plugin_t *plugin, + bool(CLAP_ABI *provide_starting_uri)(const clap_plugin_t *plugin, char *out_buffer, uint32_t out_buffer_capacity); - // Receives a single message from the webview. + // Receives a single message from the webview, which must be open and ready to receive replies. // Returns true on success. // [main-thread] bool(CLAP_ABI *receive)(const clap_plugin_t *plugin, const void *buffer, uint32_t size); @@ -36,14 +41,15 @@ typedef struct clap_plugin_webview { } clap_plugin_webview_t; typedef struct clap_host_webview { - // Checks whether the webview is open (and ready to receive messages) + // Checks whether the webview is open and likely to receive messages. + // This may be called at any time and is a hint for non-essential work, such as being able to + // skip metering calculations. // [thread-safe] bool(CLAP_ABI *is_open)(const clap_host_t *host); // Sends a single message to the webview. - // It must not allocate or block if called from the audio thread. - // Returns true on success. - // [thread-safe] + // Returns true on success. It must fail (false) if the webview is not open. + // [main-thread] bool(CLAP_ABI *send)(const clap_host_t *host, const void *buffer, uint32_t size); } clap_host_webview_t; From e527c2e777d2a3e23708de2a39dce9f5c5b31b69 Mon Sep 17 00:00:00 2001 From: Geraint Date: Mon, 25 Nov 2024 00:05:24 +0000 Subject: [PATCH 5/6] Correct include in `all.h` --- include/clap/all.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/clap/all.h b/include/clap/all.h index b7ba57ac..987972e1 100644 --- a/include/clap/all.h +++ b/include/clap/all.h @@ -13,4 +13,4 @@ #include "ext/draft/tuning.h" #include "ext/draft/undo.h" #include "ext/draft/scratch-memory.h" -#include "ext/draft/web.h" +#include "ext/draft/webview.h" From 33093295cca08dce9e56c26462017ba18edc2bc6 Mon Sep 17 00:00:00 2001 From: Geraint Luff Date: Mon, 2 Dec 2024 15:03:54 +0000 Subject: [PATCH 6/6] Clarified wording --- include/clap/ext/draft/webview.h | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/include/clap/ext/draft/webview.h b/include/clap/ext/draft/webview.h index 9bcae6ae..f7751f8a 100644 --- a/include/clap/ext/draft/webview.h +++ b/include/clap/ext/draft/webview.h @@ -21,7 +21,7 @@ extern "C" { typedef struct clap_plugin_webview { // Returns the URL for the webview's initial navigation, as a null-terminated UTF-8 string. - // This must be called at least once before any messages are sent (or accepted by the host). + // This must be called while the webview is not open, and must be called before it is opened. // If this URL is relative, it is resolved relative to the plugin (bundle) resource directory. // The host may assume that no resources outside of that directory are used, and may use any // protocol to provide this content, following HTTP-like relative URL resolution. The page must @@ -33,7 +33,7 @@ typedef struct clap_plugin_webview { char *out_buffer, uint32_t out_buffer_capacity); - // Receives a single message from the webview, which must be open and ready to receive replies. + // Receives a single message from the webview, which must be open. // Returns true on success. // [main-thread] bool(CLAP_ABI *receive)(const clap_plugin_t *plugin, const void *buffer, uint32_t size); @@ -41,14 +41,15 @@ typedef struct clap_plugin_webview { } clap_plugin_webview_t; typedef struct clap_host_webview { - // Checks whether the webview is open and likely to receive messages. - // This may be called at any time and is a hint for non-essential work, such as being able to - // skip metering calculations. + // Returns whether the webview is "open" (running and ready to receive messages). + // If called from the main thread, it must return the open state specified by other methods. + // If called from any other thread, it must only be used as a hint for non-essential work (such + // as to skip metering calculations) as there are no synchronisation guarantees. // [thread-safe] bool(CLAP_ABI *is_open)(const clap_host_t *host); // Sends a single message to the webview. - // Returns true on success. It must fail (false) if the webview is not open. + // Returns true on success. Should fail if the webview is not open. // [main-thread] bool(CLAP_ABI *send)(const clap_host_t *host, const void *buffer, uint32_t size);