sf::SoundBuffer Class Reference
[Audio module]

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

#include <SoundBuffer.hpp>

Inheritance diagram for sf::SoundBuffer:
sf::Resource< SoundBuffer >

List of all members.

Public Member Functions

 SoundBuffer ()
 Default constructor.
 SoundBuffer (const SoundBuffer &copy)
 Copy constructor.
 ~SoundBuffer ()
 Destructor.
bool LoadFromFile (const std::string &filename)
 Load the sound buffer from a file.
bool LoadFromMemory (const void *data, std::size_t sizeInBytes)
 Load the sound buffer from a file in memory.
bool LoadFromStream (InputStream &stream)
 Load the sound buffer from a custom stream.
bool LoadFromSamples (const Int16 *samples, std::size_t samplesCount, unsigned int channelsCount, unsigned int sampleRate)
 Load the sound buffer from an array of audio samples.
bool SaveToFile (const std::string &filename) const
 Save the sound buffer to an audio file.
const Int16 * GetSamples () const
 Get the array of audio samples stored in the buffer.
std::size_t GetSamplesCount () const
 Get the number of samples stored in the buffer.
unsigned int GetSampleRate () const
 Get the sample rate of the sound.
unsigned int GetChannelsCount () const
 Get the number of channels used by the sound.
Uint32 GetDuration () const
 Get the total duration of the sound.
SoundBufferoperator= (const SoundBuffer &right)
 Overload of assignment operator.

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
 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 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::GetChannelsCount (  )  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
Uint32 sf::SoundBuffer::GetDuration (  )  const

Get the total duration of the sound.

Returns:
Sound duration, in milliseconds
See also:
GetSampleRate, GetChannelsCount
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:
GetChannelsCount, 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 GetSamplesCount() function.

Returns:
Read-only pointer to the array of sound samples
See also:
GetSamplesCount
std::size_t sf::SoundBuffer::GetSamplesCount (  )  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
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  samplesCount,
unsigned int  channelsCount,
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
samplesCount Number of samples in the array
channelsCount 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: