.. index:: pair: class; EE::Audio::SoundBuffer
.. _doxid-class_e_e_1_1_audio_1_1_sound_buffer:

class EE::Audio::SoundBuffer
============================

.. toctree::
	:hidden:

Overview
~~~~~~~~

Storage for audio samples defining a sound. :ref:`More...<details-class_e_e_1_1_audio_1_1_sound_buffer>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	#include <soundbuffer.hpp>
	
	class SoundBuffer: private :ref:`EE::Audio::AlResource<doxid-class_e_e_1_1_audio_1_1_al_resource>` {
	public:
		// construction
	
		:target:`SoundBuffer<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a8dd84549df161dfc310cd554c05519b7>`();
		:ref:`SoundBuffer<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a05d0de08edfbbd0fb614497d40310aa6>`(const SoundBuffer& copy);
		:target:`~SoundBuffer<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a3a378db5d51b3cd9ec2f0ab1bd82e3e5>`();

		// methods
	
		bool :ref:`loadFromFile<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a90d0d1a0cd50318fec427a25d3953692>`(const std::string& filename);
		bool :ref:`loadFromMemory<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a8abf7fd8a8625edac832d02f88469a9e>`(const void* data, std::size_t sizeInBytes);
		bool :ref:`loadFromStream<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1aca3dc430a056f0d2f393ce0e19625318>`(:ref:`IOStream<doxid-class_e_e_1_1_system_1_1_i_o_stream>`& stream);
		bool :ref:`loadFromSamples<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a688a61e4f1ffdf316b990224e8bc6247>`(const :ref:`Int16<doxid-namespace_e_e_1a73642650c4b4c754551791873b930462>`* samples, :ref:`Uint64<doxid-namespace_e_e_1ae05f59b032c290566852fe63cb26135c>` sampleCount, unsigned int channelCount, unsigned int sampleRate);
		bool :target:`loadFromPack<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1ac207b0f2cc2bea0b24e586d946a6ff24>`(:ref:`Pack<doxid-class_e_e_1_1_system_1_1_pack>`* pack, std::string filePackPath);
		bool :ref:`saveToFile<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1aaa31f2a25a0e194caac367faae746ea1>`(const std::string& filename) const;
		const :ref:`Int16<doxid-namespace_e_e_1a73642650c4b4c754551791873b930462>`* :ref:`getSamples<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a295f36b8db83e44ae577bccb0471db11>`() const;
		:ref:`Uint64<doxid-namespace_e_e_1ae05f59b032c290566852fe63cb26135c>` :ref:`getSampleCount<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a13caeafb75c1ad4e95fa9fe27e465578>`() const;
		unsigned int :ref:`getSampleRate<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a25e560870332301e67fc7cf567986498>`() const;
		unsigned int :ref:`getChannelCount<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a91d6c89ccf85ca544a73af78f9b54125>`() const;
		:ref:`Time<doxid-class_e_e_1_1_system_1_1_time>` :ref:`getDuration<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a535099599f4c42b2882f9565c7878472>`() const;
		SoundBuffer& :ref:`operator=<doxid-class_e_e_1_1_audio_1_1_sound_buffer_1ac2cc17073c20661047743df3c130a7a3>`(const SoundBuffer& right);
	};
.. _details-class_e_e_1_1_audio_1_1_sound_buffer:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

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 :ref:`SoundBuffer <doxid-class_e_e_1_1_audio_1_1_sound_buffer>` is similar to a Texture.

A sound buffer can be loaded from a file (see :ref:`loadFromFile() <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a90d0d1a0cd50318fec427a25d3953692>` for the complete list of supported formats), from memory, from a custom stream (see IOStream) or directly from an array of samples. It can also be saved back to a file.

:ref:`Sound <doxid-class_e_e_1_1_audio_1_1_sound>` buffers alone are not very useful: they hold the audio data but cannot be played. To do so, you need to use the :ref:`Sound <doxid-class_e_e_1_1_audio_1_1_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 :ref:`SoundBuffer <doxid-class_e_e_1_1_audio_1_1_sound_buffer>` is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a :ref:`Sound <doxid-class_e_e_1_1_audio_1_1_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 :ref:`Sound <doxid-class_e_e_1_1_audio_1_1_sound>` instances to the same :ref:`SoundBuffer <doxid-class_e_e_1_1_audio_1_1_sound_buffer>`.

It is important to note that the :ref:`Sound <doxid-class_e_e_1_1_audio_1_1_sound>` instance doesn't copy the buffer that it uses, it only keeps a reference to it. Thus, a :ref:`SoundBuffer <doxid-class_e_e_1_1_audio_1_1_sound_buffer>` must not be destructed while it is used by a :ref:`Sound <doxid-class_e_e_1_1_audio_1_1_sound>` (i.e. never write a function that uses a local :ref:`SoundBuffer <doxid-class_e_e_1_1_audio_1_1_sound_buffer>` instance for loading a sound).

Usage example:

.. ref-code-block:: cpp

	// Declare a new sound buffer
	SoundBuffer buffer;
	
	// Load it from a file
	if (!buffer.loadFromFile("sound.wav"))
	{
	 // error...
	}
	
	// Create a sound source and bind it to the buffer
	Sound sound1;
	sound1.setBuffer(buffer);
	
	// Play the sound
	sound1.play();
	
	// Create another sound source bound to the same buffer
	Sound sound2;
	sound2.setBuffer(buffer);
	
	// Play it with a higher pitch -- the first sound remains unchanged
	sound2.setPitch(2);
	sound2.play();



.. rubric:: See also:

:ref:`Sound <doxid-class_e_e_1_1_audio_1_1_sound>`, :ref:`SoundBufferRecorder <doxid-class_e_e_1_1_audio_1_1_sound_buffer_recorder>`

Construction
------------

.. index:: pair: function; SoundBuffer
.. _doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a05d0de08edfbbd0fb614497d40310aa6:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	SoundBuffer(const SoundBuffer& copy)

Copy constructor.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- copy

		- Instance to copy

Methods
-------

.. index:: pair: function; loadFromFile
.. _doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a90d0d1a0cd50318fec427a25d3953692:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool loadFromFile(const std::string& filename)

Load the sound buffer from a file.

See the documentation of :ref:`InputSoundFile <doxid-class_e_e_1_1_audio_1_1_input_sound_file>` for the list of supported formats.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- filename

		- Path of the sound file to load



.. rubric:: Returns:

True if loading succeeded, false if it failed



.. rubric:: See also:

:ref:`loadFromMemory <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a8abf7fd8a8625edac832d02f88469a9e>`, :ref:`loadFromStream <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1aca3dc430a056f0d2f393ce0e19625318>`, :ref:`loadFromSamples <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a688a61e4f1ffdf316b990224e8bc6247>`, :ref:`saveToFile <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1aaa31f2a25a0e194caac367faae746ea1>`

.. index:: pair: function; loadFromMemory
.. _doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a8abf7fd8a8625edac832d02f88469a9e:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool loadFromMemory(const void* data, std::size_t sizeInBytes)

Load the sound buffer from a file in memory.

See the documentation of :ref:`InputSoundFile <doxid-class_e_e_1_1_audio_1_1_input_sound_file>` for the list of supported formats.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- data

		- Pointer to the file data in memory

	*
		- sizeInBytes

		- Size of the data to load, in bytes



.. rubric:: Returns:

True if loading succeeded, false if it failed



.. rubric:: See also:

:ref:`loadFromFile <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a90d0d1a0cd50318fec427a25d3953692>`, :ref:`loadFromStream <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1aca3dc430a056f0d2f393ce0e19625318>`, :ref:`loadFromSamples <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a688a61e4f1ffdf316b990224e8bc6247>`

.. index:: pair: function; loadFromStream
.. _doxid-class_e_e_1_1_audio_1_1_sound_buffer_1aca3dc430a056f0d2f393ce0e19625318:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool loadFromStream(:ref:`IOStream<doxid-class_e_e_1_1_system_1_1_i_o_stream>`& stream)

Load the sound buffer from a custom stream.

See the documentation of :ref:`InputSoundFile <doxid-class_e_e_1_1_audio_1_1_input_sound_file>` for the list of supported formats.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- stream

		- Source stream to read from



.. rubric:: Returns:

True if loading succeeded, false if it failed



.. rubric:: See also:

:ref:`loadFromFile <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a90d0d1a0cd50318fec427a25d3953692>`, :ref:`loadFromMemory <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a8abf7fd8a8625edac832d02f88469a9e>`, :ref:`loadFromSamples <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a688a61e4f1ffdf316b990224e8bc6247>`

.. index:: pair: function; loadFromSamples
.. _doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a688a61e4f1ffdf316b990224e8bc6247:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool loadFromSamples(const :ref:`Int16<doxid-namespace_e_e_1a73642650c4b4c754551791873b930462>`* samples, :ref:`Uint64<doxid-namespace_e_e_1ae05f59b032c290566852fe63cb26135c>` 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 (Int16).



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- 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)



.. rubric:: Returns:

True if loading succeeded, false if it failed



.. rubric:: See also:

:ref:`loadFromFile <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a90d0d1a0cd50318fec427a25d3953692>`, :ref:`loadFromMemory <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a8abf7fd8a8625edac832d02f88469a9e>`, :ref:`saveToFile <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1aaa31f2a25a0e194caac367faae746ea1>`

.. index:: pair: function; saveToFile
.. _doxid-class_e_e_1_1_audio_1_1_sound_buffer_1aaa31f2a25a0e194caac367faae746ea1:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool saveToFile(const std::string& filename) const

Save the sound buffer to an audio file.

See the documentation of :ref:`OutputSoundFile <doxid-class_e_e_1_1_audio_1_1_output_sound_file>` for the list of supported formats.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- filename

		- Path of the sound file to write



.. rubric:: Returns:

True if saving succeeded, false if it failed



.. rubric:: See also:

:ref:`loadFromFile <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a90d0d1a0cd50318fec427a25d3953692>`, :ref:`loadFromMemory <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a8abf7fd8a8625edac832d02f88469a9e>`, :ref:`loadFromSamples <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a688a61e4f1ffdf316b990224e8bc6247>`

.. index:: pair: function; getSamples
.. _doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a295f36b8db83e44ae577bccb0471db11:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	const :ref:`Int16<doxid-namespace_e_e_1a73642650c4b4c754551791873b930462>`* getSamples() const

Get the array of audio samples stored in the buffer.

The format of the returned samples is 16 bits signed integer (Int16). The total number of samples in this array is given by the :ref:`getSampleCount() <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a13caeafb75c1ad4e95fa9fe27e465578>` function.



.. rubric:: Returns:

Read-only pointer to the array of sound samples



.. rubric:: See also:

:ref:`getSampleCount <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a13caeafb75c1ad4e95fa9fe27e465578>`

.. index:: pair: function; getSampleCount
.. _doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a13caeafb75c1ad4e95fa9fe27e465578:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Uint64<doxid-namespace_e_e_1ae05f59b032c290566852fe63cb26135c>` getSampleCount() const

Get the number of samples stored in the buffer.

The array of samples can be accessed with the :ref:`getSamples() <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a295f36b8db83e44ae577bccb0471db11>` function.



.. rubric:: Returns:

Number of samples



.. rubric:: See also:

:ref:`getSamples <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a295f36b8db83e44ae577bccb0471db11>`

.. index:: pair: function; getSampleRate
.. _doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a25e560870332301e67fc7cf567986498:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	unsigned int 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).



.. rubric:: Returns:

Sample rate (number of samples per second)



.. rubric:: See also:

:ref:`getChannelCount <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a91d6c89ccf85ca544a73af78f9b54125>`, :ref:`getDuration <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a535099599f4c42b2882f9565c7878472>`

.. index:: pair: function; getChannelCount
.. _doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a91d6c89ccf85ca544a73af78f9b54125:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	unsigned int 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.



.. rubric:: Returns:

Number of channels



.. rubric:: See also:

:ref:`getSampleRate <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a25e560870332301e67fc7cf567986498>`, :ref:`getDuration <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a535099599f4c42b2882f9565c7878472>`

.. index:: pair: function; getDuration
.. _doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a535099599f4c42b2882f9565c7878472:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Time<doxid-class_e_e_1_1_system_1_1_time>` getDuration() const

Get the total duration of the sound.



.. rubric:: Returns:

:ref:`Sound <doxid-class_e_e_1_1_audio_1_1_sound>` duration



.. rubric:: See also:

:ref:`getSampleRate <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a25e560870332301e67fc7cf567986498>`, :ref:`getChannelCount <doxid-class_e_e_1_1_audio_1_1_sound_buffer_1a91d6c89ccf85ca544a73af78f9b54125>`

.. index:: pair: function; operator=
.. _doxid-class_e_e_1_1_audio_1_1_sound_buffer_1ac2cc17073c20661047743df3c130a7a3:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	SoundBuffer& operator=(const SoundBuffer& right)

Overload of assignment operator.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- right

		- Instance to assign



.. rubric:: Returns:

Reference to self