annotate vamp-hostsdk/PluginBufferingAdapter.h @ 233:521734d2b498 distinct-libraries

* Flatten directory tree a bit, update doxygen
author cannam
date Fri, 07 Nov 2008 15:28:33 +0000
parents
children 3cf5bd155e5b
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@233 9 Copyright 2006-2007 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@233 41 #include "PluginWrapper.h"
cannam@233 42
cannam@233 43 namespace Vamp {
cannam@233 44
cannam@233 45 namespace HostExt {
cannam@233 46
cannam@233 47 /**
cannam@233 48 * \class PluginBufferingAdapter PluginBufferingAdapter.h <vamp-hostsdk/PluginBufferingAdapter.h>
cannam@233 49 *
cannam@233 50 * PluginBufferingAdapter is a Vamp plugin adapter that allows plugins
cannam@233 51 * to be used by a host supplying an audio stream in non-overlapping
cannam@233 52 * buffers of arbitrary size.
cannam@233 53 *
cannam@233 54 * A host using PluginBufferingAdapter may ignore the preferred step
cannam@233 55 * and block size reported by the plugin, and still expect the plugin
cannam@233 56 * to run. The value of blockSize and stepSize passed to initialise
cannam@233 57 * should be the size of the buffer which the host will supply; the
cannam@233 58 * stepSize should be equal to the blockSize.
cannam@233 59 *
cannam@233 60 * If the internal step size used for the plugin differs from that
cannam@233 61 * supplied by the host, the adapter will modify the sample type and
cannam@233 62 * rate specifications for the plugin outputs appropriately, and set
cannam@233 63 * timestamps on the output features for outputs that formerly used a
cannam@233 64 * different sample rate specification. This is necessary in order to
cannam@233 65 * obtain correct time stamping.
cannam@233 66 *
cannam@233 67 * In other respects, the PluginBufferingAdapter behaves identically
cannam@233 68 * to the plugin that it wraps. The wrapped plugin will be deleted
cannam@233 69 * when the wrapper is deleted.
cannam@233 70 */
cannam@233 71
cannam@233 72 class PluginBufferingAdapter : public PluginWrapper
cannam@233 73 {
cannam@233 74 public:
cannam@233 75 PluginBufferingAdapter(Plugin *plugin); // I take ownership of plugin
cannam@233 76 virtual ~PluginBufferingAdapter();
cannam@233 77
cannam@233 78 /**
cannam@233 79 * Return the preferred step size for this adapter.
cannam@233 80 *
cannam@233 81 * Because of the way this adapter works, its preferred step size
cannam@233 82 * will always be the same as its preferred block size. This may
cannam@233 83 * or may not be the same as the preferred step size of the
cannam@233 84 * underlying plugin, which may be obtained by calling
cannam@233 85 * getPluginPreferredStepSize().
cannam@233 86 */
cannam@233 87 size_t getPreferredStepSize() const;
cannam@233 88
cannam@233 89 /**
cannam@233 90 * Return the preferred block size for this adapter.
cannam@233 91 *
cannam@233 92 * This may or may not be the same as the preferred block size of
cannam@233 93 * the underlying plugin, which may be obtained by calling
cannam@233 94 * getPluginPreferredBlockSize().
cannam@233 95 *
cannam@233 96 * Note that this adapter may be initialised with any block size,
cannam@233 97 * not just its supposedly preferred one.
cannam@233 98 */
cannam@233 99 size_t getPreferredBlockSize() const;
cannam@233 100
cannam@233 101 /**
cannam@233 102 * Initialise the adapter (and therefore the plugin) for the given
cannam@233 103 * number of channels. Initialise the adapter for the given step
cannam@233 104 * and block size, which must be equal.
cannam@233 105 *
cannam@233 106 * The step and block size used for the underlying plugin will
cannam@233 107 * depend on its preferences, or any values previously passed to
cannam@233 108 * setPluginStepSize and setPluginBlockSize.
cannam@233 109 */
cannam@233 110 bool initialise(size_t channels, size_t stepSize, size_t blockSize);
cannam@233 111
cannam@233 112 /**
cannam@233 113 * Return the preferred step size of the plugin wrapped by this
cannam@233 114 * adapter.
cannam@233 115 *
cannam@233 116 * This is included mainly for informational purposes. This value
cannam@233 117 * is not likely to be a valid step size for the adapter itself,
cannam@233 118 * and it is not usually of any use in interpreting the results
cannam@233 119 * (because the adapter re-writes OneSamplePerStep outputs to
cannam@233 120 * FixedSampleRate so that the hop size no longer needs to be
cannam@233 121 * known beforehand in order to interpret them).
cannam@233 122 */
cannam@233 123 size_t getPluginPreferredStepSize() const;
cannam@233 124
cannam@233 125 /**
cannam@233 126 * Return the preferred block size of the plugin wrapped by this
cannam@233 127 * adapter.
cannam@233 128 *
cannam@233 129 * This is included mainly for informational purposes.
cannam@233 130 */
cannam@233 131 size_t getPluginPreferredBlockSize() const;
cannam@233 132
cannam@233 133 /**
cannam@233 134 * Set the step size that will be used for the underlying plugin
cannam@233 135 * when initialise() is called. If this is not set, the plugin's
cannam@233 136 * own preferred step size will be used. You will not usually
cannam@233 137 * need to call this function. If you do call it, it must be
cannam@233 138 * before the first call to initialise().
cannam@233 139 */
cannam@233 140 void setPluginStepSize(size_t stepSize);
cannam@233 141
cannam@233 142 /**
cannam@233 143 * Set the block size that will be used for the underlying plugin
cannam@233 144 * when initialise() is called. If this is not set, the plugin's
cannam@233 145 * own preferred block size will be used. You will not usually
cannam@233 146 * need to call this function. If you do call it, it must be
cannam@233 147 * before the first call to initialise().
cannam@233 148 */
cannam@233 149 void setPluginBlockSize(size_t blockSize);
cannam@233 150
cannam@233 151 /**
cannam@233 152 * Return the step and block sizes that were actually used when
cannam@233 153 * initialising the underlying plugin.
cannam@233 154 *
cannam@233 155 * This is included mainly for informational purposes. You will
cannam@233 156 * not usually need to call this function. If this is called
cannam@233 157 * before initialise(), it will return 0 for both values. If it
cannam@233 158 * is called after a failed call to initialise(), it will return
cannam@233 159 * the values that were used in the failed call to the plugin's
cannam@233 160 * initialise() function.
cannam@233 161 */
cannam@233 162 void getActualStepAndBlockSizes(size_t &stepSize, size_t &blockSize);
cannam@233 163
cannam@233 164 OutputList getOutputDescriptors() const;
cannam@233 165
cannam@233 166 void reset();
cannam@233 167
cannam@233 168 FeatureSet process(const float *const *inputBuffers, RealTime timestamp);
cannam@233 169
cannam@233 170 FeatureSet getRemainingFeatures();
cannam@233 171
cannam@233 172 protected:
cannam@233 173 class Impl;
cannam@233 174 Impl *m_impl;
cannam@233 175 };
cannam@233 176
cannam@233 177 }
cannam@233 178
cannam@233 179 }
cannam@233 180
cannam@233 181 #endif