/extlibs/SFML/include/SFML/Audio/SoundBuffer.hpp
C++ Header | 327 lines | 39 code | 30 blank | 258 comment | 0 complexity | 6db38f3763076b394731d2bf103f807b MD5 | raw file
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////////////////////////////////////////////////////////////