Documentation of SFML 2.4.0

Warning: this page refers to an old version of SFML. Click here to switch to the latest version.
sf::SoundBuffer Class Reference

Storage for audio samples defining a sound. More...

#include <SoundBuffer.hpp>

Inheritance diagram for sf::SoundBuffer:
sf::AlResource

Public Member Functions

 SoundBuffer ()
 Default constructor. More...
 
 SoundBuffer (const SoundBuffer &copy)
 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, Uint64 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...
 
Uint64 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...
 
SoundBufferoperator= (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 reconstituted 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
// Load it from a file
if (!buffer.loadFromFile("sound.wav"))
{
// 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 49 of file SoundBuffer.hpp.

Constructor & Destructor Documentation

sf::SoundBuffer::SoundBuffer ( )

Default constructor.

sf::SoundBuffer::SoundBuffer ( const SoundBuffer copy)

Copy constructor.

Parameters
copyInstance 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

Get the total duration of the sound.

Returns
Sound duration
See also
getSampleRate, getChannelCount
Uint64 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.

See the documentation of sf::InputSoundFile for the list of supported formats.

Parameters
filenamePath 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.

See the documentation of sf::InputSoundFile for the list of supported formats.

Parameters
dataPointer to the file data in memory
sizeInBytesSize 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,
Uint64  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
samplesPointer to the array of samples in memory
sampleCountNumber of samples in the array
channelCountNumber of channels (1 = mono, 2 = stereo, ...)
sampleRateSample 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.

See the documentation of sf::InputSoundFile for the list of supported formats.

Parameters
streamSource 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
rightInstance to assign
Returns
Reference to self
bool sf::SoundBuffer::saveToFile ( const std::string &  filename) const

Save the sound buffer to an audio file.

See the documentation of sf::OutputSoundFile for the list of supported formats.

Parameters
filenamePath 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: