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     /// Returns a pointer to the beginning of the output samples.
  63     /// This function is provided for accessing the output samples directly.
  64     /// Please be careful for not to corrupt the book-keeping!
  65     ///
  66     /// When using this function to output samples, also remember to 'remove' the
  67     /// output samples from the buffer by calling the
  68     /// 'receiveSamples(numSamples)' function
  69     virtual SAMPLETYPE *ptrBegin() const = 0;
  70
  71     /// Adds 'numSamples' pcs of samples from the 'samples' memory position to
  72     /// the sample buffer.
  73     virtual void putSamples(const SAMPLETYPE *samples,  ///< Pointer to samples.
  74                             uint numSamples                         ///< Number of samples to insert.
  75                             ) = 0;
  76
  77
  78     // Moves samples from the 'other' pipe instance to this instance.
  79     void moveSamples(FIFOSamplePipe &other  ///< Other pipe instance where from the receive the data.
  80          )
  81     {
  82         int oNumSamples = other.numSamples();
  83
  84         putSamples(other.ptrBegin(), oNumSamples);
  85         other.receiveSamples(oNumSamples);
  86     };
  87
  88     /// Output samples from beginning of the sample buffer. Copies requested samples to
  89     /// output buffer and removes them from the sample buffer. If there are less than
  90     /// 'numsample' samples in the buffer, returns all that available.
  91     ///
  92     /// \return Number of samples returned.
  93     virtual uint receiveSamples(SAMPLETYPE *output, ///< Buffer where to copy output samples.
  94                                 uint maxSamples                 ///< How many samples to receive at max.
  95                                 ) = 0;
  96
  97     /// Adjusts book-keeping so that given number of samples are removed from beginning of the
  98     /// sample buffer without copying them anywhere.
  99     ///
 100     /// Used to reduce the number of samples in the buffer when accessing the sample buffer directly
 101     /// with 'ptrBegin' function.
 102     virtual uint receiveSamples(uint maxSamples   ///< Remove this many samples from the beginning of pipe.
 103                                 ) = 0;
 104
 105     /// Returns number of samples currently available.
 106     virtual uint numSamples() const = 0;
 107
 108     // Returns nonzero if there aren't any samples available for outputting.
 109     virtual int isEmpty() const = 0;
 110
 111     /// Clears all the samples.
 112     virtual void clear() = 0;
 113 };
 114
 115
 116
 117 /// Base-class for sound processing routines working in FIFO principle. With this base
 118 /// class it's easy to implement sound processing stages that can be chained together,
 119 /// so that samples that are fed into beginning of the pipe automatically go through
 120 /// all the processing stages.
 121 ///
 122 /// When samples are input to this class, they're first processed and then put to
 123 /// the FIFO pipe that's defined as output of this class. This output pipe can be
 124 /// either other processing stage or a FIFO sample buffer.
 125 class FIFOProcessor :public FIFOSamplePipe
 126 {
 127 protected:
 128     /// Internal pipe where processed samples are put.
 129     FIFOSamplePipe *output;
 130
 131     /// Sets output pipe.
 132     void setOutPipe(FIFOSamplePipe *pOutput)
 133     {
 134         assert(output == NULL);
 135         assert(pOutput != NULL);
 136         output = pOutput;
 137     }
 138
 139
 140     /// Constructor. Doesn't define output pipe; it has to be set be
 141     /// 'setOutPipe' function.
 142     FIFOProcessor()
 143     {
 144         output = NULL;
 145     }
 146
 147
 148     /// Constructor. Configures output pipe.
 149     FIFOProcessor(FIFOSamplePipe *pOutput   ///< Output pipe.
 150                  )
 151     {
 152         output = pOutput;
 153     }
 154
 155
 156     /// Destructor.
 157     virtual ~FIFOProcessor()
 158     {
 159     }
 160
 161
 162     /// Returns a pointer to the beginning of the output samples.
 163     /// This function is provided for accessing the output samples directly.
 164     /// Please be careful for not to corrupt the book-keeping!
 165     ///
 166     /// When using this function to output samples, also remember to 'remove' the
 167     /// output samples from the buffer by calling the
 168     /// 'receiveSamples(numSamples)' function
 169     virtual SAMPLETYPE *ptrBegin() const
 170     {
 171         return output->ptrBegin();
 172     }
 173
 174 public:
 175
 176     /// Output samples from beginning of the sample buffer. Copies requested samples to
 177     /// output buffer and removes them from the sample buffer. If there are less than
 178     /// 'numsample' samples in the buffer, returns all that available.
 179     ///
 180     /// \return Number of samples returned.
 181     virtual uint receiveSamples(SAMPLETYPE *outBuffer, ///< Buffer where to copy output samples.
 182                                 uint maxSamples                    ///< How many samples to receive at max.
 183                                 )
 184     {
 185         return output->receiveSamples(outBuffer, maxSamples);
 186     }
 187
 188
 189     /// Adjusts book-keeping so that given number of samples are removed from beginning of the
 190     /// sample buffer without copying them anywhere.
 191     ///
 192     /// Used to reduce the number of samples in the buffer when accessing the sample buffer directly
 193     /// with 'ptrBegin' function.
 194     virtual uint receiveSamples(uint maxSamples   ///< Remove this many samples from the beginning of pipe.
 195                                 )
 196     {
 197         return output->receiveSamples(maxSamples);
 198     }
 199
 200
 201     /// Returns number of samples currently available.
 202     virtual uint numSamples() const
 203     {
 204         return output->numSamples();
 205     }
 206
 207
 208     /// Returns nonzero if there aren't any samples available for outputting.
 209     virtual int isEmpty() const
 210     {
 211         return output->isEmpty();
 212     }
 213 };
 214
 215 }
 216
 217 #endif