From c8b942918517fdeefd9886bfbae1d00ec62d47b0 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Sat, 17 Dec 2016 22:32:34 -0500 Subject: Add C++ bindings --- lv2/lv2plug.in/ns/ext/atom/atom.hpp | 81 +++++++++++ lv2/lv2plug.in/ns/ext/urid/urid.hpp | 114 +++++++++++++++ lv2/lv2plug.in/ns/lv2core/Feature.hpp | 74 ++++++++++ lv2/lv2plug.in/ns/lv2core/Lib.hpp | 81 +++++++++++ lv2/lv2plug.in/ns/lv2core/Plugin.hpp | 260 ++++++++++++++++++++++++++++++++++ 5 files changed, 610 insertions(+) create mode 100644 lv2/lv2plug.in/ns/ext/atom/atom.hpp create mode 100644 lv2/lv2plug.in/ns/ext/urid/urid.hpp create mode 100644 lv2/lv2plug.in/ns/lv2core/Feature.hpp create mode 100644 lv2/lv2plug.in/ns/lv2core/Lib.hpp create mode 100644 lv2/lv2plug.in/ns/lv2core/Plugin.hpp (limited to 'lv2') diff --git a/lv2/lv2plug.in/ns/ext/atom/atom.hpp b/lv2/lv2plug.in/ns/ext/atom/atom.hpp new file mode 100644 index 0000000..87871c0 --- /dev/null +++ b/lv2/lv2plug.in/ns/ext/atom/atom.hpp @@ -0,0 +1,81 @@ +/* + Copyright 2008-2014 David Robillard + + Permission to use, copy, modify, and/or distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +*/ + +#ifndef LV2_ATOM_ATOM_HPP +#define LV2_ATOM_ATOM_HPP + +#include "lv2/lv2plug.in/ns/ext/atom/atom.h" +#include "lv2/lv2plug.in/ns/ext/atom/util.h" + +namespace lv2 { +namespace atom { + +typedef LV2_Atom Atom; + +struct Event : public LV2_Atom_Event +{ + inline uint32_t type() const { return body.type; } + inline uint32_t size() const { return body.size; } + + /** Convenience accessor for byte-oriented payloads. */ + inline uint8_t operator[](size_t i) const { + return *((const uint8_t*)(&body + 1) + i); + } +}; + +class Sequence : public LV2_Atom_Sequence +{ +public: + class const_iterator { + public: + inline const_iterator(const Event* ev) : m_ev(ev) {} + + inline const_iterator operator++() { + m_ev = (const Event*)( + (const uint8_t*)m_ev + + sizeof(LV2_Atom_Event) + + lv2_atom_pad_size(m_ev->body.size)); + return *this; + } + + inline bool operator==(const const_iterator& i) const { + return m_ev == i.m_ev; + } + + inline bool operator!=(const const_iterator& i) const { + return m_ev != i.m_ev; + } + + inline const Event& operator*() const { return *m_ev; } + inline const Event* operator->() const { return m_ev; } + + private: + const Event* m_ev; + }; + + inline const_iterator begin() const { + return const_iterator((const Event*)(&body + 1)); + } + + inline const_iterator end() const { + return const_iterator((const Event*)((const char*)&body + atom.size)); + } +}; + +} // namespace atom +} // namespace lv2 + +#endif // LV2_ATOM_ATOM_HPP diff --git a/lv2/lv2plug.in/ns/ext/urid/urid.hpp b/lv2/lv2plug.in/ns/ext/urid/urid.hpp new file mode 100644 index 0000000..38fa8be --- /dev/null +++ b/lv2/lv2plug.in/ns/ext/urid/urid.hpp @@ -0,0 +1,114 @@ +/* + Copyright 2015 David Robillard + + Permission to use, copy, modify, and/or distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +*/ + +#ifndef LV2_URID_HPP +#define LV2_URID_HPP + +#include "lv2/lv2plug.in/ns/lv2core/Feature.hpp" +#include "lv2/lv2plug.in/ns/ext/urid/urid.h" + +namespace lv2 { +namespace urid { + +/** + URI mapped to an integer. +*/ +typedef LV2_URID URID; + +/** + URID Map Feature (LV2_URID__map) +*/ +template +class Map : public Feature +{ +public: + Map(const LV2_Feature*const* features, + bool* valid) + : Feature(features, LV2_URID__map, valid) + {} + + /** + Get the numeric ID of a URI. + + If the ID does not already exist, it will be created. + + This function is referentially transparent; any number of calls with the + same arguments is guaranteed to return the same value over the life of a + plugin instance. Note, however, that several URIs MAY resolve to the + same ID if the host considers those URIs equivalent. + + This function is not necessarily very fast or RT-safe: plugins SHOULD + cache any IDs they might need in performance critical situations. + + The return value 0 is reserved and indicates that an ID for that URI + could not be created for whatever reason. However, hosts SHOULD NOT + return 0 from this function in non-exceptional circumstances (i.e. the + URI map SHOULD be dynamic). + + @param handle Must be the callback_data member of this struct. + @param uri The URI to be mapped to an integer ID. + */ + LV2_URID map(const char* uri) { + return this->m_data->map(this->m_data->handle, uri); + } + + /** + Convenience wrapper for calling map(). + */ + LV2_URID operator()(const char* uri) { return map(uri); } +}; + +/** + URI Unmap Feature (LV2_URID__unmap) +*/ +template +class Unmap : public Feature +{ +public: + Unmap(const LV2_Feature*const* features, + bool* valid) + : Feature(features, LV2_URID__unmap, valid) + {} + + /** + Get the URI for a previously mapped numeric ID. + + Returns NULL if `urid` is not yet mapped. Otherwise, the corresponding + URI is returned in a canonical form. This MAY not be the exact same + string that was originally passed to LV2_URID_Map::map(), but it MUST be + an identical URI according to the URI syntax specification (RFC3986). A + non-NULL return for a given `urid` will always be the same for the life + of the plugin. Plugins that intend to perform string comparison on + unmapped URIs SHOULD first canonicalise URI strings with a call to + map_uri() followed by a call to unmap_uri(). + + @param handle Must be the callback_data member of this struct. + @param urid The ID to be mapped back to the URI string. + */ + const char* unmap(LV2_URID urid) { + return this->m_data->unmap(this->m_data->handle, urid); + } + + /** + Convenience wrapper for calling unmap(). + */ + const char* operator()(LV2_URID urid) { return unmap(urid); } +}; + +} // namespace urid +} // namespace lv2 + +#endif // LV2_URID_HPP diff --git a/lv2/lv2plug.in/ns/lv2core/Feature.hpp b/lv2/lv2plug.in/ns/lv2core/Feature.hpp new file mode 100644 index 0000000..81be218 --- /dev/null +++ b/lv2/lv2plug.in/ns/lv2core/Feature.hpp @@ -0,0 +1,74 @@ +/* + Copyright 2015 David Robillard + + Permission to use, copy, modify, and/or distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +*/ + +#ifndef LV2_FEATURE_HPP +#define LV2_FEATURE_HPP + +#include + +#include "lv2/lv2plug.in/ns/lv2core/lv2.h" +#include "lv2/lv2plug.in/ns/ext/urid/urid.h" + +namespace lv2 { + +/** + Feature. + + Features allow hosts to make additional functionality available to plugins + without requiring modification to the LV2 API. Extensions may define new + features and specify the `URI` and `data` to be used if necessary. + Some features, such as lv2:isLive, do not require the host to pass data. +*/ +template +class Feature +{ +public: + /** + Initialize feature by retrieving data from the host. + + @param features Feature array passed by the host. + @param uri URI of this feature. + @param valid Set to false iff feature is required but unsupported. + */ + Feature(const LV2_Feature*const* features, + const char* uri, + bool* valid) + : m_data(nullptr) + , m_supported(false) + { + for (const LV2_Feature*const* f = features; *f; ++f) { + if (!strcmp((*f)->URI, uri)) { + m_data = (Data*)(*f)->data; + m_supported = true; + break; + } + } + if (Required && !m_supported) { + *valid = false; + } + } + + Data* data() const { return m_data; } + bool supported() const { return m_supported; } + +protected: + Data* m_data; + bool m_supported; +}; + +} // namespace lv2 + +#endif // LV2_URID_HPP diff --git a/lv2/lv2plug.in/ns/lv2core/Lib.hpp b/lv2/lv2plug.in/ns/lv2core/Lib.hpp new file mode 100644 index 0000000..5d7670b --- /dev/null +++ b/lv2/lv2plug.in/ns/lv2core/Lib.hpp @@ -0,0 +1,81 @@ +/* + Copyright 2015 David Robillard + + Permission to use, copy, modify, and/or distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +*/ + +#ifndef LV2_LIB_HPP +#define LV2_LIB_HPP + +#include "lv2/lv2plug.in/ns/lv2core/Plugin.hpp" + +namespace lv2 { + +/** + C++ wrapper for an LV2 plugin library. + + This interface is a convenience for plugin authors only, and is not an ABI + used by hosts. Plugin authors should inherit from this interface, passing + their derived class as the template parameter, and provide an + lv2_lib_descriptor entry point in C: + + @code + class MyLib : public lv2::Lib { ... }; + + LV2_SYMBOL_EXPORT static const LV2_Lib_Descriptor* + lv2_lib_descriptor(const char* bundle_path, + const LV2_Feature *const * features) + { + return new MyLib(bundle_path, features); + } + @endcode +*/ +template +class Lib : public LV2_Lib_Descriptor +{ +public: + /** + Library constructor. + */ + Lib(const char* bundle_path, + const LV2_Feature*const* features) + { + LV2_Lib_Descriptor::handle = this; + LV2_Lib_Descriptor::size = sizeof(LV2_Lib_Descriptor); + LV2_Lib_Descriptor::cleanup = s_cleanup; + LV2_Lib_Descriptor::get_plugin = s_get_plugin; + } + + /** + Plugin accessor, override to return your plugin descriptors. + + Plugins are accessed by index using values from 0 upwards. Out of range + indices MUST result in this function returning NULL, so the host can + enumerate plugins by increasing `index` until NULL is returned. + */ + const LV2_Descriptor* get_plugin(uint32_t index) { return NULL; } + +private: + static void s_cleanup(LV2_Lib_Handle handle) { + delete reinterpret_cast(handle); + } + + static const LV2_Descriptor* s_get_plugin(LV2_Lib_Handle handle, + uint32_t index) { + return reinterpret_cast(handle)->get_plugin(index); + } +}; + +} /* namespace lv2 */ + +#endif /* LV2_LIB_HPP */ diff --git a/lv2/lv2plug.in/ns/lv2core/Plugin.hpp b/lv2/lv2plug.in/ns/lv2core/Plugin.hpp new file mode 100644 index 0000000..f671640 --- /dev/null +++ b/lv2/lv2plug.in/ns/lv2core/Plugin.hpp @@ -0,0 +1,260 @@ +/* + Copyright 2015 David Robillard + + Permission to use, copy, modify, and/or distribute this software for any + purpose with or without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + + THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +*/ + +#ifndef LV2_PLUGIN_HPP +#define LV2_PLUGIN_HPP + +#include "lv2/lv2plug.in/ns/lv2core/lv2.h" + +namespace lv2 { + +/** + C++ interface for writing an LV2 plugin. + + This interface is a convenience for plugin authors only, and is not an ABI + used by hosts. To implement a plugin, inherit from this interface with the + derived class passed as the template parameter. The C LV2_Descriptor for the + plugin can be fetched with descriptor(). + + @code + class MyPlug : public lv2::Plugin { + // ... + }; + + static const LV2_Descriptor p = MyPlug::descriptor("http://example.org/plug"); + @endcode + + This class is a stateless interface and imposes no restrictions or overhead + compared to a plugin implemented using the underlying C interface. Note + that this is not a virtual class, so calling methods from a Plugin* base + pointer will not work. Instead, anything that must dispatch on Plugin + methods takes a template parameter for static dispatch. + + The destructor will be called when the host cleans up the plugin. +*/ +template +class Plugin +{ +public: + /** + Instantiate the plugin. + + Note that instance initialisation should generally occur in activate() + rather than here. If a host calls instantiate(), it MUST call cleanup() + at some point in the future. + + @param sample_rate Sample rate, in Hz, for the new plugin instance. + + @param bundle_path Path to the LV2 bundle which contains this plugin + binary. It MUST include the trailing directory separator (e.g. '/') so + that simply appending a filename will yield the path to that file in the + bundle. + + @param features A NULL terminated array of LV2_Feature structs which + represent the features the host supports. Plugins may refuse to + instantiate if required features are not found here. However, hosts MUST + NOT use this as a discovery mechanism: instead, use the RDF data to + determine which features are required and do not attempt to instantiate + unsupported plugins at all. This parameter MUST NOT be NULL, i.e. a host + that supports no features MUST pass a single element array containing + NULL. + + @param valid A pointer to a boolean that must be set to true if the + plugin instantiates correctly. The C++ wrappers will free the instance + and return NULL to the host automatically on failure. + + @return A handle for the new plugin instance, or NULL if instantiation + has failed. + */ + Plugin(double sample_rate, + const char* bundle_path, + const LV2_Feature*const* features, + bool* valid) + {} + + /** + Connect a port on a plugin instance to a memory location. + + Plugin writers should be aware that the host may elect to use the same + buffer for more than one port and even use the same buffer for both + input and output (see lv2:inPlaceBroken in lv2.ttl). + + If the plugin has the feature lv2:hardRTCapable then there are various + things that the plugin MUST NOT do within the connect_port() function; + see lv2core.ttl for details. + + connect_port() MUST be called at least once for each port before run() + is called, unless that port is lv2:connectionOptional. The plugin must + pay careful attention to the block size passed to run() since the block + allocated may only just be large enough to contain the data, and is not + guaranteed to remain constant between run() calls. + + connect_port() may be called more than once for a plugin instance to + allow the host to change the buffers that the plugin is reading or + writing. These calls may be made before or after activate() or + deactivate() calls. + + @param port Index of the port to connect. The host MUST NOT try to + connect a port index that is not defined in the plugin's RDF data. If + it does, the plugin's behaviour is undefined (a crash is likely). + + @param data_location Pointer to data of the type defined by the port + type in the plugin's RDF data (e.g. an array of float for an + lv2:AudioPort). This pointer must be stored by the plugin instance and + used to read/write data when run() is called. Data present at the time + of the connect_port() call MUST NOT be considered meaningful. + */ + void connect_port(uint32_t port, void* data_location) {} + + /** + Initialise a plugin instance and activate it for use. + + This is separated from instantiate() to aid real-time support and so + that hosts can reinitialise a plugin instance by calling deactivate() + and then activate(). In this case the plugin instance MUST reset all + state information dependent on the history of the plugin instance except + for any data locations provided by connect_port(). If there is nothing + for activate() to do then this field may be NULL. + + When present, hosts MUST call this function once before run() is called + for the first time. This call SHOULD be made as close to the run() call + as possible and indicates to real-time plugins that they are now live, + however plugins MUST NOT rely on a prompt call to run() after + activate(). + + The host MUST NOT call activate() again until deactivate() has been + called first. If a host calls activate(), it MUST call deactivate() at + some point in the future. Note that connect_port() may be called before + or after activate(). + */ + void activate() {} + + /** + Run a plugin instance for a block. + + Note that if an activate() function exists then it must be called before + run(). If deactivate() is called for a plugin instance then run() may + not be called until activate() has been called again. + + If the plugin has the feature lv2:hardRTCapable then there are various + things that the plugin MUST NOT do within the run() function (see + lv2core.ttl for details). + + As a special case, when `sample_count` is 0, the plugin should update + any output ports that represent a single instant in time (e.g. control + ports, but not audio ports). This is particularly useful for latent + plugins, which should update their latency output port so hosts can + pre-roll plugins to compute latency. Plugins MUST NOT crash when + `sample_count` is 0. + + @param sample_count The block size (in samples) for which the plugin + instance must run. + */ + void run(uint32_t sample_count) {} + + /** + Deactivate a plugin instance (counterpart to activate()). + + Hosts MUST deactivate all activated instances after they have been run() + for the last time. This call SHOULD be made as close to the last run() + call as possible and indicates to real-time plugins that they are no + longer live, however plugins MUST NOT rely on prompt deactivation. If + there is nothing for deactivate() to do then this field may be NULL + + Deactivation is not similar to pausing since the plugin instance will be + reinitialised by activate(). However, deactivate() itself MUST NOT fully + reset plugin state. For example, the host may deactivate a plugin, then + store its state (using some extension to do so). + + Hosts MUST NOT call deactivate() unless activate() was previously + called. Note that connect_port() may be called before or after + deactivate(). + */ + void deactivate() {} + + /** + Return additional plugin data defined by some extenion. + + A typical use of this facility is to return a struct containing function + pointers to extend the LV2_Descriptor API. + + The actual type and meaning of the returned object MUST be specified + precisely by the extension. This function MUST return NULL for any + unsupported URI. If a plugin does not support any extension data, this + field may be NULL. + + The host is never responsible for freeing the returned value. + */ + static const void* extension_data(const char* uri) { return NULL; } + + /** + Get an LV2_Descriptor for a plugin class. + + @code + static const LV2_Descriptor a = lv2::descriptor("http://example.org/amp"); + @endcode + */ + static LV2_Descriptor descriptor(const char* uri) { + const LV2_Descriptor desc = { uri, + &s_instantiate, + &s_connect_port, + &s_activate, + &s_run, + &s_deactivate, + &s_cleanup, + &Plugin::extension_data }; + return desc; + } + +private: + static LV2_Handle s_instantiate(const LV2_Descriptor* descriptor, + double rate, + const char* bundle, + const LV2_Feature* const* features) { + bool valid = true; + Derived* instance = new Derived(rate, bundle, features, &valid); + if (!valid) { + delete instance; + return nullptr; + } + return reinterpret_cast(instance); + } + + static void s_connect_port(LV2_Handle instance, uint32_t port, void* buf) { + reinterpret_cast(instance)->connect_port(port, buf); + } + + static void s_activate(LV2_Handle instance) { + reinterpret_cast(instance)->activate(); + } + + static void s_run(LV2_Handle instance, uint32_t sample_count) { + reinterpret_cast(instance)->run(sample_count); + } + + static void s_deactivate(LV2_Handle instance) { + reinterpret_cast(instance)->deactivate(); + } + + static void s_cleanup(LV2_Handle instance) { + delete reinterpret_cast(instance); + } +}; + +} /* namespace lv2 */ + +#endif /* LV2_PLUGIN_HPP */ + -- cgit v1.2.1