commit ad0e2aaf1703bb8aad6b28e52b545b53c38c872d
parent 874e8fe5ce9559c7e60bb5ddd171101943d4d634
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date: Mon, 20 Oct 2014 23:46:51 +0200
Update embeding extension
Diffstat:
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">-></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">-></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">-></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->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">-></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">&</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 <clap/clap.h>
+#include <clap/clap-embed-win32.h>
+</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">-></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">-></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">-></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->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">-></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>
@@ -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 <stdio.h>
#include <dlfcn.h>
@@ -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 (<--- 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 "clap.h"
+</span>
+<span class="cp"># define CLAP_EMBED "clap/embed"
+</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 <windows.h>
+</span>
+<span class="cp"># include "clap.h"
+# include "clap-embed.h"
+</span>
+<span class="cp"># define CLAP_EMBED_WIN32 "clap/embed/win32"
+</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 <X11/Xlib.h>
+</span>
+<span class="cp"># include "clap.h"
+# include "clap-embed.h"
+</span>
+<span class="cp"># define CLAP_EMBED_XLIB "clap/embed/xlib"
+</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->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
+
