gitweb.forssennils.se Git - TDDC76_proj.git/blob

   1 ////////////////////////////////////////////////////////////
   2 //
   3 // SFML - Simple and Fast Multimedia Library
   4 // Copyright (C) 2007-2013 Laurent Gomila (laurent.gom@gmail.com)
   5 //
   6 // This software is provided 'as-is', without any express or implied warranty.
   7 // In no event will the authors be held liable for any damages arising from the use of this software.
   8 //
   9 // Permission is granted to anyone to use this software for any purpose,
  10 // including commercial applications, and to alter it and redistribute it freely,
  11 // subject to the following restrictions:
  12 //
  13 // 1. The origin of this software must not be misrepresented;
  14 //    you must not claim that you wrote the original software.
  15 //    If you use this software in a product, an acknowledgment
  16 //    in the product documentation would be appreciated but is not required.
  17 //
  18 // 2. Altered source versions must be plainly marked as such,
  19 //    and must not be misrepresented as being the original software.
  20 //
  21 // 3. This notice may not be removed or altered from any source distribution.
  22 //
  23 ////////////////////////////////////////////////////////////
  24
  25 #ifndef SFML_SOUNDRECORDER_HPP
  26 #define SFML_SOUNDRECORDER_HPP
  27
  28 ////////////////////////////////////////////////////////////
  29 // Headers
  30 ////////////////////////////////////////////////////////////
  31 #include <SFML/Audio/Export.hpp>
  32 #include <SFML/System/Thread.hpp>
  33 #include <vector>
  34
  35
  36 namespace sf
  37 {
  38 ////////////////////////////////////////////////////////////
  39 /// \brief Abstract base class for capturing sound data
  40 ///
  41 ////////////////////////////////////////////////////////////
  42 class SFML_AUDIO_API SoundRecorder
  43 {
  44 public :
  45
  46     ////////////////////////////////////////////////////////////
  47     /// \brief destructor
  48     ///
  49     ////////////////////////////////////////////////////////////
  50     virtual ~SoundRecorder();
  51
  52     ////////////////////////////////////////////////////////////
  53     /// \brief Start the capture
  54     ///
  55     /// The \a sampleRate parameter defines the number of audio samples
  56     /// captured per second. The higher, the better the quality
  57     /// (for example, 44100 samples/sec is CD quality).
  58     /// This function uses its own thread so that it doesn't block
  59     /// the rest of the program while the capture runs.
  60     /// Please note that only one capture can happen at the same time.
  61     ///
  62     /// \param sampleRate Desired capture rate, in number of samples per second
  63     ///
  64     /// \see stop
  65     ///
  66     ////////////////////////////////////////////////////////////
  67     void start(unsigned int sampleRate = 44100);
  68
  69     ////////////////////////////////////////////////////////////
  70     /// \brief Stop the capture
  71     ///
  72     /// \see start
  73     ///
  74     ////////////////////////////////////////////////////////////
  75     void stop();
  76
  77     ////////////////////////////////////////////////////////////
  78     /// \brief Get the sample rate
  79     ///
  80     /// The sample rate defines the number of audio samples
  81     /// captured per second. The higher, the better the quality
  82     /// (for example, 44100 samples/sec is CD quality).
  83     ///
  84     /// \return Sample rate, in samples per second
  85     ///
  86     ////////////////////////////////////////////////////////////
  87     unsigned int getSampleRate() const;
  88
  89     ////////////////////////////////////////////////////////////
  90     /// \brief Check if the system supports audio capture
  91     ///
  92     /// This function should always be called before using
  93     /// the audio capture features. If it returns false, then
  94     /// any attempt to use sf::SoundRecorder or one of its derived
  95     /// classes will fail.
  96     ///
  97     /// \return True if audio capture is supported, false otherwise
  98     ///
  99     ////////////////////////////////////////////////////////////
 100     static bool isAvailable();
 101
 102 protected :
 103
 104     ////////////////////////////////////////////////////////////
 105     /// \brief Default constructor
 106     ///
 107     /// This constructor is only meant to be called by derived classes.
 108     ///
 109     ////////////////////////////////////////////////////////////
 110     SoundRecorder();
 111
 112     ////////////////////////////////////////////////////////////
 113     /// \brief Start capturing audio data
 114     ///
 115     /// This virtual function may be overriden by a derived class
 116     /// if something has to be done every time a new capture
 117     /// starts. If not, this function can be ignored; the default
 118     /// implementation does nothing.
 119     ///
 120     /// \return True to start the capture, or false to abort it
 121     ///
 122     ////////////////////////////////////////////////////////////
 123     virtual bool onStart();
 124
 125     ////////////////////////////////////////////////////////////
 126     /// \brief Process a new chunk of recorded samples
 127     ///
 128     /// This virtual function is called every time a new chunk of
 129     /// recorded data is available. The derived class can then do
 130     /// whatever it wants with it (storing it, playing it, sending
 131     /// it over the network, etc.).
 132     ///
 133     /// \param samples     Pointer to the new chunk of recorded samples
 134     /// \param sampleCount Number of samples pointed by \a samples
 135     ///
 136     /// \return True to continue the capture, or false to stop it
 137     ///
 138     ////////////////////////////////////////////////////////////
 139     virtual bool onProcessSamples(const Int16* samples, std::size_t sampleCount) = 0;
 140
 141     ////////////////////////////////////////////////////////////
 142     /// \brief Stop capturing audio data
 143     ///
 144     /// This virtual function may be overriden by a derived class
 145     /// if something has to be done every time the capture
 146     /// ends. If not, this function can be ignored; the default
 147     /// implementation does nothing.
 148     ///
 149     ////////////////////////////////////////////////////////////
 150     virtual void onStop();
 151
 152 private :
 153
 154     ////////////////////////////////////////////////////////////
 155     /// \brief Function called as the entry point of the thread
 156     ///
 157     /// This function starts the recording loop, and returns
 158     /// only when the capture is stopped.
 159     ///
 160     ////////////////////////////////////////////////////////////
 161     void record();
 162
 163     ////////////////////////////////////////////////////////////
 164     /// \brief Get the new available audio samples and process them
 165     ///
 166     /// This function is called continuously during the
 167     /// capture loop. It retrieves the captured samples and
 168     /// forwards them to the derived class.
 169     ///
 170     ////////////////////////////////////////////////////////////
 171     void processCapturedSamples();
 172
 173     ////////////////////////////////////////////////////////////
 174     /// \brief Clean up the recorder's internal resources
 175     ///
 176     /// This function is called when the capture stops.
 177     ///
 178     ////////////////////////////////////////////////////////////
 179     void cleanup();
 180
 181     ////////////////////////////////////////////////////////////
 182     // Member data
 183     ////////////////////////////////////////////////////////////
 184     Thread             m_thread;      ///< Thread running the background recording task
 185     std::vector<Int16> m_samples;     ///< Buffer to store captured samples
 186     unsigned int       m_sampleRate;  ///< Sample rate
 187     bool               m_isCapturing; ///< Capturing state
 188 };
 189
 190 } // namespace sf
 191
 192
 193 #endif // SFML_SOUNDRECORDER_HPP
 194
 195
 196 ////////////////////////////////////////////////////////////
 197 /// \class sf::SoundRecorder
 198 /// \ingroup audio
 199 ///
 200 /// sf::SoundBuffer provides a simple interface to access
 201 /// the audio recording capabilities of the computer
 202 /// (the microphone). As an abstract base class, it only cares
 203 /// about capturing sound samples, the task of making something
 204 /// useful with them is left to the derived class. Note that
 205 /// SFML provides a built-in specialization for saving the
 206 /// captured data to a sound buffer (see sf::SoundBufferRecorder).
 207 ///
 208 /// A derived class has only one virtual function to override:
 209 /// \li onProcessSamples provides the new chunks of audio samples while the capture happens
 210 ///
 211 /// Moreover, two additionnal virtual functions can be overriden
 212 /// as well if necessary:
 213 /// \li onStart is called before the capture happens, to perform custom initializations
 214 /// \li onStop is called after the capture ends, to perform custom cleanup
 215 ///
 216 /// The audio capture feature may not be supported or activated
 217 /// on every platform, thus it is recommended to check its
 218 /// availability with the isAvailable() function. If it returns
 219 /// false, then any attempt to use an audio recorder will fail.
 220 ///
 221 /// It is important to note that the audio capture happens in a
 222 /// separate thread, so that it doesn't block the rest of the
 223 /// program. In particular, the onProcessSamples and onStop
 224 /// virtual functions (but not onStart) will be called
 225 /// from this separate thread. It is important to keep this in
 226 /// mind, because you may have to take care of synchronization
 227 /// issues if you share data between threads.
 228 ///
 229 /// Usage example:
 230 /// \code
 231 /// class CustomRecorder : public sf::SoundRecorder
 232 /// {
 233 ///     virtual bool onStart() // optional
 234 ///     {
 235 ///         // Initialize whatever has to be done before the capture starts
 236 ///         ...
 237 ///
 238 ///         // Return true to start playing
 239 ///         return true;
 240 ///     }
 241 ///
 242 ///     virtual bool onProcessSamples(const Int16* samples, std::size_t sampleCount)
 243 ///     {
 244 ///         // Do something with the new chunk of samples (store them, send them, ...)
 245 ///         ...
 246 ///
 247 ///         // Return true to continue playing
 248 ///         return true;
 249 ///     }
 250 ///
 251 ///     virtual void onStop() // optional
 252 ///     {
 253 ///         // Clean up whatever has to be done after the capture ends
 254 ///         ...
 255 ///     }
 256 /// }
 257 ///
 258 /// // Usage
 259 /// if (CustomRecorder::isAvailable())
 260 /// {
 261 ///     CustomRecorder recorder;
 262 ///     recorder.start();
 263 ///     ...
 264 ///     recorder.stop();
 265 /// }
 266 /// \endcode
 267 ///
 268 /// \see sf::SoundBufferRecorder
 269 ///
 270 ////////////////////////////////////////////////////////////