clap

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

commit ad0e2aaf1703bb8aad6b28e52b545b53c38c872d
parent 874e8fe5ce9559c7e60bb5ddd171101943d4d634
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date:   Mon, 20 Oct 2014 23:46:51 +0200

Update embeding extension

Diffstat:
Minclude/clap/clap-embed-win32.h | 8+++++---
Minclude/clap/clap-embed-xlib.h | 10++++++++--
Ainclude/clap/clap-embed.h | 13+++++++++++++
Mspec.html | 171+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------
Mspec.rst | 65++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------
5 files changed, 235 insertions(+), 32 deletions(-)

diff --git a/include/clap/clap-embed-win32.h b/include/clap/clap-embed-win32.h @@ -4,13 +4,15 @@ # include <windows.h> # include "clap.h" +# include "clap-embed.h" # define CLAP_EMBED_WIN32 "clap/embed/win32" -struct clap_embed_win32 +struct clap_plugin_embed_win32 { - bool (*embed)(struct clap_plugin *plugin, - HWND window); + void (*get_size)(uint32_t *width, uint32_t *height); + bool (*embed)(struct clap_plugin *plugin, HWND window); + bool (*disembed)(struct clap_plugin *plugin); }; #endif /* !CLAP_EMBED_WIN32_H */ diff --git a/include/clap/clap-embed-xlib.h b/include/clap/clap-embed-xlib.h @@ -4,14 +4,20 @@ # include <X11/Xlib.h> # include "clap.h" +# include "clap-embed.h" # define CLAP_EMBED_XLIB "clap/embed/xlib" -struct clap_embed_xlib +struct clap_plugin_embed_xlib { + void (*get_size)(uint32_t *width, uint32_t *height); + + /* the display_name can be retrieved from your own + * display->display_name. */ bool (*embed)(struct clap_plugin *plugin, Window window, - Display *display); + const char *display_name); + bool (*disembed)(struct clap_plugin *plugin); }; #endif /* !CLAP_EMBED_XLIB_H */ diff --git a/include/clap/clap-embed.h b/include/clap/clap-embed.h @@ -0,0 +1,13 @@ +#ifndef CLAP_EMBED_H +# define CLAP_EMBED_H + +# include "clap.h" + +# define CLAP_EMBED "clap/embed" + +struct clap_host_embed +{ + bool (*resize)(uint32_t width, uint32_t height); +}; + +#endif /* !CLAP_EMBED_H */ diff --git a/spec.html b/spec.html @@ -161,23 +161,30 @@ tt.docutils { <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="#sample-on-windows" id="id41">Sample on Windows</a></li> </ul> </li> -<li><a class="reference internal" href="#presets" id="id40">Presets</a><ul> -<li><a class="reference internal" href="#list-plugin-s-presets" id="id41">List plugin's presets</a></li> -<li><a class="reference internal" href="#load-a-preset" id="id42">Load a preset</a></li> </ul> </li> -<li><a class="reference internal" href="#save-and-restore-plugin-s-state" id="id43">Save and restore plugin's state</a></li> -<li><a class="reference internal" href="#extension-system" id="id44">Extension system</a></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="#examples" id="id45">Examples</a><ul> -<li><a class="reference internal" href="#samples-clap-info-c" id="id46">samples/clap-info.c</a></li> +<li><a class="reference internal" href="#save-and-restore-plugin-s-state" id="id45">Save and restore plugin's state</a></li> +<li><a class="reference internal" href="#extension-system" id="id46">Extension system</a></li> </ul> </li> -<li><a class="reference internal" href="#references" id="id47">References</a><ul> -<li><a class="reference internal" href="#clap-c" id="id48">clap.c</a></li> +<li><a class="reference internal" href="#examples" id="id47">Examples</a><ul> +<li><a class="reference internal" href="#samples-clap-info-c" id="id48">samples/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-h" id="id50">clap.h</a></li> +<li><a class="reference internal" href="#clap-embed-h" id="id51">clap-embed.h</a></li> +<li><a class="reference internal" href="#clap-embed-win32-h" id="id52">clap-embed-win32.h</a></li> +<li><a class="reference internal" href="#clap-embed-xlib-h" id="id53">clap-embed-xlib.h</a></li> </ul> </li> </ul> @@ -592,7 +599,7 @@ is used to process the feedback stream:</p> <span class="p">}</span> <span class="c1">// process one sample feedback -</span> <span class="n">process</span><span class="o">-&gt;</span><span class="n">feedback</span><span class="p">(</span><span class="n">process</span><span class="p">,</span> <span class="n">stream_id</span><span class="p">,</span> <span class="mi">1</span><span class="p">);</span> +</span> <span class="n">process</span><span class="o">-&gt;</span><span class="n">feedback</span><span class="p">(</span><span class="n">process</span><span class="p">,</span> <span class="n">stream_id</span><span class="p">,</span> <span class="n">process</span><span class="o">-&gt;</span><span class="n">feedback_chunk_size</span><span class="p">);</span> <span class="c1">// audio processing of the feedback values: </span> <span class="c1">// process-&gt;input[fb_in][offset + i] @@ -827,11 +834,63 @@ send an event <tt class="docutils literal">CLAP_EVENT_GUI_CLOSED</tt> to the hos <span class="n">host</span><span class="o">-&gt;</span><span class="n">events</span><span class="p">(</span><span class="n">host</span><span class="p">,</span> <span class="n">plugin</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">ev</span><span class="p">);</span> </pre> </div> +<div class="section" id="embedding"> +<h3><a class="toc-backref" href="#id40">Embedding</a></h3> +<p>Some host are designed to embed plugin's window. +As embedding is not a Clap requirement, it is offered as an extension. +Also the OS dependency brought by this feature makes it ideal as an extension.</p> +<table border="1" class="docutils"> +<colgroup> +<col width="16%" /> +<col width="32%" /> +<col width="30%" /> +<col width="22%" /> +</colgroup> +<thead valign="bottom"> +<tr><th class="head">GUI</th> +<th class="head">header</th> +<th class="head">extension</th> +<th class="head">comment</th> +</tr> +</thead> +<tbody valign="top"> +<tr><td>Generic</td> +<td><a class="reference internal" href="#clap-embed-h">clap-embed.h</a></td> +<td><tt class="docutils literal">CLAP_EMBED</tt></td> +<td>For the host</td> +</tr> +<tr><td>Windows</td> +<td><a class="reference internal" href="#clap-embed-win32-h">clap-embed-win32.h</a></td> +<td><tt class="docutils literal">CLAP_EMBED_WIN32</tt></td> +<td>For the plugin</td> +</tr> +<tr><td>X11</td> +<td><a class="reference internal" href="#clap-embed-xlib-h">clap-embed-xlib.h</a></td> +<td><tt class="docutils literal">CLAP_EMBED_XLIB</tt></td> +<td>For the plugin</td> +</tr> +</tbody> +</table> +<div class="section" id="sample-on-windows"> +<h4><a class="toc-backref" href="#id41">Sample on Windows</a></h4> +<pre class="code c literal-block"> +<span class="cp">#include &lt;clap/clap.h&gt; +#include &lt;clap/clap-embed-win32.h&gt; +</span> +<span class="k">struct</span> <span class="n">clap_embed_win32</span> <span class="o">*</span><span class="n">embed</span> <span class="o">=</span> <span class="n">plugin</span><span class="o">-&gt;</span><span class="n">get_extension</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="p">{</span> + <span class="c1">// the plugin can embed +</span> <span class="n">embed</span><span class="o">-&gt;</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="p">}</span> +<span class="n">plugin</span><span class="o">-&gt;</span><span class="n">show_gui</span><span class="p">(</span><span class="n">plugin</span><span class="p">);</span> +</pre> +</div> +</div> </div> <div class="section" id="presets"> -<h2><a class="toc-backref" href="#id40">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="#id41">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 preset by calling:</p> <ul class="simple"> <li><tt class="docutils literal"><span class="pre">plugin-&gt;get_presets_count(plugin);</span></tt> to know how many presets it has.</li> @@ -840,7 +899,7 @@ details.</li> </ul> </div> <div class="section" id="load-a-preset"> -<h3><a class="toc-backref" href="#id42">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 @@ -848,7 +907,7 @@ the plugin.</p> </div> </div> <div class="section" id="save-and-restore-plugin-s-state"> -<h2><a class="toc-backref" href="#id43">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:</p> <pre class="code c literal-block"> <span class="kt">void</span> <span class="o">*</span><span class="n">buffer</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span> @@ -868,7 +927,7 @@ plugin state on a little endian machine and send it through the network to a big endian machine, it should load again successfully.</p> </div> <div class="section" id="extension-system"> -<h2><a class="toc-backref" href="#id44">Extension system</a></h2> +<h2><a class="toc-backref" href="#id46">Extension system</a></h2> <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">-&gt;</span><span class="n">extension</span><span class="p">(</span><span class="n">plug</span><span class="p">,</span> <span class="s">&quot;company/ext-name&quot;</span><span class="p">);</span> @@ -878,9 +937,9 @@ big endian machine, it should load again successfully.</p> </div> </div> <div class="section" id="examples"> -<h1><a class="toc-backref" href="#id45">Examples</a></h1> +<h1><a class="toc-backref" href="#id47">Examples</a></h1> <div class="section" id="samples-clap-info-c"> -<h2><a class="toc-backref" href="#id46">samples/clap-info.c</a></h2> +<h2><a class="toc-backref" href="#id48">samples/clap-info.c</a></h2> <pre class="code c literal-block"> <span class="cp">#include &lt;stdio.h&gt; #include &lt;dlfcn.h&gt; @@ -980,9 +1039,9 @@ big endian machine, it should load again successfully.</p> </div> </div> <div class="section" id="references"> -<h1><a class="toc-backref" href="#id47">References</a></h1> -<div class="section" id="clap-c"> -<h2><a class="toc-backref" href="#id48">clap.c</a></h2> +<h1><a class="toc-backref" href="#id49">References</a></h1> +<div class="section" id="clap-h"> +<h2><a class="toc-backref" href="#id50">clap.h</a></h2> <pre class="code c literal-block"> <span class="cm">/** * CLAP - CLever Audio Plugin (&lt;--- needs to find a marketing ok name) @@ -1404,6 +1463,78 @@ big endian machine, it should load again successfully.</p> <span class="cp">#endif </span><span class="cm">/* !CLAP_H */</span> </pre> </div> +<div class="section" id="clap-embed-h"> +<h2><a class="toc-backref" href="#id51">clap-embed.h</a></h2> +<pre class="code c literal-block"> +<span class="cp">#ifndef CLAP_EMBED_H +# define CLAP_EMBED_H +</span> +<span class="cp"># include &quot;clap.h&quot; +</span> +<span class="cp"># define CLAP_EMBED &quot;clap/embed&quot; +</span> +<span class="k">struct</span> <span class="n">clap_host_embed</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="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="p">};</span> + +<span class="cp">#endif </span><span class="cm">/* !CLAP_EMBED_H */</span><span class="cp"> +</span> +</pre> +</div> +<div class="section" id="clap-embed-win32-h"> +<h2><a class="toc-backref" href="#id52">clap-embed-win32.h</a></h2> +<pre class="code c literal-block"> +<span class="cp">#ifndef CLAP_EMBED_WIN32_H +# define CLAP_EMBED_WIN32_H +</span> +<span class="cp"># include &lt;windows.h&gt; +</span> +<span class="cp"># include &quot;clap.h&quot; +# include &quot;clap-embed.h&quot; +</span> +<span class="cp"># define CLAP_EMBED_WIN32 &quot;clap/embed/win32&quot; +</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">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">embed</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">disembed</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_WIN32_H */</span><span class="cp"> +</span> +</pre> +</div> +<div class="section" id="clap-embed-xlib-h"> +<h2><a class="toc-backref" href="#id53">clap-embed-xlib.h</a></h2> +<pre class="code c literal-block"> +<span class="cp">#ifndef CLAP_EMBED_XLIB_H +# define CLAP_EMBED_XLIB_H +</span> +<span class="cp"># include &lt;X11/Xlib.h&gt; +</span> +<span class="cp"># include &quot;clap.h&quot; +# include &quot;clap-embed.h&quot; +</span> +<span class="cp"># define CLAP_EMBED_XLIB &quot;clap/embed/xlib&quot; +</span> +<span class="k">struct</span> <span class="n">clap_plugin_embed_xlib</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="cm">/* the display_name can be retrieved from your own + * display-&gt;display_name. */</span> + <span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">embed</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="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">disembed</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><span class="cp"> +</span> +</pre> +</div> </div> </div> </body> diff --git a/spec.rst b/spec.rst @@ -94,17 +94,17 @@ For example: +-------------+---------------------------+ | x86_64 | DigitalDragon.x86_64.so | +-------------+---------------------------+ -| alpha | DigitalDrapon.alpha.so | +| alpha | DigitalDragon.alpha.so | +-------------+---------------------------+ -| arm | DigitalDrapon.arm.so | +| arm | DigitalDragon.arm.so | +-------------+---------------------------+ -| sparc | DigitalDrapon.sparc.so | +| sparc | DigitalDragon.sparc.so | +-------------+---------------------------+ -| hppa | DigitalDrapon.hppa.so | +| hppa | DigitalDragon.hppa.so | +-------------+---------------------------+ -| ppc | DigitalDrapon.ppc.so | +| ppc | DigitalDragon.ppc.so | +-------------+---------------------------+ -| ppc64 | DigitalDrapon.ppc64.so | +| ppc64 | DigitalDragon.ppc64.so | +-------------+---------------------------+ If the name does not contain an indicator, then the plugin should be @@ -539,6 +539,38 @@ send an event ``CLAP_EVENT_GUI_CLOSED`` to the host. ev.sample_offset = host->steady_time(host); host->events(host, plugin, &ev); +Embedding +~~~~~~~~~ + +Some host are designed to embed plugin's window. +As embedding is not a Clap requirement, it is offered as an extension. +Also the OS dependency brought by this feature makes it ideal as an extension. + ++------------+-----------------------+----------------------+----------------+ +| GUI | header | extension | comment | ++============+=======================+======================+================+ +| Generic | `clap-embed.h`_ | ``CLAP_EMBED`` | For the host | ++------------+-----------------------+----------------------+----------------+ +| Windows | `clap-embed-win32.h`_ | ``CLAP_EMBED_WIN32`` | For the plugin | ++------------+-----------------------+----------------------+----------------+ +| X11 | `clap-embed-xlib.h`_ | ``CLAP_EMBED_XLIB`` | For the plugin | ++------------+-----------------------+----------------------+----------------+ + +Sample on Windows +````````````````` + +.. code:: c + + #include <clap/clap.h> + #include <clap/clap-embed-win32.h> + + struct clap_embed_win32 *embed = plugin->get_extension(CLAP_EMBED_WIN32); + if (embed) { + // the plugin can embed + embed->embed(plugin, window); + } + plugin->show_gui(plugin); + Presets ------- @@ -610,8 +642,27 @@ samples/clap-info.c References ========== -clap.c +clap.h ------ .. include:: include/clap/clap.h :code: c + +clap-embed.h +------------ + +.. include:: include/clap/clap-embed.h + :code: c + +clap-embed-win32.h +------------------ + +.. include:: include/clap/clap-embed-win32.h + :code: c + +clap-embed-xlib.h +----------------- + +.. include:: include/clap/clap-embed-xlib.h + :code: c +