- cpp3ds
- SoundBuffer
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, 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... | |
| SoundBuffer & | operator= (const SoundBuffer &right) |
| Overload of assignment operator. More... | |
Friends | |
| class | Sound |
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 cpp3ds::SoundBuffer is similar to a cpp3ds::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 cpp3ds::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 cpp3ds::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 cpp3ds::SoundBuffer is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a cpp3ds::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 cpp3ds::Sound instances to the same cpp3ds::SoundBuffer.
It is important to note that the cpp3ds::Sound instance doesn't copy the buffer that it uses, it only keeps a reference to it. Thus, a cpp3ds::SoundBuffer must not be destructed while it is used by a cpp3ds::Sound (i.e. never write a function that uses a local cpp3ds::SoundBuffer instance for loading a sound).
Usage example:
Definition at line 51 of file SoundBuffer.hpp.
| cpp3ds::SoundBuffer::SoundBuffer | ( | ) |
Default constructor.
| cpp3ds::SoundBuffer::SoundBuffer | ( | const SoundBuffer & | copy | ) |
Copy constructor.
| copy | Instance to copy |
| cpp3ds::SoundBuffer::~SoundBuffer | ( | ) |
Destructor.
| unsigned int cpp3ds::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.
| Time cpp3ds::SoundBuffer::getDuration | ( | ) | const |
| Uint64 cpp3ds::SoundBuffer::getSampleCount | ( | ) | const |
Get the number of samples stored in the buffer.
The array of samples can be accessed with the getSamples() function.
| unsigned int cpp3ds::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).
| const Int16* cpp3ds::SoundBuffer::getSamples | ( | ) | const |
Get the array of audio samples stored in the buffer.
The format of the returned samples is 16 bits signed integer (cpp3ds::Int16). The total number of samples in this array is given by the getSampleCount() function.
| bool cpp3ds::SoundBuffer::loadFromFile | ( | const std::string & | filename | ) |
Load the sound buffer from a file.
See the documentation of cpp3ds::InputSoundFile for the list of supported formats.
| filename | Path of the sound file to load |
| bool cpp3ds::SoundBuffer::loadFromMemory | ( | const void * | data, |
| std::size_t | sizeInBytes | ||
| ) |
Load the sound buffer from a file in memory.
See the documentation of cpp3ds::InputSoundFile for the list of supported formats.
| data | Pointer to the file data in memory |
| sizeInBytes | Size of the data to load, in bytes |
| bool cpp3ds::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 (cpp3ds::Int16).
| 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) |
| bool cpp3ds::SoundBuffer::loadFromStream | ( | InputStream & | stream | ) |
Load the sound buffer from a custom stream.
See the documentation of cpp3ds::InputSoundFile for the list of supported formats.
| stream | Source stream to read from |
| SoundBuffer& cpp3ds::SoundBuffer::operator= | ( | const SoundBuffer & | right | ) |
Overload of assignment operator.
| right | Instance to assign |
| bool cpp3ds::SoundBuffer::saveToFile | ( | const std::string & | filename | ) | const |
Save the sound buffer to an audio file.
See the documentation of cpp3ds::OutputSoundFile for the list of supported formats.
| filename | Path of the sound file to write |