libsound/InputStream.h

   1 // sound/InputStream.h -- Audio input stream interface
   2 //
   3 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012
   4 //   Free Software Foundation, Inc
   5 //
   6 // This program is free software; you can redistribute it and/or modify
   7 // it under the terms of the GNU General Public License as published by
   8 // the Free Software Foundation; either version 3 of the License, or
   9 // (at your option) any later version.
  10 //
  11 // This program is distributed in the hope that it will be useful,
  12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 // GNU General Public License for more details.
  15 //
  16 // You should have received a copy of the GNU General Public License
  17 // along with this program; if not, write to the Free Software
  18 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  19
  20
  21 #ifndef SOUND_INPUTSTREAM_H
  22 #define SOUND_INPUTSTREAM_H
  23
  24 #include <boost/cstdint.hpp> // For C99 int types
  25
  26 namespace gnash {
  27 namespace sound {
  28
  29 /// A %sound input stream
  30 //
  31 /// Instance of this class are sounds you can
  32 /// pull samples from.
  33 ///
  34 /// The format of the samples you pull is expected to
  35 /// be PCM samples as signed 16bit values
  36 /// in system-endian format.
  37 ///
  38 /// It is expected that consecutive samples fetched
  39 /// are one for left and one for right stereo channel,
  40 /// in that order (even indexes for left channel, odd
  41 /// indexes for right channel).
  42 ///
  43 /// Instances of this class would be the input
  44 /// for the gnash Mixer (currently sound_handler)
  45 /// instance.
  46 ///
  47 class InputStream {
  48
  49 public:
  50
  51     /// Fetch the given amount of samples, non-blocking and thread-safe.
  52     //
  53     /// @param to
  54     ///     Output buffer, must be at least nSamples*bytes.
  55     ///     (or nSamples items sized, being a container of 16bit values).
  56     ///
  57     /// @param nSamples
  58     ///     Number of samples to fetch.
  59     ///     It is expected that the fetcher fetches samples in multiples
  60     ///     of 2, being each couple composed by a sample for the left
  61     ///     channel and a sample for the right channel, in that order.
  62     ///
  63     /// @return number of samples actually written to the output buffer.
  64     ///         If < nSamples this InputStream ran out of data, either
  65     ///         temporarly or permanently. Use eof() to tell.
  66     ///
  67     /// @throws a SoundException (to be better defined a set of them)
  68     ///     if unable to process this and further requests due to internal
  69     ///     errors (not if it just happens to complete its source)
  70     ///
  71     virtual unsigned int fetchSamples(boost::int16_t* to, unsigned int nSamples)=0;
  72
  73     /// Return number of samples fetched from this stream
  74     //
  75     /// It is expected for the return to be always a multiple
  76     /// of 2, being each stereo sample unit composed by a sample
  77     /// for the left channel and a sample for the right channel,
  78     /// in that order.
  79     ///
  80     virtual unsigned int samplesFetched() const=0;
  81
  82     /// Return true if there'll be no more data to fetch.
  83     virtual bool eof() const=0;
  84
  85     virtual ~InputStream() {}
  86
  87 };
  88
  89
  90 } // gnash.sound namespace
  91 } // namespace gnash
  92
  93 #endif // SOUND_INPUTSTREAM_H