Chris@14: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */ Chris@14: Chris@14: /* Chris@14: Vamp Chris@14: Chris@14: An API for audio analysis and feature extraction plugins. Chris@14: Chris@14: Centre for Digital Music, Queen Mary, University of London. Chris@14: Copyright 2006-2009 Chris Cannam and QMUL. Chris@14: Chris@14: Permission is hereby granted, free of charge, to any person Chris@14: obtaining a copy of this software and associated documentation Chris@14: files (the "Software"), to deal in the Software without Chris@14: restriction, including without limitation the rights to use, copy, Chris@14: modify, merge, publish, distribute, sublicense, and/or sell copies Chris@14: of the Software, and to permit persons to whom the Software is Chris@14: furnished to do so, subject to the following conditions: Chris@14: Chris@14: The above copyright notice and this permission notice shall be Chris@14: included in all copies or substantial portions of the Software. Chris@14: Chris@14: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, Chris@14: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF Chris@14: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND Chris@14: NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR Chris@14: ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF Chris@14: CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION Chris@14: WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Chris@14: Chris@14: Except as contained in this notice, the names of the Centre for Chris@14: Digital Music; Queen Mary, University of London; and Chris Cannam Chris@14: shall not be used in advertising or otherwise to promote the sale, Chris@14: use or other dealings in this Software without prior written Chris@14: authorization. Chris@14: */ Chris@14: Chris@14: #ifndef _VAMP_PLUGIN_CHANNEL_ADAPTER_H_ Chris@14: #define _VAMP_PLUGIN_CHANNEL_ADAPTER_H_ Chris@14: Chris@14: #include "hostguard.h" Chris@14: #include "PluginWrapper.h" Chris@14: Chris@14: _VAMP_SDK_HOSTSPACE_BEGIN(PluginChannelAdapter.h) Chris@14: Chris@14: namespace Vamp { Chris@14: Chris@14: namespace HostExt { Chris@14: Chris@14: /** Chris@14: * \class PluginChannelAdapter PluginChannelAdapter.h Chris@14: * Chris@14: * PluginChannelAdapter is a Vamp plugin adapter that implements a Chris@14: * policy for management of plugins that expect a different number of Chris@14: * input channels from the number actually available in the source Chris@14: * audio data. Chris@14: * Chris@14: * A host using PluginChannelAdapter may ignore the getMinChannelCount Chris@14: * and getMaxChannelCount reported by the plugin, and still expect the Chris@14: * plugin to run. Chris@14: * Chris@14: * PluginChannelAdapter implements the following policy: Chris@14: * Chris@14: * - If the plugin supports the provided number of channels directly, Chris@14: * PluginChannelAdapter will just run the plugin as normal. Chris@14: * Chris@14: * - If the plugin only supports exactly one channel but more than Chris@14: * one channel is provided, PluginChannelAdapter will use the mean of Chris@14: * the channels. This ensures that the resulting values remain Chris@14: * within the same magnitude range as expected for mono data. Chris@14: * Chris@14: * - If the plugin requires more than one channel but exactly one is Chris@14: * provided, the provided channel will be duplicated across all the Chris@14: * plugin input channels. Chris@14: * Chris@14: * If none of the above apply: Chris@14: * Chris@14: * - If the plugin requires more channels than are provided, the Chris@14: * minimum acceptable number of channels will be produced by adding Chris@14: * empty (zero valued) channels to those provided. Chris@14: * Chris@14: * - If the plugin requires fewer channels than are provided, the Chris@14: * maximum acceptable number of channels will be produced by Chris@14: * discarding the excess channels. Chris@14: * Chris@14: * Hosts requiring a different channel policy from the above will need Chris@14: * to implement it themselves, instead of using PluginChannelAdapter. Chris@14: * Chris@14: * Note that PluginChannelAdapter does not override the minimum and Chris@14: * maximum channel counts returned by the wrapped plugin. The host Chris@14: * will need to be aware that it is using a PluginChannelAdapter, and Chris@14: * be prepared to ignore these counts as necessary. (This contrasts Chris@14: * with the approach used in PluginInputDomainAdapter, which aims to Chris@14: * make the host completely unaware of which underlying input domain Chris@14: * is in fact in use.) Chris@14: * Chris@14: * (The rationale for this is that a host may wish to use the Chris@14: * PluginChannelAdapter but still discriminate in some way on the Chris@14: * basis of the number of channels actually supported. For example, a Chris@14: * simple stereo audio host may prefer to reject plugins that require Chris@14: * more than two channels on the grounds that doesn't actually Chris@14: * understand what they are for, rather than allow the channel adapter Chris@14: * to make a potentially meaningless channel conversion for them.) Chris@14: * Chris@14: * In every respect other than its management of channels, the Chris@14: * PluginChannelAdapter behaves identically to the plugin that it Chris@14: * wraps. The wrapped plugin will be deleted when the wrapper is Chris@14: * deleted. Chris@14: * Chris@14: * \note This class was introduced in version 1.1 of the Vamp plugin SDK. Chris@14: */ Chris@14: Chris@14: class PluginChannelAdapter : public PluginWrapper Chris@14: { Chris@14: public: Chris@14: /** Chris@14: * Construct a PluginChannelAdapter wrapping the given plugin. Chris@14: * The adapter takes ownership of the plugin, which will be Chris@14: * deleted when the adapter is deleted. Chris@14: */ Chris@14: PluginChannelAdapter(Plugin *plugin); Chris@14: virtual ~PluginChannelAdapter(); Chris@14: Chris@14: bool initialise(size_t channels, size_t stepSize, size_t blockSize); Chris@14: Chris@14: FeatureSet process(const float *const *inputBuffers, RealTime timestamp); Chris@14: Chris@14: /** Chris@14: * Call process(), providing interleaved audio data with the Chris@14: * number of channels passed to initialise(). The adapter will Chris@14: * de-interleave into temporary buffers as appropriate before Chris@14: * calling process(). Chris@14: * Chris@14: * \note This function was introduced in version 1.4 of the Vamp Chris@14: * plugin SDK. Chris@14: */ Chris@14: FeatureSet processInterleaved(const float *inputBuffer, RealTime timestamp); Chris@14: Chris@14: protected: Chris@14: class Impl; Chris@14: Impl *m_impl; Chris@14: }; Chris@14: Chris@14: } Chris@14: Chris@14: } Chris@14: Chris@14: _VAMP_SDK_HOSTSPACE_END(PluginChannelAdapter.h) Chris@14: Chris@14: #endif