A class representing a buffer of multichannel audio data. More...

#include <omSoundBuffer.h>

Public Member Functions
	SoundBuffer ()
	Create a SoundBuffer object with zero channels of zero samples each. More...

	SoundBuffer (Size newNumChannels)
	Create a SoundBuffer object with the specified number of channels. More...

	SoundBuffer (Size newNumChannels, Size newNumSamples, SampleRate newSampleRate=44100)
	Create a SoundBuffer object with the specified number of channels and buffer size. More...

	SoundBuffer (ChannelLayoutType newLayoutType)
	Create a SoundBuffer object that uses the specified predefined channel layout type. More...

	SoundBuffer (ChannelLayoutType newLayoutType, Size newNumSamples, SampleRate newSampleRate=44100)
	Create a SoundBuffer object that uses the specified channel layout type, size, and sample rate. More...

	SoundBuffer (const ChannelLayout &newLayout)
	Create a SoundBuffer object that uses the specified channel layout. More...

	SoundBuffer (const ChannelLayout &newLayout, Size newNumSamples, SampleRate newSampleRate=44100)
	Create a SoundBuffer object that uses the specified channel layout, size, and sample rate. More...

	SoundBuffer (const SoundBuffer &other)
	Create an exact copy of the specified SoundBuffer. More...

	SoundBuffer (const SoundBuffer &other, Size numSamples)
	Create a copy of the specified SoundBuffer, using at most the specified number of samples. More...

	~SoundBuffer ()
	Destroy a SoundBuffer object. More...

SoundBuffer &	operator= (const SoundBuffer &other)
	Copy the contents of one SoundBuffer object into this SoundBuffer object. More...

const ChannelLayout &	getLayout () const
	Return a reference to an object describing this buffer's channel layout. More...

void	setLayout (const ChannelLayout &newLayout)
	Replace the current channel layout of this sound buffer with the specified one. More...

void	setLayout (ChannelLayoutType newLayoutType)
	Replace the current channel layout of this sound buffer with a predefined layout of the given type. More...

Size	getChannelCount () const
	Get the number of channels that this SoundBuffer object has. More...

void	setChannelCount (Size newNumChannels)
	Set the number of channels that this SoundBuffer object has. More...

ChannelType	getChannelType (Index channelIndex) const
	Return an object representing the semantic type of the channel at the specified index. More...

void	setChannelType (Index channelIndex, ChannelType newType)
	Set the semantic type of the channel at the specified index. More...

Vector3f	getChannelPosition (Index channelIndex) const
	Return a the channel position at the specified index. More...

void	setChannelPosition (Index channelIndex, const Vector2f &newPosition)
	Set the position of the channel's speaker at the specified index. More...

Size	getSize () const
	Return the number of samples that this SoundBuffer object is holding. More...

void	setSize (Size newSize)
	Set the number of samples that this SoundBuffer object is holding. More...

Size	getSizeInBytes () const
	Return the approximate number of bytes of memory allocated by this sound buffer. More...

SampleRate	getSampleRate () const
	Return the sampling rate of this sound buffer in samples per second. More...

void	setSampleRate (SampleRate newSampleRate)
	Set the sampling rate of this sound buffer in samples per second. More...

Sample32f *	getChannel (Index channelIndex)
	Get a pointer to the first sample within the channel with the specified index. More...

const Sample32f *	getChannel (Index channelIndex) const
	Get a pointer to the first sample within the channel with the specified index. More...

Sample32f *	getChannelEnd (Index channelIndex)
	Get a pointer to just past the last sample within the channel with the specified index. More...

const Sample32f *	getChannelEnd (Index channelIndex) const
	Get a pointer to just past the last sample within the channel with the specified index. More...

Size	getStride () const
	Return the advance (in samples) between successive samples of the same channel in this sound buffer. More...

void	zero ()
	Zero-out the entire contents of this SoundBuffer. More...

void	zero (Index startIndex, Size numSamplesToZero)
	Zero-out a range of the contents of this SoundBuffer. More...

Size	copyToInterleavedBuffer (Sample32f *output, Size numSamplesToCopy) const
	Copy the specified number of samples from each channel of this buffer to the output buffer. More...

Size	copyTo (SoundBuffer &other) const
	Copy the contents of this buffer to the other specified sound buffer. More...

Size	copyTo (SoundBuffer &other, Size numSamplesToCopy) const
	Copy the specified number of samples from this buffer to the other specified sound buffer. More...

Size	mixTo (SoundBuffer &other) const
	Mix the contents of this buffer with the other specified sound buffer. More...

Size	mixTo (SoundBuffer &other, Size numSamples) const
	Mix the specified number of samples from this buffer with the other specified sound buffer. More...

Size	mixTo (SoundBuffer &other, Size numSamples, Gain gain) const
	Mix the specified number of samples from this buffer with the other specified sound buffer after applying a gain factor. More...

void	applyGain (Gain linearGain)
	Apply the specified linear gain factor to all samples in this buffer, modifying it. More...

void	applyGain (Gain linearGain, Size numSamples)
	Apply the specified linear gain factor to the specified number of samples in this buffer, modifying it. More...

void	invertPolarity ()
	Invert the polarity for the all of the samples in the buffer. More...

void	invertPolarity (Size numSamples)
	Invert the polarity for the specified number of samples in the buffer. More...

void	copyFormatTo (SoundBuffer &other) const
	Copy the format of this buffer to the other specified buffer. More...

void	copyFormatTo (SoundBuffer &other, Size minimumNumberOfSamples) const
	Copy the format of this buffer to the other specified buffer. More...

void	setFormat (Size newNumChannels, Size newNumSamples)
	Set the format of this buffer, so that it has the specified number of channels and samples. More...

Static Public Attributes
static const om::resources::ResourceType	RESOURCE_TYPE
	The resource type for a SoundBuffer resource. More...

Detailed Description

A class representing a buffer of multichannel audio data.

A SoundBuffer class contains zero or more non-interleaved channels of audio data. All channels are the same length. The class will not allocate any memory for audio data unless the number of channels and length of the buffer are non-zero, saving unnecessary allocations. The class also uses a fixed-size internal array of channel pointers, avoiding channel array allocations for small numbers of channels.

The sampling rate of the audio contained in a SoundBuffer is stored in each instance of the class. This sampling rate may be changed without affecting the samples stored in the buffer, resulting in a pitch shifting effect when interpreted at the new sample rate.

The starting samples for each channel in a buffer are guaranteed to be 16-byte aligned which allows efficient SIMD processing of channel data.

Constructor & Destructor Documentation

om::sound::base::SoundBuffer::SoundBuffer ( )

inline

Create a SoundBuffer object with zero channels of zero samples each.

No memory is allocated until the number of channels is set to a non-zero value using the setChannelCount() method.

The default sampling rate of 44.1 kHz is used.

The channel layout for this buffer is by default ChannelLayout::UNDEFINED.

om::sound::base::SoundBuffer::SoundBuffer ( Size newNumChannels )

Create a SoundBuffer object with the specified number of channels.

The buffer is initially of length 0, meaning that no channel data will be allocated until the size of the buffer is set to a value greater than 0.

The default sampling rate of 44.1 kHz is used. The channel layout for this buffer is by default ChannelLayout::UNDEFINED.

Parameters

newNumChannels - the number of channels that this sound buffers should have.

om::sound::base::SoundBuffer::SoundBuffer	(	Size	newNumChannels,
		Size	newNumSamples,
		SampleRate	newSampleRate = `44100`
	)

Create a SoundBuffer object with the specified number of channels and buffer size.

This constructor allows the user to specify the desired sample rate of the sound contained in the buffer, with a default value of 44.1 kHz.

The channel layout for this buffer is by default ChannelLayout::UNDEFINED.

Parameters

newNumChannels	- the number of channels that this sound buffers should have.
newNumSamples	- the length in samples that this buffer should have.
newSampleRate	- the sample rate to use for the audio contained in this buffer.

om::sound::base::SoundBuffer::SoundBuffer ( ChannelLayoutType newLayoutType )

Create a SoundBuffer object that uses the specified predefined channel layout type.

The channel layout type determines the total number of channels in the buffer, as well as their types. The buffer is initially of length 0, meaning that no channel data will be allocated until the size of the buffer is set to a value greater than 0.

The default sampling rate of 44.1 kHz is used.

om::sound::base::SoundBuffer::SoundBuffer	(	ChannelLayoutType	newLayoutType,
		Size	newNumSamples,
		SampleRate	newSampleRate = `44100`
	)

Create a SoundBuffer object that uses the specified channel layout type, size, and sample rate.

The channel layout type determines the total number of channels in the buffer, as well as their types.

The default sampling rate of 44.1 kHz is used.

om::sound::base::SoundBuffer::SoundBuffer ( const ChannelLayout & newLayout )

Create a SoundBuffer object that uses the specified channel layout.

The channel layout determines the total number of channels in the buffer, as well as their types. The buffer is initially of length 0, meaning that no channel data will be allocated until the size of the buffer is set to a value greater than 0.

The default sampling rate of 44.1 kHz is used.

om::sound::base::SoundBuffer::SoundBuffer	(	const ChannelLayout &	newLayout,
		Size	newNumSamples,
		SampleRate	newSampleRate = `44100`
	)

Create a SoundBuffer object that uses the specified channel layout, size, and sample rate.

The channel layout determines the total number of channels in the buffer, as well as their types.

The default sampling rate of 44.1 kHz is used.

om::sound::base::SoundBuffer::SoundBuffer ( const SoundBuffer & other )

Create an exact copy of the specified SoundBuffer.

Parameters

other - the SoundBuffer object whose state is to be copied.

om::sound::base::SoundBuffer::SoundBuffer	(	const SoundBuffer &	other,
		Size	numSamples
	)

Create a copy of the specified SoundBuffer, using at most the specified number of samples.

Parameters

other	- the SoundBuffer object whose state is to be copied.
numSamples	- the number of samples to copy from the specified sound buffer.

om::sound::base::SoundBuffer::~SoundBuffer ( )

Destroy a SoundBuffer object.

All internally allocated data is released.

Member Function Documentation

SoundBuffer& om::sound::base::SoundBuffer::operator= ( const SoundBuffer & other )

Copy the contents of one SoundBuffer object into this SoundBuffer object.

All previously existing internal state is released and new state allocated to exactly replicate the specified SoundBuffer object.

Parameters

other - the SoundBuffer object whose state should replace this SoundBuffer's.

Returns: a reference to this SoundBuffer object, allowing assignment chaining.

const ChannelLayout& om::sound::base::SoundBuffer::getLayout ( ) const

inline

Return a reference to an object describing this buffer's channel layout.

void om::sound::base::SoundBuffer::setLayout ( const ChannelLayout & newLayout )

Replace the current channel layout of this sound buffer with the specified one.

This method may resize the number of channels in the buffer so that it is at least the number of channels in the specified layout.

void om::sound::base::SoundBuffer::setLayout ( ChannelLayoutType newLayoutType )

Replace the current channel layout of this sound buffer with a predefined layout of the given type.

This method may resize the number of channels in the buffer so that it is at least the number of channels in the specified layout.

Size om::sound::base::SoundBuffer::getChannelCount ( ) const

inline

Get the number of channels that this SoundBuffer object has.

Returns: the number of channels that this sound buffer has.

void om::sound::base::SoundBuffer::setChannelCount ( Size newNumChannels )

Set the number of channels that this SoundBuffer object has.

Changing the number of channels entails reallocating the internal array of channels and is a potentially expensive operation.

Parameters

newNumChannels - the new number of channels that this SoundBuffer object should have.

ChannelType om::sound::base::SoundBuffer::getChannelType ( Index channelIndex ) const

inline

Return an object representing the semantic type of the channel at the specified index.

If the given channel index is invalid, the ChannelType::UNDEFINED type is returned.

void om::sound::base::SoundBuffer::setChannelType	(	Index	channelIndex,
		ChannelType	newType
	)

inline

Set the semantic type of the channel at the specified index.

If the given channel index is invalid, the method has no effect.

Vector3f om::sound::base::SoundBuffer::getChannelPosition ( Index channelIndex ) const

inline

Return a the channel position at the specified index.

If the channel index is invalid or if the speaker is not positional, the vector (0,0,0) is returned.

void om::sound::base::SoundBuffer::setChannelPosition	(	Index	channelIndex,
		const Vector2f &	newPosition
	)

inline

Set the position of the channel's speaker at the specified index.

Size om::sound::base::SoundBuffer::getSize ( ) const

inline

Return the number of samples that this SoundBuffer object is holding.

Returns: the number of samples that this SoundBuffer object is holding.

void om::sound::base::SoundBuffer::setSize ( Size newSize )

Set the number of samples that this SoundBuffer object is holding.

This method reallocates the internal channel buffers if necessary to hold the specified number of samples. If the specified size is less than the current size, no memory may be reallocated if not necessary. The existing samples in the old buffer are coppied over to the new buffer if one is allocated. The remaining new samples are uninitialized and have undefined contents.

Parameters

newSize - the new number of samples that this SoundBuffer should hold.

Size om::sound::base::SoundBuffer::getSizeInBytes ( ) const

inline

Return the approximate number of bytes of memory allocated by this sound buffer.

SampleRate om::sound::base::SoundBuffer::getSampleRate ( ) const

inline

Return the sampling rate of this sound buffer in samples per second.

void om::sound::base::SoundBuffer::setSampleRate ( SampleRate newSampleRate )

inline

Set the sampling rate of this sound buffer in samples per second.

This method does not alter the channel count, the number of samples, or any of the samples in the buffer. It simply sets the sampling rate at which the buffer's samples should be interpreted.

Sample32f* om::sound::base::SoundBuffer::getChannel ( Index channelIndex )

inline

Get a pointer to the first sample within the channel with the specified index.

If the specified channel index is not within the valid bounds of channel indices, an assertion is raised.

Parameters

channelIndex - the channel whose start pointer should be accessed.

Returns: a pointer to the first sample of the specified channel within this SoundBuffer.

const Sample32f* om::sound::base::SoundBuffer::getChannel ( Index channelIndex ) const

inline

Get a pointer to the first sample within the channel with the specified index.

If the specified channel index is not within the valid bounds of channel indices, an assertion is raised.

Parameters

channelIndex - the channel whose start pointer should be accessed.

Returns: a pointer to the first sample of the specified channel within this SoundBuffer.

Sample32f* om::sound::base::SoundBuffer::getChannelEnd ( Index channelIndex )

inline

Get a pointer to just past the last sample within the channel with the specified index.

If the specified channel index is not within the valid bounds of channel indices, an assertion is raised.

Parameters

channelIndex - the channel whose end pointer should be accessed.

Returns: a pointer to the first sample after the end of the specified channel.

const Sample32f* om::sound::base::SoundBuffer::getChannelEnd ( Index channelIndex ) const

inline

Get a pointer to just past the last sample within the channel with the specified index.

If the specified channel index is not within the valid bounds of channel indices, an assertion is raised.

Parameters

channelIndex - the channel whose end pointer should be accessed.

Returns: a pointer to the first sample after the end of the specified channel.

Size om::sound::base::SoundBuffer::getStride ( ) const

inline

Return the advance (in samples) between successive samples of the same channel in this sound buffer.

The stride is always 0 for non-interleaved buffer (the default). For interleaved buffers, the stride depends on the storage format of the buffer.

void om::sound::base::SoundBuffer::zero ( )

inline

Zero-out the entire contents of this SoundBuffer.

void om::sound::base::SoundBuffer::zero	(	Index	startIndex,
		Size	numSamplesToZero
	)

Zero-out a range of the contents of this SoundBuffer.

This method writes zero to every sample of every channel in this SoundBuffer starting at the specified sample start index and ending numSamples past that index.

Parameters

startIndex	- the first sample to be zero-d out in the SoundBuffer object.
numSamplesToZero	- the number of samples to be zero-d out after the start index.

Size om::sound::base::SoundBuffer::copyToInterleavedBuffer	(	Sample32f *	output,
		Size	numSamplesToCopy
	)		const

Copy the specified number of samples from each channel of this buffer to the output buffer.

The method interleaves the channel samples in the output buffer. The output buffer must be at least as large as the number of requested samples multiplied by the number of channels in this SoundBuffer.

If the supplied buffer pointer is NULL, the method return immediately and has no effect. If the number of samples in this SoundBuffer is less than the specified number of requested samples, the number of requested samples is clamped to the size of the SoundBuffer.

The method returns the total number of samples copied to the output buffer per channel.

Size om::sound::base::SoundBuffer::copyTo ( SoundBuffer & other ) const

inline

Copy the contents of this buffer to the other specified sound buffer.

The method returns the total number of samples per channel actually copied from this buffer.

Size om::sound::base::SoundBuffer::copyTo	(	SoundBuffer &	other,
		Size	numSamplesToCopy
	)		const

Copy the specified number of samples from this buffer to the other specified sound buffer.

The other buffer is enlarged to hold the contents of this buffer if necessary and as many samples as possible, up to the specified number of samples, are copied to the other buffer. The method returns the total number of samples per channel actually copied from this buffer.

Size om::sound::base::SoundBuffer::mixTo ( SoundBuffer & other ) const

inline

Mix the contents of this buffer with the other specified sound buffer.

This method overwrites the contents of the other buffer with the mixed output. The method returns the total number of samples per channel actually mixed from this buffer.

If the other buffer is smaller than the number of samples from this buffer, only that many samples are mixed (truncating the other samples).

Size om::sound::base::SoundBuffer::mixTo	(	SoundBuffer &	other,
		Size	numSamples
	)		const

Mix the specified number of samples from this buffer with the other specified sound buffer.

This method overwrites the contents of the other buffer with the mixed output. The method returns the total number of samples per channel actually mixed from this buffer.

If the other buffer is smaller than the number of samples from this buffer, only that many samples are mixed (truncating the other samples). If there is a mismatch in the number of buffer channels, as many channels as possible are mixed with the output buffer.

Size om::sound::base::SoundBuffer::mixTo	(	SoundBuffer &	other,
		Size	numSamples,
		Gain	gain
	)		const

Mix the specified number of samples from this buffer with the other specified sound buffer after applying a gain factor.

This method overwrites the contents of the other buffer with the mixed output. The method returns the total number of samples per channel actually mixed from this buffer.

If the other buffer is smaller than the number of samples from this buffer, only that many samples are mixed (truncating the other samples). If there is a mismatch in the number of buffer channels, as many channels as possible are mixed with the output buffer.

void om::sound::base::SoundBuffer::applyGain ( Gain linearGain )

inline

Apply the specified linear gain factor to all samples in this buffer, modifying it.

This method has the effect of multiplying all samples in the buffer by the specified gain factor.

void om::sound::base::SoundBuffer::applyGain	(	Gain	linearGain,
		Size	numSamples
	)

Apply the specified linear gain factor to the specified number of samples in this buffer, modifying it.

This method has the effect of multiplying the specified number of samples in the buffer by the specified gain factor.

void om::sound::base::SoundBuffer::invertPolarity ( )

inline

Invert the polarity for the all of the samples in the buffer.

void om::sound::base::SoundBuffer::invertPolarity ( Size numSamples )

Invert the polarity for the specified number of samples in the buffer.

void om::sound::base::SoundBuffer::copyFormatTo ( SoundBuffer & other ) const

inline

Copy the format of this buffer to the other specified buffer.

This method ensures that the specified buffer has the same sample rate, channel layout, number of channels, and size as this buffer.

void om::sound::base::SoundBuffer::copyFormatTo	(	SoundBuffer &	other,
		Size	minimumNumberOfSamples
	)		const

Copy the format of this buffer to the other specified buffer.

This method ensures that the specified buffer has the same sample rate, channel layout, and number of channels as this buffer. In addition, the specified buffer is enlarged to be at least as large as the specified minimum number of samples.

void om::sound::base::SoundBuffer::setFormat	(	Size	newNumChannels,
		Size	newNumSamples
	)

Set the format of this buffer, so that it has the specified number of channels and samples.

Member Data Documentation

const om::resources::ResourceType om::sound::base::SoundBuffer::RESOURCE_TYPE

static

The resource type for a SoundBuffer resource.

The documentation for this class was generated from the following file:

omSoundBuffer.h

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation