dsfml.audio.soundbuffer

A sound buffer holds the data of a sound, which is an array of audio samples. A sample is a 16 bits signed integer that defines the amplitude of the sound at a given time. The sound is then restituted by playing these samples at a high rate (for example, 44100 samples per second is the standard rate used for playing CDs). In short, audio samples are like texture pixels, and a SoundBuffer is similar to a Texture.

A sound buffer can be loaded from a file (see loadFromFile() for the complete list of supported formats), from memory, from a custom stream (see $(INPUTSTREAM_LINK)) or directly from an array of samples. It can also be saved back to a file.

Sound buffers alone are not very useful: they hold the audio data but cannot be played. To do so, you need to use the $(SOUND_LINK) class, which provides functions to play/pause/stop the sound as well as changing the way it is outputted (volume, pitch, 3D position, ...).

This separation allows more flexibility and better performances: indeed a $(U SoundBuffer) is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a $(SOUND_LINK) is a lightweight object, which can use the audio data of a sound buffer and change the way it is played without actually modifying that data. Note that it is also possible to bind several $(SOUND_LINK) instances to the same $(U SoundBuffer).

It is important to note that the Sound instance doesn't copy the buffer that it uses, it only keeps a reference to it. Thus, a $(U SoundBuffer) must not be destructed while it is used by a Sound (i.e. never write a function that uses a local $(U SoundBuffer) instance for loading a sound).

*Example:

1 // Declare a new sound buffer
2 auto buffer = SoundBuffer();
3 
4 // Load it from a file
5 if (!buffer.loadFromFile("sound.wav"))
6 {
7    // error...
8 }
9 
10 // Create a sound source and bind it to the buffer
11 auto sound1 = new Sound();
12 sound1.setBuffer(buffer);
13 
14 // Play the sound
15 sound1.play();
16 
17 // Create another sound source bound to the same buffer
18 auto sound2 = new Sound();
19 sound2.setBuffer(buffer);
20 
21 // Play it with a higher pitch -- the first sound remains unchanged
22 sound2.pitch = 2;
23 sound2.play();