commit afa99b2ce86d24bc16cba9a47cf35f700b963c5e
parent 43edca7ee8fd9853425ce5cc4e093da7f3d05252
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date: Wed, 12 Oct 2016 09:03:14 +0200
Re-organize doc
Diffstat:
| M | spec.html | | | 1089 | ++++++++++++++++++++++++++++++++++++++----------------------------------------- |
| M | spec.rst | | | 54 | ++++++++++++++++++++++++------------------------------ |
2 files changed, 550 insertions(+), 593 deletions(-)
diff --git a/spec.html b/spec.html
@@ -125,71 +125,65 @@ tt.docutils {
<li><a class="reference internal" href="#instantiate-a-plugin" id="id13">Instantiate a plugin</a><ul>
<li><a class="reference internal" href="#precautions" id="id14">Precautions</a></li>
<li><a class="reference internal" href="#release-a-plugin" id="id15">Release a plugin</a></li>
-<li><a class="reference internal" href="#plugins-collection" id="id16">Plugins collection</a><ul>
-<li><a class="reference internal" href="#sample-plugin-loader" id="id17">Sample plugin loader</a></li>
+<li><a class="reference internal" href="#plugins-collection" id="id16">Plugins collection</a></li>
+<li><a class="reference internal" href="#plugin-description" id="id17">Plugin description</a></li>
+<li><a class="reference internal" href="#extension-system" id="id18">Extension system</a></li>
+<li><a class="reference internal" href="#audio-ports-configuration" id="id19">Audio ports configuration</a><ul>
+<li><a class="reference internal" href="#pin-layout" id="id20">Pin layout</a></li>
+<li><a class="reference internal" href="#configurations" id="id21">Configurations</a></li>
+<li><a class="reference internal" href="#getting-the-ports-configurations" id="id22">Getting the ports configurations</a></li>
+<li><a class="reference internal" href="#selecting-a-configuration" id="id23">Selecting a configuration</a></li>
+<li><a class="reference internal" href="#repeatable-channels" id="id24">Repeatable channels</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#plugin-description" id="id18">Plugin description</a></li>
-<li><a class="reference internal" href="#extension-system" id="id19">Extension system</a></li>
-<li><a class="reference internal" href="#audio-ports-configuration" id="id20">Audio ports configuration</a><ul>
-<li><a class="reference internal" href="#pin-layout" id="id21">Pin layout</a></li>
-<li><a class="reference internal" href="#configurations" id="id22">Configurations</a></li>
-<li><a class="reference internal" href="#getting-the-ports-configurations" id="id23">Getting the ports configurations</a></li>
-<li><a class="reference internal" href="#selecting-a-configuration" id="id24">Selecting a configuration</a></li>
-<li><a class="reference internal" href="#repeatable-channels" id="id25">Repeatable channels</a></li>
</ul>
</li>
+<li><a class="reference internal" href="#activation" id="id25">Activation</a></li>
+<li><a class="reference internal" href="#processing" id="id26">Processing</a><ul>
+<li><a class="reference internal" href="#audio-buffers" id="id27">Audio buffers</a></li>
+<li><a class="reference internal" href="#events" id="id28">Events</a><ul>
+<li><a class="reference internal" href="#notes" id="id29">Notes</a></li>
+<li><a class="reference internal" href="#parameters" id="id30">Parameters</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#activation" id="id26">Activation</a></li>
-<li><a class="reference internal" href="#processing" id="id27">Processing</a><ul>
-<li><a class="reference internal" href="#audio-buffers" id="id28">Audio buffers</a></li>
-<li><a class="reference internal" href="#events" id="id29">Events</a><ul>
-<li><a class="reference internal" href="#notes" id="id30">Notes</a></li>
-<li><a class="reference internal" href="#parameters" id="id31">Parameters</a></li>
</ul>
</li>
+<li><a class="reference internal" href="#id1" id="id31">Parameters</a><ul>
+<li><a class="reference internal" href="#types" id="id32">Types</a></li>
+<li><a class="reference internal" href="#scales" id="id33">Scales</a></li>
+<li><a class="reference internal" href="#automation" id="id34">Automation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#id1" id="id32">Parameters</a><ul>
-<li><a class="reference internal" href="#types" id="id33">Types</a></li>
-<li><a class="reference internal" href="#scales" id="id34">Scales</a></li>
-<li><a class="reference internal" href="#automation" id="id35">Automation</a></li>
+<li><a class="reference internal" href="#graphical-user-interface" id="id35">Graphical User Interface</a><ul>
+<li><a class="reference internal" href="#showing-the-gui" id="id36">Showing the GUI</a></li>
+<li><a class="reference internal" href="#sending-events-to-the-host" id="id37">Sending events to the host</a></li>
+<li><a class="reference internal" href="#hiding-the-gui" id="id38">Hiding the GUI</a></li>
+<li><a class="reference internal" href="#embedding" id="id39">Embedding</a><ul>
+<li><a class="reference internal" href="#example-on-windows" id="id40">Example on Windows</a></li>
+<li><a class="reference internal" href="#resizing-the-window" id="id41">Resizing the window</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#graphical-user-interface" id="id36">Graphical User Interface</a><ul>
-<li><a class="reference internal" href="#showing-the-gui" id="id37">Showing the GUI</a></li>
-<li><a class="reference internal" href="#sending-events-to-the-host" id="id38">Sending events to the host</a></li>
-<li><a class="reference internal" href="#hiding-the-gui" id="id39">Hiding the GUI</a></li>
-<li><a class="reference internal" href="#embedding" id="id40">Embedding</a><ul>
-<li><a class="reference internal" href="#example-on-windows" id="id41">Example on Windows</a></li>
-<li><a class="reference internal" href="#resizing-the-window" id="id42">Resizing the window</a></li>
</ul>
</li>
+<li><a class="reference internal" href="#presets" id="id42">Presets</a><ul>
+<li><a class="reference internal" href="#list-plugin-s-presets" id="id43">List plugin's presets</a></li>
+<li><a class="reference internal" href="#load-a-preset" id="id44">Load a preset</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#presets" id="id43">Presets</a><ul>
-<li><a class="reference internal" href="#list-plugin-s-presets" id="id44">List plugin's presets</a></li>
-<li><a class="reference internal" href="#load-a-preset" id="id45">Load a preset</a></li>
+<li><a class="reference internal" href="#save-and-restore-plugin-s-state" id="id45">Save and restore plugin's state</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#save-and-restore-plugin-s-state" id="id46">Save and restore plugin's state</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#examples" id="id47">Examples</a><ul>
-<li><a class="reference internal" href="#examples-clap-info-clap-info-c" id="id48">examples/clap-info/clap-info.c</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#references" id="id49">References</a><ul>
-<li><a class="reference internal" href="#clap-clap-h" id="id50">clap/clap.h</a></li>
-<li><a class="reference internal" href="#clap-ext-ports-h" id="id51">clap/ext/ports.h</a></li>
-<li><a class="reference internal" href="#clap-ext-gui-h" id="id52">clap/ext/gui.h</a></li>
-<li><a class="reference internal" href="#clap-ext-state-h" id="id53">clap/ext/state.h</a></li>
-<li><a class="reference internal" href="#clap-ext-params-h" id="id54">clap/ext/params.h</a></li>
-<li><a class="reference internal" href="#clap-ext-presets-h" id="id55">clap/ext/presets.h</a></li>
-<li><a class="reference internal" href="#clap-ext-embed-h" id="id56">clap/ext/embed.h</a></li>
-<li><a class="reference internal" href="#clap-ext-embed-win32-h" id="id57">clap/ext/embed-win32.h</a></li>
-<li><a class="reference internal" href="#clap-ext-embed-xlib-h" id="id58">clap/ext/embed-xlib.h</a></li>
+<li><a class="reference internal" href="#references" id="id46">References</a><ul>
+<li><a class="reference internal" href="#clap-clap-h" id="id47">clap/clap.h</a></li>
+<li><a class="reference internal" href="#clap-ext-state-h" id="id48">clap/ext/state.h</a></li>
+<li><a class="reference internal" href="#clap-ext-ports-h" id="id49">clap/ext/ports.h</a></li>
+<li><a class="reference internal" href="#clap-ext-params-h" id="id50">clap/ext/params.h</a></li>
+<li><a class="reference internal" href="#clap-ext-gui-h" id="id51">clap/ext/gui.h</a></li>
+<li><a class="reference internal" href="#clap-ext-embed-h" id="id52">clap/ext/embed.h</a></li>
+<li><a class="reference internal" href="#clap-ext-embed-win32-h" id="id53">clap/ext/embed-win32.h</a></li>
+<li><a class="reference internal" href="#clap-ext-embed-x11-h" id="id54">clap/ext/embed-x11.h</a></li>
+<li><a class="reference internal" href="#clap-ext-embed-cocoa-h" id="id55">clap/ext/embed-cocoa.h</a></li>
+<li><a class="reference internal" href="#clap-ext-presets-h" id="id56">clap/ext/presets.h</a></li>
</ul>
</li>
</ul>
@@ -197,15 +191,15 @@ tt.docutils {
<div class="section" id="goals">
<h1><a class="toc-backref" href="#id2">Goals</a></h1>
<ul class="simple">
-<li>Make a free digital instrument and effect plugin format</li>
+<li>Make a free digital instrument and effect plugin interface</li>
<li>Be easy to understand and implement</li>
-<li>Bring new features missed in VST 2.4</li>
+<li>Don't require alien technology</li>
<li>Designed to work on any operating system and processor architecture</li>
<li>Be event oriented</li>
<li>Be extensible</li>
<li>Be easy to bridge</li>
-<li>Support dynamic configuration: let a modular plugin dynamically
-add new parameters, new outputs/inputs, etc...</li>
+<li>Support dynamic configuration: let a plugin dynamically
+add new parameters, io ports, etc...</li>
</ul>
<div class="section" id="design-choice">
<h2><a class="toc-backref" href="#id3">Design choice</a></h2>
@@ -328,13 +322,9 @@ into the parameter <tt class="docutils literal">*plugins_count</tt>. After that
of them by using an <tt class="docutils literal">index</tt> between <tt class="docutils literal">0</tt> and <tt class="docutils literal">*plugins_count</tt>.</p>
<p><tt class="docutils literal">clap_create</tt> returns <tt class="docutils literal">NULL</tt> if the plugin creation failed or if
<tt class="docutils literal">plugin_index >= plugin_count</tt>.</p>
-<div class="section" id="sample-plugin-loader">
-<h4><a class="toc-backref" href="#id17">Sample plugin loader</a></h4>
-<p>See <a class="reference internal" href="#examples-clap-info-clap-info-c">examples/clap-info/clap-info.c</a></p>
-</div>
</div>
<div class="section" id="plugin-description">
-<h3><a class="toc-backref" href="#id18">Plugin description</a></h3>
+<h3><a class="toc-backref" href="#id17">Plugin description</a></h3>
<p><tt class="docutils literal">struct clap_plugin</tt> only contains a interger <tt class="docutils literal">clap_version</tt> which
indicates which version of the clap interface has been used to build the plugin, and
a few methods. This attribute must be initialized by the plugin with
@@ -407,7 +397,7 @@ the DAW's task scheduling.</td>
</table>
</div>
<div class="section" id="extension-system">
-<h3><a class="toc-backref" href="#id19">Extension system</a></h3>
+<h3><a class="toc-backref" href="#id18">Extension system</a></h3>
<p>To extend clap's functionnality, there is a pretty simple mechanism:</p>
<pre class="code c literal-block">
<span class="kt">void</span> <span class="o">*</span><span class="n">plug_ext</span> <span class="o">=</span> <span class="n">plugin</span><span class="o">-></span><span class="n">extension</span><span class="p">(</span><span class="n">plug</span><span class="p">,</span> <span class="s">"company/ext-name"</span><span class="p">);</span>
@@ -416,7 +406,7 @@ the DAW's task scheduling.</td>
<p>If the extension is not supported, the plugin should return <tt class="docutils literal">NULL</tt>.</p>
</div>
<div class="section" id="audio-ports-configuration">
-<h3><a class="toc-backref" href="#id20">Audio ports configuration</a></h3>
+<h3><a class="toc-backref" href="#id19">Audio ports configuration</a></h3>
<p>A plugin may have multiple audio ports, and so multiple audio ports
layout or configurations.</p>
<p>An audio port has a type: mono, stereo, surround and a role: main
@@ -424,7 +414,7 @@ input/output or sidechain. We might add a feedback role in the futur
if there is a need for it. Also, an instrument/effect can load and host
clap effects for its feedback loops.</p>
<div class="section" id="pin-layout">
-<h4><a class="toc-backref" href="#id21">Pin layout</a></h4>
+<h4><a class="toc-backref" href="#id20">Pin layout</a></h4>
<table border="1" class="docutils">
<colgroup>
<col width="28%" />
@@ -478,7 +468,7 @@ clap effects for its feedback loops.</p>
</table>
</div>
<div class="section" id="configurations">
-<h4><a class="toc-backref" href="#id22">Configurations</a></h4>
+<h4><a class="toc-backref" href="#id21">Configurations</a></h4>
<p>After the call to <tt class="docutils literal">clap_create()</tt> the new plugin uses the default ports
configuration: 1 stereo input and 1 stereo output. So if you're fine with
it, there is nothing more to do.</p>
@@ -538,9 +528,9 @@ during the plugin activation (<tt class="docutils literal"><span class="pre">plu
</table>
</div>
<div class="section" id="getting-the-ports-configurations">
-<h4><a class="toc-backref" href="#id23">Getting the ports configurations</a></h4>
+<h4><a class="toc-backref" href="#id22">Getting the ports configurations</a></h4>
<pre class="code c literal-block">
-<span class="cp">#include <clap/ext/ports.h>
+<span class="cp">#include</span> <span class="cpf"><clap/ext/ports.h></span><span class="cp">
</span>
<span class="k">struct</span> <span class="n">clap_plugin_ports</span> <span class="o">*</span><span class="n">ports</span> <span class="o">=</span> <span class="n">plugin</span><span class="o">-></span><span class="n">extension</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">CLAP_EXT_PORTS</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">ports</span><span class="p">)</span>
@@ -562,13 +552,13 @@ you have to call
<tt class="docutils literal"><span class="pre">ports->get_info(plugin,</span> config_index, port_index, &port);</tt>.</p>
</div>
<div class="section" id="selecting-a-configuration">
-<h4><a class="toc-backref" href="#id24">Selecting a configuration</a></h4>
+<h4><a class="toc-backref" href="#id23">Selecting a configuration</a></h4>
<p>Selecting an audio configuration has to be done when the plugin is deactivated.
It is done by calling <tt class="docutils literal"><span class="pre">plugin->set_port_config(plugin,</span> config_index)</tt>.
If the call returns false, then the plugin is in failed state.</p>
</div>
<div class="section" id="repeatable-channels">
-<h4><a class="toc-backref" href="#id25">Repeatable channels</a></h4>
+<h4><a class="toc-backref" href="#id24">Repeatable channels</a></h4>
<p>Repeatable channels are a special case. A channel can be identified as
repeatable if <tt class="docutils literal"><span class="pre">channel->is_repeatable</span> == true</tt>.</p>
<p>A useful case is for an analyzer. Imagine a spectroscope, to which you want to
@@ -585,7 +575,7 @@ the call.</p>
</div>
</div>
<div class="section" id="activation">
-<h2><a class="toc-backref" href="#id26">Activation</a></h2>
+<h2><a class="toc-backref" href="#id25">Activation</a></h2>
<p>Before doing any processing, the plugin must be activated by calling
<tt class="docutils literal">bool succeed = <span class="pre">plugin->activate(plugin);</span></tt>.</p>
<p>If <tt class="docutils literal">succeed == true</tt> then the activation succeed. If the activation failed,
@@ -602,7 +592,7 @@ thread as it may take time.</p>
<p>The host must de-activate the plugin before destroying it.</p>
</div>
<div class="section" id="processing">
-<h2><a class="toc-backref" href="#id27">Processing</a></h2>
+<h2><a class="toc-backref" href="#id26">Processing</a></h2>
<p>The processing is done in one call: <tt class="docutils literal"><span class="pre">plugin->process(plugin,</span> process);</tt>.
The data structure process regroup everything needed by the plugin:</p>
<ul class="simple">
@@ -638,7 +628,7 @@ which can be:</p>
(see <tt class="docutils literal">CLAP_EVENT_PARAM_RAMP</tt> event), then the host must send a <tt class="docutils literal">CLAP_EVENT_PARAM_SET</tt>
or <tt class="docutils literal">CLAP_EVENT_PARAM_RAMP</tt> for those parameters at the next call to process.</p>
<div class="section" id="audio-buffers">
-<h3><a class="toc-backref" href="#id28">Audio buffers</a></h3>
+<h3><a class="toc-backref" href="#id27">Audio buffers</a></h3>
<ul class="simple">
<li>The audio buffers are allocated by the host. They must be aligned by the
maximum requirement of the vector instructions currently available.</li>
@@ -650,14 +640,14 @@ if the plugin has the attribute <tt class="docutils literal">CLAP_ATTR_SUPPORTS_
</ul>
</div>
<div class="section" id="events">
-<h3><a class="toc-backref" href="#id29">Events</a></h3>
+<h3><a class="toc-backref" href="#id28">Events</a></h3>
<ul class="simple">
<li>Event's time must be within the process duration:
<tt class="docutils literal"><span class="pre">[process->steady_time</span> .. <span class="pre">process->steady_time</span> + <span class="pre">process->nb_sambles]</span></tt>.</li>
<li>The plugin must not modify the events.</li>
</ul>
<div class="section" id="notes">
-<h4><a class="toc-backref" href="#id30">Notes</a></h4>
+<h4><a class="toc-backref" href="#id29">Notes</a></h4>
<p>A note is identified by a key. A key correspond to the keys of a midi keyboard (128 keys).
If the plugin supports tuning then it should use the <tt class="docutils literal"><span class="pre">event->note.pitch</span></tt> as
the note frequency.</p>
@@ -687,7 +677,7 @@ a note with a pitch of 54Hz</li>
it can quickly figure which voice is playing the given key.</p>
</div>
<div class="section" id="parameters">
-<h4><a class="toc-backref" href="#id31">Parameters</a></h4>
+<h4><a class="toc-backref" href="#id30">Parameters</a></h4>
<p>Parameters can be automated by the host using <tt class="docutils literal">CLAP_EVENT_PARAM_SET</tt> or
<tt class="docutils literal">CLAP_EVENT_PARAM_RAMP</tt>.</p>
<p>When using <tt class="docutils literal">CLAP_EVENT_PARAM_RAMP</tt>, the parameter is set to <tt class="docutils literal"><span class="pre">ev->param.value</span></tt>
@@ -698,7 +688,7 @@ for the sample at <tt class="docutils literal"><span class="pre">ev->steady_t
</div>
</div>
<div class="section" id="id1">
-<h2><a class="toc-backref" href="#id32">Parameters</a></h2>
+<h2><a class="toc-backref" href="#id31">Parameters</a></h2>
<p>The host can get the plugin's parameters tree by using the params extension:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">params->count(plugin);</span></tt> to know the number of parameters</li>
@@ -706,7 +696,7 @@ for the sample at <tt class="docutils literal"><span class="pre">ev->steady_t
value and description</li>
</ul>
<pre class="code c literal-block">
-<span class="cp">#include <clap/ext/params.h>
+<span class="cp">#include</span> <span class="cpf"><clap/ext/params.h></span><span class="cp">
</span>
<span class="k">struct</span> <span class="n">clap_plugin_params</span> <span class="o">*</span><span class="n">params</span> <span class="o">=</span> <span class="n">plugin</span><span class="o">-></span><span class="n">extension</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">CLAP_EXT_PARAMS</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">params</span><span class="p">)</span>
@@ -775,7 +765,7 @@ types.</td>
</tbody>
</table>
<div class="section" id="types">
-<h3><a class="toc-backref" href="#id33">Types</a></h3>
+<h3><a class="toc-backref" href="#id32">Types</a></h3>
<p>There are a few parameter types:</p>
<table border="1" class="docutils">
<colgroup>
@@ -817,14 +807,14 @@ should rely on <tt class="docutils literal">display_text</tt> to show its value.
</table>
</div>
<div class="section" id="scales">
-<h3><a class="toc-backref" href="#id34">Scales</a></h3>
+<h3><a class="toc-backref" href="#id33">Scales</a></h3>
<p>The plugin can inform the host, which scale to use for the parameter's UI
(knob, slider, ...). <tt class="docutils literal"><span class="pre">clap_param->scale</span></tt> can be set to <tt class="docutils literal">CLAP_PARAM_LINEAR</tt>
or <tt class="docutils literal">CLAP_PARAM_LOG</tt>. A logarithmic scale is convinient for a frequency
parameter.</p>
</div>
<div class="section" id="automation">
-<h3><a class="toc-backref" href="#id35">Automation</a></h3>
+<h3><a class="toc-backref" href="#id34">Automation</a></h3>
<p>When a parameter is modified by the GUI, the plugin should send a
<tt class="docutils literal">CLAP_EVENT_PARAM_SET</tt> event must be sent to the host, using
<tt class="docutils literal"><span class="pre">host->events(host,</span> plugin, events);</tt> so the host can record the automation.</p>
@@ -836,14 +826,14 @@ To do that the plugin uses <tt class="docutils literal"><span class="pre">clap_e
</div>
</div>
<div class="section" id="graphical-user-interface">
-<h2><a class="toc-backref" href="#id36">Graphical User Interface</a></h2>
+<h2><a class="toc-backref" href="#id35">Graphical User Interface</a></h2>
<div class="section" id="showing-the-gui">
-<h3><a class="toc-backref" href="#id37">Showing the GUI</a></h3>
+<h3><a class="toc-backref" href="#id36">Showing the GUI</a></h3>
<p>To show the plugin's GUI, you need to use the gui extension: <tt class="docutils literal"><span class="pre">gui->open(plugin)</span></tt>.
If the plugin succeed to show the GUI, it returns <tt class="docutils literal">true</tt>, <tt class="docutils literal">false</tt>
otherwise.</p>
<pre class="code c literal-block">
-<span class="cp">#include <clap/ext/gui.h>
+<span class="cp">#include</span> <span class="cpf"><clap/ext/gui.h></span><span class="cp">
</span>
<span class="k">struct</span> <span class="n">clap_plugin_gui</span> <span class="o">*</span><span class="n">gui</span> <span class="o">=</span> <span class="n">plugin</span><span class="o">-></span><span class="n">extension</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">CLAP_EXT_GUI</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">gui</span><span class="p">)</span>
@@ -852,7 +842,7 @@ otherwise.</p>
<p>See <a class="reference internal" href="#clap-ext-gui-h">clap/ext/gui.h</a>.</p>
</div>
<div class="section" id="sending-events-to-the-host">
-<h3><a class="toc-backref" href="#id38">Sending events to the host</a></h3>
+<h3><a class="toc-backref" href="#id37">Sending events to the host</a></h3>
<p>The plugin can notify the host of parameter changes by sending events to:
<tt class="docutils literal"><span class="pre">host->events(host,</span> plugin, events);</tt>.</p>
<p>Events sent to the host should be stamped:</p>
@@ -864,7 +854,7 @@ otherwise.</p>
</pre>
</div>
<div class="section" id="hiding-the-gui">
-<h3><a class="toc-backref" href="#id39">Hiding the GUI</a></h3>
+<h3><a class="toc-backref" href="#id38">Hiding the GUI</a></h3>
<p>The plugin should hide the GUI after a call to <tt class="docutils literal"><span class="pre">gui->close(plugin)</span></tt>.
If the plugin window has been closed by the user, then the plugin should
send an event <tt class="docutils literal">CLAP_EVENT_GUI_CLOSED</tt> to the host.</p>
@@ -877,7 +867,7 @@ send an event <tt class="docutils literal">CLAP_EVENT_GUI_CLOSED</tt> to the hos
</pre>
</div>
<div class="section" id="embedding">
-<h3><a class="toc-backref" href="#id40">Embedding</a></h3>
+<h3><a class="toc-backref" href="#id39">Embedding</a></h3>
<p>Some host are designed to embed plugin's window.
As embedding is not a requirement and is OS specific, it is then offered as
an extension.</p>
@@ -907,18 +897,23 @@ an extension.</p>
<td>For the plugin</td>
</tr>
<tr><td>X11</td>
-<td><a class="reference internal" href="#clap-ext-embed-xlib-h">clap/ext/embed-xlib.h</a></td>
-<td><tt class="docutils literal">CLAP_EMBED_XLIB</tt></td>
+<td><a class="reference internal" href="#clap-ext-embed-x11-h">clap/ext/embed-x11.h</a></td>
+<td><tt class="docutils literal">CLAP_EMBED_X11</tt></td>
+<td>For the plugin</td>
+</tr>
+<tr><td>Cocoa</td>
+<td><a class="reference internal" href="#clap-ext-embed-cocoa-h">clap/ext/embed-cocoa.h</a></td>
+<td><tt class="docutils literal">CLAP_EMBED_COCOA</tt></td>
<td>For the plugin</td>
</tr>
</tbody>
</table>
<div class="section" id="example-on-windows">
-<h4><a class="toc-backref" href="#id41">Example on Windows</a></h4>
+<h4><a class="toc-backref" href="#id40">Example on Windows</a></h4>
<pre class="code c literal-block">
-<span class="cp">#include <clap/clap.h>
-#include <clap/ext/gui.h>
-#include <clap/ext/embed-win32.h>
+<span class="cp">#include</span> <span class="cpf"><clap/clap.h></span><span class="cp">
+#include</span> <span class="cpf"><clap/ext/gui.h></span><span class="cp">
+#include</span> <span class="cpf"><clap/ext/embed-win32.h></span><span class="cp">
</span>
<span class="k">struct</span> <span class="n">clap_plugin_embed_win32</span> <span class="o">*</span><span class="n">embed</span> <span class="o">=</span> <span class="n">plugin</span><span class="o">-></span><span class="n">get_extension</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">CLAP_EMBED_WIN32</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">embed</span><span class="p">)</span>
@@ -930,10 +925,10 @@ an extension.</p>
</pre>
</div>
<div class="section" id="resizing-the-window">
-<h4><a class="toc-backref" href="#id42">Resizing the window</a></h4>
+<h4><a class="toc-backref" href="#id41">Resizing the window</a></h4>
<pre class="code c literal-block">
-<span class="cp">#include <clap/clap.h>
-#include <clap/ext/embed.h>
+<span class="cp">#include</span> <span class="cpf"><clap/clap.h></span><span class="cp">
+#include</span> <span class="cpf"><clap/ext/embed.h></span><span class="cp">
</span>
<span class="c1">// plugin code
</span><span class="k">struct</span> <span class="n">clap_host_embed</span> <span class="o">*</span><span class="n">embed</span> <span class="o">=</span> <span class="n">host</span><span class="o">-></span><span class="n">get_extension</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">CLAP_EMBED</span><span class="p">);</span>
@@ -945,13 +940,13 @@ an extension.</p>
</div>
</div>
<div class="section" id="presets">
-<h2><a class="toc-backref" href="#id43">Presets</a></h2>
+<h2><a class="toc-backref" href="#id42">Presets</a></h2>
<div class="section" id="list-plugin-s-presets">
-<h3><a class="toc-backref" href="#id44">List plugin's presets</a></h3>
+<h3><a class="toc-backref" href="#id43">List plugin's presets</a></h3>
<p>The host can browse the plugin's presets by using the preset extension:</p>
<pre class="code c literal-block">
-<span class="cp">#include <clap/clap.h>
-#include <clap/ext/presets.h>
+<span class="cp">#include</span> <span class="cpf"><clap/clap.h></span><span class="cp">
+#include</span> <span class="cpf"><clap/ext/presets.h></span><span class="cp">
</span>
<span class="k">struct</span> <span class="n">clap_plugin_presets</span> <span class="o">*</span><span class="n">presets</span> <span class="o">=</span> <span class="n">plugin</span><span class="o">-></span><span class="n">get_extension</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">CLAP_PRESETS</span><span class="p">);</span>
<span class="k">struct</span> <span class="n">clap_preset_iterator</span> <span class="o">*</span><span class="n">iter</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
@@ -972,7 +967,7 @@ an extension.</p>
<p>See <a class="reference internal" href="#clap-ext-presets-h">clap/ext/presets.h</a>.</p>
</div>
<div class="section" id="load-a-preset">
-<h3><a class="toc-backref" href="#id45">Load a preset</a></h3>
+<h3><a class="toc-backref" href="#id44">Load a preset</a></h3>
<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
@@ -980,11 +975,11 @@ the plugin.</p>
</div>
</div>
<div class="section" id="save-and-restore-plugin-s-state">
-<h2><a class="toc-backref" href="#id46">Save and restore plugin's state</a></h2>
+<h2><a class="toc-backref" href="#id45">Save and restore plugin's state</a></h2>
<p>Saving the plugin's state is done by using the state extension:</p>
<pre class="code c literal-block">
-<span class="cp">#include <clap/clap.h>
-#include <clap/ext/state.h>
+<span class="cp">#include</span> <span class="cpf"><clap/clap.h></span><span class="cp">
+#include</span> <span class="cpf"><clap/ext/state.h></span><span class="cp">
</span>
<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>
@@ -1008,182 +1003,16 @@ big endian machine, it should load again successfully.</p>
plugin's parameters and restore them.</p>
</div>
</div>
-<div class="section" id="examples">
-<h1><a class="toc-backref" href="#id47">Examples</a></h1>
-<div class="section" id="examples-clap-info-clap-info-c">
-<h2><a class="toc-backref" href="#id48">examples/clap-info/clap-info.c</a></h2>
-<pre class="code c literal-block">
-<span class="cp">#include <stdio.h>
-#include <dlfcn.h>
-</span>
-<span class="cp">#include <clap/clap.h>
-#include <clap/ext/params.h>
-</span>
-<span class="k">static</span> <span class="kt">void</span> <span class="nf">host_events</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>
- <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">struct</span> <span class="n">clap_event</span> <span class="o">*</span><span class="n">events</span><span class="p">)</span>
-<span class="p">{</span>
-<span class="p">}</span>
-
-<span class="k">static</span> <span class="kt">void</span> <span class="o">*</span><span class="nf">host_extension</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> <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">extension_id</span><span class="p">)</span>
-<span class="p">{</span>
- <span class="k">return</span> <span class="nb">NULL</span><span class="p">;</span>
-<span class="p">}</span>
-
-<span class="k">static</span> <span class="kt">void</span> <span class="nf">initialize_host</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>
-<span class="p">{</span>
- <span class="k">static</span> <span class="kt">uint64_t</span> <span class="n">steady_time</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
-
- <span class="n">host</span><span class="o">-></span><span class="n">clap_version</span> <span class="o">=</span> <span class="n">CLAP_VERSION</span><span class="p">;</span>
- <span class="n">host</span><span class="o">-></span><span class="n">events</span> <span class="o">=</span> <span class="n">host_events</span><span class="p">;</span>
- <span class="n">host</span><span class="o">-></span><span class="n">steady_time</span> <span class="o">=</span> <span class="o">&</span><span class="n">steady_time</span><span class="p">;</span>
- <span class="n">host</span><span class="o">-></span><span class="n">extension</span> <span class="o">=</span> <span class="n">host_extension</span><span class="p">;</span>
-<span class="p">}</span>
-
-<span class="k">static</span> <span class="kt">void</span> <span class="nf">print_attr</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="p">{</span>
- <span class="kt">char</span> <span class="n">buffer</span><span class="p">[</span><span class="mi">256</span><span class="p">];</span>
-
-<span class="cp">#define prt_attr(Attr) \
- do { \
- int size = plugin->get_attribute( \
- plugin, CLAP_ATTR_##Attr, buffer, sizeof (buffer)); \
- if (size > 0) \
- fprintf(stdout, " %s: %s\n", CLAP_ATTR_##Attr, buffer); \
- } while (0)
-</span>
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stdout</span><span class="p">,</span> <span class="s">"Attributes:</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">ID</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">NAME</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">DESCRIPTION</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">MANUFACTURER</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">VERSION</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">URL</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">SUPPORT</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">LICENSE</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">CATEGORIES</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">TYPE</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">CHUNK_SIZE</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">LATENCY</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">SUPPORTS_TUNING</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">SUPPORTS_IN_PLACE_PROCESSING</span><span class="p">);</span>
- <span class="n">prt_attr</span><span class="p">(</span><span class="n">IS_REMOTE_PROCESSING</span><span class="p">);</span>
-
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stdout</span><span class="p">,</span> <span class="s">"-------------------</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
-
-<span class="cp">#undef print_attr
-</span><span class="p">}</span>
-
-<span class="k">static</span> <span class="kt">void</span> <span class="nf">print_params</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="p">{</span>
- <span class="k">struct</span> <span class="n">clap_plugin_params</span> <span class="o">*</span><span class="n">params</span> <span class="o">=</span> <span class="n">plugin</span><span class="o">-></span><span class="n">extension</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">CLAP_EXT_PARAMS</span><span class="p">);</span>
-
- <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">params</span><span class="p">)</span> <span class="p">{</span>
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stdout</span><span class="p">,</span> <span class="s">"no parameter extension</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
- <span class="k">return</span><span class="p">;</span>
- <span class="p">}</span>
-
- <span class="kt">uint32_t</span> <span class="n">count</span> <span class="o">=</span> <span class="n">params</span><span class="o">-></span><span class="n">count</span><span class="p">(</span><span class="n">plugin</span><span class="p">);</span>
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stdout</span><span class="p">,</span> <span class="s">"parameters count: %d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">count</span><span class="p">);</span>
-
- <span class="k">struct</span> <span class="n">clap_param</span> <span class="n">param</span><span class="p">;</span>
- <span class="k">for</span> <span class="p">(</span><span class="kt">uint32_t</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">count</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
- <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">params</span><span class="o">-></span><span class="n">get</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="o">&</span><span class="n">param</span><span class="p">))</span>
- <span class="k">continue</span><span class="p">;</span>
-
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stdout</span><span class="p">,</span> <span class="s">" => {id: %s, name: %s, desc: %s, display: %s, "</span>
- <span class="s">"is_per_note: %d, is_used: %d, is_periodic: %d"</span><span class="p">,</span>
- <span class="n">param</span><span class="p">.</span><span class="n">id</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">name</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">desc</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">display</span><span class="p">,</span>
- <span class="n">param</span><span class="p">.</span><span class="n">is_per_note</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">is_used</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">is_periodic</span><span class="p">);</span>
-
- <span class="k">switch</span> <span class="p">(</span><span class="n">param</span><span class="p">.</span><span class="n">type</span><span class="p">)</span> <span class="p">{</span>
- <span class="k">case</span> <span class="nl">CLAP_PARAM_FLOAT</span><span class="p">:</span>
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stdout</span><span class="p">,</span> <span class="s">", type: float, value: %f, min: %f, max: %f, default: %f"</span><span class="p">,</span>
- <span class="n">param</span><span class="p">.</span><span class="n">value</span><span class="p">.</span><span class="n">f</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">min</span><span class="p">.</span><span class="n">f</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">max</span><span class="p">.</span><span class="n">f</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">deflt</span><span class="p">.</span><span class="n">f</span><span class="p">);</span>
- <span class="k">break</span><span class="p">;</span>
-
- <span class="k">case</span> <span class="nl">CLAP_PARAM_INT</span><span class="p">:</span>
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stdout</span><span class="p">,</span> <span class="s">", type: int, value: %d, min: %d, max: %d, default: %d"</span><span class="p">,</span>
- <span class="n">param</span><span class="p">.</span><span class="n">value</span><span class="p">.</span><span class="n">i</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">min</span><span class="p">.</span><span class="n">i</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">max</span><span class="p">.</span><span class="n">i</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">deflt</span><span class="p">.</span><span class="n">i</span><span class="p">);</span>
- <span class="k">break</span><span class="p">;</span>
-
- <span class="k">case</span> <span class="nl">CLAP_PARAM_ENUM</span><span class="p">:</span>
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stdout</span><span class="p">,</span> <span class="s">", type: enum, value: %d, min: %d, max: %d, default: %d"</span><span class="p">,</span>
- <span class="n">param</span><span class="p">.</span><span class="n">value</span><span class="p">.</span><span class="n">i</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">min</span><span class="p">.</span><span class="n">i</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">max</span><span class="p">.</span><span class="n">i</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">deflt</span><span class="p">.</span><span class="n">i</span><span class="p">);</span>
- <span class="k">break</span><span class="p">;</span>
-
- <span class="k">case</span> <span class="nl">CLAP_PARAM_BOOL</span><span class="p">:</span>
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stdout</span><span class="p">,</span> <span class="s">", type: bool, value: %d, min: %d, max: %d, default: %d"</span><span class="p">,</span>
- <span class="n">param</span><span class="p">.</span><span class="n">value</span><span class="p">.</span><span class="n">i</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">min</span><span class="p">.</span><span class="n">i</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">max</span><span class="p">.</span><span class="n">i</span><span class="p">,</span> <span class="n">param</span><span class="p">.</span><span class="n">deflt</span><span class="p">.</span><span class="n">i</span><span class="p">);</span>
- <span class="k">break</span><span class="p">;</span>
-
- <span class="k">case</span> <span class="nl">CLAP_PARAM_GROUP</span><span class="p">:</span>
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stdout</span><span class="p">,</span> <span class="s">", type: group"</span><span class="p">);</span>
- <span class="k">break</span><span class="p">;</span>
- <span class="p">}</span>
-
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stdout</span><span class="p">,</span> <span class="s">"}</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
- <span class="p">}</span>
-
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stdout</span><span class="p">,</span> <span class="s">"-------------------</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
-<span class="p">}</span>
-
-<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span>
-<span class="p">{</span>
- <span class="k">struct</span> <span class="n">clap_host</span> <span class="n">host</span><span class="p">;</span>
- <span class="n">initialize_host</span><span class="p">(</span><span class="o">&</span><span class="n">host</span><span class="p">);</span>
-
- <span class="kt">void</span> <span class="o">*</span> <span class="n">handle</span> <span class="o">=</span> <span class="n">dlopen</span><span class="p">(</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="n">RTLD_NOW</span> <span class="o">|</span> <span class="n">RTLD_LOCAL</span><span class="p">);</span>
- <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">handle</span><span class="p">)</span> <span class="p">{</span>
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"failed to load %s: %s</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="n">dlerror</span><span class="p">());</span>
- <span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
- <span class="p">}</span>
-
- <span class="k">union</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="n">clap_create_f</span> <span class="n">clap_create</span><span class="p">;</span>
- <span class="p">}</span> <span class="n">symbol</span><span class="p">;</span>
-
- <span class="n">symbol</span><span class="p">.</span><span class="n">ptr</span> <span class="o">=</span> <span class="n">dlsym</span><span class="p">(</span><span class="n">handle</span><span class="p">,</span> <span class="s">"clap_create"</span><span class="p">);</span>
- <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">symbol</span><span class="p">.</span><span class="n">ptr</span><span class="p">)</span> <span class="p">{</span>
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"symbol not found: clap_create</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
- <span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
- <span class="p">}</span>
-
- <span class="kt">uint32_t</span> <span class="n">plugin_count</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
- <span class="k">for</span> <span class="p">(</span><span class="kt">uint32_t</span> <span class="n">index</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">index</span> <span class="o"><</span> <span class="n">plugin_count</span><span class="p">;</span> <span class="o">++</span><span class="n">index</span><span class="p">)</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="o">=</span> <span class="n">symbol</span><span class="p">.</span><span class="n">clap_create</span><span class="p">(</span>
- <span class="n">index</span><span class="p">,</span> <span class="o">&</span><span class="n">host</span><span class="p">,</span> <span class="mi">48000</span><span class="p">,</span> <span class="o">&</span><span class="n">plugin_count</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="p">)</span> <span class="p">{</span>
- <span class="n">fprintf</span><span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"failed to create plugin index %d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">index</span><span class="p">);</span>
- <span class="k">continue</span><span class="p">;</span>
- <span class="p">}</span>
-
- <span class="n">print_attr</span><span class="p">(</span><span class="n">plugin</span><span class="p">);</span>
- <span class="n">print_params</span><span class="p">(</span><span class="n">plugin</span><span class="p">);</span>
-
- <span class="c1">// destroy the plugin
-</span> <span class="n">plugin</span><span class="o">-></span><span class="n">destroy</span><span class="p">(</span><span class="n">plugin</span><span class="p">);</span>
- <span class="p">}</span>
-
- <span class="n">dlclose</span><span class="p">(</span><span class="n">handle</span><span class="p">);</span>
-
- <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
-<span class="p">}</span>
-</pre>
-</div>
-</div>
<div class="section" id="references">
-<h1><a class="toc-backref" href="#id49">References</a></h1>
+<h1><a class="toc-backref" href="#id46">References</a></h1>
<div class="section" id="clap-clap-h">
-<h2><a class="toc-backref" href="#id50">clap/clap.h</a></h2>
+<h2><a class="toc-backref" href="#id47">clap/clap.h</a></h2>
<pre class="code c literal-block">
<span class="cm">/*
- * CLAP - CLever Audio Plugin (<--- needs to find a marketing ok name)
+ * CLAP - CLever Audio Plugin
* ~~~~~~~~~~~~~~~~~~~~~~~~~~
*
- * Copyright (c) 2014 Alexandre BIQUE <bique.alexandre@gmail.com>
+ * Copyright (c) 2014...2016 Alexandre BIQUE <bique.alexandre@gmail.com>
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -1217,11 +1046,25 @@ plugin's parameters and restore them.</p>
</span>
<span class="cp"># define CLAP_VERSION_MAKE(Major, Minor, Revision) \
((((Major) & 0xff) << 16) | (((Minor) & 0xff) << 8) | ((Revision) & 0xff))
-# define CLAP_VERSION CLAP_VERSION_MAKE(0, 1, 0)
+# define CLAP_VERSION CLAP_VERSION_MAKE(0, 2, 0)
# define CLAP_VERSION_MAJ(Version) (((Version) >> 16) & 0xff)
# define CLAP_VERSION_MIN(Version) (((Version) >> 8) & 0xff)
# define CLAP_VERSION_REV(Version) ((Version) & 0xff)
</span>
+<span class="cp">#if defined _WIN32 || defined __CYGWIN__
+# ifdef __GNUC__
+# define CLAP_EXPORT __attribute__ ((dllexport))
+# else
+# define CLAP_EXPORT __declspec(dllexport)
+# endif
+#else
+# if __GNUC__ >= 4
+# define CLAP_EXPORT __attribute__ ((visibility ("default")))
+# else
+# define CLAP_EXPORT
+# endif
+#endif
+</span>
<span class="c1">///////////////////////////
// FORWARD DELCLARATIONS //
///////////////////////////
@@ -1231,12 +1074,11 @@ plugin's parameters and restore them.</p>
<span class="k">enum</span> <span class="n">clap_string_size</span>
<span class="p">{</span>
- <span class="n">CLAP_ID_SIZE</span> <span class="o">=</span> <span class="mi">48</span><span class="p">,</span>
- <span class="n">CLAP_NAME_SIZE</span> <span class="o">=</span> <span class="mi">32</span><span class="p">,</span>
+ <span class="n">CLAP_ID_SIZE</span> <span class="o">=</span> <span class="mi">64</span><span class="p">,</span>
+ <span class="n">CLAP_NAME_SIZE</span> <span class="o">=</span> <span class="mi">64</span><span class="p">,</span>
<span class="n">CLAP_DESC_SIZE</span> <span class="o">=</span> <span class="mi">256</span><span class="p">,</span>
- <span class="n">CLAP_DISPLAY_SIZE</span> <span class="o">=</span> <span class="mi">32</span><span class="p">,</span>
- <span class="n">CLAP_TAGS_SIZE</span> <span class="o">=</span> <span class="mi">128</span><span class="p">,</span>
- <span class="n">CLAP_URL_SIZE</span> <span class="o">=</span> <span class="mi">256</span><span class="p">,</span>
+ <span class="n">CLAP_DISPLAY_SIZE</span> <span class="o">=</span> <span class="mi">64</span><span class="p">,</span>
+ <span class="n">CLAP_TAGS_SIZE</span> <span class="o">=</span> <span class="mi">256</span><span class="p">,</span>
<span class="p">};</span>
<span class="k">enum</span> <span class="n">clap_log_severity</span>
@@ -1259,10 +1101,9 @@ plugin's parameters and restore them.</p>
# define CLAP_ATTR_CATEGORIES "clap/categories"
# define CLAP_ATTR_TYPE "clap/type"
# define CLAP_ATTR_CHUNK_SIZE "clap/chunk_size"
-# define CLAP_ATTR_LATENCY "clap/latency"
</span><span class="c1">// Should be "1" if the plugin supports tunning.
</span><span class="cp"># define CLAP_ATTR_SUPPORTS_TUNING "clap/supports_tuning"
-</span><span class="c1">// Shoudl be "1" if the plugin is doing remote processing.
+</span><span class="c1">// Should be "1" if the plugin is doing remote processing.
// This is a hint for the host to optimize task scheduling.
</span><span class="cp"># define CLAP_ATTR_IS_REMOTE_PROCESSING "clap/is_remote_processing"
</span><span class="c1">// Should be "1" if the plugin supports in place processing.
@@ -1285,108 +1126,103 @@ plugin's parameters and restore them.</p>
</span>
<span class="k">enum</span> <span class="n">clap_event_type</span>
<span class="p">{</span>
- <span class="n">CLAP_EVENT_NOTE_ON</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="c1">// note attribute
-</span> <span class="n">CLAP_EVENT_NOTE_OFF</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="c1">// note attribute
-</span>
- <span class="n">CLAP_EVENT_PARAM_SET</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span> <span class="c1">// param attribute
-</span> <span class="n">CLAP_EVENT_PARAM_RAMP</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span> <span class="c1">// param attribute
-</span> <span class="n">CLAP_EVENT_PRESET_SET</span> <span class="o">=</span> <span class="mi">4</span><span class="p">,</span> <span class="c1">// preset attribute
-</span>
- <span class="n">CLAP_EVENT_MIDI</span> <span class="o">=</span> <span class="mi">5</span><span class="p">,</span> <span class="c1">// midi attribute
-</span> <span class="n">CLAP_EVENT_CONTROL</span> <span class="o">=</span> <span class="mi">6</span><span class="p">,</span> <span class="c1">// control attribute
+ <span class="n">CLAP_EVENT_NOTE_ON</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="c1">// note attribute
+</span> <span class="n">CLAP_EVENT_NOTE_OFF</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="c1">// note attribute
+</span> <span class="n">CLAP_EVENT_NOTE_CHOKE</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span> <span class="c1">// note attribute
</span>
- <span class="n">CLAP_EVENT_GUI_OPENED</span> <span class="o">=</span> <span class="mi">7</span><span class="p">,</span> <span class="c1">// plugin to host, no attribute
-</span> <span class="n">CLAP_EVENT_GUI_CLOSED</span> <span class="o">=</span> <span class="mi">8</span><span class="p">,</span> <span class="c1">// plugin to host, no attribute
+ <span class="n">CLAP_EVENT_PARAM_SET</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span> <span class="c1">// param attribute
+</span> <span class="n">CLAP_EVENT_PARAM_RAMP</span> <span class="o">=</span> <span class="mi">4</span><span class="p">,</span> <span class="c1">// param attribute
</span>
- <span class="n">CLAP_EVENT_NEW_PRESETS</span> <span class="o">=</span> <span class="mi">9</span><span class="p">,</span> <span class="c1">// plugin to host, no attribute
-</span> <span class="n">CLAP_EVENT_NEW_PORTS_CONFIGS</span> <span class="o">=</span> <span class="mi">10</span><span class="p">,</span> <span class="c1">// plugin to host, no attribute
-</span>
- <span class="n">CLAP_EVENT_LATENCY_CHANGED</span> <span class="o">=</span> <span class="mi">11</span><span class="p">,</span> <span class="c1">// plugin to host, latency attribute
+ <span class="n">CLAP_EVENT_CONTROL</span> <span class="o">=</span> <span class="mi">5</span><span class="p">,</span> <span class="c1">// control attribute
+</span> <span class="n">CLAP_EVENT_MIDI</span> <span class="o">=</span> <span class="mi">6</span><span class="p">,</span> <span class="c1">// midi attribute
</span>
<span class="n">CLAP_EVENT_PLAY</span> <span class="o">=</span> <span class="mi">12</span><span class="p">,</span> <span class="c1">// no attribute
</span> <span class="n">CLAP_EVENT_PAUSE</span> <span class="o">=</span> <span class="mi">13</span><span class="p">,</span> <span class="c1">// no attribute
</span> <span class="n">CLAP_EVENT_STOP</span> <span class="o">=</span> <span class="mi">14</span><span class="p">,</span> <span class="c1">// no attribute
+</span> <span class="n">CLAP_EVENT_JUMP</span> <span class="o">=</span> <span class="mi">15</span><span class="p">,</span> <span class="c1">// attribute jump
</span>
- <span class="n">CLAP_EVENT_JUMP</span> <span class="o">=</span> <span class="mi">15</span><span class="p">,</span> <span class="c1">// attribute jump
-</span><span class="p">};</span>
-
-<span class="k">struct</span> <span class="n">clap_event_note</span>
-<span class="p">{</span>
- <span class="kt">uint8_t</span> <span class="n">key</span><span class="p">;</span>
- <span class="kt">float</span> <span class="n">pitch</span><span class="p">;</span>
- <span class="kt">float</span> <span class="n">velocity</span><span class="p">;</span> <span class="c1">// 0..1
+ <span class="n">CLAP_EVENT_PROGRAM</span> <span class="o">=</span> <span class="mi">16</span><span class="p">,</span> <span class="c1">// program attribute
</span><span class="p">};</span>
<span class="k">struct</span> <span class="n">clap_event_param</span>
<span class="p">{</span>
- <span class="cm">/* key/voice index */</span>
- <span class="kt">bool</span> <span class="n">is_global</span><span class="p">;</span> <span class="c1">// is this event global?
-</span> <span class="kt">uint8_t</span> <span class="n">key</span><span class="p">;</span> <span class="c1">// if !is_global, target key
+ <span class="cm">/* key/channel index */</span>
+ <span class="kt">int8_t</span> <span class="n">key</span><span class="p">;</span> <span class="c1">// 0..127
+</span> <span class="kt">int8_t</span> <span class="n">channel</span><span class="p">;</span> <span class="c1">// 0..16
</span>
<span class="cm">/* parameter */</span>
- <span class="kt">uint32_t</span> <span class="n">index</span><span class="p">;</span> <span class="c1">// parameter index
+ <span class="kt">int32_t</span> <span class="n">index</span><span class="p">;</span> <span class="c1">// parameter index
</span> <span class="k">union</span> <span class="n">clap_param_value</span> <span class="n">value</span><span class="p">;</span>
- <span class="kt">float</span> <span class="n">increment</span><span class="p">;</span> <span class="c1">// for param ramp
-</span> <span class="kt">char</span> <span class="n">display_text</span><span class="p">[</span><span class="n">CLAP_DISPLAY_SIZE</span><span class="p">];</span> <span class="c1">// use this for display.
-</span> <span class="kt">bool</span> <span class="n">is_recordable</span><span class="p">;</span> <span class="c1">// used to tell the host if this event
-</span> <span class="c1">// can be recorded
-</span> <span class="kt">bool</span> <span class="n">is_used</span><span class="p">;</span> <span class="c1">// is the parameter used in the patch?
+ <span class="kt">float</span> <span class="n">increment</span><span class="p">;</span> <span class="c1">// for param ramp
</span><span class="p">};</span>
-<span class="k">struct</span> <span class="n">clap_event_control</span>
+<span class="cm">/** Note On/Off event. */</span>
+<span class="k">struct</span> <span class="n">clap_event_note</span>
<span class="p">{</span>
- <span class="cm">/* voice/key index */</span>
- <span class="kt">bool</span> <span class="n">is_global</span><span class="p">;</span> <span class="c1">// is this event global?
-</span> <span class="kt">uint8_t</span> <span class="n">key</span><span class="p">;</span> <span class="c1">// if !is_global, target key
-</span>
- <span class="cm">/* control */</span>
- <span class="kt">uint32_t</span> <span class="n">index</span><span class="p">;</span>
- <span class="kt">float</span> <span class="n">value</span><span class="p">;</span> <span class="c1">// 0 .. 1.0f
+ <span class="kt">int8_t</span> <span class="n">key</span><span class="p">;</span> <span class="c1">// 0..127
+</span> <span class="kt">int8_t</span> <span class="n">channel</span><span class="p">;</span> <span class="c1">// 0..15
+</span> <span class="kt">float</span> <span class="n">pitch</span><span class="p">;</span> <span class="c1">// hertz
+</span> <span class="kt">float</span> <span class="n">velocity</span><span class="p">;</span> <span class="c1">// 0..1
</span><span class="p">};</span>
-<span class="k">struct</span> <span class="n">clap_event_preset</span>
+<span class="k">struct</span> <span class="n">clap_event_control</span>
<span class="p">{</span>
- <span class="kt">char</span> <span class="n">url</span><span class="p">[</span><span class="n">CLAP_URL_SIZE</span><span class="p">];</span> <span class="c1">// the url to the preset
+ <span class="kt">int8_t</span> <span class="n">key</span><span class="p">;</span> <span class="c1">// 0..127
+</span> <span class="kt">int8_t</span> <span class="n">channel</span><span class="p">;</span> <span class="c1">// 0..15
+</span> <span class="kt">int8_t</span> <span class="n">control</span><span class="p">;</span> <span class="c1">// 0..127
+</span> <span class="kt">float</span> <span class="n">value</span><span class="p">;</span> <span class="c1">// 0..1
</span><span class="p">};</span>
<span class="k">struct</span> <span class="n">clap_event_midi</span>
<span class="p">{</span>
- <span class="cm">/* voice/key index */</span>
- <span class="kt">bool</span> <span class="n">is_global</span><span class="p">;</span> <span class="c1">// is this event global?
-</span> <span class="kt">uint8_t</span> <span class="n">key</span><span class="p">;</span> <span class="c1">// if !is_global, target key
-</span>
<span class="cm">/* midi event */</span>
<span class="k">const</span> <span class="kt">uint8_t</span> <span class="o">*</span><span class="n">buffer</span><span class="p">;</span>
- <span class="kt">uint32_t</span> <span class="n">size</span><span class="p">;</span>
+ <span class="kt">int32_t</span> <span class="n">size</span><span class="p">;</span>
<span class="p">};</span>
-<span class="k">struct</span> <span class="n">clap_event_latency</span>
+<span class="k">struct</span> <span class="n">clap_event_jump</span>
<span class="p">{</span>
- <span class="kt">uint32_t</span> <span class="n">latency</span><span class="p">;</span>
-<span class="p">};</span>
+ <span class="kt">int32_t</span> <span class="n">tempo</span><span class="p">;</span> <span class="c1">// tempo in samples
+</span> <span class="kt">int32_t</span> <span class="n">bar</span><span class="p">;</span> <span class="c1">// the bar number
+</span> <span class="kt">int32_t</span> <span class="n">bar_offset</span><span class="p">;</span> <span class="c1">// 0 <= bar_offset < tsig_denom * tempo
+</span> <span class="kt">int64_t</span> <span class="n">song_time</span><span class="p">;</span> <span class="c1">// song time in micro seconds
+</span> <span class="kt">int32_t</span> <span class="n">tsig_num</span><span class="p">;</span> <span class="c1">// time signature numerator
+</span> <span class="kt">int32_t</span> <span class="n">tsig_denom</span><span class="p">;</span> <span class="c1">// time signature denominator
+</span><span class="p">};</span>
-<span class="k">struct</span> <span class="n">clap_event_jump</span>
+<span class="cm">/**
+ * Asks the plugin to load a program.
+ * This is analogue to the midi program set:
+ * bank msb goes into bank0
+ * bank lsb goes into bank1
+ * program goes into program
+ *
+ * Clap is not limited to 127.
+ *
+ * The main advantage of setting a program instead of loading
+ * a preset, is that the program should already be in the plugin's
+ * memory, and can be set instantly. If the plugin has to load
+ * a preset from the filesystem, then parse it, do memory allocation,
+ * there is no guarentee that the preset will be loaded in time.
+ */</span>
+<span class="k">struct</span> <span class="n">clap_event_program</span>
<span class="p">{</span>
- <span class="kt">uint32_t</span> <span class="n">tempo</span><span class="p">;</span> <span class="c1">// tempo in samples
-</span> <span class="kt">uint32_t</span> <span class="n">bar</span><span class="p">;</span> <span class="c1">// the bar number
-</span> <span class="kt">uint32_t</span> <span class="n">bar_offset</span><span class="p">;</span> <span class="c1">// 0 <= cycle_offset < tsig_denom * tempo
-</span> <span class="kt">uint32_t</span> <span class="n">tsig_num</span><span class="p">;</span> <span class="c1">// time signature numerator
-</span> <span class="kt">uint32_t</span> <span class="n">tsig_denom</span><span class="p">;</span> <span class="c1">// time signature denominator
+ <span class="kt">int32_t</span> <span class="n">bank0</span><span class="p">;</span> <span class="c1">// 0..0x7FFFFFFF
+</span> <span class="kt">int32_t</span> <span class="n">bank1</span><span class="p">;</span> <span class="c1">// 0..0x7FFFFFFF
+</span> <span class="kt">int32_t</span> <span class="n">program</span><span class="p">;</span> <span class="c1">// 0..0x7FFFFFFF
</span><span class="p">};</span>
<span class="k">struct</span> <span class="n">clap_event</span>
<span class="p">{</span>
<span class="k">struct</span> <span class="n">clap_event</span> <span class="o">*</span><span class="n">next</span><span class="p">;</span> <span class="c1">// linked list, NULL on end
</span> <span class="k">enum</span> <span class="n">clap_event_type</span> <span class="n">type</span><span class="p">;</span>
- <span class="kt">uint64_t</span> <span class="n">steady_time</span><span class="p">;</span> <span class="c1">// steady_time of the event, see host->steady_time(host)
+ <span class="kt">int64_t</span> <span class="n">time</span><span class="p">;</span> <span class="c1">// offset from the first sample in the process block
</span>
<span class="k">union</span> <span class="p">{</span>
<span class="k">struct</span> <span class="n">clap_event_note</span> <span class="n">note</span><span class="p">;</span>
+ <span class="k">struct</span> <span class="n">clap_event_control</span> <span class="n">control</span><span class="p">;</span>
<span class="k">struct</span> <span class="n">clap_event_param</span> <span class="n">param</span><span class="p">;</span>
- <span class="k">struct</span> <span class="n">clap_event_preset</span> <span class="n">preset</span><span class="p">;</span>
<span class="k">struct</span> <span class="n">clap_event_midi</span> <span class="n">midi</span><span class="p">;</span>
- <span class="k">struct</span> <span class="n">clap_event_control</span> <span class="n">control</span><span class="p">;</span>
- <span class="k">struct</span> <span class="n">clap_event_latency</span> <span class="n">latency</span><span class="p">;</span>
<span class="k">struct</span> <span class="n">clap_event_jump</span> <span class="n">jump</span><span class="p">;</span>
<span class="p">};</span>
<span class="p">};</span>
@@ -1404,20 +1240,19 @@ plugin's parameters and restore them.</p>
<span class="n">CLAP_PROCESS_CONTINUE</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
<span class="cm">/* Processing succeed, but no more processing is required, until next event. */</span>
- <span class="n">CLAP_PROCESS_STOP</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
+ <span class="n">CLAP_PROCESS_SLEEP</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
<span class="p">};</span>
<span class="k">struct</span> <span class="n">clap_process</span>
<span class="p">{</span>
- <span class="cm">/* audio buffers */</span>
- <span class="kt">float</span> <span class="o">**</span><span class="n">inputs</span><span class="p">;</span>
- <span class="kt">float</span> <span class="o">**</span><span class="n">outputs</span><span class="p">;</span>
- <span class="kt">uint32_t</span> <span class="n">samples_count</span><span class="p">;</span>
+ <span class="cm">/* number of frame to process */</span>
+ <span class="kt">int32_t</span> <span class="n">frames_count</span><span class="p">;</span>
<span class="cm">/* process info */</span>
- <span class="kt">uint64_t</span> <span class="n">steady_time</span><span class="p">;</span> <span class="c1">// the steady time in samples
+ <span class="kt">int64_t</span> <span class="n">steady_time</span><span class="p">;</span> <span class="c1">// the steady time in samples
</span>
- <span class="cm">/* events */</span>
+ <span class="cm">/* Linked list of events
+ * The plugin must not modify those events. */</span>
<span class="k">struct</span> <span class="n">clap_event</span> <span class="o">*</span><span class="n">events</span><span class="p">;</span>
<span class="p">};</span>
@@ -1427,23 +1262,15 @@ plugin's parameters and restore them.</p>
</span>
<span class="k">struct</span> <span class="n">clap_host</span>
<span class="p">{</span>
- <span class="kt">uint32_t</span> <span class="n">clap_version</span><span class="p">;</span> <span class="c1">// initialized to CLAP_VERSION
+ <span class="kt">int32_t</span> <span class="n">clap_version</span><span class="p">;</span> <span class="c1">// initialized to CLAP_VERSION
+</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">host_data</span><span class="p">;</span> <span class="c1">// reserved pointer for the host
</span>
<span class="cm">/* returns the size of the original string, 0 if not string */</span>
- <span class="kt">uint32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">get_attribute</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>
- <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">attr</span><span class="p">,</span>
- <span class="kt">char</span> <span class="o">*</span><span class="n">buffer</span><span class="p">,</span>
- <span class="kt">uint32_t</span> <span class="n">size</span><span class="p">);</span>
-
- <span class="cm">/* for events generated by the plugin. */</span>
- <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">events</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>
- <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">struct</span> <span class="n">clap_event</span> <span class="o">*</span><span class="n">events</span><span class="p">);</span>
-
- <span class="cm">/* The time in samples, this clock is monotonicaly increasing,
- * it means that each time you read the value, it must be greater
- * or equal to the previous one. */</span>
- <span class="k">const</span> <span class="kt">uint64_t</span> <span class="o">*</span><span class="n">steady_time</span><span class="p">;</span>
+ <span class="kt">int32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">get_attribute</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>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">attr</span><span class="p">,</span>
+ <span class="kt">char</span> <span class="o">*</span><span class="n">buffer</span><span class="p">,</span>
+ <span class="kt">int32_t</span> <span class="n">size</span><span class="p">);</span>
<span class="cm">/* Log a message through the host. */</span>
<span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">log</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>
@@ -1451,7 +1278,7 @@ plugin's parameters and restore them.</p>
<span class="k">enum</span> <span class="n">clap_log_severity</span> <span class="n">severity</span><span class="p">,</span>
<span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">msg</span><span class="p">);</span>
- <span class="cm">/* feature extensions */</span>
+ <span class="cm">/* query an extension */</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_host</span> <span class="o">*</span><span class="n">host</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="p">};</span>
@@ -1463,14 +1290,16 @@ plugin's parameters and restore them.</p>
</span><span class="k">enum</span> <span class="n">clap_plugin_type</span>
<span class="p">{</span>
<span class="n">CLAP_PLUGIN_INSTRUMENT</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">0</span><span class="p">),</span>
- <span class="n">CLAP_PLUGIN_EFFECT</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">1</span><span class="p">),</span>
+ <span class="n">CLAP_PLUGIN_AUDIO_EFFECT</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">1</span><span class="p">),</span>
<span class="n">CLAP_PLUGIN_EVENT_EFFECT</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">2</span><span class="p">),</span> <span class="c1">// can be seen as midi effect
</span> <span class="n">CLAP_PLUGIN_ANALYZER</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">3</span><span class="p">),</span>
+ <span class="n">CLAP_PLUGIN_PATCHER</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">4</span><span class="p">),</span>
+ <span class="n">CLAP_PLUGIN_STREAMER</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o"><<</span> <span class="mi">5</span><span class="p">),</span>
<span class="p">};</span>
<span class="k">struct</span> <span class="n">clap_plugin</span>
<span class="p">{</span>
- <span class="kt">uint32_t</span> <span class="n">clap_version</span><span class="p">;</span> <span class="c1">// initialized to CALP_VERSION
+ <span class="kt">int32_t</span> <span class="n">clap_version</span><span class="p">;</span> <span class="c1">// initialized to CLAP_VERSION
</span>
<span class="kt">void</span> <span class="o">*</span><span class="n">host_data</span><span class="p">;</span> <span class="c1">// reserved pointer for the host
</span> <span class="kt">void</span> <span class="o">*</span><span class="n">plugin_data</span><span class="p">;</span> <span class="c1">// reserved pointer for the plugin
@@ -1483,40 +1312,43 @@ plugin's parameters and restore them.</p>
* This function must place a '\0' byte at the end of the string.
* Returns the size of the original string or 0 if there is no
* value for this attributes. */</span>
- <span class="kt">uint32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">get_attribute</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">attr</span><span class="p">,</span>
- <span class="kt">char</span> <span class="o">*</span><span class="n">buffer</span><span class="p">,</span>
- <span class="kt">uint32_t</span> <span class="n">size</span><span class="p">);</span>
+ <span class="kt">int32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">get_attribute</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">attr</span><span class="p">,</span>
+ <span class="kt">char</span> <span class="o">*</span><span class="n">buffer</span><span class="p">,</span>
+ <span class="kt">int32_t</span> <span class="n">size</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>
<span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">deactivate</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">/* process */</span>
+ <span class="cm">/* process audio, events, ... */</span>
<span class="k">enum</span> <span class="nf">clap_process_status</span> <span class="p">(</span><span class="o">*</span><span class="n">process</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">struct</span> <span class="n">clap_process</span> <span class="o">*</span><span class="n">process</span><span class="p">);</span>
- <span class="cm">/* features extensions */</span>
+ <span class="cm">/* query an extension */</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>
-<span class="k">typedef</span> <span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="p">(</span><span class="o">*</span><span class="n">clap_create_f</span><span class="p">)(</span><span class="kt">uint32_t</span> <span class="n">plugin_index</span><span class="p">,</span>
+<span class="k">typedef</span> <span class="k">struct</span> <span class="n">clap_plugin</span> <span class="o">*</span><span class="p">(</span><span class="o">*</span><span class="n">clap_create_f</span><span class="p">)(</span><span class="kt">int32_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>
- <span class="kt">uint32_t</span> <span class="n">sample_rate</span><span class="p">,</span>
- <span class="kt">uint32_t</span> <span class="o">*</span><span class="n">plugins_count</span><span class="p">);</span>
+ <span class="kt">int32_t</span> <span class="n">sample_rate</span><span class="p">,</span>
+ <span class="kt">int32_t</span> <span class="o">*</span><span class="n">plugins_count</span><span class="p">);</span>
<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).
*
+ * Common sample rate values are: 44100, 48000, 88200, 96000,
+ * 176400, 192000.
+ *
* This function must be thread-safe. */</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="n">CLAP_EXPORT</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">int32_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>
- <span class="kt">uint32_t</span> <span class="n">sample_rate</span><span class="p">,</span>
- <span class="kt">uint32_t</span> <span class="o">*</span><span class="n">plugins_count</span><span class="p">);</span>
+ <span class="kt">int32_t</span> <span class="n">sample_rate</span><span class="p">,</span>
+ <span class="kt">int32_t</span> <span class="o">*</span><span class="n">plugins_count</span><span class="p">);</span>
<span class="cp"># ifdef __cplusplus
</span><span class="p">}</span>
@@ -1525,117 +1357,134 @@ plugin's parameters and restore them.</p>
<span class="cp">#endif </span><span class="cm">/* !CLAP_H */</span>
</pre>
</div>
-<div class="section" id="clap-ext-ports-h">
-<h2><a class="toc-backref" href="#id51">clap/ext/ports.h</a></h2>
+<div class="section" id="clap-ext-state-h">
+<h2><a class="toc-backref" href="#id48">clap/ext/state.h</a></h2>
<pre class="code c literal-block">
-<span class="cp">#ifndef CLAP_EXT_PORTS_H
-# define CLAP_EXT_PORTS_H
+<span class="cp">#ifndef CLAP_EXT_STATE_H
+# define CLAP_EXT_STATE_H
</span>
<span class="cp"># include "../clap.h"
</span>
-<span class="cp"># define CLAP_EXT_PORTS "clap/ports"
+<span class="cp"># define CLAP_EXT_STATE "clap/state"
</span>
-<span class="k">enum</span> <span class="n">clap_port_type</span>
+<span class="k">struct</span> <span class="n">clap_plugin_state</span>
<span class="p">{</span>
- <span class="n">CLAP_PORT_MONO</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
- <span class="n">CLAP_PORT_STEREO</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
- <span class="n">CLAP_PORT_SURROUND</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
+ <span class="cm">/* The plugin has to allocate and save its state into *buffer.
+ * 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">int32_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">int32_t</span> <span class="n">size</span><span class="p">);</span>
<span class="p">};</span>
-<span class="k">enum</span> <span class="n">clap_port_role</span>
+<span class="cp">#endif </span><span class="cm">/* !CLAP_EXT_STATE_H */</span>
+</pre>
+</div>
+<div class="section" id="clap-ext-ports-h">
+<h2><a class="toc-backref" href="#id49">clap/ext/ports.h</a></h2>
+<pre class="code c literal-block">
+<span class="cp">#ifndef CLAP_EXT_AUDIO_PORTS_H
+# define CLAP_EXT_AUDIO_PORTS_H
+</span>
+<span class="cp"># include "../clap.h"
+</span>
+<span class="cp"># define CLAP_EXT_AUDIO_PORTS "clap/audio-ports"
+</span>
+<span class="k">enum</span> <span class="n">clap_audio_port_channel_mapping</span>
<span class="p">{</span>
- <span class="n">CLAP_PORT_INOUT</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
- <span class="n">CLAP_PORT_SIDECHAIN</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
+ <span class="n">CLAP_AUDIO_PORT_UNSPECIFIED</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
+ <span class="n">CLAP_AUDIO_PORT_MONO</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
+
+ <span class="c1">// left, right
+</span> <span class="n">CLAP_AUDIO_PORT_STEREO</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
+
+ <span class="c1">// front left, front right, center, low, surround left, surround right
+</span> <span class="c1">// surround back left, surround back right
+</span> <span class="n">CLAP_AUDIO_PORT_SURROUND</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span>
<span class="p">};</span>
-<span class="k">struct</span> <span class="n">clap_port_info</span>
+<span class="k">enum</span> <span class="n">clap_audio_port_role</span>
<span class="p">{</span>
- <span class="k">enum</span> <span class="n">clap_port_type</span> <span class="n">type</span><span class="p">;</span>
- <span class="k">enum</span> <span class="n">clap_port_role</span> <span class="n">role</span><span class="p">;</span>
- <span class="kt">char</span> <span class="n">name</span><span class="p">[</span><span class="n">CLAP_NAME_SIZE</span><span class="p">];</span>
- <span class="kt">bool</span> <span class="n">is_repeatable</span><span class="p">;</span>
+ <span class="n">CLAP_AUDIO_PORT_INOUT</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
+ <span class="n">CLAP_AUDIO_PORT_SIDECHAIN</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
+ <span class="n">CLAP_AUDIO_PORT_MODULATION</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
<span class="p">};</span>
-<span class="k">struct</span> <span class="n">clap_ports_config</span>
+<span class="k">struct</span> <span class="n">clap_audio_port_info</span>
<span class="p">{</span>
- <span class="kt">char</span> <span class="n">name</span><span class="p">[</span><span class="n">CLAP_NAME_SIZE</span><span class="p">];</span>
- <span class="kt">uint32_t</span> <span class="n">inputs_count</span><span class="p">;</span>
- <span class="kt">uint32_t</span> <span class="n">outputs_count</span><span class="p">;</span>
+ <span class="kt">int32_t</span> <span class="n">id</span><span class="p">;</span>
+ <span class="kt">bool</span> <span class="n">is_input</span><span class="p">;</span>
+ <span class="kt">int32_t</span> <span class="n">channel_count</span><span class="p">;</span>
+ <span class="k">enum</span> <span class="n">clap_audio_port_channel_mapping</span> <span class="n">channel_mapping</span><span class="p">;</span>
+ <span class="k">enum</span> <span class="n">clap_audio_port_role</span> <span class="n">role</span><span class="p">;</span>
+ <span class="kt">char</span> <span class="n">name</span><span class="p">[</span><span class="n">CLAP_NAME_SIZE</span><span class="p">];</span>
+
+ <span class="cm">/* If false, then the port can be connected only once.
+ * If true, then this is a virtual port which can be cloned
+ * and connected multiple times. */</span>
+ <span class="kt">bool</span> <span class="n">is_repeatable</span><span class="p">;</span>
<span class="p">};</span>
-<span class="cm">/* The audio ports configuration has to be done while the plugin is
- * deactivated. */</span>
-<span class="k">struct</span> <span class="n">clap_plugin_ports</span>
+<span class="k">struct</span> <span class="n">clap_audio_port</span>
<span class="p">{</span>
- <span class="cm">/* Returns the number of available configurations */</span>
- <span class="kt">uint32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">get_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_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>
- <span class="k">struct</span> <span class="n">clap_ports_config</span> <span class="o">*</span><span class="n">config</span><span class="p">);</span>
- <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">get_info</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>
- <span class="kt">uint32_t</span> <span class="n">port_index</span><span class="p">,</span>
- <span class="k">struct</span> <span class="n">clap_port_info</span> <span class="o">*</span><span class="n">port</span><span class="p">);</span>
- <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">set_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>
- <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">set_repeat</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">port_index</span><span class="p">,</span>
- <span class="kt">uint32_t</span> <span class="n">count</span><span class="p">);</span>
+ <span class="kt">int32_t</span> <span class="n">channel_count</span><span class="p">;</span>
+ <span class="k">enum</span> <span class="n">clap_audio_port_channel_mapping</span> <span class="n">channel_mapping</span><span class="p">;</span>
+ <span class="kt">float</span> <span class="o">**</span><span class="n">data</span><span class="p">;</span>
<span class="p">};</span>
-<span class="cp">#endif </span><span class="cm">/* !CLAP_EXT_PORT_H */</span>
-</pre>
-</div>
-<div class="section" id="clap-ext-gui-h">
-<h2><a class="toc-backref" href="#id52">clap/ext/gui.h</a></h2>
-<pre class="code c literal-block">
-<span class="cp">#ifndef CLAP_EXT_GUI_H
-# define CLAP_EXT_GUI_H
-</span>
-<span class="cp"># include "../clap.h"
-</span>
-<span class="cp"># define CLAP_EXT_GUI "clap/gui"
-</span>
-<span class="k">struct</span> <span class="n">clap_plugin_gui</span>
+<span class="cm">/* The audio ports configuration has to be done while the plugin is
+ * deactivated. */</span>
+<span class="k">struct</span> <span class="n">clap_plugin_audio_ports</span>
<span class="p">{</span>
- <span class="cm">/* gui */</span>
- <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">open</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="p">(</span><span class="o">*</span><span class="n">close</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">/* number of ports, including inputs and outputs */</span>
+ <span class="kt">int32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">get_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">void</span> <span class="p">(</span><span class="o">*</span><span class="n">get_info</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">int32_t</span> <span class="n">index</span><span class="p">,</span>
+ <span class="k">struct</span> <span class="n">clap_audio_port_info</span> <span class="o">*</span><span class="n">info</span><span class="p">);</span>
+
+ <span class="cm">/* Connect the given port to the plugin's port at index.
+ * user_name is the name of the peer port given by the host/user.
+ * It can be useful especialy for repeatable ports.
+ * Returns the id of the port. In case of repeatable port,
+ * make sure that each connected port has a different id.
+ * Returns -1 if the connection failed. */</span>
+ <span class="kt">int32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">connect</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">int32_t</span> <span class="n">port_id</span><span class="p">,</span>
+ <span class="k">const</span> <span class="k">struct</span> <span class="n">clap_audio_port</span> <span class="o">*</span><span class="n">port</span><span class="p">,</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">user_name</span><span class="p">);</span>
+
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">disconnect</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">int32_t</span> <span class="n">port_id</span><span class="p">);</span>
+
+ <span class="cm">/* Returns the absolute port latency in samples. */</span>
+ <span class="kt">int32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">get_latency</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">int32_t</span> <span class="n">port_id</span><span class="p">);</span>
<span class="p">};</span>
-<span class="cp">#endif </span><span class="cm">/* !CLAP_EXT_GUI_H */</span>
-</pre>
-</div>
-<div class="section" id="clap-ext-state-h">
-<h2><a class="toc-backref" href="#id53">clap/ext/state.h</a></h2>
-<pre class="code c literal-block">
-<span class="cp">#ifndef CLAP_EXT_STATE_H
-# define CLAP_EXT_STATE_H
-</span>
-<span class="cp"># include "../clap.h"
-</span>
-<span class="cp"># define CLAP_EXT_STATE "clap/state"
-</span>
-<span class="k">struct</span> <span class="n">clap_plugin_state</span>
+<span class="k">struct</span> <span class="n">clap_host_audio_ports</span>
<span class="p">{</span>
- <span class="cm">/* The plugin has to allocate and save its state into *buffer.
- * 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">uint32_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">uint32_t</span> <span class="n">size</span><span class="p">);</span>
+ <span class="cm">/* Tell the host that the plugin ports has changed.
+ * The host shall scan the ports again. */</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">changed</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>
+ <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">/* Tell the host that the latency changed. The host should
+ * call get_port_latency on each ports. */</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">latency_changed</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>
+ <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="p">};</span>
-<span class="cp">#endif </span><span class="cm">/* !CLAP_EXT_STATE_H */</span>
+<span class="cp">#endif </span><span class="cm">/* !CLAP_EXT_PORT_H */</span>
</pre>
</div>
<div class="section" id="clap-ext-params-h">
-<h2><a class="toc-backref" href="#id54">clap/ext/params.h</a></h2>
+<h2><a class="toc-backref" href="#id50">clap/ext/params.h</a></h2>
<pre class="code c literal-block">
<span class="cp">#ifndef CLAP_EXT_PARAMS_H
# define CLAP_EXT_PARAMS_H
</span>
<span class="cp"># include "../clap.h"
-# include "../serialize/serialize.h"
+# include "ports.h"
</span>
<span class="cp">#ifdef __cplusplus
</span><span class="k">extern</span> <span class="s">"C"</span> <span class="p">{</span>
@@ -1645,78 +1494,111 @@ plugin's parameters and restore them.</p>
</span>
<span class="k">enum</span> <span class="n">clap_param_type</span>
<span class="p">{</span>
- <span class="n">CLAP_PARAM_GROUP</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="c1">// no value for this one
+ <span class="n">CLAP_PARAM_FLOAT</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="c1">// uses value.f
</span> <span class="n">CLAP_PARAM_BOOL</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="c1">// uses value.b
-</span> <span class="n">CLAP_PARAM_FLOAT</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span> <span class="c1">// uses value.f
-</span> <span class="n">CLAP_PARAM_INT</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span> <span class="c1">// uses value.i
-</span> <span class="n">CLAP_PARAM_ENUM</span> <span class="o">=</span> <span class="mi">4</span><span class="p">,</span> <span class="c1">// uses value.i
+</span> <span class="n">CLAP_PARAM_INT</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span> <span class="c1">// uses value.i
+</span> <span class="n">CLAP_PARAM_ENUM</span> <span class="o">=</span> <span class="mi">3</span><span class="p">,</span> <span class="c1">// uses value.i
</span><span class="p">};</span>
<span class="k">enum</span> <span class="n">clap_param_scale</span>
<span class="p">{</span>
- <span class="n">CLAP_PARAM_LINEAR</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
- <span class="n">CLAP_PARAM_LOG</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
+ <span class="n">CLAP_PARAM_SCALE_LINEAR</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
+ <span class="n">CLAP_PARAM_SCALE_LOG</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
+ <span class="n">CLAP_PARAM_SCALE_EXP</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span>
<span class="p">};</span>
+<span class="cm">/* This describes the parameter and provides the current value */</span>
<span class="k">struct</span> <span class="n">clap_param</span>
<span class="p">{</span>
- <span class="cm">/* tree fields */</span>
- <span class="kt">uint32_t</span> <span class="n">index</span><span class="p">;</span> <span class="c1">// parameter's index
-</span> <span class="kt">uint32_t</span> <span class="n">parent</span><span class="p">;</span> <span class="c1">// parent's index, -1 for no parent
+ <span class="kt">int32_t</span> <span class="n">index</span><span class="p">;</span> <span class="c1">// parameter's index
</span>
<span class="cm">/* param info */</span>
+ <span class="kt">char</span> <span class="n">module_id</span><span class="p">[</span><span class="n">CLAP_ID_SIZE</span><span class="p">];</span>
<span class="kt">char</span> <span class="n">id</span><span class="p">[</span><span class="n">CLAP_ID_SIZE</span><span class="p">];</span> <span class="c1">// a string which identify the param
</span> <span class="kt">char</span> <span class="n">name</span><span class="p">[</span><span class="n">CLAP_NAME_SIZE</span><span class="p">];</span> <span class="c1">// the display name
</span> <span class="kt">char</span> <span class="n">desc</span><span class="p">[</span><span class="n">CLAP_DESC_SIZE</span><span class="p">];</span>
<span class="kt">char</span> <span class="n">display</span><span class="p">[</span><span class="n">CLAP_DISPLAY_SIZE</span><span class="p">];</span> <span class="c1">// the text used to display the value
-</span> <span class="k">enum</span> <span class="n">clap_param_type</span> <span class="n">type</span><span class="p">;</span>
- <span class="kt">bool</span> <span class="n">is_per_note</span><span class="p">;</span>
- <span class="kt">bool</span> <span class="n">is_used</span><span class="p">;</span> <span class="c1">// is this parameter used by the patch?
-</span> <span class="kt">bool</span> <span class="n">is_periodic</span><span class="p">;</span>
- <span class="kt">bool</span> <span class="n">is_locked</span><span class="p">;</span> <span class="c1">// if true, the parameter can't be changed by
+</span> <span class="kt">bool</span> <span class="n">is_per_note</span><span class="p">;</span>
+ <span class="kt">bool</span> <span class="n">is_per_channel</span><span class="p">;</span>
+ <span class="kt">bool</span> <span class="n">is_used</span><span class="p">;</span> <span class="c1">// is this parameter used by the patch?
+</span> <span class="kt">bool</span> <span class="n">is_periodic</span><span class="p">;</span> <span class="c1">// after the last value, go back to the first one
+</span> <span class="kt">bool</span> <span class="n">is_locked</span><span class="p">;</span> <span class="c1">// if true, the parameter can't be changed by
</span> <span class="c1">// the host
-</span> <span class="k">union</span> <span class="n">clap_param_value</span> <span class="n">value</span><span class="p">;</span>
- <span class="k">union</span> <span class="n">clap_param_value</span> <span class="n">min</span><span class="p">;</span>
- <span class="k">union</span> <span class="n">clap_param_value</span> <span class="n">max</span><span class="p">;</span>
- <span class="k">union</span> <span class="n">clap_param_value</span> <span class="n">deflt</span><span class="p">;</span> <span class="c1">// default value
-</span> <span class="k">enum</span> <span class="n">clap_param_scale</span> <span class="n">scale</span><span class="p">;</span>
+</span>
+ <span class="cm">/* Can the parameter be automated at sample rate by an audio buffer? */</span>
+ <span class="kt">bool</span> <span class="n">supports_audio_automation</span><span class="p">;</span>
+
+ <span class="cm">/* Can the parameter be automated by automation events? */</span>
+ <span class="kt">bool</span> <span class="n">supports_events_automation</span><span class="p">;</span>
+ <span class="kt">bool</span> <span class="n">supports_ramp_events</span><span class="p">;</span>
+
+ <span class="cm">/* value */</span>
+ <span class="k">enum</span> <span class="n">clap_param_type</span> <span class="n">type</span><span class="p">;</span>
+ <span class="k">union</span> <span class="n">clap_param_value</span> <span class="n">value</span><span class="p">;</span> <span class="c1">// current value
+</span> <span class="k">union</span> <span class="n">clap_param_value</span> <span class="n">min</span><span class="p">;</span> <span class="c1">// minimum value
+</span> <span class="k">union</span> <span class="n">clap_param_value</span> <span class="n">max</span><span class="p">;</span> <span class="c1">// maximum value
+</span> <span class="k">union</span> <span class="n">clap_param_value</span> <span class="n">deflt</span><span class="p">;</span> <span class="c1">// default value
+</span> <span class="k">enum</span> <span class="n">clap_param_scale</span> <span class="n">scale</span><span class="p">;</span> <span class="c1">// scaling of the knob in the UI.
+</span><span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">clap_param_module</span>
+<span class="p">{</span>
+ <span class="kt">char</span> <span class="n">id</span><span class="p">[</span><span class="n">CLAP_ID_SIZE</span><span class="p">];</span>
+ <span class="kt">char</span> <span class="n">parent_id</span><span class="p">[</span><span class="n">CLAP_ID_SIZE</span><span class="p">];</span>
+ <span class="kt">char</span> <span class="n">name</span><span class="p">[</span><span class="n">CLAP_NAME_SIZE</span><span class="p">];</span>
+ <span class="kt">char</span> <span class="n">desc</span><span class="p">[</span><span class="n">CLAP_DESC_SIZE</span><span class="p">];</span>
<span class="p">};</span>
<span class="k">struct</span> <span class="n">clap_plugin_params</span>
<span class="p">{</span>
<span class="cm">/* Returns the number of parameters. */</span>
- <span class="kt">uint32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">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">int32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">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="cm">/* Copies the parameter's info to param and returns true.
* If index is greater or equal to the number then return false. */</span>
- <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">get</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">int32_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">/* Copies the module's info to module and returns true.
+ * If module_id is NULL or invalid then return false. */</span>
+ <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">get_module</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">module_id</span><span class="p">,</span>
+ <span class="k">struct</span> <span class="n">clap_param_module</span> <span class="o">*</span><span class="n">module</span><span class="p">);</span>
+
+ <span class="cm">/* Use an audio buffer to automate a parameter at sample rate.
+ * Once a parameter is automated by an audio buffer, concurrent
+ * automation event shall be ignored in favor of the audio rate
+ * automation.
+ *
+ * To disconnect the automation, set buffer to NULL. */</span>
+ <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">set_param_buffer</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">int32_t</span> <span class="n">param_index</span><span class="p">,</span>
+ <span class="kt">int32_t</span> <span class="n">channel</span><span class="p">,</span>
+ <span class="kt">int32_t</span> <span class="n">note</span><span class="p">,</span>
+ <span class="k">struct</span> <span class="n">clap_audio_port</span> <span class="o">*</span><span class="n">port</span><span class="p">);</span>
<span class="p">};</span>
-<span class="cm">/* Helper that will serialize the plugin's parameters value into the buffer.
- * (*size) must be set to the size of the buffer.
- * At return, (*size) contains the number of bytes used and returns true on
- * success, the only possible error is that the buffer is too small.
- */</span>
-<span class="k">static</span> <span class="kr">inline</span> <span class="kt">bool</span>
-<span class="nf">clap_plugin_params_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">uint8_t</span> <span class="o">*</span><span class="n">buffer</span><span class="p">,</span>
- <span class="kt">uint32_t</span> <span class="o">*</span><span class="n">size</span><span class="p">);</span>
-
-<span class="cm">/* Helper that will deserialize parameters value from the buffer
- * and send CLAP_EVENT_PARAM_SET to the plugin to restore them.
- * The steady_time is required because the plugin can discard
- * events from the past.
- */</span>
-<span class="k">static</span> <span class="kr">inline</span> <span class="kt">void</span>
-<span class="nf">clap_plugin_params_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">uint8_t</span> <span class="o">*</span><span class="n">buffer</span><span class="p">,</span>
- <span class="kt">uint32_t</span> <span class="n">size</span><span class="p">,</span>
- <span class="kt">uint64_t</span> <span class="n">steady_time</span><span class="p">);</span>
+<span class="k">struct</span> <span class="n">clap_host_params</span>
+<span class="p">{</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">touch_begin</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>
+ <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">int32_t</span> <span class="n">index</span><span class="p">);</span>
+
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">touch_end</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>
+ <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">int32_t</span> <span class="n">index</span><span class="p">);</span>
+
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">changed</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>
+ <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">int32_t</span> <span class="n">index</span><span class="p">,</span>
+ <span class="k">union</span> <span class="n">clap_param_value</span> <span class="n">value</span><span class="p">,</span>
+ <span class="kt">bool</span> <span class="n">is_recordable</span><span class="p">);</span>
+
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">rescan</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>
+ <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="p">};</span>
-<span class="cp"># include "params.c"
-</span>
<span class="cp">#ifdef __cplusplus
</span><span class="p">}</span>
<span class="cp">#endif
@@ -1724,72 +1606,41 @@ plugin's parameters and restore them.</p>
<span class="cp">#endif </span><span class="cm">/* !CLAP_EXT_PARAMS_H */</span>
</pre>
</div>
-<div class="section" id="clap-ext-presets-h">
-<h2><a class="toc-backref" href="#id55">clap/ext/presets.h</a></h2>
+<div class="section" id="clap-ext-gui-h">
+<h2><a class="toc-backref" href="#id51">clap/ext/gui.h</a></h2>
<pre class="code c literal-block">
-<span class="cp">#ifndef CLAP_EXT_PRESETS_H
-# define CLAP_EXT_PRESETS_H
+<span class="cp">#ifndef CLAP_EXT_GUI_H
+# define CLAP_EXT_GUI_H
</span>
<span class="cp"># include "../clap.h"
</span>
-<span class="cp"># define CLAP_EXT_PRESETS "clap/presets"
+<span class="cp"># define CLAP_EXT_GUI "clap/gui"
</span>
-<span class="k">struct</span> <span class="n">clap_preset</span>
+<span class="k">struct</span> <span class="n">clap_plugin_gui</span>
<span class="p">{</span>
- <span class="kt">char</span> <span class="n">url</span><span class="p">[</span><span class="n">CLAP_URL_SIZE</span><span class="p">];</span> <span class="c1">// location to the patch
-</span> <span class="kt">char</span> <span class="n">name</span><span class="p">[</span><span class="n">CLAP_NAME_SIZE</span><span class="p">];</span> <span class="c1">// display name
-</span> <span class="kt">char</span> <span class="n">desc</span><span class="p">[</span><span class="n">CLAP_DESC_SIZE</span><span class="p">];</span> <span class="c1">// desc and how to use it
-</span> <span class="kt">char</span> <span class="n">author</span><span class="p">[</span><span class="n">CLAP_NAME_SIZE</span><span class="p">];</span>
- <span class="kt">char</span> <span class="n">tags</span><span class="p">[</span><span class="n">CLAP_TAGS_SIZE</span><span class="p">];</span> <span class="c1">// "tag1;tag2;tag3;..."
-</span> <span class="kt">uint8_t</span> <span class="n">score</span><span class="p">;</span> <span class="c1">// 0 = garbage, ..., 4 = favorite
-</span><span class="p">};</span>
-
-<span class="k">struct</span> <span class="n">clap_preset_iterator</span><span class="p">;</span>
+ <span class="cm">/* gui */</span>
+ <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">open</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="p">(</span><span class="o">*</span><span class="n">hide</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="p">(</span><span class="o">*</span><span class="n">close</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="p">};</span>
-<span class="k">struct</span> <span class="n">clap_plugin_presets</span>
+<span class="k">struct</span> <span class="n">clap_host_gui</span>
<span class="p">{</span>
- <span class="cm">/* Allocate a new preset iterator positioned at the beginning of the
- * preset collection, store its pointer into (*iter).
- * Returns true on success, false otherwise.
- * If the collection is empty, then it must return false and (*iter)
- * should be NULL. */</span>
- <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">iter_begin</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">struct</span> <span class="n">clap_preset_iterator</span> <span class="o">**</span><span class="n">iter</span><span class="p">);</span>
-
- <span class="cm">/* Iterate to the next value. If the iterator reached the end of the
- * collection, returns false.
- * Returns true on success. */</span>
- <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">iter_next</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">struct</span> <span class="n">clap_preset_iterator</span> <span class="o">*</span><span class="n">iter</span><span class="p">);</span>
-
- <span class="cm">/* Release the iterator.
- * If iter is NULL, then do nothing. */</span>
- <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">iter_destroy</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">struct</span> <span class="n">clap_preset_iterator</span> <span class="o">*</span><span class="n">iter</span><span class="p">);</span>
-
- <span class="cm">/* Get preset at the current iterator position.
- * Returns true on success, false otherwise. */</span>
- <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">iter_get</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">struct</span> <span class="n">clap_preset_iterator</span> <span class="o">*</span><span class="n">iter</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">/* Get a preset info by its URL and returns true.
- * If the preset is not found, then it should return false. */</span>
- <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">get</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">url</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">/* Set the preset score. */</span>
- <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">set_score</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">url</span><span class="p">,</span>
- <span class="kt">uint8_t</span> <span class="n">score</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">gui_opened</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>
+ <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="p">(</span><span class="o">*</span><span class="n">gui_hidden</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>
+ <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="p">(</span><span class="o">*</span><span class="n">gui_closed</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>
+ <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="p">};</span>
-<span class="cp">#endif </span><span class="cm">/* !CLAP_EXT_PRESETS_H */</span>
+<span class="cp">#endif </span><span class="cm">/* !CLAP_EXT_GUI_H */</span>
</pre>
</div>
<div class="section" id="clap-ext-embed-h">
-<h2><a class="toc-backref" href="#id56">clap/ext/embed.h</a></h2>
+<h2><a class="toc-backref" href="#id52">clap/ext/embed.h</a></h2>
<pre class="code c literal-block">
<span class="cp">#ifndef CLAP_EXT_EMBED_H
# define CLAP_EXT_EMBED_H
@@ -1802,14 +1653,14 @@ plugin's parameters and restore them.</p>
<span class="p">{</span>
<span class="cm">/* Request the host to resize the client area to width, height.
* Return true on success, false otherwise. */</span>
- <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">resize</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> <span class="kt">uint32_t</span> <span class="n">width</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="n">height</span><span class="p">);</span>
+ <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">resize</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> <span class="kt">int32_t</span> <span class="n">width</span><span class="p">,</span> <span class="kt">int32_t</span> <span class="n">height</span><span class="p">);</span>
<span class="p">};</span>
<span class="cp">#endif </span><span class="cm">/* !CLAP_EXT_EMBED_H */</span>
</pre>
</div>
<div class="section" id="clap-ext-embed-win32-h">
-<h2><a class="toc-backref" href="#id57">clap/ext/embed-win32.h</a></h2>
+<h2><a class="toc-backref" href="#id53">clap/ext/embed-win32.h</a></h2>
<pre class="code c literal-block">
<span class="cp">#ifndef CLAP_EXT_EMBED_WIN32_H
# define CLAP_EXT_EMBED_WIN32_H
@@ -1823,7 +1674,9 @@ plugin's parameters and restore them.</p>
</span>
<span class="k">struct</span> <span class="n">clap_plugin_embed_win32</span>
<span class="p">{</span>
- <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">get_size</span><span class="p">)(</span><span class="kt">uint32_t</span> <span class="o">*</span><span class="n">width</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="o">*</span><span class="n">height</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">get_size</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">int32_t</span> <span class="o">*</span><span class="n">width</span><span class="p">,</span>
+ <span class="kt">int32_t</span> <span class="o">*</span><span class="n">height</span><span class="p">);</span>
<span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">attach</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="n">HWND</span> <span class="n">window</span><span class="p">);</span>
<span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">detach</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="p">};</span>
@@ -1831,22 +1684,22 @@ plugin's parameters and restore them.</p>
<span class="cp">#endif </span><span class="cm">/* !CLAP_EXT_EMBED_WIN32_H */</span>
</pre>
</div>
-<div class="section" id="clap-ext-embed-xlib-h">
-<h2><a class="toc-backref" href="#id58">clap/ext/embed-xlib.h</a></h2>
+<div class="section" id="clap-ext-embed-x11-h">
+<h2><a class="toc-backref" href="#id54">clap/ext/embed-x11.h</a></h2>
<pre class="code c literal-block">
-<span class="cp">#ifndef CLAP_EXT_EMBED_XLIB_H
-# define CLAP_EXT_EMBED_XLIB_H
-</span>
-<span class="cp"># include <X11/Xlib.h>
+<span class="cp">#ifndef CLAP_EXT_EMBED_X11_H
+# define CLAP_EXT_EMBED_X11_H
</span>
<span class="cp"># include "../clap.h"
# include "embed.h"
</span>
-<span class="cp"># define CLAP_EXT_EMBED_XLIB "clap/embed/xlib"
+<span class="cp"># define CLAP_EXT_EMBED_X11 "clap/embed/x11"
</span>
-<span class="k">struct</span> <span class="n">clap_plugin_embed_xlib</span>
+<span class="k">struct</span> <span class="n">clap_plugin_embed_x11</span>
<span class="p">{</span>
- <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">get_size</span><span class="p">)(</span><span class="kt">uint32_t</span> <span class="o">*</span><span class="n">width</span><span class="p">,</span> <span class="kt">uint32_t</span> <span class="o">*</span><span class="n">height</span><span class="p">);</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">get_size</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">int32_t</span> <span class="o">*</span><span class="n">width</span><span class="p">,</span>
+ <span class="kt">int32_t</span> <span class="o">*</span><span class="n">height</span><span class="p">);</span>
<span class="cm">/* Note for the client, you can get a Display* by calling
* XOpenDisplay(display_name).
@@ -1854,14 +1707,124 @@ plugin's parameters and restore them.</p>
* Note for the host, the display_name can be retrieved from your own
* display->display_name. */</span>
<span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">attach</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="n">Window</span> <span class="n">window</span><span class="p">,</span>
- <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">display_name</span><span class="p">);</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">display_name</span><span class="p">,</span>
+ <span class="kt">unsigned</span> <span class="kt">long</span> <span class="n">window</span><span class="p">);</span>
<span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">detach</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="p">};</span>
<span class="cp">#endif </span><span class="cm">/* !CLAP_EMBED_XLIB_H */</span>
</pre>
</div>
+<div class="section" id="clap-ext-embed-cocoa-h">
+<h2><a class="toc-backref" href="#id55">clap/ext/embed-cocoa.h</a></h2>
+<pre class="code c literal-block">
+<span class="cp">#ifndef CLAP_EXT_EMBED_COCOA_H
+# define CLAP_EXT_EMBED_COCOA_H
+</span>
+<span class="cp"># include "../clap.h"
+# include "embed.h"
+</span>
+<span class="cp"># define CLAP_EXT_EMBED_COCOA "clap/embed/cocoa"
+</span>
+<span class="k">struct</span> <span class="n">clap_plugin_embed_cocoa</span>
+<span class="p">{</span>
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">get_size</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">int32_t</span> <span class="o">*</span><span class="n">width</span><span class="p">,</span>
+ <span class="kt">int32_t</span> <span class="o">*</span><span class="n">height</span><span class="p">);</span>
+
+ <span class="cm">/* Note for the client, you can get a Display* by calling
+ * XOpenDisplay(display_name).
+ *
+ * Note for the host, the display_name can be retrieved from your own
+ * display->display_name. */</span>
+ <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">attach</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">nsView</span><span class="p">);</span>
+ <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">detach</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="p">};</span>
+
+<span class="cp">#endif </span><span class="cm">/* !CLAP_EXT_EMBED_COCOA_H */</span>
+</pre>
+</div>
+<div class="section" id="clap-ext-presets-h">
+<h2><a class="toc-backref" href="#id56">clap/ext/presets.h</a></h2>
+<pre class="code c literal-block">
+<span class="cp">#ifndef CLAP_EXT_PRESETS_H
+# define CLAP_EXT_PRESETS_H
+</span>
+<span class="cp"># include "../clap.h"
+</span>
+<span class="cp"># define CLAP_EXT_PRESETS "clap/presets"
+</span>
+<span class="k">struct</span> <span class="n">clap_preset_info</span>
+<span class="p">{</span>
+ <span class="kt">char</span> <span class="n">plugin_id</span><span class="p">[</span><span class="n">CLAP_ID_SIZE</span><span class="p">];</span> <span class="c1">// used to identify which plugin can load the preset
+</span> <span class="kt">char</span> <span class="n">id</span><span class="p">[</span><span class="n">CLAP_ID_SIZE</span><span class="p">];</span> <span class="c1">// used to identify a preset in a preset bank
+</span> <span class="kt">char</span> <span class="n">name</span><span class="p">[</span><span class="n">CLAP_NAME_SIZE</span><span class="p">];</span> <span class="c1">// display name
+</span> <span class="kt">char</span> <span class="n">desc</span><span class="p">[</span><span class="n">CLAP_DESC_SIZE</span><span class="p">];</span> <span class="c1">// desc and how to use it
+</span> <span class="kt">char</span> <span class="n">author</span><span class="p">[</span><span class="n">CLAP_NAME_SIZE</span><span class="p">];</span>
+ <span class="kt">char</span> <span class="n">categories</span><span class="p">[</span><span class="n">CLAP_TAGS_SIZE</span><span class="p">];</span> <span class="c1">// "cat1;cat2;cat3;..."
+</span> <span class="kt">char</span> <span class="n">tags</span><span class="p">[</span><span class="n">CLAP_TAGS_SIZE</span><span class="p">];</span> <span class="c1">// "tag1;tag2;tag3;..."
+</span> <span class="kt">int8_t</span> <span class="n">score</span><span class="p">;</span> <span class="c1">// 0 = garbage, ..., 100 = best, -1 = no score
+</span><span class="p">};</span>
+
+<span class="cm">/* Interface implemented by the plugin */</span>
+<span class="k">struct</span> <span class="n">clap_plugin_preset</span>
+<span class="p">{</span>
+ <span class="cm">/* Create a preset library for this plugin */</span>
+ <span class="k">struct</span> <span class="n">clap_preset_library</span> <span class="o">*</span><span class="p">(</span><span class="o">*</span><span class="n">create_preset_library</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">/* Get the current preset info */</span>
+ <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">get_current_preset_info</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">struct</span> <span class="n">clap_preset_info</span> <span class="o">*</span><span class="n">preset</span><span class="p">);</span>
+
+ <span class="cm">/* Load a preset from a bank file */</span>
+ <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">load_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="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">path</span><span class="p">,</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">preset_id</span><span class="p">);</span>
+<span class="p">};</span>
+
+<span class="cm">/* opaque type */</span>
+<span class="k">struct</span> <span class="n">clap_bank_handle</span><span class="p">;</span>
+
+<span class="cm">/* The principle behind this extension is that the host gets a list of
+ * directories to scan recursively, and then for each files, it can ask
+ * the interface to load the preset.
+ *
+ * Every file are considered as preset bank, so they can contain between
+ * 0 and many presets. */</span>
+<span class="k">struct</span> <span class="n">clap_preset_library</span>
+<span class="p">{</span>
+ <span class="cm">/* Copies at most *path_size bytes into path.
+ * If directory_index is bigger than the number of directories,
+ * then return false. */</span>
+ <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">get_directory</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_preset_library</span> <span class="o">*</span><span class="n">library</span><span class="p">,</span>
+ <span class="kt">int</span> <span class="n">directory_index</span><span class="p">,</span>
+ <span class="kt">char</span> <span class="o">*</span><span class="n">path</span><span class="p">,</span>
+ <span class="kt">int32_t</span> <span class="o">*</span><span class="n">path_size</span><span class="p">);</span>
+
+ <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">open_bank</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_preset_library</span> <span class="o">*</span><span class="n">library</span><span class="p">,</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">path</span><span class="p">,</span>
+ <span class="k">struct</span> <span class="n">clap_bank_handle</span> <span class="o">*</span><span class="n">handle</span><span class="p">);</span>
+
+ <span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">close_bank</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_preset_library</span> <span class="o">*</span><span class="n">library</span><span class="p">,</span>
+ <span class="k">struct</span> <span class="n">clap_bank_handle</span> <span class="o">*</span><span class="n">handle</span><span class="p">);</span>
+
+ <span class="kt">int32_t</span> <span class="p">(</span><span class="o">*</span><span class="n">get_bank_size</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_preset_library</span> <span class="o">*</span><span class="n">library</span><span class="p">,</span>
+ <span class="k">struct</span> <span class="n">clap_bank_handle</span> <span class="o">*</span><span class="n">handle</span><span class="p">);</span>
+
+ <span class="cm">/* Get a preset info from its path and returns true.
+ * In case of a preset bank file, index is used, and *has_next
+ * should be set to false when index reaches the last preset.
+ * If the preset is not found, then it should return false. */</span>
+ <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">get_bank_preset</span><span class="p">)(</span><span class="k">struct</span> <span class="n">clap_preset_library</span> <span class="o">*</span><span class="n">library</span><span class="p">,</span>
+ <span class="k">struct</span> <span class="n">clap_bank_handle</span> <span class="o">*</span><span class="n">handle</span><span class="p">,</span>
+ <span class="k">struct</span> <span class="n">clap_preset_info</span> <span class="o">*</span><span class="n">preset_info</span><span class="p">,</span>
+ <span class="kt">int32_t</span> <span class="n">index</span><span class="p">);</span>
+<span class="p">};</span>
+
+<span class="cp">#endif </span><span class="cm">/* !CLAP_EXT_PRESETS_H */</span>
+</pre>
+</div>
</div>
</div>
</body>
diff --git a/spec.rst b/spec.rst
@@ -133,11 +133,6 @@ of them by using an ``index`` between ``0`` and ``*plugins_count``.
``clap_create`` returns ``NULL`` if the plugin creation failed or if
``plugin_index >= plugin_count``.
-Sample plugin loader
-````````````````````
-
-See `examples/clap-info/clap-info.c`_
-
Plugin description
~~~~~~~~~~~~~~~~~~
@@ -609,7 +604,9 @@ an extension.
+------------+---------------------------+----------------------+----------------+
| Windows | `clap/ext/embed-win32.h`_ | ``CLAP_EMBED_WIN32`` | For the plugin |
+------------+---------------------------+----------------------+----------------+
-| X11 | `clap/ext/embed-xlib.h`_ | ``CLAP_EMBED_XLIB`` | For the plugin |
+| X11 | `clap/ext/embed-x11.h`_ | ``CLAP_EMBED_X11`` | For the plugin |
++------------+---------------------------+----------------------+----------------+
+| Cocoa | `clap/ext/embed-cocoa.h`_ | ``CLAP_EMBED_COCOA`` | For the plugin |
+------------+---------------------------+----------------------+----------------+
Example on Windows
@@ -719,15 +716,6 @@ See `clap/ext/state.h`_.
Note: if the plugin do not have the state extension, the host can save the
plugin's parameters and restore them.
-Examples
-========
-
-examples/clap-info/clap-info.c
-------------------------------
-
-.. include:: tools/clap-info/clap-info.c
- :code: c
-
References
==========
@@ -737,22 +725,16 @@ clap/clap.h
.. include:: include/clap/clap.h
:code: c
-clap/ext/ports.h
+clap/ext/state.h
----------------
-.. include:: include/clap/ext/ports.h
- :code: c
-
-clap/ext/gui.h
---------------
-
-.. include:: include/clap/ext/gui.h
+.. include:: include/clap/ext/state.h
:code: c
-clap/ext/state.h
+clap/ext/ports.h
----------------
-.. include:: include/clap/ext/state.h
+.. include:: include/clap/ext/ports.h
:code: c
clap/ext/params.h
@@ -761,10 +743,10 @@ clap/ext/params.h
.. include:: include/clap/ext/params.h
:code: c
-clap/ext/presets.h
-------------------
+clap/ext/gui.h
+--------------
-.. include:: include/clap/ext/presets.h
+.. include:: include/clap/ext/gui.h
:code: c
clap/ext/embed.h
@@ -779,8 +761,20 @@ clap/ext/embed-win32.h
.. include:: include/clap/ext/embed-win32.h
:code: c
-clap/ext/embed-xlib.h
+clap/ext/embed-x11.h
---------------------
-.. include:: include/clap/ext/embed-xlib.h
+.. include:: include/clap/ext/embed-x11.h
+ :code: c
+
+clap/ext/embed-cocoa.h
+----------------------
+
+.. include:: include/clap/ext/embed-cocoa.h
+ :code: c
+
+clap/ext/presets.h
+------------------
+
+.. include:: include/clap/ext/presets.h
:code: c
