sf::SoundBuffer Class Reference
Storage for audio samples defining a sound. More...
#include <SoundBuffer.hpp>
Public Member Functions | |
| SoundBuffer () | |
| Default constructor. More... | |
| SoundBuffer (const SoundBuffer ©) | |
| Copy constructor. More... | |
| ~SoundBuffer () | |
| Destructor. More... | |
| bool | loadFromFile (const std::string &filename) |
| Load the sound buffer from a file. More... | |
| bool | loadFromMemory (const void *data, std::size_t sizeInBytes) |
| Load the sound buffer from a file in memory. More... | |
| bool | loadFromStream (InputStream &stream) |
| Load the sound buffer from a custom stream. More... | |
| bool | loadFromSamples (const Int16 *samples, std::size_t sampleCount, unsigned int channelCount, unsigned int sampleRate) |
| Load the sound buffer from an array of audio samples. More... | |
| bool | saveToFile (const std::string &filename) const |
| Save the sound buffer to an audio file. More... | |
| const Int16 * | getSamples () const |
| Get the array of audio samples stored in the buffer. More... | |
| std::size_t | getSampleCount () const |
| Get the number of samples stored in the buffer. More... | |
| unsigned int | getSampleRate () const |
| Get the sample rate of the sound. More... | |
| unsigned int | getChannelCount () const |
| Get the number of channels used by the sound. More... | |
| Time | getDuration () const |
| Get the total duration of the sound. More... | |
| SoundBuffer & | operator= (const SoundBuffer &right) |
| Overload of assignment operator. More... | |
Friends | |
| class | Sound |
Detailed Description
Storage for audio samples defining a sound.
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 sf::SoundBuffer is similar to a sf::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 sf::InputStream) 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 sf::Sound 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 sf::SoundBuffer is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a sf::Sound 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 sf::Sound instances to the same sf::SoundBuffer.
It is important to note that the sf::Sound instance doesn't copy the buffer that it uses, it only keeps a reference to it. Thus, a sf::SoundBuffer must not be destructed while it is used by a sf::Sound (i.e. never write a function that uses a local sf::SoundBuffer instance for loading a sound).
Usage example:
// Declare a new sound buffer
sf::SoundBuffer buffer;
// Load it from a file
{
// error...
}
// Create a sound source and bind it to the buffer
sf::Sound sound1;
sound1.setBuffer(buffer);
// Play the sound
sound1.play();
// Create another sound source bound to the same buffer
sf::Sound sound2;
sound2.setBuffer(buffer);
// Play it with a higher pitch -- the first sound remains unchanged
sound2.setPitch(2);
sound2.play();
- See also
- sf::Sound, sf::SoundBufferRecorder
Definition at line 52 of file SoundBuffer.hpp.
Constructor & Destructor Documentation
| sf::SoundBuffer::SoundBuffer | ( | ) |
Default constructor.
| sf::SoundBuffer::SoundBuffer | ( | const SoundBuffer & | copy | ) |
Copy constructor.
- Parameters
-
copy Instance to copy
| sf::SoundBuffer::~SoundBuffer | ( | ) |
Destructor.
Member Function Documentation
| unsigned int sf::SoundBuffer::getChannelCount | ( | ) | const |
Get the number of channels used by the sound.
If the sound is mono then the number of channels will be 1, 2 for stereo, etc.
- Returns
- Number of channels
- See also
- getSampleRate, getDuration
| Time sf::SoundBuffer::getDuration | ( | ) | const |
| std::size_t sf::SoundBuffer::getSampleCount | ( | ) | const |
Get the number of samples stored in the buffer.
The array of samples can be accessed with the getSamples() function.
- Returns
- Number of samples
- See also
- getSamples
| unsigned int sf::SoundBuffer::getSampleRate | ( | ) | const |
Get the sample rate of the sound.
The sample rate is the number of samples played per second. The higher, the better the quality (for example, 44100 samples/s is CD quality).
- Returns
- Sample rate (number of samples per second)
- See also
- getChannelCount, getDuration
| const Int16* sf::SoundBuffer::getSamples | ( | ) | const |
Get the array of audio samples stored in the buffer.
The format of the returned samples is 16 bits signed integer (sf::Int16). The total number of samples in this array is given by the getSampleCount() function.
- Returns
- Read-only pointer to the array of sound samples
- See also
- getSampleCount
| bool sf::SoundBuffer::loadFromFile | ( | const std::string & | filename | ) |
Load the sound buffer from a file.
Here is a complete list of all the supported audio formats: ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
- Parameters
-
filename Path of the sound file to load
- Returns
- True if loading succeeded, false if it failed
- See also
- loadFromMemory, loadFromStream, loadFromSamples, saveToFile
| bool sf::SoundBuffer::loadFromMemory | ( | const void * | data, |
| std::size_t | sizeInBytes | ||
| ) |
Load the sound buffer from a file in memory.
Here is a complete list of all the supported audio formats: ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
- Parameters
-
data Pointer to the file data in memory sizeInBytes Size of the data to load, in bytes
- Returns
- True if loading succeeded, false if it failed
- See also
- loadFromFile, loadFromStream, loadFromSamples
| bool sf::SoundBuffer::loadFromSamples | ( | const Int16 * | samples, |
| std::size_t | sampleCount, | ||
| unsigned int | channelCount, | ||
| unsigned int | sampleRate | ||
| ) |
Load the sound buffer from an array of audio samples.
The assumed format of the audio samples is 16 bits signed integer (sf::Int16).
- Parameters
-
samples Pointer to the array of samples in memory sampleCount Number of samples in the array channelCount Number of channels (1 = mono, 2 = stereo, ...) sampleRate Sample rate (number of samples to play per second)
- Returns
- True if loading succeeded, false if it failed
- See also
- loadFromFile, loadFromMemory, saveToFile
| bool sf::SoundBuffer::loadFromStream | ( | InputStream & | stream | ) |
Load the sound buffer from a custom stream.
Here is a complete list of all the supported audio formats: ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
- Parameters
-
stream Source stream to read from
- Returns
- True if loading succeeded, false if it failed
- See also
- loadFromFile, loadFromMemory, loadFromSamples
| SoundBuffer& sf::SoundBuffer::operator= | ( | const SoundBuffer & | right | ) |
Overload of assignment operator.
- Parameters
-
right Instance to assign
- Returns
- Reference to self
| bool sf::SoundBuffer::saveToFile | ( | const std::string & | filename | ) | const |
Save the sound buffer to an audio file.
Here is a complete list of all the supported audio formats: ogg, wav, flac, aiff, au, raw, paf, svx, nist, voc, ircam, w64, mat4, mat5 pvf, htk, sds, avr, sd2, caf, wve, mpc2k, rf64.
- Parameters
-
filename Path of the sound file to write
- Returns
- True if saving succeeded, false if it failed
- See also
- loadFromFile, loadFromMemory, loadFromSamples
The documentation for this class was generated from the following file: