commit 16382cc3a2305ad4460b2af8473a33dca44a038d
parent 3d3a4185c8cb00b7737e4b019d35d62b43a8e22e
Author: Alexandre Bique <bique.alexandre@gmail.com>
Date: Wed, 1 Oct 2014 08:32:40 +0200
Update the spec
Diffstat:
| M | clap.h | | | 51 | ++++++++++++++++++++++++++++++--------------------- |
| M | spec.rst | | | 97 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- |
2 files changed, 125 insertions(+), 23 deletions(-)
diff --git a/clap.h b/clap.h
@@ -35,22 +35,6 @@ extern "C" {
# define CLAP_VERSION_MAKE(Major, Minor, Revision) (((Major) << 16) | ((Minor) << 8) | (Revision))
# define CLAP_VERSION CLAP_VERSION_MAKE(1, 0, 0)
-struct clap_host
-{
- uint32_t clap_version; // initialized to CALP_VERSION
-
- const char *name;
- const char *manufacturer;
- const char *version;
-
- /* gui */
- uint32_t (*gui_opened)(struct clap_host *host, struct clap_plugin *plugin);
- uint32_t (*gui_closed)(struct clap_host *host, struct clap_plugin *plugin);
-
- /* future features */
- void *(*extention)(struct clap_plugin *plugin, const char *extention_id);
-};
-
enum clap_param_type
{
CLAP_PARAM_BOOL,
@@ -138,6 +122,24 @@ struct clap_event
};
};
+struct clap_host
+{
+ uint32_t clap_version; // initialized to CALP_VERSION
+
+ const char *name;
+ const char *manufacturer;
+ const char *version;
+
+ /* for events generated outside of process, like from the network
+ * or the GUI. */
+ void (*events)(struct clap_host *host,
+ struct clap_plugin *plugin,
+ struct clap_event *events);
+
+ /* future features */
+ void *(*extention)(struct clap_plugin *plugin, const char *extention_id);
+};
+
struct clap_process
{
/* audio buffers, they must be aligned on the machine's best vector instructions requirement */
@@ -167,12 +169,19 @@ enum clap_plugin_type
CLAP_PLUGIN_ANALYZER = (1 << 3),
};
+struct clap_preset_iterator
+{
+ struct clap_preset_info info;
+ void *plugin_ptr; // reserved data for the plugin
+ void (*destroy)(struct clap_preset_iterator *iter);
+};
+
struct clap_plugin
{
uint32_t clap_version; // initialized to CALP_VERSION
- void *host_data;
- void *plugin_data;
+ void *host_data; // reserved pointer for the host
+ void *plugin_data; // reserved pointer for the plugin
/* free plugin's resources */
void (*destroy)(struct clap_plugin *plugin);
@@ -196,11 +205,11 @@ struct clap_plugin
void (*get_param_info)(struct clap_plugin *plugin, uint32_t index, struct clap_param_info *param);
/* presets */
- uint32_t (*get_preset_count)(struct clap_plugin *plugin);
- void (*get_preset_info)(struct clap_plugin *plugin, uint32_t index, struct clap_preset_info *preset);
+ struct clap_preset_iterator *(*presets_begin)(struct clap_plugin *plugin);
+ bool (*presets_next)(struct clap_plugin *plugin, struct clap_preset_iterator *iter);
/* activation */
- void (*activate)(struct clap_plugin *plugin);
+ bool (*activate)(struct clap_plugin *plugin);
void (*deactivate)(struct clap_plugin *plugin);
/* work */
diff --git a/spec.rst b/spec.rst
@@ -16,6 +16,7 @@ Goals
- Bring new features missed in VST 2.4
- Replace old concepts by modern design
- Designed to work on any operating system
+- Be event oriented
- Provide a reference host
- Provide some reference plugins
- Provide a validation plugin, which should signal anything wrong the host does
@@ -25,6 +26,12 @@ Goals
Specification
=============
+Encoding
+--------
+
+All the strings exchanged through the CLAP interface must be encoded in UTF-8
+and must be valid.
+
Locate the plugins
------------------
@@ -81,23 +88,109 @@ Sample
Description
~~~~~~~~~~~
+Both the plugin and host have a few attribute giving general plugin description.
+
++--------------+---------------------------------------------------------------+
+| Attribute | Description |
++==============+===============================================================+
+| clap_version | Described the plugin format version implemented. Should be |
+| | initialized with CLAP_PLUGIN_VERSION, |
+| | or CLAP_VERSION_MAKE(1, 0, 0) if you want to only support |
+| | version 1.0.0 |
++--------------+---------------------------------------------------------------+
+| id | Unique identifier of the plugin. It should never change. It |
+| | should be the same on 32bits or 64bits or whatever. |
++--------------+---------------------------------------------------------------+
+| name | The name of the product. |
++--------------+---------------------------------------------------------------+
+| description | A brief description of the product. |
++--------------+---------------------------------------------------------------+
+| manufacturer | Which company made the plugin. |
++--------------+---------------------------------------------------------------+
+| version | A string describing the product version. |
++--------------+---------------------------------------------------------------+
+| url | An URL to the product homepage. |
++--------------+---------------------------------------------------------------+
+| license | The plugin license type, Custom, GPLv3, MIT, ... |
++--------------+---------------------------------------------------------------+
+| support | A link to the support, it can be |
+| | ``mailto:support@company.com`` or |
+| | ``http://company.com/support``. |
++--------------+---------------------------------------------------------------+
+| categories | An array of categories, the plugins fits into. Eg: analogue, |
+| | digital, fm, delay, reverb, compressor, ... |
++--------------+---------------------------------------------------------------+
+| plugin_type | Bitfield describing what the plugin does. See enum |
+| | clap_plugin_type. |
++--------------+---------------------------------------------------------------+
+| inputs_count | The number of input buffers. |
++--------------+---------------------------------------------------------------+
+| outputs_count| The number of output buffers. |
++--------------+---------------------------------------------------------------+
+| host_data | Reserved pointer for the host. |
++--------------+---------------------------------------------------------------+
+| plugin_data | Reserved pointer for the plugin. |
++--------------+---------------------------------------------------------------+
Threading
---------
The plugin is not thread safe, and must not be called concurrently.
-Yet, show_gui() and hide_gui() should be called from an other thread, and can be called concurrently.
+Yet, show_gui() and hide_gui() have to be called from an other thread,
+and can be called concurrently.
+
Rational: starting the GUI requires to load resources which may be done
synchronously and can take time. So to avoid blocking the audio
-processing, we choose to start the GUI from an other thread.
+processing, we choose to start the GUI from a different thread that the
+audio processing thread.
+
+Activation
+----------
+
+Before doing any processing, the plugin must be activated by calling
+``bool succeed = plugin->activate(plugin);``.
+
+If ``succeed == true`` then the activation succeed. If the activation failed,
+then the plugin is unusable.
+
+The host must not call ``activate()`` if the plugin is already activated.
+Yet the plugin should handle correctly double calls to ``activate()``.
+
+The plugin activation could be nothing, or could be a task which takes time,
+like connecting a remote server. So the host should not activate plugins in
+the audio processing thread.
+
+To deactivate the plugin, just call ``plugin->deactivate(plugin)``. Like
+``activate()``, ``deactivate()`` should not be called from the audio processing
+thread as it may take time.
+
+Also ``deactivate()`` should not be called if the plugin is not activated.
+Yet the plugin should handle a call to ``deactivate()`` even if it is
+not activated.
+
+It is preferable to de-activate the plugin before destroying it.
Processing
----------
+The processing is done in one call: ``plugin->process(plugin, process);``.
+The data structure process regroup everything needed by the plugin:
+
+- audio buffers (in, out)
+- events (in, out)
+- tempo, time, is offline? (in)
+- more processing needed (out)
+
Audio buffers
~~~~~~~~~~~~~
+The audio buffers are allocated by the host. They must be aligned by the
+maximum requirement of the vector instructions currently avalaible.
+
+- TBD: static buffer?
+- TBD: in place processing?
+
Events
~~~~~~
