clap

CLAP Audio Plugin API
Log | Files | Refs | README | LICENSE

commit 7eff950840027cbf0711c4f9f1a949780493ff6d
parent 0404e6527d06823c41fb6a39b4e3dc8e91bc0a3c
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date:   Mon, 28 Nov 2022 19:03:12 +0100

Merge pull request #193 from abique/resource-directory

resource directory extension
Diffstat:
Ainclude/clap/ext/draft/resource-directory.h | 85+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 85 insertions(+), 0 deletions(-)

diff --git a/include/clap/ext/draft/resource-directory.h b/include/clap/ext/draft/resource-directory.h @@ -0,0 +1,85 @@ +#pragma once + +#include "../../plugin.h" + +static CLAP_CONSTEXPR const char CLAP_EXT_RESOURCE_DIRECTORY[] = "clap.resource-directory.draft/0"; + +#ifdef __cplusplus +extern "C" { +#endif + +/// @page Resource Directory +/// +/// This extension provides a way for the plugin to store its resources as file in a directory +/// provided by the host and recover them later on. +/// +/// The plugin **must** store relative path in its state toward resource directories. +/// +/// Resource sharing: +/// - shared directory is shared among all plugin instances, hence mostly appropriate for read-only +/// content +/// -> suitable for read-only content +/// - exclusive directory is exclusive to the plugin instance +/// -> if the plugin, then its exclusive directory must be duplicated too +/// -> suitable for read-write content +/// +/// Keeping the shared directory clean: +/// - to avoid clashes in the shared directory, plugins are encourraged to organize their files in +/// sub-folders, for example create one subdirectory using the vendor name +/// - don't use symbolic links or hard links which points outside of the directory +/// +/// Resource life-time: +/// - exclusive folder content is managed by the plugin instance +/// - exclusive folder content is deleted when the plugin instance is removed from the project +/// - shared folder content isn't managed by the host, until all plugins using the shared directory +/// are removed from the project +/// +/// Note for the host +/// - try to use the filesytem's copy-on-write feature when possible for reducing exclusive folder +/// space usage on duplication +/// - host can "garbage collect" the files in the shared folder using: +/// clap_plugin_resource_directory.get_files_count() +/// clap_plugin_resource_directory.get_file_path() +/// but be **very** careful before deleting any resources + +typedef struct clap_plugin_resource_directory { + // Sets the directory in which the plugin can save its resources. + // The directory remains valid until it is overriden or the plugin is destroyed. + // If path is null or blank, it clears the directory location. + // path must be absolute. + // [main-thread] + void(CLAP_ABI *set_directory)(const clap_plugin_t *plugin, const char *path, bool is_shared); + + // Asks the plugin to put its resources into the resources directory. + // It is not necessary to collect files which belongs to the plugin's + // factory content unless the param all is true. + // [main-thread] + void(CLAP_ABI *collect)(const clap_plugin_t *plugin, bool all); + + // Returns the number of files used by the plugin in the shared resource folder. + // [main-thread] + uint32_t(CLAP_ABI *get_files_count)(const clap_plugin_t *plugin); + + // Retrieves relative file path to the resources directory. + // @param path writable memory to store the path + // @param path_size number of available bytes in path + // Returns the number of bytes in the path, or -1 on error + // [main-thread] + int32_t(CLAP_ABI* get_file_path)(const clap_plugin_t *plugin, uint32_t index, char *path, uint32_t path_size); +} clap_plugin_resource_directory_t; + +typedef struct clap_host_resource_directory { + // Request the host to setup a resource directory with the specified sharing. + // Returns true if the host will perform the request. + // [main-thread] + bool(CLAP_ABI *request_directory)(const clap_host *host, bool is_shared); + + // Tell the host that the resource directory of the specified sharing is no longer required. + // If is_shared = false, then the host may delete the directory content. + // [main-thread] + void(CLAP_ABI *release_directory)(const clap_host *host, bool is_shared); +} clap_host_resource_directory_t; + +#ifdef __cplusplus +} +#endif