media/libsoundtouch/src/FIFOSamplePipe.h

   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