Struct FFTConvolver

Source

pub struct FFTConvolver<F: FftNum> { /* private fields */ }

Expand description

FFTConvolver Implementation of a partitioned FFT convolution algorithm with uniform block size.

Some notes on how to use it:

After initialization with an impulse response, subsequent data portions of arbitrary length can be convolved. The convolver internally can handle this by using appropriate buffering.
The convolver works without “latency” (except for the required processing time, of course), i.e. the output always is the convolved input for each processing call.
The convolver is suitable for real-time processing which means that no “unpredictable” operations like allocations, locking, API calls, etc. are performed during processing (all necessary allocations and preparations take place during initialization).

Implementations§

Source §

impl<F: FftNum> FFTConvolver<F>

Source

pub fn init( &mut self, block_size: usize, impulse_response: &[F], ) -> Result<(), FFTConvolverError>

Initializes the convolver with an impulse response

This method sets up all internal buffers and prepares the convolver for processing. The block size determines the internal partition size and affects efficiency. It will be rounded up to the next power of 2.

All memory allocations happen during initialization, making subsequent processing operations real-time safe.

§Arguments

block_size - Block size internally used by the convolver (partition size). Will be rounded up to the next power of 2. Must be > 0.
impulse_response - The impulse response to convolve with. Can be empty.

§Returns

Returns BlockSizeZero if block_size is 0.

§Example

use fft_convolver::FFTConvolver;

let mut convolver = FFTConvolver::<f32>::default();
let ir = vec![0.5, 0.3, 0.2, 0.1];
convolver.init(128, &ir).unwrap();

Source

pub fn set_response( &mut self, impulse_response: &[F], ) -> Result<(), FFTConvolverError>

Updates the impulse response without reallocating buffers

This method allows changing the impulse response at runtime while maintaining real-time safety by avoiding allocations. The new impulse response must not exceed the length of the original impulse response used during initialization.

§Arguments

impulse_response - The new impulse response (must be ≤ original length)

§Returns

Returns ImpulseResponseExceedsCapacity if the new impulse response is longer than the original one.

§Example

use fft_convolver::FFTConvolver;

let mut convolver = FFTConvolver::<f32>::default();
let ir1 = vec![0.5, 0.3, 0.2, 0.1];
convolver.init(4, &ir1).unwrap();

// Update to a different impulse response of same or shorter length
let ir2 = vec![0.8, 0.6, 0.4];
convolver.set_response(&ir2).unwrap();

Source

pub fn process( &mut self, input: &[F], output: &mut [F], ) -> Result<(), FFTConvolverError>

Convolves the input samples with the impulse response and outputs the result

This is a real-time safe operation that performs no allocations. The input and output buffers can be of any length. Internal buffering handles arbitrary sizes and ensures the output is always properly aligned with the input (zero latency except for processing time).

If the convolver has no active impulse response, the output is filled with zeros.

§Arguments

input - The input samples to convolve
output - Buffer to write the convolution result. Must have the same length as input.

§Returns

Returns Fft error if an FFT operation fails.

§Example

use fft_convolver::FFTConvolver;

let mut convolver = FFTConvolver::<f32>::default();
let ir = vec![0.5, 0.3, 0.2];
convolver.init(128, &ir).unwrap();

let input = vec![1.0; 256];
let mut output = vec![0.0; 256];
convolver.process(&input, &mut output).unwrap();

Source

pub fn reset(&mut self)

Clears the internal processing state while preserving the impulse response

This real-time safe operation resets all internal buffers that store the convolution state, effectively removing any “history” or “tail” from previous processing. The impulse response configuration remains intact, so processing can continue immediately.

This is useful when handling stream discontinuities such as:

Seeking in audio playback
Pause/resume operations with large time gaps
Switching between different audio sources

After calling reset(), the next process() call will produce output as if the convolver had just been initialized.

§Example

use fft_convolver::FFTConvolver;

let mut convolver = FFTConvolver::<f32>::default();
let ir = vec![0.5, 0.3, 0.2];
convolver.init(128, &ir).unwrap();

let input = vec![1.0; 256];
let mut output = vec![0.0; 256];
convolver.process(&input, &mut output).unwrap();

// Clear the state when seeking to a new position
convolver.reset();

// Continue processing with fresh state
convolver.process(&input, &mut output).unwrap();