commit dcc3b9399d5ef8c674d0c7295dee25ca8a301cdf
parent 0437c8fcdd3af629429433435e5a6f4ffac258d9
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date: Mon, 20 Oct 2014 22:15:01 +0200
Update the spec
Diffstat:
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->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->get_presets_count(plugin);</span></tt> to know how many presets it has.</li>
+<li><tt class="docutils literal"><span class="pre">plugin->get_preset(plugin,</span> preset_index, &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">-></span><span class="n">save</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="o">&</span><span class="n">buffer</span><span class="p">,</span> <span class="o">&</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">-></span><span class="n">save</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="o">&</span><span class="n">buffer</span><span class="p">,</span> <span class="o">&</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->destroy(plugin).
- */</span>
+ * The return value has to be freed by calling plugin->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:
