annotate vamp-sdk/hostext/PluginChannelAdapter.h @ 75:0f8524203677

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