JUCE
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
Public Member Functions | List of all members
AudioSampleBuffer Class Reference

A multi-channel buffer of 32-bit floating point audio samples. More...

Public Member Functions

 AudioSampleBuffer () noexcept
 Creates an empty buffer with 0 channels and 0 length.
 
 AudioSampleBuffer (int numChannels, int numSamples) noexcept
 Creates a buffer with a specified number of channels and samples.
 
 AudioSampleBuffer (float *const *dataToReferTo, int numChannels, int numSamples) noexcept
 Creates a buffer using a pre-allocated block of memory.
 
 AudioSampleBuffer (float *const *dataToReferTo, int numChannels, int startSample, int numSamples) noexcept
 Creates a buffer using a pre-allocated block of memory.
 
 AudioSampleBuffer (const AudioSampleBuffer &) noexcept
 Copies another buffer.
 
AudioSampleBufferoperator= (const AudioSampleBuffer &) noexcept
 Copies another buffer onto this one.
 
 ~AudioSampleBuffer () noexcept
 Destructor.
 
int getNumChannels () const noexcept
 Returns the number of channels of audio data that this buffer contains.
 
int getNumSamples () const noexcept
 Returns the number of samples allocated in each of the buffer's channels.
 
const float * getReadPointer (int channelNumber) const noexcept
 Returns a pointer to an array of read-only samples in one of the buffer's channels.
 
const float * getReadPointer (int channelNumber, int sampleIndex) const noexcept
 Returns a pointer to an array of read-only samples in one of the buffer's channels.
 
float * getWritePointer (int channelNumber) noexcept
 Returns a writeable pointer to one of the buffer's channels.
 
float * getWritePointer (int channelNumber, int sampleIndex) noexcept
 Returns a writeable pointer to one of the buffer's channels.
 
const float ** getArrayOfReadPointers () const noexcept
 Returns an array of pointers to the channels in the buffer.
 
float ** getArrayOfWritePointers () noexcept
 Returns an array of pointers to the channels in the buffer.
 
void setSize (int newNumChannels, int newNumSamples, bool keepExistingContent=false, bool clearExtraSpace=false, bool avoidReallocating=false) noexcept
 Changes the buffer's size or number of channels.
 
void setDataToReferTo (float **dataToReferTo, int numChannels, int numSamples) noexcept
 Makes this buffer point to a pre-allocated set of channel data arrays.
 
void clear () noexcept
 Clears all the samples in all channels.
 
void clear (int startSample, int numSamples) noexcept
 Clears a specified region of all the channels.
 
void clear (int channel, int startSample, int numSamples) noexcept
 Clears a specified region of just one channel.
 
bool hasBeenCleared () const noexcept
 Returns true if the buffer has been entirely cleared.
 
float getSample (int channel, int sampleIndex) const noexcept
 Returns a sample from the buffer.
 
void setSample (int destChannel, int destSample, float newValue) noexcept
 Sets a sample in the buffer.
 
void addSample (int destChannel, int destSample, float valueToAdd) noexcept
 Adds a value to a sample in the buffer.
 
void applyGain (int channel, int startSample, int numSamples, float gain) noexcept
 Applies a gain multiple to a region of one channel.
 
void applyGain (int startSample, int numSamples, float gain) noexcept
 Applies a gain multiple to a region of all the channels.
 
void applyGain (float gain) noexcept
 Applies a gain multiple to all the audio data.
 
void applyGainRamp (int channel, int startSample, int numSamples, float startGain, float endGain) noexcept
 Applies a range of gains to a region of a channel.
 
void applyGainRamp (int startSample, int numSamples, float startGain, float endGain) noexcept
 Applies a range of gains to a region of all channels.
 
void addFrom (int destChannel, int destStartSample, const AudioSampleBuffer &source, int sourceChannel, int sourceStartSample, int numSamples, float gainToApplyToSource=1.0f) noexcept
 Adds samples from another buffer to this one.
 
void addFrom (int destChannel, int destStartSample, const float *source, int numSamples, float gainToApplyToSource=1.0f) noexcept
 Adds samples from an array of floats to one of the channels.
 
void addFromWithRamp (int destChannel, int destStartSample, const float *source, int numSamples, float startGain, float endGain) noexcept
 Adds samples from an array of floats, applying a gain ramp to them.
 
void copyFrom (int destChannel, int destStartSample, const AudioSampleBuffer &source, int sourceChannel, int sourceStartSample, int numSamples) noexcept
 Copies samples from another buffer to this one.
 
void copyFrom (int destChannel, int destStartSample, const float *source, int numSamples) noexcept
 Copies samples from an array of floats into one of the channels.
 
void copyFrom (int destChannel, int destStartSample, const float *source, int numSamples, float gain) noexcept
 Copies samples from an array of floats into one of the channels, applying a gain to it.
 
void copyFromWithRamp (int destChannel, int destStartSample, const float *source, int numSamples, float startGain, float endGain) noexcept
 Copies samples from an array of floats into one of the channels, applying a gain ramp.
 
Range< float > findMinMax (int channel, int startSample, int numSamples) const noexcept
 Returns a Range indicating the lowest and highest sample values in a given section.
 
float getMagnitude (int channel, int startSample, int numSamples) const noexcept
 Finds the highest absolute sample value within a region of a channel.
 
float getMagnitude (int startSample, int numSamples) const noexcept
 Finds the highest absolute sample value within a region on all channels.
 
float getRMSLevel (int channel, int startSample, int numSamples) const noexcept
 Returns the root mean squared level for a region of a channel.
 
void reverse (int channel, int startSample, int numSamples) const noexcept
 Reverses a part of a channel.
 
void reverse (int startSample, int numSamples) const noexcept
 Reverses a part of the buffer.
 

Detailed Description

A multi-channel buffer of 32-bit floating point audio samples.

Constructor & Destructor Documentation

AudioSampleBuffer::AudioSampleBuffer ( )
noexcept

Creates an empty buffer with 0 channels and 0 length.

AudioSampleBuffer::AudioSampleBuffer ( int  numChannels,
int  numSamples 
)
noexcept

Creates a buffer with a specified number of channels and samples.

The contents of the buffer will initially be undefined, so use clear() to set all the samples to zero.

The buffer will allocate its memory internally, and this will be released when the buffer is deleted. If the memory can't be allocated, this will throw a std::bad_alloc exception.

AudioSampleBuffer::AudioSampleBuffer ( float *const *  dataToReferTo,
int  numChannels,
int  numSamples 
)
noexcept

Creates a buffer using a pre-allocated block of memory.

Note that if the buffer is resized or its number of channels is changed, it will re-allocate memory internally and copy the existing data to this new area, so it will then stop directly addressing this memory.

Parameters
dataToReferToa pre-allocated array containing pointers to the data for each channel that should be used by this buffer. The buffer will only refer to this memory, it won't try to delete it when the buffer is deleted or resized.
numChannelsthe number of channels to use - this must correspond to the number of elements in the array passed in
numSamplesthe number of samples to use - this must correspond to the size of the arrays passed in
AudioSampleBuffer::AudioSampleBuffer ( float *const *  dataToReferTo,
int  numChannels,
int  startSample,
int  numSamples 
)
noexcept

Creates a buffer using a pre-allocated block of memory.

Note that if the buffer is resized or its number of channels is changed, it will re-allocate memory internally and copy the existing data to this new area, so it will then stop directly addressing this memory.

Parameters
dataToReferToa pre-allocated array containing pointers to the data for each channel that should be used by this buffer. The buffer will only refer to this memory, it won't try to delete it when the buffer is deleted or resized.
numChannelsthe number of channels to use - this must correspond to the number of elements in the array passed in
startSamplethe offset within the arrays at which the data begins
numSamplesthe number of samples to use - this must correspond to the size of the arrays passed in
AudioSampleBuffer::AudioSampleBuffer ( const AudioSampleBuffer )
noexcept

Copies another buffer.

This buffer will make its own copy of the other's data, unless the buffer was created using an external data buffer, in which case boths buffers will just point to the same shared block of data.

AudioSampleBuffer::~AudioSampleBuffer ( )
noexcept

Destructor.

This will free any memory allocated by the buffer.

Member Function Documentation

AudioSampleBuffer& AudioSampleBuffer::operator= ( const AudioSampleBuffer )
noexcept

Copies another buffer onto this one.

This buffer's size will be changed to that of the other buffer.

int AudioSampleBuffer::getNumChannels ( ) const
noexcept

Returns the number of channels of audio data that this buffer contains.

See Also
getSampleData

Referenced by VST3BufferExchange::associateBufferTo().

int AudioSampleBuffer::getNumSamples ( ) const
noexcept

Returns the number of samples allocated in each of the buffer's channels.

See Also
getSampleData
const float* AudioSampleBuffer::getReadPointer ( int  channelNumber) const
noexcept

Returns a pointer to an array of read-only samples in one of the buffer's channels.

For speed, this doesn't check whether the channel number is out of range, so be careful when using it! If you need to write to the data, do NOT call this method and const_cast the result! Instead, you must call getWritePointer so that the buffer knows you're planning on modifying the data.

References isPositiveAndBelow(), and jassert.

const float* AudioSampleBuffer::getReadPointer ( int  channelNumber,
int  sampleIndex 
) const
noexcept

Returns a pointer to an array of read-only samples in one of the buffer's channels.

For speed, this doesn't check whether the channel number or index are out of range, so be careful when using it! If you need to write to the data, do NOT call this method and const_cast the result! Instead, you must call getWritePointer so that the buffer knows you're planning on modifying the data.

References isPositiveAndBelow(), and jassert.

float* AudioSampleBuffer::getWritePointer ( int  channelNumber)
noexcept

Returns a writeable pointer to one of the buffer's channels.

For speed, this doesn't check whether the channel number is out of range, so be careful when using it! Note that if you're not planning on writing to the data, you should always use getReadPointer instead.

References isPositiveAndBelow(), and jassert.

Referenced by VST3BufferExchange::associateBufferTo().

float* AudioSampleBuffer::getWritePointer ( int  channelNumber,
int  sampleIndex 
)
noexcept

Returns a writeable pointer to one of the buffer's channels.

For speed, this doesn't check whether the channel number or index are out of range, so be careful when using it! Note that if you're not planning on writing to the data, you should use getReadPointer instead.

References isPositiveAndBelow(), and jassert.

const float** AudioSampleBuffer::getArrayOfReadPointers ( ) const
noexcept

Returns an array of pointers to the channels in the buffer.

Don't modify any of the pointers that are returned, and bear in mind that these will become invalid if the buffer is resized.

float** AudioSampleBuffer::getArrayOfWritePointers ( )
noexcept

Returns an array of pointers to the channels in the buffer.

Don't modify any of the pointers that are returned, and bear in mind that these will become invalid if the buffer is resized.

void AudioSampleBuffer::setSize ( int  newNumChannels,
int  newNumSamples,
bool  keepExistingContent = false,
bool  clearExtraSpace = false,
bool  avoidReallocating = false 
)
noexcept

Changes the buffer's size or number of channels.

This can expand or contract the buffer's length, and add or remove channels.

If keepExistingContent is true, it will try to preserve as much of the old data as it can in the new buffer.

If clearExtraSpace is true, then any extra channels or space that is allocated will be also be cleared. If false, then this space is left uninitialised.

If avoidReallocating is true, then changing the buffer's size won't reduce the amount of memory that is currently allocated (but it will still increase it if the new size is bigger than the amount it currently has). If this is false, then a new allocation will be done so that the buffer uses takes up the minimum amount of memory that it needs.

If the required memory can't be allocated, this will throw a std::bad_alloc exception.

void AudioSampleBuffer::setDataToReferTo ( float **  dataToReferTo,
int  numChannels,
int  numSamples 
)
noexcept

Makes this buffer point to a pre-allocated set of channel data arrays.

There's also a constructor that lets you specify arrays like this, but this lets you change the channels dynamically.

Note that if the buffer is resized or its number of channels is changed, it will re-allocate memory internally and copy the existing data to this new area, so it will then stop directly addressing this memory.

Parameters
dataToReferToa pre-allocated array containing pointers to the data for each channel that should be used by this buffer. The buffer will only refer to this memory, it won't try to delete it when the buffer is deleted or resized.
numChannelsthe number of channels to use - this must correspond to the number of elements in the array passed in
numSamplesthe number of samples to use - this must correspond to the size of the arrays passed in
void AudioSampleBuffer::clear ( )
noexcept

Clears all the samples in all channels.

void AudioSampleBuffer::clear ( int  startSample,
int  numSamples 
)
noexcept

Clears a specified region of all the channels.

For speed, this doesn't check whether the channel and sample number are in-range, so be careful!

void AudioSampleBuffer::clear ( int  channel,
int  startSample,
int  numSamples 
)
noexcept

Clears a specified region of just one channel.

For speed, this doesn't check whether the channel and sample number are in-range, so be careful!

bool AudioSampleBuffer::hasBeenCleared ( ) const
noexcept

Returns true if the buffer has been entirely cleared.

Note that this does not actually measure the contents of the buffer - it simply returns a flag that is set when the buffer is cleared, and which is reset whenever functions like getWritePointer() are invoked. That means the method does not take any time, but it may return false negatives when in fact the buffer is still empty.

float AudioSampleBuffer::getSample ( int  channel,
int  sampleIndex 
) const
noexcept

Returns a sample from the buffer.

The channel and index are not checked - they are expected to be in-range. If not, an assertion will be thrown, but in a release build, you're into 'undefined behaviour' territory.

void AudioSampleBuffer::setSample ( int  destChannel,
int  destSample,
float  newValue 
)
noexcept

Sets a sample in the buffer.

The channel and index are not checked - they are expected to be in-range. If not, an assertion will be thrown, but in a release build, you're into 'undefined behaviour' territory.

void AudioSampleBuffer::addSample ( int  destChannel,
int  destSample,
float  valueToAdd 
)
noexcept

Adds a value to a sample in the buffer.

The channel and index are not checked - they are expected to be in-range. If not, an assertion will be thrown, but in a release build, you're into 'undefined behaviour' territory.

void AudioSampleBuffer::applyGain ( int  channel,
int  startSample,
int  numSamples,
float  gain 
)
noexcept

Applies a gain multiple to a region of one channel.

For speed, this doesn't check whether the channel and sample number are in-range, so be careful!

void AudioSampleBuffer::applyGain ( int  startSample,
int  numSamples,
float  gain 
)
noexcept

Applies a gain multiple to a region of all the channels.

For speed, this doesn't check whether the sample numbers are in-range, so be careful!

void AudioSampleBuffer::applyGain ( float  gain)
noexcept

Applies a gain multiple to all the audio data.

void AudioSampleBuffer::applyGainRamp ( int  channel,
int  startSample,
int  numSamples,
float  startGain,
float  endGain 
)
noexcept

Applies a range of gains to a region of a channel.

The gain that is applied to each sample will vary from startGain on the first sample to endGain on the last Sample, so it can be used to do basic fades.

For speed, this doesn't check whether the sample numbers are in-range, so be careful!

void AudioSampleBuffer::applyGainRamp ( int  startSample,
int  numSamples,
float  startGain,
float  endGain 
)
noexcept

Applies a range of gains to a region of all channels.

The gain that is applied to each sample will vary from startGain on the first sample to endGain on the last Sample, so it can be used to do basic fades.

For speed, this doesn't check whether the sample numbers are in-range, so be careful!

void AudioSampleBuffer::addFrom ( int  destChannel,
int  destStartSample,
const AudioSampleBuffer source,
int  sourceChannel,
int  sourceStartSample,
int  numSamples,
float  gainToApplyToSource = 1.0f 
)
noexcept

Adds samples from another buffer to this one.

Parameters
destChannelthe channel within this buffer to add the samples to
destStartSamplethe start sample within this buffer's channel
sourcethe source buffer to add from
sourceChannelthe channel within the source buffer to read from
sourceStartSamplethe offset within the source buffer's channel to start reading samples from
numSamplesthe number of samples to process
gainToApplyToSourcean optional gain to apply to the source samples before they are added to this buffer's samples
See Also
copyFrom
void AudioSampleBuffer::addFrom ( int  destChannel,
int  destStartSample,
const float *  source,
int  numSamples,
float  gainToApplyToSource = 1.0f 
)
noexcept

Adds samples from an array of floats to one of the channels.

Parameters
destChannelthe channel within this buffer to add the samples to
destStartSamplethe start sample within this buffer's channel
sourcethe source data to use
numSamplesthe number of samples to process
gainToApplyToSourcean optional gain to apply to the source samples before they are added to this buffer's samples
See Also
copyFrom
void AudioSampleBuffer::addFromWithRamp ( int  destChannel,
int  destStartSample,
const float *  source,
int  numSamples,
float  startGain,
float  endGain 
)
noexcept

Adds samples from an array of floats, applying a gain ramp to them.

Parameters
destChannelthe channel within this buffer to add the samples to
destStartSamplethe start sample within this buffer's channel
sourcethe source data to use
numSamplesthe number of samples to process
startGainthe gain to apply to the first sample (this is multiplied with the source samples before they are added to this buffer)
endGainthe gain to apply to the final sample. The gain is linearly interpolated between the first and last samples.
void AudioSampleBuffer::copyFrom ( int  destChannel,
int  destStartSample,
const AudioSampleBuffer source,
int  sourceChannel,
int  sourceStartSample,
int  numSamples 
)
noexcept

Copies samples from another buffer to this one.

Parameters
destChannelthe channel within this buffer to copy the samples to
destStartSamplethe start sample within this buffer's channel
sourcethe source buffer to read from
sourceChannelthe channel within the source buffer to read from
sourceStartSamplethe offset within the source buffer's channel to start reading samples from
numSamplesthe number of samples to process
See Also
addFrom
void AudioSampleBuffer::copyFrom ( int  destChannel,
int  destStartSample,
const float *  source,
int  numSamples 
)
noexcept

Copies samples from an array of floats into one of the channels.

Parameters
destChannelthe channel within this buffer to copy the samples to
destStartSamplethe start sample within this buffer's channel
sourcethe source buffer to read from
numSamplesthe number of samples to process
See Also
addFrom
void AudioSampleBuffer::copyFrom ( int  destChannel,
int  destStartSample,
const float *  source,
int  numSamples,
float  gain 
)
noexcept

Copies samples from an array of floats into one of the channels, applying a gain to it.

Parameters
destChannelthe channel within this buffer to copy the samples to
destStartSamplethe start sample within this buffer's channel
sourcethe source buffer to read from
numSamplesthe number of samples to process
gainthe gain to apply
See Also
addFrom
void AudioSampleBuffer::copyFromWithRamp ( int  destChannel,
int  destStartSample,
const float *  source,
int  numSamples,
float  startGain,
float  endGain 
)
noexcept

Copies samples from an array of floats into one of the channels, applying a gain ramp.

Parameters
destChannelthe channel within this buffer to copy the samples to
destStartSamplethe start sample within this buffer's channel
sourcethe source buffer to read from
numSamplesthe number of samples to process
startGainthe gain to apply to the first sample (this is multiplied with the source samples before they are copied to this buffer)
endGainthe gain to apply to the final sample. The gain is linearly interpolated between the first and last samples.
See Also
addFrom
Range<float> AudioSampleBuffer::findMinMax ( int  channel,
int  startSample,
int  numSamples 
) const
noexcept

Returns a Range indicating the lowest and highest sample values in a given section.

Parameters
channelthe channel to read from
startSamplethe start sample within the channel
numSamplesthe number of samples to check
float AudioSampleBuffer::getMagnitude ( int  channel,
int  startSample,
int  numSamples 
) const
noexcept

Finds the highest absolute sample value within a region of a channel.

float AudioSampleBuffer::getMagnitude ( int  startSample,
int  numSamples 
) const
noexcept

Finds the highest absolute sample value within a region on all channels.

float AudioSampleBuffer::getRMSLevel ( int  channel,
int  startSample,
int  numSamples 
) const
noexcept

Returns the root mean squared level for a region of a channel.

void AudioSampleBuffer::reverse ( int  channel,
int  startSample,
int  numSamples 
) const
noexcept

Reverses a part of a channel.

void AudioSampleBuffer::reverse ( int  startSample,
int  numSamples 
) const
noexcept

Reverses a part of the buffer.


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