clap

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

commit dcc3b9399d5ef8c674d0c7295dee25ca8a301cdf
parent 0437c8fcdd3af629429433435e5a6f4ffac258d9
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date:   Mon, 20 Oct 2014 22:15:01 +0200

Update the spec

Diffstat:
Minclude/clap/clap.h | 24+++++++++++++-----------
Mspec.html | 43+++++++++++++++++++++++++------------------
Mspec.rst | 18+++++++++++-------
3 files changed, 49 insertions(+), 36 deletions(-)

diff --git a/include/clap/clap.h b/include/clap/clap.h @@ -347,9 +347,7 @@ struct clap_plugin uint32_t latency; // latency in samples /* Audio ports. - * The port configuration has to be done before the plugin - * activation, or after the plugin deactivateion. - */ + * The port configuration has to be done while the plugin is deactivated. */ uint32_t (*get_ports_configs_count)(struct clap_plugin *plugin); bool (*get_ports_config)(struct clap_plugin *plugin, uint32_t config_index, @@ -366,11 +364,15 @@ struct clap_plugin /* Returns a newly allocated parameters tree. The caller has to free it. */ uint32_t (*get_params_count)(struct clap_plugin *plugin); - bool (*get_param)(struct clap_plugin *plugin, uint32_t index, struct clap_param *param); + bool (*get_param)(struct clap_plugin *plugin, + uint32_t index, + struct clap_param *param); /* Returns a newly allocated preset list. The caller has to free it. */ uint32_t (*get_presets_count)(struct clap_plugin *plugin); - bool (*get_preset)(struct clap_plugin *plugin, uint32_t index, struct clap_preset *preset); + bool (*get_preset)(struct clap_plugin *plugin, + uint32_t index, + struct clap_preset *preset); /* activation */ bool (*activate)(struct clap_plugin *plugin); @@ -384,12 +386,13 @@ struct clap_plugin void (*close_gui)(struct clap_plugin *plugin); /* The plugin has to allocate and save its state into *buffer. - * The host has to free *buffer after that. */ - void (*save)(struct clap_plugin *plugin, void **buffer, size_t *size); - void (*restore)(struct clap_plugin *plugin, const void *buffer, size_t size); + * The plugin is also responsible to free the buffer on the + * next call to save() or when the plugin is destroyed. */ + bool (*save)(struct clap_plugin *plugin, void **buffer, size_t *size); + bool (*restore)(struct clap_plugin *plugin, const void *buffer, size_t size); /* future features */ - void *(*extension)(struct clap_plugin *plugin, const char *extention_id, void *ptr); + void *(*extension)(struct clap_plugin *plugin, const char *id); }; /* typedef for dlsym() cast */ @@ -401,8 +404,7 @@ typedef struct clap_plugin *(*clap_create_f)(uint32_t plugin_index, /* Plugin entry point. If plugins_count is not null, then clap_create has * to store the number of plugins available in *plugins_count. * If clap_create failed to create a plugin, it returns NULL. - * The return value has to be freed by calling plugin->destroy(plugin). - */ + * The return value has to be freed by calling plugin->destroy(plugin). */ struct clap_plugin * clap_create(uint32_t plugin_index, struct clap_host *host, diff --git a/spec.html b/spec.html @@ -832,13 +832,16 @@ send an event <tt class="docutils literal">CLAP_EVENT_GUI_CLOSED</tt> to the hos <h2><a class="toc-backref" href="#id40">Presets</a></h2> <div class="section" id="list-plugin-s-presets"> <h3><a class="toc-backref" href="#id41">List plugin's presets</a></h3> -<p>The host can browse the plugin's preset by calling <tt class="docutils literal"><span class="pre">plugin-&gt;get_presets(plugin);</span></tt>. -This function returns a newly allocated preset linked list. -It is the responsibility of the host to free the linked list.</p> +<p>The host can browse the plugin's preset by calling:</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">plugin-&gt;get_presets_count(plugin);</span></tt> to know how many presets it has.</li> +<li><tt class="docutils literal"><span class="pre">plugin-&gt;get_preset(plugin,</span> preset_index, &amp;preset);</tt> to get a preset +details.</li> +</ul> </div> <div class="section" id="load-a-preset"> <h3><a class="toc-backref" href="#id42">Load a preset</a></h3> -<p>To load a preset, the host should send an event <tt class="docutils literal">CLAP_EVENT_PRESET_SET</tt> to +<p>To load a preset, the host have to send an event <tt class="docutils literal">CLAP_EVENT_PRESET_SET</tt> to the plugin.</p> <p>When a preset is loaded from the plugin's GUI, the plugin must send a <tt class="docutils literal">CLAP_EVENT_PRESET_SET</tt> to the host.</p> @@ -850,9 +853,11 @@ the plugin.</p> <pre class="code c literal-block"> <span class="kt">void</span> <span class="o">*</span><span class="n">buffer</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span> <span class="kt">size_t</span> <span class="n">size</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> -<span class="n">plugin</span><span class="o">-&gt;</span><span class="n">save</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">buffer</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">size</span><span class="p">);</span> -<span class="c1">// do what you want -</span><span class="n">free</span><span class="p">(</span><span class="n">buffer</span><span class="p">);</span> +<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">plugin</span><span class="o">-&gt;</span><span class="n">save</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">buffer</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">size</span><span class="p">))</span> <span class="p">{</span> + <span class="c1">// save failed +</span><span class="p">}</span> <span class="k">else</span> <span class="p">{</span> + <span class="c1">// save succeed +</span><span class="p">}</span> </pre> <p>Restoring the plugin's state is done by:</p> <pre class="code c literal-block"> @@ -1328,9 +1333,7 @@ big endian machine, it should load again successfully.</p> <span class="kt">uint32_t</span> <span class="n">latency</span><span class="p">;</span> <span class="c1">// latency in samples </span> <span class="cm">/* Audio ports. - * The port configuration has to be done before the plugin - * activation, or after the plugin deactivateion. - */</span> + * The port configuration has to be done while the plugin is deactivated. */</span> <span class="kt">uint32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">get_ports_configs_count</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">);</span> <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">get_ports_config</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="n">config_index</span><span class="p">,</span> @@ -1347,11 +1350,15 @@ big endian machine, it should load again successfully.</p> <span class="cm">/* Returns a newly allocated parameters tree. The caller has to free it. */</span> <span class="kt">uint32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">get_params_count</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">);</span> - <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">get_param</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="n">index</span><span class="p">,</span> <span class="k">struct</span> <span class="n">clap_param</span> <span class="o">*</span><span class="n">param</span><span class="p">);</span> + <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">get_param</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">,</span> + <span class="kt">uint32_t</span> <span class="n">index</span><span class="p">,</span> + <span class="k">struct</span> <span class="n">clap_param</span> <span class="o">*</span><span class="n">param</span><span class="p">);</span> <span class="cm">/* Returns a newly allocated preset list. The caller has to free it. */</span> <span class="kt">uint32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">get_presets_count</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">);</span> - <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">get_preset</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="n">index</span><span class="p">,</span> <span class="k">struct</span> <span class="n">clap_preset</span> <span class="o">*</span><span class="n">preset</span><span class="p">);</span> + <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">get_preset</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">,</span> + <span class="kt">uint32_t</span> <span class="n">index</span><span class="p">,</span> + <span class="k">struct</span> <span class="n">clap_preset</span> <span class="o">*</span><span class="n">preset</span><span class="p">);</span> <span class="cm">/* activation */</span> <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">activate</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">);</span> @@ -1365,12 +1372,13 @@ big endian machine, it should load again successfully.</p> <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">close_gui</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">);</span> <span class="cm">/* The plugin has to allocate and save its state into *buffer. - * The host has to free *buffer after that. */</span> - <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">save</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">,</span> <span class="kt">void</span> <span class="o">**</span><span class="n">buffer</span><span class="p">,</span> <span class="kt">size_t</span> <span class="o">*</span><span class="n">size</span><span class="p">);</span> - <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">restore</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">buffer</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">);</span> + * The plugin is also responsible to free the buffer on the + * next call to save() or when the plugin is destroyed. */</span> + <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">save</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">,</span> <span class="kt">void</span> <span class="o">**</span><span class="n">buffer</span><span class="p">,</span> <span class="kt">size_t</span> <span class="o">*</span><span class="n">size</span><span class="p">);</span> + <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">restore</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">buffer</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">size</span><span class="p">);</span> <span class="cm">/* future features */</span> - <span class="kt">void</span> <span class="o">*</span><span class="p">(</span><span class="o">*</span><span class="n">extension</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">extention_id</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">ptr</span><span class="p">);</span> + <span class="kt">void</span> <span class="o">*</span><span class="p">(</span><span class="o">*</span><span class="n">extension</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="n">plugin</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">id</span><span class="p">);</span> <span class="p">};</span> <span class="cm">/* typedef for dlsym() cast */</span> @@ -1382,8 +1390,7 @@ big endian machine, it should load again successfully.</p> <span class="cm">/* Plugin entry point. If plugins_count is not null, then clap_create has * to store the number of plugins available in *plugins_count. * If clap_create failed to create a plugin, it returns NULL. - * The return value has to be freed by calling plugin-&gt;destroy(plugin). - */</span> + * The return value has to be freed by calling plugin-&gt;destroy(plugin). */</span> <span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span> <span class="nf">clap_create</span><span class="p">(</span><span class="kt">uint32_t</span> <span class="n">plugin_index</span><span class="p">,</span> <span class="k">struct</span> <span class="n">clap_host</span> <span class="o">*</span><span class="n">host</span><span class="p">,</span> diff --git a/spec.rst b/spec.rst @@ -546,14 +546,16 @@ Presets List plugin's presets ~~~~~~~~~~~~~~~~~~~~~ -The host can browse the plugin's preset by calling ``plugin->get_presets(plugin);``. -This function returns a newly allocated preset linked list. -It is the responsibility of the host to free the linked list. +The host can browse the plugin's preset by calling: + +- ``plugin->get_presets_count(plugin);`` to know how many presets it has. +- ``plugin->get_preset(plugin, preset_index, &preset);`` to get a preset + details. Load a preset ~~~~~~~~~~~~~ -To load a preset, the host should send an event ``CLAP_EVENT_PRESET_SET`` to +To load a preset, the host have to send an event ``CLAP_EVENT_PRESET_SET`` to the plugin. When a preset is loaded from the plugin's GUI, the plugin must send a @@ -568,9 +570,11 @@ Saving the plugin's state is done by: void *buffer = NULL; size_t size = 0; - plugin->save(plugin, &buffer, &size); - // do what you want - free(buffer); + if (!plugin->save(plugin, &buffer, &size)) { + // save failed + } else { + // save succeed + } Restoring the plugin's state is done by: