FIFOSamplePipe.h (8434B)
1 //////////////////////////////////////////////////////////////////////////////// 2 /// 3 /// 'FIFOSamplePipe' : An abstract base class for classes that manipulate sound 4 /// samples by operating like a first-in-first-out pipe: New samples are fed 5 /// into one end of the pipe with the 'putSamples' function, and the processed 6 /// samples are received from the other end with the 'receiveSamples' function. 7 /// 8 /// 'FIFOProcessor' : A base class for classes the do signal processing with 9 /// the samples while operating like a first-in-first-out pipe. When samples 10 /// are input with the 'putSamples' function, the class processes them 11 /// and moves the processed samples to the given 'output' pipe object, which 12 /// may be either another processing stage, or a fifo sample buffer object. 13 /// 14 /// Author : Copyright (c) Olli Parviainen 15 /// Author e-mail : oparviai 'at' iki.fi 16 /// SoundTouch WWW: http://www.surina.net/soundtouch 17 /// 18 //////////////////////////////////////////////////////////////////////////////// 19 // 20 // License : 21 // 22 // SoundTouch audio processing library 23 // Copyright (c) Olli Parviainen 24 // 25 // This library is free software; you can redistribute it and/or 26 // modify it under the terms of the GNU Lesser General Public 27 // License as published by the Free Software Foundation; either 28 // version 2.1 of the License, or (at your option) any later version. 29 // 30 // This library is distributed in the hope that it will be useful, 31 // but WITHOUT ANY WARRANTY; without even the implied warranty of 32 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 33 // Lesser General Public License for more details. 34 // 35 // You should have received a copy of the GNU Lesser General Public 36 // License along with this library; if not, write to the Free Software 37 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 38 // 39 //////////////////////////////////////////////////////////////////////////////// 40 41 #ifndef FIFOSamplePipe_H 42 #define FIFOSamplePipe_H 43 44 #include <assert.h> 45 #include <stdlib.h> 46 #include "STTypes.h" 47 48 namespace soundtouch 49 { 50 51 /// Abstract base class for FIFO (first-in-first-out) sample processing classes. 52 class FIFOSamplePipe 53 { 54 protected: 55 56 bool verifyNumberOfChannels(int nChannels) const 57 { 58 if ((nChannels > 0) && (nChannels <= SOUNDTOUCH_MAX_CHANNELS)) 59 { 60 return true; 61 } 62 ST_THROW_RT_ERROR("Error: Illegal number of channels"); 63 return false; 64 } 65 66 public: 67 // virtual default destructor 68 virtual ~FIFOSamplePipe() {} 69 70 71 /// Returns a pointer to the beginning of the output samples. 72 /// This function is provided for accessing the output samples directly. 73 /// Please be careful for not to corrupt the book-keeping! 74 /// 75 /// When using this function to output samples, also remember to 'remove' the 76 /// output samples from the buffer by calling the 77 /// 'receiveSamples(numSamples)' function 78 virtual SAMPLETYPE *ptrBegin() = 0; 79 80 /// Adds 'numSamples' pcs of samples from the 'samples' memory position to 81 /// the sample buffer. 82 virtual void putSamples(const SAMPLETYPE *samples, ///< Pointer to samples. 83 uint numSamples ///< Number of samples to insert. 84 ) = 0; 85 86 87 // Moves samples from the 'other' pipe instance to this instance. 88 void moveSamples(FIFOSamplePipe &other ///< Other pipe instance where from the receive the data. 89 ) 90 { 91 int oNumSamples = other.numSamples(); 92 93 putSamples(other.ptrBegin(), oNumSamples); 94 other.receiveSamples(oNumSamples); 95 }; 96 97 /// Output samples from beginning of the sample buffer. Copies requested samples to 98 /// output buffer and removes them from the sample buffer. If there are less than 99 /// 'numsample' samples in the buffer, returns all that available. 100 /// 101 /// \return Number of samples returned. 102 virtual uint receiveSamples(SAMPLETYPE *output, ///< Buffer where to copy output samples. 103 uint maxSamples ///< How many samples to receive at max. 104 ) = 0; 105 106 /// Adjusts book-keeping so that given number of samples are removed from beginning of the 107 /// sample buffer without copying them anywhere. 108 /// 109 /// Used to reduce the number of samples in the buffer when accessing the sample buffer directly 110 /// with 'ptrBegin' function. 111 virtual uint receiveSamples(uint maxSamples ///< Remove this many samples from the beginning of pipe. 112 ) = 0; 113 114 /// Returns number of samples currently available. 115 virtual uint numSamples() const = 0; 116 117 // Returns nonzero if there aren't any samples available for outputting. 118 virtual int isEmpty() const = 0; 119 120 /// Clears all the samples. 121 virtual void clear() = 0; 122 123 /// allow trimming (downwards) amount of samples in pipeline. 124 /// Returns adjusted amount of samples 125 virtual uint adjustAmountOfSamples(uint numSamples) = 0; 126 127 }; 128 129 130 /// Base-class for sound processing routines working in FIFO principle. With this base 131 /// class it's easy to implement sound processing stages that can be chained together, 132 /// so that samples that are fed into beginning of the pipe automatically go through 133 /// all the processing stages. 134 /// 135 /// When samples are input to this class, they're first processed and then put to 136 /// the FIFO pipe that's defined as output of this class. This output pipe can be 137 /// either other processing stage or a FIFO sample buffer. 138 class FIFOProcessor :public FIFOSamplePipe 139 { 140 protected: 141 /// Internal pipe where processed samples are put. 142 FIFOSamplePipe *output; 143 144 /// Sets output pipe. 145 void setOutPipe(FIFOSamplePipe *pOutput) 146 { 147 assert(output == NULL); 148 assert(pOutput != NULL); 149 output = pOutput; 150 } 151 152 /// Constructor. Doesn't define output pipe; it has to be set be 153 /// 'setOutPipe' function. 154 FIFOProcessor() 155 { 156 output = NULL; 157 } 158 159 /// Constructor. Configures output pipe. 160 FIFOProcessor(FIFOSamplePipe *pOutput ///< Output pipe. 161 ) 162 { 163 output = pOutput; 164 } 165 166 /// Destructor. 167 virtual ~FIFOProcessor() 168 { 169 } 170 171 /// Returns a pointer to the beginning of the output samples. 172 /// This function is provided for accessing the output samples directly. 173 /// Please be careful for not to corrupt the book-keeping! 174 /// 175 /// When using this function to output samples, also remember to 'remove' the 176 /// output samples from the buffer by calling the 177 /// 'receiveSamples(numSamples)' function 178 virtual SAMPLETYPE *ptrBegin() 179 { 180 return output->ptrBegin(); 181 } 182 183 public: 184 185 /// Output samples from beginning of the sample buffer. Copies requested samples to 186 /// output buffer and removes them from the sample buffer. If there are less than 187 /// 'numsample' samples in the buffer, returns all that available. 188 /// 189 /// \return Number of samples returned. 190 virtual uint receiveSamples(SAMPLETYPE *outBuffer, ///< Buffer where to copy output samples. 191 uint maxSamples ///< How many samples to receive at max. 192 ) 193 { 194 return output->receiveSamples(outBuffer, maxSamples); 195 } 196 197 /// Adjusts book-keeping so that given number of samples are removed from beginning of the 198 /// sample buffer without copying them anywhere. 199 /// 200 /// Used to reduce the number of samples in the buffer when accessing the sample buffer directly 201 /// with 'ptrBegin' function. 202 virtual uint receiveSamples(uint maxSamples ///< Remove this many samples from the beginning of pipe. 203 ) 204 { 205 return output->receiveSamples(maxSamples); 206 } 207 208 /// Returns number of samples currently available. 209 virtual uint numSamples() const 210 { 211 return output->numSamples(); 212 } 213 214 /// Returns nonzero if there aren't any samples available for outputting. 215 virtual int isEmpty() const 216 { 217 return output->isEmpty(); 218 } 219 220 /// allow trimming (downwards) amount of samples in pipeline. 221 /// Returns adjusted amount of samples 222 virtual uint adjustAmountOfSamples(uint numSamples) 223 { 224 return output->adjustAmountOfSamples(numSamples); 225 } 226 }; 227 228 } 229 230 #endif