annotate vamp-hostsdk/PluginBufferingAdapter.h @ 541:0e32c328b02a tip

Added tag vamp-plugin-sdk-v2.10 for changeset fa74c473e48c
author Chris Cannam
date Mon, 18 May 2020 11:53:49 +0100
parents 8ffb8985ae8f
children
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 This file by Mark Levy and Chris Cannam, Copyright 2007-2008 QMUL.
cannam@233 11
cannam@233 12 Permission is hereby granted, free of charge, to any person
cannam@233 13 obtaining a copy of this software and associated documentation
cannam@233 14 files (the "Software"), to deal in the Software without
cannam@233 15 restriction, including without limitation the rights to use, copy,
cannam@233 16 modify, merge, publish, distribute, sublicense, and/or sell copies
cannam@233 17 of the Software, and to permit persons to whom the Software is
cannam@233 18 furnished to do so, subject to the following conditions:
cannam@233 19
cannam@233 20 The above copyright notice and this permission notice shall be
cannam@233 21 included in all copies or substantial portions of the Software.
cannam@233 22
cannam@233 23 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
cannam@233 24 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
cannam@233 25 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
cannam@233 26 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
cannam@233 27 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
cannam@233 28 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
cannam@233 29 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
cannam@233 30
cannam@233 31 Except as contained in this notice, the names of the Centre for
cannam@233 32 Digital Music; Queen Mary, University of London; and Chris Cannam
cannam@233 33 shall not be used in advertising or otherwise to promote the sale,
cannam@233 34 use or other dealings in this Software without prior written
cannam@233 35 authorization.
cannam@233 36 */
cannam@233 37
cannam@233 38 #ifndef _VAMP_PLUGIN_BUFFERING_ADAPTER_H_
cannam@233 39 #define _VAMP_PLUGIN_BUFFERING_ADAPTER_H_
cannam@233 40
cannam@243 41 #include "hostguard.h"
cannam@233 42 #include "PluginWrapper.h"
cannam@233 43
cannam@263 44 _VAMP_SDK_HOSTSPACE_BEGIN(PluginBufferingAdapter.h)
cannam@263 45
cannam@233 46 namespace Vamp {
cannam@233 47
cannam@233 48 namespace HostExt {
cannam@233 49
cannam@233 50 /**
cannam@233 51 * \class PluginBufferingAdapter PluginBufferingAdapter.h <vamp-hostsdk/PluginBufferingAdapter.h>
cannam@233 52 *
cannam@233 53 * PluginBufferingAdapter is a Vamp plugin adapter that allows plugins
cannam@233 54 * to be used by a host supplying an audio stream in non-overlapping
cannam@233 55 * buffers of arbitrary size.
cannam@233 56 *
cannam@233 57 * A host using PluginBufferingAdapter may ignore the preferred step
cannam@233 58 * and block size reported by the plugin, and still expect the plugin
cannam@233 59 * to run. The value of blockSize and stepSize passed to initialise
cannam@233 60 * should be the size of the buffer which the host will supply; the
cannam@233 61 * stepSize should be equal to the blockSize.
cannam@233 62 *
cannam@233 63 * If the internal step size used for the plugin differs from that
cannam@233 64 * supplied by the host, the adapter will modify the sample type and
cannam@233 65 * rate specifications for the plugin outputs appropriately, and set
cannam@233 66 * timestamps on the output features for outputs that formerly used a
cannam@233 67 * different sample rate specification. This is necessary in order to
cannam@233 68 * obtain correct time stamping.
cannam@233 69 *
cannam@233 70 * In other respects, the PluginBufferingAdapter behaves identically
cannam@233 71 * to the plugin that it wraps. The wrapped plugin will be deleted
Chris@538 72 * when the wrapper is deleted. If you wish to prevent this, call
Chris@538 73 * disownPlugin().
cannam@233 74 */
cannam@233 75
cannam@233 76 class PluginBufferingAdapter : public PluginWrapper
cannam@233 77 {
cannam@233 78 public:
cannam@248 79 /**
cannam@248 80 * Construct a PluginBufferingAdapter wrapping the given plugin.
cannam@248 81 * The adapter takes ownership of the plugin, which will be
Chris@538 82 * deleted when the adapter is deleted. If you wish to prevent
Chris@538 83 * this, call disownPlugin().
cannam@248 84 */
cannam@248 85 PluginBufferingAdapter(Plugin *plugin);
cannam@233 86 virtual ~PluginBufferingAdapter();
cannam@233 87
cannam@233 88 /**
cannam@233 89 * Return the preferred step size for this adapter.
cannam@233 90 *
cannam@233 91 * Because of the way this adapter works, its preferred step size
cannam@233 92 * will always be the same as its preferred block size. This may
cannam@233 93 * or may not be the same as the preferred step size of the
cannam@233 94 * underlying plugin, which may be obtained by calling
cannam@233 95 * getPluginPreferredStepSize().
cannam@233 96 */
cannam@233 97 size_t getPreferredStepSize() const;
cannam@233 98
cannam@233 99 /**
cannam@233 100 * Return the preferred block size for this adapter.
cannam@233 101 *
cannam@233 102 * This may or may not be the same as the preferred block size of
cannam@233 103 * the underlying plugin, which may be obtained by calling
cannam@233 104 * getPluginPreferredBlockSize().
cannam@233 105 *
cannam@233 106 * Note that this adapter may be initialised with any block size,
cannam@233 107 * not just its supposedly preferred one.
cannam@233 108 */
cannam@233 109 size_t getPreferredBlockSize() const;
cannam@233 110
cannam@233 111 /**
cannam@233 112 * Initialise the adapter (and therefore the plugin) for the given
cannam@233 113 * number of channels. Initialise the adapter for the given step
cannam@233 114 * and block size, which must be equal.
cannam@233 115 *
cannam@233 116 * The step and block size used for the underlying plugin will
cannam@233 117 * depend on its preferences, or any values previously passed to
cannam@233 118 * setPluginStepSize and setPluginBlockSize.
cannam@233 119 */
cannam@233 120 bool initialise(size_t channels, size_t stepSize, size_t blockSize);
cannam@233 121
cannam@233 122 /**
cannam@233 123 * Return the preferred step size of the plugin wrapped by this
cannam@233 124 * adapter.
cannam@233 125 *
cannam@233 126 * This is included mainly for informational purposes. This value
cannam@233 127 * is not likely to be a valid step size for the adapter itself,
cannam@233 128 * and it is not usually of any use in interpreting the results
cannam@233 129 * (because the adapter re-writes OneSamplePerStep outputs to
cannam@233 130 * FixedSampleRate so that the hop size no longer needs to be
cannam@233 131 * known beforehand in order to interpret them).
cannam@233 132 */
cannam@233 133 size_t getPluginPreferredStepSize() const;
cannam@233 134
cannam@233 135 /**
cannam@233 136 * Return the preferred block size of the plugin wrapped by this
cannam@233 137 * adapter.
cannam@233 138 *
cannam@233 139 * This is included mainly for informational purposes.
cannam@233 140 */
cannam@233 141 size_t getPluginPreferredBlockSize() const;
cannam@233 142
cannam@233 143 /**
cannam@233 144 * Set the step size that will be used for the underlying plugin
cannam@233 145 * when initialise() is called. If this is not set, the plugin's
cannam@233 146 * own preferred step size will be used. You will not usually
cannam@233 147 * need to call this function. If you do call it, it must be
cannam@233 148 * before the first call to initialise().
cannam@233 149 */
cannam@233 150 void setPluginStepSize(size_t stepSize);
cannam@233 151
cannam@233 152 /**
cannam@233 153 * Set the block size that will be used for the underlying plugin
cannam@233 154 * when initialise() is called. If this is not set, the plugin's
cannam@233 155 * own preferred block size will be used. You will not usually
cannam@233 156 * need to call this function. If you do call it, it must be
cannam@233 157 * before the first call to initialise().
cannam@233 158 */
cannam@233 159 void setPluginBlockSize(size_t blockSize);
cannam@233 160
cannam@233 161 /**
cannam@233 162 * Return the step and block sizes that were actually used when
cannam@233 163 * initialising the underlying plugin.
cannam@233 164 *
cannam@233 165 * This is included mainly for informational purposes. You will
cannam@233 166 * not usually need to call this function. If this is called
cannam@233 167 * before initialise(), it will return 0 for both values. If it
cannam@233 168 * is called after a failed call to initialise(), it will return
cannam@233 169 * the values that were used in the failed call to the plugin's
cannam@233 170 * initialise() function.
cannam@233 171 */
cannam@233 172 void getActualStepAndBlockSizes(size_t &stepSize, size_t &blockSize);
cannam@233 173
cannam@267 174 void setParameter(std::string, float);
cannam@267 175 void selectProgram(std::string);
cannam@267 176
cannam@233 177 OutputList getOutputDescriptors() const;
cannam@233 178
cannam@233 179 void reset();
cannam@233 180
cannam@233 181 FeatureSet process(const float *const *inputBuffers, RealTime timestamp);
cannam@233 182
cannam@233 183 FeatureSet getRemainingFeatures();
cannam@233 184
cannam@233 185 protected:
cannam@233 186 class Impl;
cannam@233 187 Impl *m_impl;
cannam@233 188 };
cannam@233 189
cannam@233 190 }
cannam@233 191
cannam@233 192 }
cannam@233 193
cannam@263 194 _VAMP_SDK_HOSTSPACE_END(PluginBufferingAdapter.h)
cannam@263 195
cannam@233 196 #endif