4-pole resonant ladder filter (Moog topology, TPT discretization). More...

#include <LadderFilter.h>

Collaboration diagram for dspark::LadderFilter< T >:

Classes
struct	ChannelState

Public Types
enum class	Mode { LP6 , LP12 , LP18 , LP24 , BP12 , HP24 }
	Defines the frequency response mode of the filter output. More...

Public Member Functions
	~LadderFilter ()=default

void	prepare (const AudioSpec &spec) noexcept
	Prepares the filter with the current audio environment.

void	processBlock (AudioBufferView< T > buffer) noexcept
	Processes an audio buffer in-place (thread-safe vs. setters).

T	processSample (T input, int channel) noexcept
	Processes a single sample on one channel.

void	reset () noexcept
	Clears the internal integrator state.

void	setCutoff (T hz) noexcept
	Sets the cutoff frequency (thread-safe, lock-free).

void	setResonance (T amount) noexcept
	Sets resonance amount (thread-safe, lock-free).

void	setDrive (T amount) noexcept
	Sets the nonlinear drive amount (thread-safe, lock-free).

void	setMode (Mode mode) noexcept
	Sets the filter output mode (thread-safe, lock-free).

T	getCutoff () const noexcept

T	getResonance () const noexcept

T	getDrive () const noexcept

Mode	getMode () const noexcept

Protected Attributes
std::array< ChannelState, kMaxChannels >	state_ {}

AudioSpec	spec_ {}

std::atomic< T >	cutoff_ {T(1000)}

std::atomic< T >	resonance_ {T(0)}

std::atomic< T >	drive_ {T(1)}

std::atomic< T >	g_ {T(0)}

std::atomic< Mode >	mode_ {Mode::LP24}

Static Protected Attributes
static constexpr int	kMaxChannels = 16

Detailed Description

template<FloatType T>
class dspark::LadderFilter< T >

4-pole resonant ladder filter (Moog topology, TPT discretization).

Four cascaded one-pole TPT lowpass stages with global feedback. The zero-delay feedback loop is resolved analytically each sample, and the multimode outputs are tap mixes of the cascade. processBlock() snapshots the parameters once per block and dispatches to a per-mode template instantiation, so the sample loop carries no branches.

Contract notes:

Like the analog original, the passband gain drops by 1/(1 + 4*resonance) as resonance rises (about -14 dB at resonance 1). Compensate externally if loudness-matched sweeps are needed.
Drive saturates the resonance feedback path only: with resonance at 0 it has no effect on the signal. With drive > 1 the bounded tanh stage keeps self-oscillation (resonance = 1) at a finite level; at drive <= 1 the loop is exactly marginal at resonance = 1, so sustained input at the cutoff accumulates without decay - back off resonance slightly or engage drive for stable self-oscillation.
Channels beyond kMaxChannels (16) pass through unprocessed.
Mode can be switched while running; the integrator state is continuous.

Template Parameters

T	Sample type (float or double). Must satisfy FloatType concept.

Definition at line 62 of file LadderFilter.h.

Member Enumeration Documentation

◆ Mode

template<FloatType T>

enum class dspark::LadderFilter::Mode

strong

Defines the frequency response mode of the filter output.

Enumerator
LP6	1-pole lowpass (6 dB/oct).
LP12	2-pole lowpass (12 dB/oct).
LP18	3-pole lowpass (18 dB/oct).
LP24	4-pole lowpass (24 dB/oct) - classic Moog style.
BP12	Bandpass (6 dB/oct per side).
HP24	4-pole highpass (24 dB/oct).

Definition at line 66 of file LadderFilter.h.

Constructor & Destructor Documentation

◆ ~LadderFilter()

template<FloatType T>

dspark::LadderFilter< T >::~LadderFilter ( )

default

Member Function Documentation

◆ getCutoff()

template<FloatType T>

T dspark::LadderFilter< T >::getCutoff ( ) const

inlinenoexcept

Definition at line 231 of file LadderFilter.h.

◆ getDrive()

template<FloatType T>

T dspark::LadderFilter< T >::getDrive ( ) const

inlinenoexcept

Definition at line 233 of file LadderFilter.h.

◆ getMode()

template<FloatType T>

Mode dspark::LadderFilter< T >::getMode ( ) const

inlinenoexcept

Definition at line 234 of file LadderFilter.h.

◆ getResonance()

template<FloatType T>

T dspark::LadderFilter< T >::getResonance ( ) const

inlinenoexcept

Definition at line 232 of file LadderFilter.h.

◆ prepare()

template<FloatType T>

void dspark::LadderFilter< T >::prepare ( const AudioSpec & spec )

inlinenoexcept

Prepares the filter with the current audio environment.

Invalid specs (sample rate not > 0, NaN included) are ignored and the previous state is kept. Clears the integrator state.

Parameters

spec	Audio specification including sample rate.

Definition at line 88 of file LadderFilter.h.

◆ processBlock()

template<FloatType T>

void dspark::LadderFilter< T >::processBlock ( AudioBufferView< T > buffer )

inlinenoexcept

Processes an audio buffer in-place (thread-safe vs. setters).

Takes an atomic snapshot of the current parameters and dispatches to a branchless inner loop instantiated per mode.

Parameters

buffer View of the multi-channel audio data to process.

Definition at line 104 of file LadderFilter.h.

◆ processSample()

template<FloatType T>

T dspark::LadderFilter< T >::processSample	(	T	input,
		int	channel
	)

inlinenoexcept

Processes a single sample on one channel.

Convenience per-sample entry point mirroring Biquad. For bulk processing prefer processBlock(), which snapshots the parameters and derives the loop coefficients once per block instead of per sample.

Note: Unlike processBlock(), no DenormalGuard is installed here (the per-sample FP-environment writes would cost more than the filter itself); per-sample callers should place one DenormalGuard around their processing loop.

Parameters

input	Input sample.
channel	Channel index in [0, kMaxChannels).

Returns: Filtered sample (returns input unchanged if channel is out of range).

Definition at line 144 of file LadderFilter.h.

◆ reset()

template<FloatType T>

void dspark::LadderFilter< T >::reset ( )

inlinenoexcept

Clears the internal integrator state.

Should be called when playback stops or continuity is broken to prevent clicks.

Definition at line 172 of file LadderFilter.h.

◆ setCutoff()

template<FloatType T>

void dspark::LadderFilter< T >::setCutoff ( T hz )

inlinenoexcept

Sets the cutoff frequency (thread-safe, lock-free).

Non-finite values (NaN/Inf) are ignored - they would poison the integrator gain permanently otherwise. Before prepare() the sample rate is unknown, so the raw request is stored and clamped to [20, sampleRate * 0.499] once prepare() runs (getCutoff() then reports the clamped value).

Parameters

hz	Cutoff frequency in Hz.

Definition at line 191 of file LadderFilter.h.

◆ setDrive()

template<FloatType T>

void dspark::LadderFilter< T >::setDrive ( T amount )

inlinenoexcept

Sets the nonlinear drive amount (thread-safe, lock-free).

Parameters

amount Drive multiplier, floored at 0.1. Values <= 1.0 keep the feedback path linear; > 1.0 saturates it (analog-style resonance compression). Non-finite values are ignored.

Definition at line 216 of file LadderFilter.h.

◆ setMode()

template<FloatType T>

void dspark::LadderFilter< T >::setMode ( Mode mode )

inlinenoexcept

Sets the filter output mode (thread-safe, lock-free).

Parameters

mode	Target frequency response type.

Definition at line 226 of file LadderFilter.h.

◆ setResonance()

template<FloatType T>

void dspark::LadderFilter< T >::setResonance ( T amount )

inlinenoexcept

Sets resonance amount (thread-safe, lock-free).

Parameters

amount Range [0.0, 1.0]. Values near 1.0 induce self-oscillation (see the class notes on drive for loop stability). Non-finite values are ignored.

Definition at line 204 of file LadderFilter.h.

Member Data Documentation

◆ cutoff_

template<FloatType T>

std::atomic<T> dspark::LadderFilter< T >::cutoff_ {T(1000)}

protected

Definition at line 253 of file LadderFilter.h.

◆ drive_

template<FloatType T>

std::atomic<T> dspark::LadderFilter< T >::drive_ {T(1)}

protected

Definition at line 255 of file LadderFilter.h.

◆ g_

template<FloatType T>

std::atomic<T> dspark::LadderFilter< T >::g_ {T(0)}

protected

Definition at line 256 of file LadderFilter.h.

◆ kMaxChannels

template<FloatType T>

constexpr int dspark::LadderFilter< T >::kMaxChannels = 16

staticconstexprprotected

Definition at line 237 of file LadderFilter.h.

◆ mode_

template<FloatType T>

std::atomic<Mode> dspark::LadderFilter< T >::mode_ {Mode::LP24}

protected

Definition at line 257 of file LadderFilter.h.

◆ resonance_

template<FloatType T>

std::atomic<T> dspark::LadderFilter< T >::resonance_ {T(0)}

protected

Definition at line 254 of file LadderFilter.h.

◆ spec_

template<FloatType T>

AudioSpec dspark::LadderFilter< T >::spec_ {}

protected

Definition at line 250 of file LadderFilter.h.

◆ state_

template<FloatType T>

std::array<ChannelState, kMaxChannels> dspark::LadderFilter< T >::state_ {}

protected

Definition at line 249 of file LadderFilter.h.

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

Core/LadderFilter.h

Classes

Public Types

Public Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Mode

Constructor & Destructor Documentation

◆ ~LadderFilter()

Member Function Documentation

◆ getCutoff()

◆ getDrive()

◆ getMode()

◆ getResonance()

◆ prepare()

◆ processBlock()

◆ processSample()

◆ reset()

◆ setCutoff()

◆ setDrive()

◆ setMode()

◆ setResonance()

Member Data Documentation

◆ cutoff_

◆ drive_

◆ g_

◆ kMaxChannels

◆ mode_

◆ resonance_

◆ spec_

◆ state_