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