/extlibs/SFML/include/SFML/Audio/SoundBuffer.hpp

  1////////////////////////////////////////////////////////////
  2//
  3// SFML - Simple and Fast Multimedia Library
  4// Copyright (C) 2007-2009 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_SOUNDBUFFER_HPP
 26#define SFML_SOUNDBUFFER_HPP
 27
 28////////////////////////////////////////////////////////////
 29// Headers
 30////////////////////////////////////////////////////////////
 31#include <SFML/Config.hpp>
 32#include <SFML/System/Resource.hpp>
 33#include <string>
 34#include <vector>
 35#include <set>
 36
 37
 38namespace sf
 39{
 40class Sound;
 41
 42////////////////////////////////////////////////////////////
 43/// \brief Storage for audio samples defining a sound
 44///
 45////////////////////////////////////////////////////////////
 46class SFML_API SoundBuffer : public Resource<SoundBuffer>
 47{
 48public :
 49
 50    ////////////////////////////////////////////////////////////
 51    /// \brief Default constructor
 52    ///
 53    ////////////////////////////////////////////////////////////
 54    SoundBuffer();
 55
 56    ////////////////////////////////////////////////////////////
 57    /// \brief Copy constructor
 58    ///
 59    /// \param copy Instance to copy
 60    ///
 61    ////////////////////////////////////////////////////////////
 62    SoundBuffer(const SoundBuffer& copy);
 63
 64    ////////////////////////////////////////////////////////////
 65    /// \brief Destructor
 66    ///
 67    ////////////////////////////////////////////////////////////
 68    ~SoundBuffer();
 69
 70    ////////////////////////////////////////////////////////////
 71    /// \brief Load the sound buffer from a file
 72    ///
 73    /// Here is a complete list of all the supported audio formats:
 74    /// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
 75    /// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
 76    ///
 77    /// \param filename Path of the sound file to load
 78    ///
 79    /// \return True if loading succeeded, false if it failed
 80    ///
 81    /// \see LoadFromMemory, LoadFromSamples, SaveToFile
 82    ///
 83    ////////////////////////////////////////////////////////////
 84    bool LoadFromFile(const std::string& filename);
 85
 86    ////////////////////////////////////////////////////////////
 87    /// \brief Load the sound buffer from a file in memory
 88    ///
 89    /// Here is a complete list of all the supported audio formats:
 90    /// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
 91    /// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
 92    ///
 93    /// \param data        Pointer to the file data in memory
 94    /// \param sizeInBytes Size of the data to load, in bytes
 95    ///
 96    /// \return True if loading succeeded, false if it failed
 97    ///
 98    /// \see LoadFromFile, LoadFromSamples, SaveToFile
 99    ///
100    ////////////////////////////////////////////////////////////
101    bool LoadFromMemory(const void* data, std::size_t sizeInBytes);
102
103    ////////////////////////////////////////////////////////////
104    /// \brief Load the sound buffer from an array of audio samples
105    ///
106    /// The assumed format of the audio samples is 16 bits signed integer
107    /// (sf::Int16).
108    ///
109    /// \param samples       Pointer to the array of samples in memory
110    /// \param samplesCount  Number of samples in the array
111    /// \param channelsCount Number of channels (1 = mono, 2 = stereo, ...)
112    /// \param sampleRate    Sample rate (number of samples to play per second)
113    ///
114    /// \return True if loading succeeded, false if it failed
115    ///
116    /// \see LoadFromFile, LoadFromMemory, SaveToFile
117    ///
118    ////////////////////////////////////////////////////////////
119    bool LoadFromSamples(const Int16* samples, std::size_t samplesCount, unsigned int channelsCount, unsigned int sampleRate);
120
121    ////////////////////////////////////////////////////////////
122    /// \brief Save the sound buffer to an audio file
123    ///
124    /// Here is a complete list of all the supported audio formats:
125    /// ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam,
126    /// w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
127    ///
128    /// \param filename Path of the sound file to write
129    ///
130    /// \return True if saving succeeded, false if it failed
131    ///
132    /// \see LoadFromFile, LoadFromMemory, LoadFromSamples
133    ///
134    ////////////////////////////////////////////////////////////
135    bool SaveToFile(const std::string& filename) const;
136
137    ////////////////////////////////////////////////////////////
138    /// \brief Get the array of audio samples stored in the buffer
139    ///
140    /// The format of the returned samples is 16 bits signed integer
141    /// (sf::Int16). The total number of samples in this array
142    /// is given by the GetSamplesCount() function.
143    ///
144    /// \return Read-only pointer to the array of sound samples
145    ///
146    /// \see GetSamplesCount
147    ///
148    ////////////////////////////////////////////////////////////
149    const Int16* GetSamples() const;
150
151    ////////////////////////////////////////////////////////////
152    /// \brief Get the number of samples stored in the buffer
153    ///
154    /// The array of samples can be accessed with the GetSamples()
155    /// function.
156    ///
157    /// \return Number of samples
158    ///
159    /// \see GetSamples
160    ///
161    ////////////////////////////////////////////////////////////
162    std::size_t GetSamplesCount() const;
163
164    ////////////////////////////////////////////////////////////
165    /// \brief Get the sample rate of the sound
166    ///
167    /// The sample rate is the number of samples played per second.
168    /// The higher, the better the quality (for example, 44100
169    /// samples/s is CD quality).
170    ///
171    /// \return Sample rate (number of samples per second)
172    ///
173    /// \see GetChannelsCount, GetDuration
174    ///
175    ////////////////////////////////////////////////////////////
176    unsigned int GetSampleRate() const;
177
178    ////////////////////////////////////////////////////////////
179    /// \brief Get the number of channels used by the sound
180    ///
181    /// If the sound is mono then the number ofchannels will
182    /// be 1, 2 for stereo, etc.
183    ///
184    /// \return Number of channels
185    ///
186    /// \see GetSampleRate, GetDuration
187    ///
188    ////////////////////////////////////////////////////////////
189    unsigned int GetChannelsCount() const;
190
191    ////////////////////////////////////////////////////////////
192    /// \brief Get the total duration of the sound
193    ///
194    /// \return Sound duration, in seconds
195    ///
196    /// \see GetSampleRate, GetChannelsCount
197    ///
198    ////////////////////////////////////////////////////////////
199    float GetDuration() const;
200
201    ////////////////////////////////////////////////////////////
202    /// \brief Overload of assignment operator
203    ///
204    /// \param right Instance to assign
205    ///
206    /// \return Reference to self
207    ///
208    ////////////////////////////////////////////////////////////
209    SoundBuffer& operator =(const SoundBuffer& right);
210
211private :
212
213    friend class Sound;
214
215    ////////////////////////////////////////////////////////////
216    /// \brief Update the internal buffer with the cached audio samples
217    ///
218    /// \param channelsCount Number of channels
219    /// \param sampleRate    Sample rate (number of samples per second)
220    ///
221    /// \return True on success, false if any error happened
222    ///
223    ////////////////////////////////////////////////////////////
224    bool Update(unsigned int channelsCount, unsigned int sampleRate);
225
226    ////////////////////////////////////////////////////////////
227    /// \brief Add a sound to the list of sounds that use this buffer
228    ///
229    /// \param sound Sound instance to attach
230    ///
231    ////////////////////////////////////////////////////////////
232    void AttachSound(Sound* sound) const;
233
234    ////////////////////////////////////////////////////////////
235    /// \brief Remove a sound from the list of sounds that use this buffer
236    ///
237    /// \param sound Sound instance to detach
238    ///
239    ////////////////////////////////////////////////////////////
240    void DetachSound(Sound* sound) const;
241
242    ////////////////////////////////////////////////////////////
243    // Types
244    ////////////////////////////////////////////////////////////
245    typedef std::set<Sound*> SoundList; ///< Set of unique sound instances
246
247    ////////////////////////////////////////////////////////////
248    // Member data
249    ////////////////////////////////////////////////////////////
250    unsigned int       myBuffer;   ///< OpenAL buffer identifier
251    std::vector<Int16> mySamples;  ///< Samples buffer
252    float              myDuration; ///< Sound duration, in seconds
253    mutable SoundList  mySounds;   ///< List of sounds that are using this buffer
254};
255
256} // namespace sf
257
258
259#endif // SFML_SOUNDBUFFER_HPP
260
261
262////////////////////////////////////////////////////////////
263/// \class sf::SoundBuffer
264/// \ingroup audio
265///
266/// A sound buffer holds the data of a sound, which is
267/// an array of audio samples. A sample is a 16 bits signed integer
268/// that defines the amplitude of the sound at a given time.
269/// The sound is then restituted by playing these samples at
270/// a high rate (for example, 44100 samples per second is the
271/// standard rate used for playing CDs). In short, audio samples
272/// are like image pixels, and a sf::SoundBuffer is similar to
273/// a sf::Image.
274///
275/// A sound buffer can be loaded from a file (see LoadFromFile()
276/// for the complete list of supported formats), from memory
277/// or directly from an array of samples. It can also be saved
278/// back to a file.
279///
280/// Sound buffers alone are not very useful: they hold the audio data
281/// but cannot be played. To do so, you need to use the sf::Sound class,
282/// which provides functions to play/pause/stop the sound as well as
283/// changing the way it is outputted (volume, pitch, 3D position, ...).
284/// This separation allows more flexibility and better performances:
285/// indeed a sf::SoundBuffer is a heavy resource, and any operation on it
286/// is slow (often too slow for real-time applications). On the other
287/// side, a sf::Sound is a lightweight object, which can use the audio data
288/// of a sound buffer and change the way it is played without actually
289/// modifying that data. Note that it is also possible to bind
290/// several sf::Sound instances to the same sf::SoundBuffer.
291///
292/// It is important to note that the sf::Sound instance doesn't
293/// copy the buffer that it uses, it only keeps a reference to it.
294/// Thus, a sf::SoundBuffer must not be destructed while it is
295/// used by a sf::Sound (i.e. never write a function that
296/// uses a local sf::SoundBuffer instance for loading a sound).
297///
298/// Usage example:
299/// \code
300/// // Declare a new sound buffer
301/// sf::SoundBuffer buffer;
302/// 
303/// // Load it from a file
304/// if (!buffer.LoadFromFile("sound.wav"))
305/// {
306///     // error...
307/// }
308/// 
309/// // Create a sound source and bind it to the buffer
310/// sf::Sound sound1;
311/// sound1.SetBuffer(buffer);
312/// 
313/// // Play the sound
314/// sound1.Play();
315/// 
316/// // Create another sound source bound to the same buffer
317/// sf::Sound sound2;
318/// sound2.SetBuffer(buffer);
319///
320/// // Play it with a higher pitch -- the first sound remains unchanged
321/// sound2.SetPitch(2);
322/// sound2.Play();
323/// \endcode
324///
325/// \see sf::Sound, sf::SoundBufferRecorder
326///
327////////////////////////////////////////////////////////////