commit 4e13601ac4d950c4f47d924cab87d1424b64b80b
parent 63e24c96d11cc86264f01300505805472897eef3
Author: Alexandre BIQUE <bique.alexandre@gmail.com>
Date: Fri, 23 Apr 2021 00:01:01 +0200
regen the doc
Diffstat:
| M | spec.html | | | 127 | +++++++++++++++++++++++++++++++------------------------------------------------ |
1 file changed, 49 insertions(+), 78 deletions(-)
diff --git a/spec.html b/spec.html
@@ -140,34 +140,32 @@ tt.docutils {
</li>
<li><a class="reference internal" href="#parameters" id="id22">Parameters</a><ul>
<li><a class="reference internal" href="#types" id="id23">Types</a></li>
-<li><a class="reference internal" href="#scales" id="id24">Scales</a></li>
-<li><a class="reference internal" href="#automation" id="id25">Automation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#graphical-user-interface" id="id26">Graphical User Interface</a><ul>
-<li><a class="reference internal" href="#showing-the-gui" id="id27">Showing the GUI</a></li>
-<li><a class="reference internal" href="#sending-events-to-the-host" id="id28">Sending events to the host</a></li>
-<li><a class="reference internal" href="#hiding-the-gui" id="id29">Hiding the GUI</a></li>
-<li><a class="reference internal" href="#embedding" id="id30">Embedding</a><ul>
-<li><a class="reference internal" href="#example-on-windows" id="id31">Example on Windows</a></li>
-<li><a class="reference internal" href="#resizing-the-window" id="id32">Resizing the window</a></li>
+<li><a class="reference internal" href="#graphical-user-interface" id="id24">Graphical User Interface</a><ul>
+<li><a class="reference internal" href="#showing-the-gui" id="id25">Showing the GUI</a></li>
+<li><a class="reference internal" href="#sending-events-to-the-host" id="id26">Sending events to the host</a></li>
+<li><a class="reference internal" href="#hiding-the-gui" id="id27">Hiding the GUI</a></li>
+<li><a class="reference internal" href="#embedding" id="id28">Embedding</a><ul>
+<li><a class="reference internal" href="#example-on-windows" id="id29">Example on Windows</a></li>
+<li><a class="reference internal" href="#resizing-the-window" id="id30">Resizing the window</a></li>
</ul>
</li>
</ul>
</li>
-<li><a class="reference internal" href="#save-and-restore-plugin-s-state" id="id33">Save and restore plugin's state</a></li>
+<li><a class="reference internal" href="#save-and-restore-plugin-s-state" id="id31">Save and restore plugin's state</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#references" id="id34">References</a><ul>
-<li><a class="reference internal" href="#clap-clap-h" id="id35">clap/clap.h</a></li>
-<li><a class="reference internal" href="#clap-ext-state-h" id="id36">clap/ext/state.h</a></li>
-<li><a class="reference internal" href="#clap-ext-audio-ports-h" id="id37">clap/ext/audio-ports.h</a></li>
-<li><a class="reference internal" href="#clap-ext-params-h" id="id38">clap/ext/params.h</a></li>
-<li><a class="reference internal" href="#clap-ext-gui-h" id="id39">clap/ext/gui.h</a></li>
-<li><a class="reference internal" href="#clap-ext-gui-win32-h" id="id40">clap/ext/gui-win32.h</a></li>
-<li><a class="reference internal" href="#clap-ext-gui-x11-h" id="id41">clap/ext/gui-x11.h</a></li>
-<li><a class="reference internal" href="#clap-ext-gui-cocoa-h" id="id42">clap/ext/gui-cocoa.h</a></li>
-<li><a class="reference internal" href="#clap-ext-draft-key-name-h" id="id43">clap/ext/draft/key-name.h</a></li>
+<li><a class="reference internal" href="#references" id="id32">References</a><ul>
+<li><a class="reference internal" href="#clap-clap-h" id="id33">clap/clap.h</a></li>
+<li><a class="reference internal" href="#clap-ext-state-h" id="id34">clap/ext/state.h</a></li>
+<li><a class="reference internal" href="#clap-ext-audio-ports-h" id="id35">clap/ext/audio-ports.h</a></li>
+<li><a class="reference internal" href="#clap-ext-params-h" id="id36">clap/ext/params.h</a></li>
+<li><a class="reference internal" href="#clap-ext-gui-h" id="id37">clap/ext/gui.h</a></li>
+<li><a class="reference internal" href="#clap-ext-gui-win32-h" id="id38">clap/ext/gui-win32.h</a></li>
+<li><a class="reference internal" href="#clap-ext-gui-x11-h" id="id39">clap/ext/gui-x11.h</a></li>
+<li><a class="reference internal" href="#clap-ext-gui-cocoa-h" id="id40">clap/ext/gui-cocoa.h</a></li>
+<li><a class="reference internal" href="#clap-ext-draft-key-name-h" id="id41">clap/ext/draft/key-name.h</a></li>
</ul>
</li>
</ul>
@@ -518,7 +516,7 @@ value and description</li>
<pre class="code c literal-block">
<span class="cp">#include</span> <span class="cpf"><clap/ext/params.h></span><span class="cp">
</span>
-<span class="k">struct</span> <span class="nc">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">const</span> <span class="k">struct</span> <span class="nc">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="k">return</span><span class="p">;</span> <span class="c1">// no params extensions
</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>
@@ -535,9 +533,9 @@ value and description</li>
<p>There are a few parameter types:</p>
<table border="1" class="docutils">
<colgroup>
-<col width="9%" />
+<col width="10%" />
<col width="22%" />
-<col width="69%" />
+<col width="68%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">type</th>
@@ -546,19 +544,13 @@ value and description</li>
</tr>
</thead>
<tbody valign="top">
-<tr><td>group</td>
-<td>none</td>
-<td>not a value, but the only parameter which can have
-child. It should be used to organize parameters in
-the host GUI.</td>
-</tr>
<tr><td>bool</td>
<td><tt class="docutils literal">value.b</tt></td>
<td>a boolean value, can be true or false</td>
</tr>
-<tr><td>float</td>
-<td><tt class="docutils literal">value.f</tt></td>
-<td>a float value</td>
+<tr><td>double</td>
+<td><tt class="docutils literal">value.d</tt></td>
+<td>a double value</td>
</tr>
<tr><td>int</td>
<td><tt class="docutils literal">value.i</tt></td>
@@ -572,29 +564,11 @@ should rely on <tt class="docutils literal">display_text</tt> to show its value.
</tbody>
</table>
</div>
-<div class="section" id="scales">
-<h3><a class="toc-backref" href="#id24">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>,
-<tt class="docutils literal">CLAP_PARAM_LOG</tt> or ... A logarithmic scale is convinient for a frequency
-parameter.</p>
-</div>
-<div class="section" id="automation">
-<h3><a class="toc-backref" href="#id25">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>
-<p>When a parameter is modified by an other parameter (this is discouraged),
-for example imagine you have a parameter modulating "absolutely" an other
-one through an XY mapping.
-The host should record the modulation source but not the modulation target.
-To do that the plugin uses <tt class="docutils literal"><span class="pre">clap_event_param->is_recordable</span></tt>.</p>
-</div>
</div>
<div class="section" id="graphical-user-interface">
-<h2><a class="toc-backref" href="#id26">Graphical User Interface</a></h2>
+<h2><a class="toc-backref" href="#id24">Graphical User Interface</a></h2>
<div class="section" id="showing-the-gui">
-<h3><a class="toc-backref" href="#id27">Showing the GUI</a></h3>
+<h3><a class="toc-backref" href="#id25">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>
@@ -608,7 +582,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="#id28">Sending events to the host</a></h3>
+<h3><a class="toc-backref" href="#id26">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>
@@ -620,7 +594,7 @@ otherwise.</p>
</pre>
</div>
<div class="section" id="hiding-the-gui">
-<h3><a class="toc-backref" href="#id29">Hiding the GUI</a></h3>
+<h3><a class="toc-backref" href="#id27">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>
@@ -633,7 +607,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="#id30">Embedding</a></h3>
+<h3><a class="toc-backref" href="#id28">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>
@@ -675,7 +649,7 @@ an extension.</p>
</tbody>
</table>
<div class="section" id="example-on-windows">
-<h4><a class="toc-backref" href="#id31">Example on Windows</a></h4>
+<h4><a class="toc-backref" href="#id29">Example on Windows</a></h4>
<pre class="code c literal-block">
<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">
@@ -684,21 +658,17 @@ an extension.</p>
<span class="k">struct</span> <span class="nc">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>
<span class="n">embed</span><span class="o">-></span><span class="n">embed</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">window</span><span class="p">);</span>
-
-<span class="k">struct</span> <span class="nc">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">get_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>
- <span class="n">gui</span><span class="o">-></span><span class="n">open</span><span class="p">(</span><span class="n">plugin</span><span class="p">);</span>
</pre>
</div>
<div class="section" id="resizing-the-window">
-<h4><a class="toc-backref" href="#id32">Resizing the window</a></h4>
+<h4><a class="toc-backref" href="#id30">Resizing the window</a></h4>
<pre class="code c literal-block">
<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="nc">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>
-<span class="k">if</span> <span class="p">(</span><span class="n">embed</span> <span class="o">&&</span> <span class="n">embed</span><span class="o">-></span><span class="n">resize</span><span class="p">(</span><span class="n">host</span><span class="p">,</span> <span class="n">width</span><span class="p">,</span> <span class="n">height</span><span class="p">))</span> <span class="p">{</span>
+</span><span class="k">struct</span> <span class="nc">clap_host_gui</span> <span class="o">*</span><span class="n">host_gui</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_EXT_GUI</span><span class="p">);</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">host_gui</span> <span class="o">&&</span> <span class="n">host_gui</span><span class="o">-></span><span class="n">resize</span><span class="p">(</span><span class="n">host</span><span class="p">,</span> <span class="n">width</span><span class="p">,</span> <span class="n">height</span><span class="p">))</span> <span class="p">{</span>
<span class="c1">// resize succeed
</span><span class="p">}</span>
</pre>
@@ -706,17 +676,16 @@ an extension.</p>
</div>
</div>
<div class="section" id="save-and-restore-plugin-s-state">
-<h2><a class="toc-backref" href="#id33">Save and restore plugin's state</a></h2>
+<h2><a class="toc-backref" href="#id31">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</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>
+<span class="k">struct</span> <span class="nc">clap_ostream</span> <span class="o">*</span><span class="n">stream</span> <span class="o">=</span> <span class="p">...;</span>
<span class="k">struct</span> <span class="nc">clap_plugin_state</span> <span class="o">*</span><span class="n">state</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_EXT_STATE</span><span class="p">);</span>
-<span class="k">if</span> <span class="p">(</span><span class="n">state</span> <span class="o">&&</span> <span class="n">state</span><span class="o">-></span><span class="n">save</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="o">&</span><span class="n">buffer</span><span class="p">,</span> <span class="o">&</span><span class="n">size</span><span class="p">))</span> <span class="p">{</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">state</span> <span class="o">&&</span> <span class="n">state</span><span class="o">-></span><span class="n">save</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">stream</span><span class="p">))</span> <span class="p">{</span>
<span class="c1">// save succeed
</span><span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
<span class="c1">// save failed
@@ -724,7 +693,7 @@ an extension.</p>
</pre>
<p>Restoring the plugin's state is done by:</p>
<pre class="code c literal-block">
-<span class="n">state</span><span class="o">-></span><span class="n">restore</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">buffer</span><span class="p">,</span> <span class="n">size</span><span class="p">);</span>
+<span class="n">state</span><span class="o">-></span><span class="n">restore</span><span class="p">(</span><span class="n">plugin</span><span class="p">,</span> <span class="n">stream</span><span class="p">);</span>
</pre>
<p>The state of the plugin should be independent of the machine: you can save a
plugin state on a little endian machine and send it through the network to a
@@ -735,9 +704,9 @@ plugin's parameters and restore them.</p>
</div>
</div>
<div class="section" id="references">
-<h1><a class="toc-backref" href="#id34">References</a></h1>
+<h1><a class="toc-backref" href="#id32">References</a></h1>
<div class="section" id="clap-clap-h">
-<h2><a class="toc-backref" href="#id35">clap/clap.h</a></h2>
+<h2><a class="toc-backref" href="#id33">clap/clap.h</a></h2>
<pre class="code c literal-block">
<span class="cm">/*
* CLAP - CLever Audio Plugin
@@ -912,6 +881,8 @@ plugin's parameters and restore them.</p>
<span class="p">};</span>
<span class="k">struct</span> <span class="nc">clap_event_list</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">ctx</span><span class="p">;</span>
+
<span class="kt">int</span> <span class="p">(</span><span class="o">*</span><span class="n">size</span><span class="p">)(</span><span class="k">const</span> <span class="k">struct</span> <span class="nc">clap_event_istream</span> <span class="o">*</span><span class="n">stream</span><span class="p">);</span>
<span class="k">const</span> <span class="k">struct</span> <span class="nc">clap_event</span> <span class="o">*</span><span class="p">(</span><span class="o">*</span><span class="n">get</span><span class="p">)(</span><span class="k">const</span> <span class="k">struct</span> <span class="nc">clap_event_istream</span> <span class="o">*</span><span class="n">stream</span><span class="p">,</span>
<span class="kt">int</span> <span class="n">index</span><span class="p">);</span>
@@ -1113,7 +1084,7 @@ plugin's parameters and restore them.</p>
</pre>
</div>
<div class="section" id="clap-ext-state-h">
-<h2><a class="toc-backref" href="#id36">clap/ext/state.h</a></h2>
+<h2><a class="toc-backref" href="#id34">clap/ext/state.h</a></h2>
<pre class="code c literal-block">
<span class="cp">#pragma once
</span>
@@ -1148,7 +1119,7 @@ plugin's parameters and restore them.</p>
</pre>
</div>
<div class="section" id="clap-ext-audio-ports-h">
-<h2><a class="toc-backref" href="#id37">clap/ext/audio-ports.h</a></h2>
+<h2><a class="toc-backref" href="#id35">clap/ext/audio-ports.h</a></h2>
<pre class="code c literal-block">
<span class="cp">#pragma once
</span>
@@ -1216,7 +1187,7 @@ plugin's parameters and restore them.</p>
</pre>
</div>
<div class="section" id="clap-ext-params-h">
-<h2><a class="toc-backref" href="#id38">clap/ext/params.h</a></h2>
+<h2><a class="toc-backref" href="#id36">clap/ext/params.h</a></h2>
<pre class="code c literal-block">
<span class="cp">#pragma once
</span>
@@ -1329,7 +1300,7 @@ plugin's parameters and restore them.</p>
</pre>
</div>
<div class="section" id="clap-ext-gui-h">
-<h2><a class="toc-backref" href="#id39">clap/ext/gui.h</a></h2>
+<h2><a class="toc-backref" href="#id37">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
@@ -1368,7 +1339,7 @@ plugin's parameters and restore them.</p>
</pre>
</div>
<div class="section" id="clap-ext-gui-win32-h">
-<h2><a class="toc-backref" href="#id40">clap/ext/gui-win32.h</a></h2>
+<h2><a class="toc-backref" href="#id38">clap/ext/gui-win32.h</a></h2>
<pre class="code c literal-block">
<span class="cp">#pragma once
</span>
@@ -1397,7 +1368,7 @@ plugin's parameters and restore them.</p>
</pre>
</div>
<div class="section" id="clap-ext-gui-x11-h">
-<h2><a class="toc-backref" href="#id41">clap/ext/gui-x11.h</a></h2>
+<h2><a class="toc-backref" href="#id39">clap/ext/gui-x11.h</a></h2>
<pre class="code c literal-block">
<span class="cp">#pragma once
</span>
@@ -1426,7 +1397,7 @@ plugin's parameters and restore them.</p>
</pre>
</div>
<div class="section" id="clap-ext-gui-cocoa-h">
-<h2><a class="toc-backref" href="#id42">clap/ext/gui-cocoa.h</a></h2>
+<h2><a class="toc-backref" href="#id40">clap/ext/gui-cocoa.h</a></h2>
<pre class="code c literal-block">
<span class="cp">#pragma once
</span>
@@ -1452,7 +1423,7 @@ plugin's parameters and restore them.</p>
</pre>
</div>
<div class="section" id="clap-ext-draft-key-name-h">
-<h2><a class="toc-backref" href="#id43">clap/ext/draft/key-name.h</a></h2>
+<h2><a class="toc-backref" href="#id41">clap/ext/draft/key-name.h</a></h2>
<pre class="code c literal-block">
<span class="cp">#pragma once
</span>
