JUCE  v6.1.6 (6.0.8-1114)
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::dsp::Convolution Class Reference

Performs stereo partitioned convolution of an input signal with an impulse response in the frequency domain, using the JUCE FFT class. More...

#include <juce_Convolution.h>

Collaboration diagram for juce::dsp::Convolution:

Classes

struct  Latency
 Contains configuration information for a convolution with a fixed latency. More...
 
class  Mixer
 
struct  NonUniform
 Contains configuration information for a non-uniform convolution. More...
 

Public Types

enum  Normalise {
  Normalise::no,
  Normalise::yes
}
 
enum  Stereo {
  Stereo::no,
  Stereo::yes
}
 
enum  Trim {
  Trim::no,
  Trim::yes
}
 

Public Member Functions

 Convolution ()
 Initialises an object for performing convolution in the frequency domain. More...
 
 Convolution (const Latency &, ConvolutionMessageQueue &)
 Behaves the same as the constructor taking a single Latency argument, but with a shared background message queue. More...
 
 Convolution (const Latency &requiredLatency)
 Initialises an object for performing convolution with a fixed latency. More...
 
 Convolution (const NonUniform &, ConvolutionMessageQueue &)
 Behaves the same as the constructor taking a single NonUniform argument, but with a shared background message queue. More...
 
 Convolution (const NonUniform &requiredHeadSize)
 Initialises an object for performing convolution in the frequency domain using a non-uniform partitioned algorithm. More...
 
 Convolution (ConvolutionMessageQueue &queue)
 Initialises a convolution engine using a shared background message queue. More...
 
 ~Convolution () noexcept
 
int getCurrentIRSize () const
 This function returns the size of the current IR in samples. More...
 
int getLatency () const
 This function returns the current latency of the process in samples. More...
 
void loadImpulseResponse (AudioBuffer< float > &&buffer, double bufferSampleRate, Stereo isStereo, Trim requiresTrimming, Normalise requiresNormalisation)
 This function loads an impulse response from an audio buffer. More...
 
void loadImpulseResponse (const File &fileImpulseResponse, Stereo isStereo, Trim requiresTrimming, size_t size, Normalise requiresNormalisation=Normalise::yes)
 This function loads an impulse response from an audio file. More...
 
void loadImpulseResponse (const void *sourceData, size_t sourceDataSize, Stereo isStereo, Trim requiresTrimming, size_t size, Normalise requiresNormalisation=Normalise::yes)
 This function loads an impulse response audio file from memory, added in a JUCE project with the Projucer as binary data. More...
 
void prepare (const ProcessSpec &)
 Must be called before first calling process. More...
 
template<typename ProcessContext , std::enable_if_t< std::is_same< typename ProcessContext::SampleType, float >::value, int > = 0>
void process (const ProcessContext &context) noexcept
 Performs the filter operation on the given set of samples with optional stereo processing. More...
 
void reset () noexcept
 Resets the processing pipeline ready to start a new stream of data. More...
 

Private Member Functions

 Convolution (const Latency &, const NonUniform &, OptionalScopedPointer< ConvolutionMessageQueue > &&)
 
void processSamples (const AudioBlock< const float > &, AudioBlock< float > &, bool isBypassed) noexcept
 

Private Attributes

bool isActive = false
 
Mixer mixer
 
std::unique_ptr< Impl > pimpl
 

Detailed Description

Performs stereo partitioned convolution of an input signal with an impulse response in the frequency domain, using the JUCE FFT class.

This class provides some thread-safe functions to load impulse responses from audio files or memory on-the-fly without noticeable artefacts, performing resampling and trimming if necessary.

The processing performed by this class is equivalent to the time domain convolution done in the FIRFilter class, with a FIRFilter::Coefficients object having the samples of the impulse response as its coefficients. However, in general it is more efficient to do frequency domain convolution when the size of the impulse response is 64 samples or greater.

Note: The default operation of this class uses zero latency and a uniform partitioned algorithm. If the impulse response size is large, or if the algorithm is too CPU intensive, it is possible to use either a fixed latency version of the algorithm, or a simple non-uniform partitioned convolution algorithm.

Threading: It is not safe to interleave calls to the methods of this class. If you need to load new impulse responses during processing the load() calls must be synchronised with process() calls, which in practice means making the load() call from the audio thread. The loadImpulseResponse() functions are wait-free and are therefore suitable for use in a realtime context.

See also
FIRFilter, FIRFilter::Coefficients, FFT

@tags{DSP}

Member Enumeration Documentation

◆ Normalise

Enumerator
no 
yes 

◆ Stereo

Enumerator
no 
yes 

◆ Trim

Enumerator
no 
yes 

Constructor & Destructor Documentation

◆ Convolution() [1/7]

juce::dsp::Convolution::Convolution ( )

Initialises an object for performing convolution in the frequency domain.

◆ Convolution() [2/7]

juce::dsp::Convolution::Convolution ( ConvolutionMessageQueue queue)
explicit

Initialises a convolution engine using a shared background message queue.

IMPORTANT: the queue must remain alive throughout the lifetime of the Convolution.

◆ Convolution() [3/7]

juce::dsp::Convolution::Convolution ( const Latency requiredLatency)
explicit

Initialises an object for performing convolution with a fixed latency.

If the requested latency is zero, the actual latency will also be zero. For requested latencies greater than zero, the actual latency will always at least as large as the requested latency. Using a fixed non-zero latency can reduce the CPU consumption of the convolution algorithm.

Parameters
requiredLatencythe minimum latency

◆ Convolution() [4/7]

juce::dsp::Convolution::Convolution ( const NonUniform requiredHeadSize)
explicit

Initialises an object for performing convolution in the frequency domain using a non-uniform partitioned algorithm.

A requiredHeadSize of 256 samples or greater will improve the efficiency of the processing for IR sizes of 4096 samples or greater (recommended for reverberation IRs).

Parameters
requiredHeadSizethe head IR size for two stage non-uniform partitioned convolution

◆ Convolution() [5/7]

juce::dsp::Convolution::Convolution ( const Latency ,
ConvolutionMessageQueue  
)

Behaves the same as the constructor taking a single Latency argument, but with a shared background message queue.

IMPORTANT: the queue must remain alive throughout the lifetime of the Convolution.

◆ Convolution() [6/7]

juce::dsp::Convolution::Convolution ( const NonUniform ,
ConvolutionMessageQueue  
)

Behaves the same as the constructor taking a single NonUniform argument, but with a shared background message queue.

IMPORTANT: the queue must remain alive throughout the lifetime of the Convolution.

◆ ~Convolution()

juce::dsp::Convolution::~Convolution ( )
noexcept

◆ Convolution() [7/7]

juce::dsp::Convolution::Convolution ( const Latency ,
const NonUniform ,
OptionalScopedPointer< ConvolutionMessageQueue > &&   
)
private

Member Function Documentation

◆ getCurrentIRSize()

int juce::dsp::Convolution::getCurrentIRSize ( ) const

This function returns the size of the current IR in samples.

◆ getLatency()

int juce::dsp::Convolution::getLatency ( ) const

This function returns the current latency of the process in samples.

Note: This is the latency of the convolution engine, not the latency associated with the current impulse response choice that has to be considered separately (linear phase filters, for example).

◆ loadImpulseResponse() [1/3]

void juce::dsp::Convolution::loadImpulseResponse ( AudioBuffer< float > &&  buffer,
double  bufferSampleRate,
Stereo  isStereo,
Trim  requiresTrimming,
Normalise  requiresNormalisation 
)

This function loads an impulse response from an audio buffer.

To avoid memory allocation on the audio thread, this function takes ownership of the buffer passed in.

If calling this function during processing, make sure that the buffer is not allocated on the audio thread (be careful of accidental copies!). If you need to pass arbitrary/generated buffers it's recommended to create these buffers on a separate thread and to use some wait-free construct (a lock-free queue or a SpinLock/GenericScopedTryLock combination) to transfer ownership to the audio thread without allocating.

Parameters
bufferthe AudioBuffer to use
bufferSampleRatethe sampleRate of the data in the AudioBuffer
isStereoselects either stereo or mono
requiresTrimmingoptionally trim the start and the end of the impulse response
requiresNormalisationoptionally normalise the impulse response amplitude

◆ loadImpulseResponse() [2/3]

void juce::dsp::Convolution::loadImpulseResponse ( const File fileImpulseResponse,
Stereo  isStereo,
Trim  requiresTrimming,
size_t  size,
Normalise  requiresNormalisation = Normalise::yes 
)

This function loads an impulse response from an audio file.

It can load any of the audio formats registered in JUCE, and performs some resampling and pre-processing as well if needed.

Parameters
fileImpulseResponsethe location of the audio file
isStereoselects either stereo or mono
requiresTrimmingoptionally trim the start and the end of the impulse response
sizethe expected size for the impulse response after loading, can be set to 0 to requesting the original impulse response size
requiresNormalisationoptionally normalise the impulse response amplitude

◆ loadImpulseResponse() [3/3]

void juce::dsp::Convolution::loadImpulseResponse ( const void *  sourceData,
size_t  sourceDataSize,
Stereo  isStereo,
Trim  requiresTrimming,
size_t  size,
Normalise  requiresNormalisation = Normalise::yes 
)

This function loads an impulse response audio file from memory, added in a JUCE project with the Projucer as binary data.

It can load any of the audio formats registered in JUCE, and performs some resampling and pre-processing as well if needed.

Note: Don't try to use this function on float samples, since the data is expected to be an audio file in its binary format. Be sure that the original data remains constant throughout the lifetime of the Convolution object, as the loading process will happen on a background thread once this function has returned.

Parameters
sourceDatathe block of data to use as the stream's source
sourceDataSizethe number of bytes in the source data block
isStereoselects either stereo or mono
requiresTrimmingoptionally trim the start and the end of the impulse response
sizethe expected size for the impulse response after loading, can be set to 0 to requesting the original impulse response size
requiresNormalisationoptionally normalise the impulse response amplitude

◆ prepare()

void juce::dsp::Convolution::prepare ( const ProcessSpec )

Must be called before first calling process.

In general, calls to loadImpulseResponse() load the impulse response (IR) asynchronously. The IR will become active once it has been completely loaded and processed, which may take some time.

Calling prepare() will ensure that the IR supplied to the most recent call to loadImpulseResponse() is fully initialised. This IR will then be active during the next call to process(). It is recommended to call loadImpulseResponse() before prepare() if a specific IR must be active during the first process() call.

◆ process()

template<typename ProcessContext , std::enable_if_t< std::is_same< typename ProcessContext::SampleType, float >::value, int > = 0>
void juce::dsp::Convolution::process ( const ProcessContext context)
inlinenoexcept

Performs the filter operation on the given set of samples with optional stereo processing.

◆ processSamples()

void juce::dsp::Convolution::processSamples ( const AudioBlock< const float > &  ,
AudioBlock< float > &  ,
bool  isBypassed 
)
privatenoexcept

◆ reset()

void juce::dsp::Convolution::reset ( )
noexcept

Resets the processing pipeline ready to start a new stream of data.

Member Data Documentation

◆ isActive

bool juce::dsp::Convolution::isActive = false
private

◆ mixer

Mixer juce::dsp::Convolution::mixer
private

◆ pimpl

std::unique_ptr<Impl> juce::dsp::Convolution::pimpl
private

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