annotate vamp-hostsdk/PluginChannelAdapter.h @ 519:be688783aa37 vamp-plugin-sdk-v2.8

Correct release date
author Chris Cannam
date Thu, 07 Feb 2019 10:19:39 +0000
parents c97e70ed5abc
children 8ffb8985ae8f
rev   line source
cannam@233 1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
cannam@233 2
cannam@233 3 /*
cannam@233 4 Vamp
cannam@233 5
cannam@233 6 An API for audio analysis and feature extraction plugins.
cannam@233 7
cannam@233 8 Centre for Digital Music, Queen Mary, University of London.
cannam@290 9 Copyright 2006-2009 Chris Cannam and QMUL.
cannam@233 10
cannam@233 11 Permission is hereby granted, free of charge, to any person
cannam@233 12 obtaining a copy of this software and associated documentation
cannam@233 13 files (the "Software"), to deal in the Software without
cannam@233 14 restriction, including without limitation the rights to use, copy,
cannam@233 15 modify, merge, publish, distribute, sublicense, and/or sell copies
cannam@233 16 of the Software, and to permit persons to whom the Software is
cannam@233 17 furnished to do so, subject to the following conditions:
cannam@233 18
cannam@233 19 The above copyright notice and this permission notice shall be
cannam@233 20 included in all copies or substantial portions of the Software.
cannam@233 21
cannam@233 22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
cannam@233 23 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
cannam@233 24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
cannam@233 25 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
cannam@233 26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
cannam@233 27 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
cannam@233 28 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
cannam@233 29
cannam@233 30 Except as contained in this notice, the names of the Centre for
cannam@233 31 Digital Music; Queen Mary, University of London; and Chris Cannam
cannam@233 32 shall not be used in advertising or otherwise to promote the sale,
cannam@233 33 use or other dealings in this Software without prior written
cannam@233 34 authorization.
cannam@233 35 */
cannam@233 36
cannam@233 37 #ifndef _VAMP_PLUGIN_CHANNEL_ADAPTER_H_
cannam@233 38 #define _VAMP_PLUGIN_CHANNEL_ADAPTER_H_
cannam@233 39
cannam@243 40 #include "hostguard.h"
cannam@233 41 #include "PluginWrapper.h"
cannam@233 42
cannam@263 43 _VAMP_SDK_HOSTSPACE_BEGIN(PluginChannelAdapter.h)
cannam@263 44
cannam@233 45 namespace Vamp {
cannam@233 46
cannam@233 47 namespace HostExt {
cannam@233 48
cannam@233 49 /**
cannam@233 50 * \class PluginChannelAdapter PluginChannelAdapter.h <vamp-hostsdk/PluginChannelAdapter.h>
cannam@233 51 *
cannam@233 52 * PluginChannelAdapter is a Vamp plugin adapter that implements a
cannam@233 53 * policy for management of plugins that expect a different number of
cannam@233 54 * input channels from the number actually available in the source
cannam@233 55 * audio data.
cannam@233 56 *
cannam@233 57 * A host using PluginChannelAdapter may ignore the getMinChannelCount
cannam@233 58 * and getMaxChannelCount reported by the plugin, and still expect the
cannam@233 59 * plugin to run.
cannam@233 60 *
cannam@233 61 * PluginChannelAdapter implements the following policy:
cannam@233 62 *
cannam@233 63 * - If the plugin supports the provided number of channels directly,
cannam@233 64 * PluginChannelAdapter will just run the plugin as normal.
cannam@233 65 *
cannam@233 66 * - If the plugin only supports exactly one channel but more than
cannam@233 67 * one channel is provided, PluginChannelAdapter will use the mean of
cannam@233 68 * the channels. This ensures that the resulting values remain
cannam@233 69 * within the same magnitude range as expected for mono data.
cannam@233 70 *
cannam@233 71 * - If the plugin requires more than one channel but exactly one is
cannam@233 72 * provided, the provided channel will be duplicated across all the
cannam@233 73 * plugin input channels.
cannam@233 74 *
cannam@233 75 * If none of the above apply:
cannam@233 76 *
cannam@233 77 * - If the plugin requires more channels than are provided, the
cannam@233 78 * minimum acceptable number of channels will be produced by adding
cannam@233 79 * empty (zero valued) channels to those provided.
cannam@233 80 *
cannam@233 81 * - If the plugin requires fewer channels than are provided, the
cannam@233 82 * maximum acceptable number of channels will be produced by
cannam@233 83 * discarding the excess channels.
cannam@233 84 *
cannam@233 85 * Hosts requiring a different channel policy from the above will need
cannam@233 86 * to implement it themselves, instead of using PluginChannelAdapter.
cannam@233 87 *
cannam@233 88 * Note that PluginChannelAdapter does not override the minimum and
cannam@233 89 * maximum channel counts returned by the wrapped plugin. The host
cannam@233 90 * will need to be aware that it is using a PluginChannelAdapter, and
cannam@233 91 * be prepared to ignore these counts as necessary. (This contrasts
cannam@233 92 * with the approach used in PluginInputDomainAdapter, which aims to
cannam@233 93 * make the host completely unaware of which underlying input domain
cannam@233 94 * is in fact in use.)
cannam@233 95 *
cannam@233 96 * (The rationale for this is that a host may wish to use the
cannam@233 97 * PluginChannelAdapter but still discriminate in some way on the
cannam@233 98 * basis of the number of channels actually supported. For example, a
cannam@233 99 * simple stereo audio host may prefer to reject plugins that require
cannam@233 100 * more than two channels on the grounds that doesn't actually
cannam@233 101 * understand what they are for, rather than allow the channel adapter
cannam@233 102 * to make a potentially meaningless channel conversion for them.)
cannam@233 103 *
cannam@233 104 * In every respect other than its management of channels, the
cannam@233 105 * PluginChannelAdapter behaves identically to the plugin that it
cannam@233 106 * wraps. The wrapped plugin will be deleted when the wrapper is
cannam@233 107 * deleted.
cannam@233 108 *
cannam@233 109 * \note This class was introduced in version 1.1 of the Vamp plugin SDK.
cannam@233 110 */
cannam@233 111
cannam@233 112 class PluginChannelAdapter : public PluginWrapper
cannam@233 113 {
cannam@233 114 public:
cannam@248 115 /**
cannam@248 116 * Construct a PluginChannelAdapter wrapping the given plugin.
cannam@248 117 * The adapter takes ownership of the plugin, which will be
cannam@248 118 * deleted when the adapter is deleted.
cannam@248 119 */
cannam@248 120 PluginChannelAdapter(Plugin *plugin);
cannam@233 121 virtual ~PluginChannelAdapter();
cannam@233 122
cannam@233 123 bool initialise(size_t channels, size_t stepSize, size_t blockSize);
cannam@233 124
cannam@233 125 FeatureSet process(const float *const *inputBuffers, RealTime timestamp);
cannam@233 126
cannam@233 127 /**
cannam@233 128 * Call process(), providing interleaved audio data with the
cannam@233 129 * number of channels passed to initialise(). The adapter will
cannam@233 130 * de-interleave into temporary buffers as appropriate before
cannam@233 131 * calling process().
cannam@233 132 *
cannam@233 133 * \note This function was introduced in version 1.4 of the Vamp
cannam@233 134 * plugin SDK.
cannam@233 135 */
cannam@233 136 FeatureSet processInterleaved(const float *inputBuffer, RealTime timestamp);
cannam@233 137
cannam@233 138 protected:
cannam@233 139 class Impl;
cannam@233 140 Impl *m_impl;
cannam@233 141 };
cannam@233 142
cannam@233 143 }
cannam@233 144
cannam@233 145 }
cannam@233 146
cannam@263 147 _VAMP_SDK_HOSTSPACE_END(PluginChannelAdapter.h)
cannam@263 148
cannam@233 149 #endif