Reusable overlap-save convolver for streaming real FIR filtering. More...

#include <fft.H>

Collaboration diagram for Aleph::FFT< Real >::OverlapSave:

Public Member Functions
	OverlapSave (const Array< Real > &kernel, const size_t block_size=0)

size_t	block_size () const noexcept
	Returns the processing block size (the hop size).

size_t	fft_size () const noexcept
	Returns the FFT size used internally (block_size + kernel_size - 1 padded to power of 2).

const Array< Real > &	kernel () const noexcept
	Returns the current FIR kernel.

size_t	overlap_size () const noexcept
	Returns the internal overlap history size.

void	reset ()
	Resets the internal filter state and history.

Array< Real >	process_block (const Array< Real > &block)
	Processes an input block and returns the corresponding filtered output.

Array< Real >	flush ()
	Flushes all buffered samples and returns the final tail of the convolution.

Array< Real >	convolve (const Array< Real > &signal)
	Convolves the input signal with the kernel (one-shot convenience).

template<typename Container > requires Is_Real_Container<Container>
Array< Real >	process_block (const Container &block)
	Processes an input block from a real-valued container.

template<typename Container > requires Is_Real_Container<Container>
Array< Real >	convolve (const Container &signal)
	Convolves an input signal from a real-valued container.

Private Member Functions
void	clear_history ()
	Rationale: Resets the state for a new filtering process.

void	update_history (const Array< Real > &padded_chunk)
	Rationale: Maintains the sliding window of historical samples required to correctly compute the linear convolution prefix of the next block.

Array< Complex >	build_segment_spectrum (const Array< Real > &chunk) const
	Rationale: Prepares a frequency-domain segment by combining historical samples with the current signal chunk.

Array< Real >	padded_chunk_copy (const Array< Real > &chunk) const
	Internal helper for zero-padding chunks.

Array< Real >	process_chunk_impl (const Array< Real > &chunk)
	Rationale: Implements the core Overlap-Save logic for one block:

Static Private Member Functions
static size_t	default_block_size (const size_t kernel_size)
	Rationale: Heuristic for choosing a block size that provides a good balance between algorithmic latency and FFT efficiency.

Private Attributes
Array< Real >	kernel_

size_t	block_size_ = 0

size_t	fft_size_ = 0

Plan	plan_

Array< Complex >	kernel_spectrum_

Array< Real >	history_

Array< Real >	pending_

size_t	total_input_size_ = 0

size_t	emitted_output_size_ = 0

Detailed Description

template<std::floating_point Real = double>
class Aleph::FFT< Real >::OverlapSave

Reusable overlap-save convolver for streaming real FIR filtering.

The configured block size controls both algorithmic latency and the number of valid samples emitted per internal FFT block.

Definition at line 14523 of file fft.H.

Constructor & Destructor Documentation

◆ OverlapSave()

template<std::floating_point Real = double>

Aleph::FFT< Real >::OverlapSave::OverlapSave	(	const Array< Real > &	kernel,
		const size_t	block_size = `0`
	)

inlineexplicit

Definition at line 14650 of file fft.H.

Member Function Documentation

◆ block_size()

template<std::floating_point Real = double>

size_t Aleph::FFT< Real >::OverlapSave::block_size ( ) const

inlinenoexcept

Returns the processing block size (the hop size).

Definition at line 14680 of file fft.H.

References Aleph::FFT< Real >::OverlapSave::block_size_.

Referenced by Aleph::FFT< Real >::OverlapSave::OverlapSave().

◆ build_segment_spectrum()

template<std::floating_point Real = double>

Array< Complex > Aleph::FFT< Real >::OverlapSave::build_segment_spectrum ( const Array< Real > & chunk ) const

inlineprivate

Rationale: Prepares a frequency-domain segment by combining historical samples with the current signal chunk.

Definition at line 14586 of file fft.H.

References ah_invalid_argument_if, Aleph::FFT< Real >::OverlapSave::block_size_, Aleph::Array< T >::create(), Aleph::divide_and_conquer_partition_dp(), Aleph::FFT< Real >::OverlapSave::fft_size_, Aleph::FFT< Real >::OverlapSave::history_, and Aleph::Array< T >::size().

◆ clear_history()

template<std::floating_point Real = double>

void Aleph::FFT< Real >::OverlapSave::clear_history ( )

inlineprivate

Rationale: Resets the state for a new filtering process.

Definition at line 14549 of file fft.H.

References Aleph::divide_and_conquer_partition_dp(), Aleph::FFT< Real >::OverlapSave::history_, and Aleph::Array< T >::size().

Referenced by Aleph::FFT< Real >::OverlapSave::OverlapSave(), and Aleph::FFT< Real >::OverlapSave::reset().

◆ convolve() [1/2]

template<std::floating_point Real = double>

Array< Real > Aleph::FFT< Real >::OverlapSave::convolve ( const Array< Real > & signal )

inline

Convolves the input signal with the kernel (one-shot convenience).

Definition at line 14772 of file fft.H.

References Aleph::FFT< Real >::append_all(), Aleph::FFT< Real >::OverlapSave::flush(), output, Aleph::FFT< Real >::OverlapSave::process_block(), and Aleph::FFT< Real >::OverlapSave::reset().

Referenced by Aleph::FFT< Real >::OverlapSave::convolve(), and Aleph::FFT< Real >::overlap_save_convolution().

◆ convolve() [2/2]

template<std::floating_point Real = double>

template<typename Container >
requires Is_Real_Container<Container>

Array< Real > Aleph::FFT< Real >::OverlapSave::convolve ( const Container & signal )

inline

Convolves an input signal from a real-valued container.

Definition at line 14793 of file fft.H.

References Aleph::FFT< Real >::build_real_input(), and Aleph::FFT< Real >::OverlapSave::convolve().

◆ default_block_size()

template<std::floating_point Real = double>

static size_t Aleph::FFT< Real >::OverlapSave::default_block_size ( const size_t kernel_size )

inlinestaticprivate

Rationale: Heuristic for choosing a block size that provides a good balance between algorithmic latency and FFT efficiency.

Definition at line 14539 of file fft.H.

References ah_invalid_argument_if, Aleph::divide_and_conquer_partition_dp(), and Aleph::FFT< Real >::next_power_of_two().

Referenced by Aleph::FFT< Real >::OverlapSave::OverlapSave().

◆ fft_size()

template<std::floating_point Real = double>

size_t Aleph::FFT< Real >::OverlapSave::fft_size ( ) const

inlinenoexcept

Returns the FFT size used internally (block_size + kernel_size - 1 padded to power of 2).

Definition at line 14683 of file fft.H.

References Aleph::FFT< Real >::OverlapSave::fft_size_.

◆ flush()

template<std::floating_point Real = double>

Array< Real > Aleph::FFT< Real >::OverlapSave::flush ( )

inline

Flushes all buffered samples and returns the final tail of the convolution.

Zero-padding is applied to complete the final processing block if necessary. The filter is reset after flushing.

Returns: The remaining filtered samples.

Definition at line 14738 of file fft.H.

Referenced by Aleph::FFT< Real >::OverlapSave::convolve().

◆ kernel()

template<std::floating_point Real = double>

const Array< Real > & Aleph::FFT< Real >::OverlapSave::kernel ( ) const

inlinenoexcept

Returns the current FIR kernel.

Definition at line 14686 of file fft.H.

References Aleph::FFT< Real >::OverlapSave::kernel_.

◆ overlap_size()

template<std::floating_point Real = double>

size_t Aleph::FFT< Real >::OverlapSave::overlap_size ( ) const

inlinenoexcept

Returns the internal overlap history size.

Definition at line 14689 of file fft.H.

References Aleph::FFT< Real >::OverlapSave::history_, and Aleph::Array< T >::size().

◆ padded_chunk_copy()

template<std::floating_point Real = double>

Array< Real > Aleph::FFT< Real >::OverlapSave::padded_chunk_copy ( const Array< Real > & chunk ) const

inlineprivate

Internal helper for zero-padding chunks.

Definition at line 14608 of file fft.H.

References Aleph::FFT< Real >::OverlapSave::block_size_, Aleph::Array< T >::create(), Aleph::divide_and_conquer_partition_dp(), and Aleph::Array< T >::size().

Referenced by Aleph::FFT< Real >::OverlapSave::process_chunk_impl().

◆ process_block() [1/2]

template<std::floating_point Real = double>

Array< Real > Aleph::FFT< Real >::OverlapSave::process_block ( const Array< Real > & block )

inline

Processes an input block and returns the corresponding filtered output.

Input samples are buffered until a full block is available. Multiple blocks might be emitted if the input is large.

Parameters

block Input signal block.

Returns: Filtered output samples available so far.

Definition at line 14709 of file fft.H.

References Aleph::FFT< Real >::append_all(), Aleph::FFT< Real >::OverlapSave::block_size_, Aleph::divide_and_conquer_partition_dp(), Aleph::Array< T >::is_empty(), Aleph::FFT< Real >::OverlapSave::pending_, Aleph::FFT< Real >::OverlapSave::process_chunk_impl(), Aleph::Array< T >::size(), Aleph::FFT< Real >::slice_copy(), and Aleph::FFT< Real >::OverlapSave::total_input_size_.

Referenced by Aleph::FFT< Real >::OverlapSave::convolve(), and Aleph::FFT< Real >::OverlapSave::process_block().

◆ process_block() [2/2]

template<std::floating_point Real = double>

template<typename Container >
requires Is_Real_Container<Container>

Array< Real > Aleph::FFT< Real >::OverlapSave::process_block ( const Container & block )

inline

Processes an input block from a real-valued container.

Definition at line 14784 of file fft.H.

References Aleph::FFT< Real >::build_real_input(), and Aleph::FFT< Real >::OverlapSave::process_block().

◆ process_chunk_impl()

template<std::floating_point Real = double>

Array< Real > Aleph::FFT< Real >::OverlapSave::process_chunk_impl ( const Array< Real > & chunk )

inlineprivate

Rationale: Implements the core Overlap-Save logic for one block:

Combine History + Chunk.
FFT to frequency domain.
Pointwise multiply with kernel spectrum.
Inverse FFT to time domain.
Discard corrupted (circular) samples and emit valid results.
Update history for next block.

Definition at line 14625 of file fft.H.

Referenced by Aleph::FFT< Real >::OverlapSave::flush(), and Aleph::FFT< Real >::OverlapSave::process_block().

◆ reset()

template<std::floating_point Real = double>

void Aleph::FFT< Real >::OverlapSave::reset ( )

inline

Resets the internal filter state and history.

Definition at line 14692 of file fft.H.

References Aleph::FFT< Real >::OverlapSave::clear_history(), Aleph::FFT< Real >::OverlapSave::emitted_output_size_, Aleph::FFT< Real >::OverlapSave::pending_, and Aleph::FFT< Real >::OverlapSave::total_input_size_.

Referenced by Aleph::FFT< Real >::OverlapSave::convolve(), and Aleph::FFT< Real >::OverlapSave::flush().

◆ update_history()

template<std::floating_point Real = double>

void Aleph::FFT< Real >::OverlapSave::update_history ( const Array< Real > & padded_chunk )

inlineprivate

Rationale: Maintains the sliding window of historical samples required to correctly compute the linear convolution prefix of the next block.

Definition at line 14560 of file fft.H.

References Aleph::Array< T >::create(), Aleph::divide_and_conquer_partition_dp(), Aleph::FFT< Real >::OverlapSave::history_, Aleph::Array< T >::is_empty(), and Aleph::Array< T >::size().

Referenced by Aleph::FFT< Real >::OverlapSave::process_chunk_impl().

Member Data Documentation

◆ block_size_

template<std::floating_point Real = double>

size_t Aleph::FFT< Real >::OverlapSave::block_size_ = 0

private

Definition at line 14526 of file fft.H.

Referenced by Aleph::FFT< Real >::OverlapSave::OverlapSave(), Aleph::FFT< Real >::OverlapSave::block_size(), Aleph::FFT< Real >::OverlapSave::build_segment_spectrum(), Aleph::FFT< Real >::OverlapSave::flush(), Aleph::FFT< Real >::OverlapSave::padded_chunk_copy(), Aleph::FFT< Real >::OverlapSave::process_block(), and Aleph::FFT< Real >::OverlapSave::process_chunk_impl().

◆ emitted_output_size_

template<std::floating_point Real = double>

size_t Aleph::FFT< Real >::OverlapSave::emitted_output_size_ = 0

private

Definition at line 14533 of file fft.H.

Referenced by Aleph::FFT< Real >::OverlapSave::flush(), Aleph::FFT< Real >::OverlapSave::process_chunk_impl(), and Aleph::FFT< Real >::OverlapSave::reset().

◆ fft_size_

template<std::floating_point Real = double>

size_t Aleph::FFT< Real >::OverlapSave::fft_size_ = 0

private

Definition at line 14527 of file fft.H.

Referenced by Aleph::FFT< Real >::OverlapSave::OverlapSave(), Aleph::FFT< Real >::OverlapSave::build_segment_spectrum(), Aleph::FFT< Real >::OverlapSave::fft_size(), and Aleph::FFT< Real >::OverlapSave::process_chunk_impl().

◆ history_

template<std::floating_point Real = double>

Array<Real> Aleph::FFT< Real >::OverlapSave::history_

private

Definition at line 14530 of file fft.H.

Referenced by Aleph::FFT< Real >::OverlapSave::OverlapSave(), Aleph::FFT< Real >::OverlapSave::build_segment_spectrum(), Aleph::FFT< Real >::OverlapSave::clear_history(), Aleph::FFT< Real >::OverlapSave::overlap_size(), Aleph::FFT< Real >::OverlapSave::process_chunk_impl(), and Aleph::FFT< Real >::OverlapSave::update_history().

◆ kernel_

template<std::floating_point Real = double>

Array<Real> Aleph::FFT< Real >::OverlapSave::kernel_

private

Definition at line 14525 of file fft.H.

Referenced by Aleph::FFT< Real >::OverlapSave::OverlapSave(), Aleph::FFT< Real >::OverlapSave::flush(), Aleph::FFT< Real >::OverlapSave::kernel(), and Aleph::FFT< Real >::OverlapSave::process_chunk_impl().

◆ kernel_spectrum_

template<std::floating_point Real = double>

Array<Complex> Aleph::FFT< Real >::OverlapSave::kernel_spectrum_

private

Definition at line 14529 of file fft.H.

Referenced by Aleph::FFT< Real >::OverlapSave::OverlapSave(), and Aleph::FFT< Real >::OverlapSave::process_chunk_impl().

◆ pending_

template<std::floating_point Real = double>

Array<Real> Aleph::FFT< Real >::OverlapSave::pending_

private

Definition at line 14531 of file fft.H.

Referenced by Aleph::FFT< Real >::OverlapSave::flush(), Aleph::FFT< Real >::OverlapSave::process_block(), and Aleph::FFT< Real >::OverlapSave::reset().

◆ plan_

template<std::floating_point Real = double>

Plan Aleph::FFT< Real >::OverlapSave::plan_

private

Definition at line 14528 of file fft.H.

Referenced by Aleph::FFT< Real >::OverlapSave::OverlapSave(), and Aleph::FFT< Real >::OverlapSave::process_chunk_impl().

◆ total_input_size_

template<std::floating_point Real = double>

size_t Aleph::FFT< Real >::OverlapSave::total_input_size_ = 0

private

Definition at line 14532 of file fft.H.

Referenced by Aleph::FFT< Real >::OverlapSave::flush(), Aleph::FFT< Real >::OverlapSave::process_block(), and Aleph::FFT< Real >::OverlapSave::reset().

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

fft.H

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ OverlapSave()

Member Function Documentation

◆ block_size()

◆ build_segment_spectrum()

◆ clear_history()

◆ convolve() [1/2]

◆ convolve() [2/2]

◆ default_block_size()

◆ fft_size()

◆ flush()

◆ kernel()

◆ overlap_size()

◆ padded_chunk_copy()

◆ process_block() [1/2]

◆ process_block() [2/2]

◆ process_chunk_impl()

◆ reset()

◆ update_history()

Member Data Documentation

◆ block_size_

◆ emitted_output_size_

◆ fft_size_

◆ history_

◆ kernel_

◆ kernel_spectrum_

◆ pending_

◆ plan_

◆ total_input_size_