annotate vamp-hostsdk/PluginInputDomainAdapter.h @ 288:283e15f6e548

* The beginnings of making the shift-timestamp or shift-data behaviour of PluginInputDomainAdapter into an option
author cannam
date Tue, 15 Sep 2009 16:24:53 +0000
parents 4454843ff384
children c97e70ed5abc
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
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_INPUT_DOMAIN_ADAPTER_H_
cannam@233 38 #define _VAMP_PLUGIN_INPUT_DOMAIN_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(PluginInputDomainAdapter.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 PluginInputDomainAdapter PluginInputDomainAdapter.h <vamp-hostsdk/PluginInputDomainAdapter.h>
cannam@233 51 *
cannam@233 52 * PluginInputDomainAdapter is a Vamp plugin adapter that converts
cannam@233 53 * time-domain input into frequency-domain input for plugins that need
cannam@233 54 * it. This permits a host to use time- and frequency-domain plugins
cannam@233 55 * interchangeably without needing to handle the conversion itself.
cannam@233 56 *
cannam@233 57 * This adapter uses a basic Hanning windowed FFT that supports
cannam@233 58 * power-of-two block sizes only. If a frequency domain plugin
cannam@233 59 * requests a non-power-of-two blocksize, the adapter will adjust it
cannam@233 60 * to a nearby power of two instead. Thus, getPreferredBlockSize()
cannam@233 61 * will always return a power of two if the wrapped plugin is a
cannam@233 62 * frequency domain one. If the plugin doesn't accept the adjusted
cannam@233 63 * power of two block size, initialise() will fail.
cannam@233 64 *
cannam@233 65 * The adapter provides no way for the host to discover whether the
cannam@233 66 * underlying plugin is actually a time or frequency domain plugin
cannam@233 67 * (except that if the preferred block size is not a power of two, it
cannam@233 68 * must be a time domain plugin).
cannam@233 69 *
cannam@233 70 * The FFT implementation is simple and self-contained, but unlikely
cannam@233 71 * to be the fastest available: a host can usually do better if it
cannam@233 72 * cares enough.
cannam@233 73 *
cannam@233 74 * In every respect other than its input domain handling, the
cannam@233 75 * PluginInputDomainAdapter behaves identically to the plugin that it
cannam@233 76 * wraps. The wrapped plugin will be deleted when the wrapper is
cannam@233 77 * deleted.
cannam@233 78 *
cannam@233 79 * \note This class was introduced in version 1.1 of the Vamp plugin SDK.
cannam@233 80 */
cannam@233 81
cannam@233 82 class PluginInputDomainAdapter : public PluginWrapper
cannam@233 83 {
cannam@233 84 public:
cannam@248 85 /**
cannam@248 86 * Construct a PluginInputDomainAdapter wrapping the given plugin.
cannam@248 87 * The adapter takes ownership of the plugin, which will be
cannam@248 88 * deleted when the adapter is deleted.
cannam@248 89 */
cannam@248 90 PluginInputDomainAdapter(Plugin *plugin);
cannam@233 91 virtual ~PluginInputDomainAdapter();
cannam@233 92
cannam@233 93 bool initialise(size_t channels, size_t stepSize, size_t blockSize);
cannam@288 94 void reset();
cannam@233 95
cannam@233 96 InputDomain getInputDomain() const;
cannam@233 97
cannam@233 98 size_t getPreferredStepSize() const;
cannam@233 99 size_t getPreferredBlockSize() const;
cannam@233 100
cannam@233 101 FeatureSet process(const float *const *inputBuffers, RealTime timestamp);
cannam@233 102
cannam@233 103 /**
cannam@288 104 * ProcessTimestampMethod determines how the
cannam@288 105 * PluginInputDomainAdapter handles timestamps for the data passed
cannam@288 106 * to the process() function of the plugin it wraps, in the case
cannam@288 107 * where the plugin is expecting frequency-domain data.
cannam@288 108 *
cannam@288 109 *
cannam@288 110 * The Vamp API mandates that the timestamp passed to the plugin
cannam@288 111 * for time-domain input should be the time of the first sample in
cannam@288 112 * the block, but the timestamp passed for frequency-domain input
cannam@288 113 * should be the timestamp of the centre of the block.
cannam@288 114 *
cannam@288 115 * Since we claim to permit the code that uses this plugin wrapper
cannam@288 116 * not to care whether the plugin itself has time or frequency
cannam@288 117 * domain input, that means that we need to ensure this timestamp
cannam@288 118 * is correctly adjusted ourselves, and the way we handle this is
cannam@288 119 * controlled by the ProcessTimestampMethod.
cannam@288 120 *
cannam@288 121 * If ProcessTimestampMethod is ShiftTimestamp (the default), then
cannam@288 122 * the data passed to the wrapped plugin will be calculated from
cannam@288 123 * the same input data block as passed to the wrapper, but the
cannam@288 124 * timestamp passed to the plugin will be advanced by half of the
cannam@288 125 * window size.
cannam@288 126 *
cannam@288 127 * If ProcessTimestampMethod is ShiftData, then the timestamp
cannam@288 128 * passed to the wrapped plugin will be the same as that passed to
cannam@288 129 * the process call of the wrapper, but the data block used to
cannam@288 130 * calculate the input will be shifted back (earlier) by half of
cannam@288 131 * the window size, with half a block of padding at the start of
cannam@288 132 * the first process call.
cannam@288 133 *
cannam@288 134 * This function must be called before the first call to
cannam@288 135 * process().
cannam@288 136 */
cannam@288 137 enum ProcessTimestampMethod {
cannam@288 138 ShiftTimestamp,
cannam@288 139 ShiftData
cannam@288 140 };
cannam@288 141
cannam@288 142 void setProcessTimestampMethod(ProcessTimestampMethod);
cannam@288 143 ProcessTimestampMethod getProcessTimestampMethod() const;
cannam@288 144
cannam@288 145 /**
cannam@233 146 * Return the amount by which the timestamps supplied to process()
cannam@233 147 * are being incremented when they are passed to the plugin's own
cannam@233 148 * process() implementation.
cannam@233 149 *
cannam@233 150 * The Vamp API mandates that the timestamp passed to the plugin
cannam@233 151 * for time-domain input should be the time of the first sample in
cannam@233 152 * the block, but the timestamp passed for frequency-domain input
cannam@233 153 * should be the timestamp of the centre of the block.
cannam@233 154 *
cannam@233 155 * The PluginInputDomainAdapter adjusts its timestamps properly so
cannam@233 156 * that the plugin receives correct times, but in some
cannam@233 157 * circumstances (such as for establishing the correct timing of
cannam@233 158 * implicitly-timed features, i.e. features without their own
cannam@233 159 * timestamps) the host may need to be aware that this adjustment
cannam@233 160 * is taking place.
cannam@233 161 *
cannam@288 162 * If the plugin requires time-domain input or the
cannam@288 163 * PluginInputDomainAdapter is configured with its
cannam@288 164 * ProcessTimestampMethod set to ShiftData instead of
cannam@288 165 * ShiftTimestamp, then this function will return zero.
cannam@288 166 *
cannam@288 167 * The result of calling this function before initialise() has
cannam@288 168 * been called is undefined.
cannam@233 169 */
cannam@233 170 RealTime getTimestampAdjustment() const;
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@263 181 _VAMP_SDK_HOSTSPACE_END(PluginInputDomainAdapter.h)
cannam@263 182
cannam@233 183 #endif