EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2026-06-02 08:58:13
0001 //////////////////////////////////////////////////////////// 0002 // 0003 // SFML - Simple and Fast Multimedia Library 0004 // Copyright (C) 2007-2023 Laurent Gomila (laurent@sfml-dev.org) 0005 // 0006 // This software is provided 'as-is', without any express or implied warranty. 0007 // In no event will the authors be held liable for any damages arising from the use of this software. 0008 // 0009 // Permission is granted to anyone to use this software for any purpose, 0010 // including commercial applications, and to alter it and redistribute it freely, 0011 // subject to the following restrictions: 0012 // 0013 // 1. The origin of this software must not be misrepresented; 0014 // you must not claim that you wrote the original software. 0015 // If you use this software in a product, an acknowledgment 0016 // in the product documentation would be appreciated but is not required. 0017 // 0018 // 2. Altered source versions must be plainly marked as such, 0019 // and must not be misrepresented as being the original software. 0020 // 0021 // 3. This notice may not be removed or altered from any source distribution. 0022 // 0023 //////////////////////////////////////////////////////////// 0024 0025 #ifndef SFML_SOUNDBUFFER_HPP 0026 #define SFML_SOUNDBUFFER_HPP 0027 0028 //////////////////////////////////////////////////////////// 0029 // Headers 0030 //////////////////////////////////////////////////////////// 0031 #include <SFML/Audio/Export.hpp> 0032 #include <SFML/Audio/AlResource.hpp> 0033 #include <SFML/System/Time.hpp> 0034 #include <string> 0035 #include <vector> 0036 #include <set> 0037 0038 0039 namespace sf 0040 { 0041 class Sound; 0042 class InputSoundFile; 0043 class InputStream; 0044 0045 //////////////////////////////////////////////////////////// 0046 /// \brief Storage for audio samples defining a sound 0047 /// 0048 //////////////////////////////////////////////////////////// 0049 class SFML_AUDIO_API SoundBuffer : AlResource 0050 { 0051 public: 0052 0053 //////////////////////////////////////////////////////////// 0054 /// \brief Default constructor 0055 /// 0056 //////////////////////////////////////////////////////////// 0057 SoundBuffer(); 0058 0059 //////////////////////////////////////////////////////////// 0060 /// \brief Copy constructor 0061 /// 0062 /// \param copy Instance to copy 0063 /// 0064 //////////////////////////////////////////////////////////// 0065 SoundBuffer(const SoundBuffer& copy); 0066 0067 //////////////////////////////////////////////////////////// 0068 /// \brief Destructor 0069 /// 0070 //////////////////////////////////////////////////////////// 0071 ~SoundBuffer(); 0072 0073 //////////////////////////////////////////////////////////// 0074 /// \brief Load the sound buffer from a file 0075 /// 0076 /// See the documentation of sf::InputSoundFile for the list 0077 /// of supported formats. 0078 /// 0079 /// \param filename Path of the sound file to load 0080 /// 0081 /// \return True if loading succeeded, false if it failed 0082 /// 0083 /// \see loadFromMemory, loadFromStream, loadFromSamples, saveToFile 0084 /// 0085 //////////////////////////////////////////////////////////// 0086 bool loadFromFile(const std::string& filename); 0087 0088 //////////////////////////////////////////////////////////// 0089 /// \brief Load the sound buffer from a file in memory 0090 /// 0091 /// See the documentation of sf::InputSoundFile for the list 0092 /// of supported formats. 0093 /// 0094 /// \param data Pointer to the file data in memory 0095 /// \param sizeInBytes Size of the data to load, in bytes 0096 /// 0097 /// \return True if loading succeeded, false if it failed 0098 /// 0099 /// \see loadFromFile, loadFromStream, loadFromSamples 0100 /// 0101 //////////////////////////////////////////////////////////// 0102 bool loadFromMemory(const void* data, std::size_t sizeInBytes); 0103 0104 //////////////////////////////////////////////////////////// 0105 /// \brief Load the sound buffer from a custom stream 0106 /// 0107 /// See the documentation of sf::InputSoundFile for the list 0108 /// of supported formats. 0109 /// 0110 /// \param stream Source stream to read from 0111 /// 0112 /// \return True if loading succeeded, false if it failed 0113 /// 0114 /// \see loadFromFile, loadFromMemory, loadFromSamples 0115 /// 0116 //////////////////////////////////////////////////////////// 0117 bool loadFromStream(InputStream& stream); 0118 0119 //////////////////////////////////////////////////////////// 0120 /// \brief Load the sound buffer from an array of audio samples 0121 /// 0122 /// The assumed format of the audio samples is 16 bits signed integer 0123 /// (sf::Int16). 0124 /// 0125 /// \param samples Pointer to the array of samples in memory 0126 /// \param sampleCount Number of samples in the array 0127 /// \param channelCount Number of channels (1 = mono, 2 = stereo, ...) 0128 /// \param sampleRate Sample rate (number of samples to play per second) 0129 /// 0130 /// \return True if loading succeeded, false if it failed 0131 /// 0132 /// \see loadFromFile, loadFromMemory, saveToFile 0133 /// 0134 //////////////////////////////////////////////////////////// 0135 bool loadFromSamples(const Int16* samples, Uint64 sampleCount, unsigned int channelCount, unsigned int sampleRate); 0136 0137 //////////////////////////////////////////////////////////// 0138 /// \brief Save the sound buffer to an audio file 0139 /// 0140 /// See the documentation of sf::OutputSoundFile for the list 0141 /// of supported formats. 0142 /// 0143 /// \param filename Path of the sound file to write 0144 /// 0145 /// \return True if saving succeeded, false if it failed 0146 /// 0147 /// \see loadFromFile, loadFromMemory, loadFromSamples 0148 /// 0149 //////////////////////////////////////////////////////////// 0150 bool saveToFile(const std::string& filename) const; 0151 0152 //////////////////////////////////////////////////////////// 0153 /// \brief Get the array of audio samples stored in the buffer 0154 /// 0155 /// The format of the returned samples is 16 bits signed integer 0156 /// (sf::Int16). The total number of samples in this array 0157 /// is given by the getSampleCount() function. 0158 /// 0159 /// \return Read-only pointer to the array of sound samples 0160 /// 0161 /// \see getSampleCount 0162 /// 0163 //////////////////////////////////////////////////////////// 0164 const Int16* getSamples() const; 0165 0166 //////////////////////////////////////////////////////////// 0167 /// \brief Get the number of samples stored in the buffer 0168 /// 0169 /// The array of samples can be accessed with the getSamples() 0170 /// function. 0171 /// 0172 /// \return Number of samples 0173 /// 0174 /// \see getSamples 0175 /// 0176 //////////////////////////////////////////////////////////// 0177 Uint64 getSampleCount() const; 0178 0179 //////////////////////////////////////////////////////////// 0180 /// \brief Get the sample rate of the sound 0181 /// 0182 /// The sample rate is the number of samples played per second. 0183 /// The higher, the better the quality (for example, 44100 0184 /// samples/s is CD quality). 0185 /// 0186 /// \return Sample rate (number of samples per second) 0187 /// 0188 /// \see getChannelCount, getDuration 0189 /// 0190 //////////////////////////////////////////////////////////// 0191 unsigned int getSampleRate() const; 0192 0193 //////////////////////////////////////////////////////////// 0194 /// \brief Get the number of channels used by the sound 0195 /// 0196 /// If the sound is mono then the number of channels will 0197 /// be 1, 2 for stereo, etc. 0198 /// 0199 /// \return Number of channels 0200 /// 0201 /// \see getSampleRate, getDuration 0202 /// 0203 //////////////////////////////////////////////////////////// 0204 unsigned int getChannelCount() const; 0205 0206 //////////////////////////////////////////////////////////// 0207 /// \brief Get the total duration of the sound 0208 /// 0209 /// \return Sound duration 0210 /// 0211 /// \see getSampleRate, getChannelCount 0212 /// 0213 //////////////////////////////////////////////////////////// 0214 Time getDuration() const; 0215 0216 //////////////////////////////////////////////////////////// 0217 /// \brief Overload of assignment operator 0218 /// 0219 /// \param right Instance to assign 0220 /// 0221 /// \return Reference to self 0222 /// 0223 //////////////////////////////////////////////////////////// 0224 SoundBuffer& operator =(const SoundBuffer& right); 0225 0226 private: 0227 0228 friend class Sound; 0229 0230 //////////////////////////////////////////////////////////// 0231 /// \brief Initialize the internal state after loading a new sound 0232 /// 0233 /// \param file Sound file providing access to the new loaded sound 0234 /// 0235 /// \return True on successful initialization, false on failure 0236 /// 0237 //////////////////////////////////////////////////////////// 0238 bool initialize(InputSoundFile& file); 0239 0240 //////////////////////////////////////////////////////////// 0241 /// \brief Update the internal buffer with the cached audio samples 0242 /// 0243 /// \param channelCount Number of channels 0244 /// \param sampleRate Sample rate (number of samples per second) 0245 /// 0246 /// \return True on success, false if any error happened 0247 /// 0248 //////////////////////////////////////////////////////////// 0249 bool update(unsigned int channelCount, unsigned int sampleRate); 0250 0251 //////////////////////////////////////////////////////////// 0252 /// \brief Add a sound to the list of sounds that use this buffer 0253 /// 0254 /// \param sound Sound instance to attach 0255 /// 0256 //////////////////////////////////////////////////////////// 0257 void attachSound(Sound* sound) const; 0258 0259 //////////////////////////////////////////////////////////// 0260 /// \brief Remove a sound from the list of sounds that use this buffer 0261 /// 0262 /// \param sound Sound instance to detach 0263 /// 0264 //////////////////////////////////////////////////////////// 0265 void detachSound(Sound* sound) const; 0266 0267 //////////////////////////////////////////////////////////// 0268 // Types 0269 //////////////////////////////////////////////////////////// 0270 typedef std::set<Sound*> SoundList; //!< Set of unique sound instances 0271 0272 //////////////////////////////////////////////////////////// 0273 // Member data 0274 //////////////////////////////////////////////////////////// 0275 unsigned int m_buffer; //!< OpenAL buffer identifier 0276 std::vector<Int16> m_samples; //!< Samples buffer 0277 Time m_duration; //!< Sound duration 0278 mutable SoundList m_sounds; //!< List of sounds that are using this buffer 0279 }; 0280 0281 } // namespace sf 0282 0283 0284 #endif // SFML_SOUNDBUFFER_HPP 0285 0286 0287 //////////////////////////////////////////////////////////// 0288 /// \class sf::SoundBuffer 0289 /// \ingroup audio 0290 /// 0291 /// A sound buffer holds the data of a sound, which is 0292 /// an array of audio samples. A sample is a 16 bits signed integer 0293 /// that defines the amplitude of the sound at a given time. 0294 /// The sound is then reconstituted by playing these samples at 0295 /// a high rate (for example, 44100 samples per second is the 0296 /// standard rate used for playing CDs). In short, audio samples 0297 /// are like texture pixels, and a sf::SoundBuffer is similar to 0298 /// a sf::Texture. 0299 /// 0300 /// A sound buffer can be loaded from a file (see loadFromFile() 0301 /// for the complete list of supported formats), from memory, from 0302 /// a custom stream (see sf::InputStream) or directly from an array 0303 /// of samples. It can also be saved back to a file. 0304 /// 0305 /// Sound buffers alone are not very useful: they hold the audio data 0306 /// but cannot be played. To do so, you need to use the sf::Sound class, 0307 /// which provides functions to play/pause/stop the sound as well as 0308 /// changing the way it is outputted (volume, pitch, 3D position, ...). 0309 /// This separation allows more flexibility and better performances: 0310 /// indeed a sf::SoundBuffer is a heavy resource, and any operation on it 0311 /// is slow (often too slow for real-time applications). On the other 0312 /// side, a sf::Sound is a lightweight object, which can use the audio data 0313 /// of a sound buffer and change the way it is played without actually 0314 /// modifying that data. Note that it is also possible to bind 0315 /// several sf::Sound instances to the same sf::SoundBuffer. 0316 /// 0317 /// It is important to note that the sf::Sound instance doesn't 0318 /// copy the buffer that it uses, it only keeps a reference to it. 0319 /// Thus, a sf::SoundBuffer must not be destructed while it is 0320 /// used by a sf::Sound (i.e. never write a function that 0321 /// uses a local sf::SoundBuffer instance for loading a sound). 0322 /// 0323 /// Usage example: 0324 /// \code 0325 /// // Declare a new sound buffer 0326 /// sf::SoundBuffer buffer; 0327 /// 0328 /// // Load it from a file 0329 /// if (!buffer.loadFromFile("sound.wav")) 0330 /// { 0331 /// // error... 0332 /// } 0333 /// 0334 /// // Create a sound source and bind it to the buffer 0335 /// sf::Sound sound1; 0336 /// sound1.setBuffer(buffer); 0337 /// 0338 /// // Play the sound 0339 /// sound1.play(); 0340 /// 0341 /// // Create another sound source bound to the same buffer 0342 /// sf::Sound sound2; 0343 /// sound2.setBuffer(buffer); 0344 /// 0345 /// // Play it with a higher pitch -- the first sound remains unchanged 0346 /// sound2.setPitch(2); 0347 /// sound2.play(); 0348 /// \endcode 0349 /// 0350 /// \see sf::Sound, sf::SoundBufferRecorder 0351 /// 0352 ////////////////////////////////////////////////////////////
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|