clap

commit d793af8ad58711b22088bc391ac9e813759bd7cf
parent 3686af00f1766c5505f27e9a2f22539e32d63fe0
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date:   Mon,  5 Sep 2022 10:08:52 +0200

Merge pull request #149 from tim-janik/file-reference-docs

File reference docs
Diffstat:
M
include/clap/ext/draft/file-reference.h
 | 
19
+++++++++++++------

1 file changed, 13 insertions(+), 6 deletions(-)
diff --git a/include/clap/ext/draft/file-reference.h b/include/clap/ext/draft/file-reference.h
@@ -31,20 +31,24 @@ extern "C" {
 // This describes a file currently used by the plugin
 typedef struct clap_file_reference {
    clap_id resource_id;
+
+   // Flag indicating that the plugin may be able to (re-)install a collection that provides
+   // this resource. DAWs can provide a user option to ignore or include this resource during
+   // "collect and save".
    bool    belongs_to_plugin_collection;
 
    size_t path_capacity; // [in] the number of bytes reserved in path
    size_t path_size;     // [out] the actual length of the path, can be bigger than path_capacity
-   char  *path; // [in,out] path to the file on the disk, must be null terminated, and may be
-                // truncated if the capacity is less than the size
+   char  *path; // [in,out] absolute path to the file on the disk, must be null terminated, and
+                // may be truncated if the capacity is less than the size
 } clap_file_reference_t;
 
 typedef struct clap_plugin_file_reference {
-   // returns the number of file reference this plugin has
+   // Returns the number of file reference this plugin has
    // [main-thread]
    uint32_t(CLAP_ABI *count)(const clap_plugin_t *plugin);
 
-   // gets the file reference at index
+   // Gets the file reference at index
    // returns true on success
    // [main-thread]
    bool(CLAP_ABI *get)(const clap_plugin_t   *plugin,
@@ -67,19 +71,22 @@ typedef struct clap_plugin_file_reference {
    // [main-thread]
    bool(CLAP_ABI *get_file_size)(const clap_plugin_t *plugin, clap_id resource_id, uint64_t *size);
 
-   // updates the path to a file reference
+   // Updates the path to a file reference
    // [main-thread]
    bool(CLAP_ABI *update_path)(const clap_plugin_t *plugin, clap_id resource_id, const char *path);
 
+   // Request all pending changes to be flushed to disk (e.g. for destructive
+   // sample editor plugins), needed during "collect and save".
    // [main-thread]
    bool(CLAP_ABI *save_resources)(const clap_plugin_t *plugin);
 } clap_plugin_file_reference_t;
 
 typedef struct clap_host_file_reference {
-   // informs the host that the file references have changed, the host should schedule a full rescan
+   // Informs the host that the file references have changed, the host should schedule a full rescan.
    // [main-thread]
    void(CLAP_ABI *changed)(const clap_host_t *host);
 
+   // Informs the host that file contents have changed, a call to save_resources() is needed.
    // [main-thread]
    void(CLAP_ABI *set_dirty)(const clap_host_t *host, clap_id resource_id);
 } clap_host_file_reference;