TPT State Variable Filter with simultaneous multi-output. More...

#include <StateVariableFilter.h>

Collaboration diagram for dspark::StateVariableFilter< T >:

[legend]

Classes
struct	ChannelState

struct	MultiOutput
	Result struct for simultaneous multi-output processing. More...

Public Types
enum class	Mode { LowPass , HighPass , BandPass , Notch , AllPass , Bell , LowShelf , HighShelf }
	Filter output mode for processBlock/processSample. More...

Public Member Functions
	~StateVariableFilter ()=default

void	prepare (const AudioSpec &spec) noexcept
	Prepares the filter.

void	processBlock (AudioBufferView< T > buffer) noexcept
	Processes an audio buffer in-place using the selected Mode.

T	processSample (T input, int channel) noexcept
	Processes a single sample (selected Mode output).

MultiOutput	processMultiOutput (T input, int channel) noexcept
	Processes a single sample returning LP, HP, BP simultaneously.

void	reset () noexcept
	Resets internal state.

void	setCutoff (T hz) noexcept
	Sets the cutoff/center frequency.

void	setResonance (T resonance) noexcept
	Sets the resonance amount.

void	setQ (T q) noexcept
	Sets the Q factor directly.

void	setMode (Mode mode) noexcept
	Sets the output mode.

void	setGain (T dB) noexcept
	Sets gain for Bell/Shelf modes (in dB).

T	getCutoff () const noexcept

T	getResonance () const noexcept

T	getQ () const noexcept

T	getGain () const noexcept

Mode	getMode () const noexcept

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

AudioSpec	spec_ {}

T	cutoff_ = T(1000)

T	resonance_ = T(0)

T	gainDb_ = T(0)

T	g_ = T(0)

T	R_ = T(1)

T	Rbell_ = T(1)

T	A_ = T(1)

Mode	mode_ = Mode::LowPass

T	effG_ = T(0)

T	effR_ = T(1)

T	a1_ = T(1)

T	a2_ = T(0)

T	a3_ = T(0)

Static Protected Attributes
static constexpr int	kMaxChannels = 16

Detailed Description

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

TPT State Variable Filter with simultaneous multi-output.

Note: Threading contract: this is a modulation-oriented filter (its whole point is artifact-free per-sample cutoff changes from the audio thread). Parameter setters are therefore intended to be called from the audio thread (or externally synchronised), NOT concurrently with process() from a different thread. Internal coefficients are intentionally non-atomic to keep the per-sample modulation path branch-free. For lock-free cross-thread cutoff control use LadderFilter (atomic) or wrap this filter with your own parameter queue.; Channels beyond kMaxChannels (16) pass through unprocessed in processBlock(); out-of-range channel indices on the per-sample calls are rejected safely (input passed through / zero side outputs).

Template Parameters

T	Sample type (float or double).

Definition at line 91 of file StateVariableFilter.h.

Member Enumeration Documentation

◆ Mode

template<FloatType T>

enum class dspark::StateVariableFilter::Mode

strong

Filter output mode for processBlock/processSample.

Enumerator
LowPass	2nd-order lowpass (12 dB/oct).
HighPass	2nd-order highpass (12 dB/oct).
BandPass	Bandpass (constant skirt gain).
Notch	Band-reject (notch).
AllPass	Allpass (phase shift, unity gain).
Bell	Parametric bell (boost/cut at frequency).
LowShelf	Low shelf (boost/cut below frequency).
HighShelf	High shelf (boost/cut above frequency).

Definition at line 95 of file StateVariableFilter.h.

Constructor & Destructor Documentation

◆ ~StateVariableFilter()

template<FloatType T>

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

default

Member Function Documentation

◆ getCutoff()

template<FloatType T>

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

inlinenoexcept

Definition at line 289 of file StateVariableFilter.h.

◆ getGain()

template<FloatType T>

T dspark::StateVariableFilter< T >::getGain ( ) const

inlinenoexcept

Definition at line 292 of file StateVariableFilter.h.

◆ getMode()

template<FloatType T>

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

inlinenoexcept

Definition at line 293 of file StateVariableFilter.h.

◆ getQ()

template<FloatType T>

T dspark::StateVariableFilter< T >::getQ ( ) const

inlinenoexcept

Definition at line 291 of file StateVariableFilter.h.

◆ getResonance()

template<FloatType T>

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

inlinenoexcept

Definition at line 290 of file StateVariableFilter.h.

◆ prepare()

template<FloatType T>

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

inlinenoexcept

Prepares the filter.

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

Parameters

spec	Audio environment.

Definition at line 132 of file StateVariableFilter.h.

◆ processBlock()

template<FloatType T>

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

inlinenoexcept

Processes an audio buffer in-place using the selected Mode.

Parameters

buffer Audio data.

Definition at line 144 of file StateVariableFilter.h.

◆ processMultiOutput()

template<FloatType T>

MultiOutput dspark::StateVariableFilter< T >::processMultiOutput	(	T	input,
		int	channel
	)

inlinenoexcept

Processes a single sample returning LP, HP, BP simultaneously.

This is the Level 2 API for DSP engineers who need multiple outputs from the same filter structure (e.g., crossover design, multiband split).

Parameters

input	Input sample.
channel	Channel index in [0, kMaxChannels). Out of range returns {input, 0, 0} (an LP/HP split still reconstructs the input) without touching any state.

Returns: {lowpass, highpass, bandpass} outputs.

Definition at line 194 of file StateVariableFilter.h.

◆ processSample()

template<FloatType T>

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

inlinenoexcept

Processes a single sample (selected Mode output).

Modulation-friendly: you can call setCutoff() before every sample without artifacts, unlike biquad filters.

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 output (returns input unchanged if channel is out of range).

Definition at line 176 of file StateVariableFilter.h.

◆ reset()

template<FloatType T>

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

inlinenoexcept

Resets internal state.

Definition at line 201 of file StateVariableFilter.h.

◆ setCutoff()

template<FloatType T>

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

inlinenoexcept

Sets the cutoff/center frequency.

Can be called per-sample without artifacts (unlike biquads). Non-finite values (NaN/Inf) are ignored - they would poison the coefficients 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.

Parameters

hz	Frequency in Hz.

Definition at line 223 of file StateVariableFilter.h.

◆ setGain()

template<FloatType T>

void dspark::StateVariableFilter< T >::setGain ( T dB )

inlinenoexcept

Sets gain for Bell/Shelf modes (in dB).

Parameters

dB	Gain in decibels. Non-finite values are ignored.

Definition at line 278 of file StateVariableFilter.h.

◆ setMode()

template<FloatType T>

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

inlinenoexcept

Sets the output mode.

Definition at line 268 of file StateVariableFilter.h.

◆ setQ()

template<FloatType T>

void dspark::StateVariableFilter< T >::setQ ( T q )

inlinenoexcept

Sets the Q factor directly.

For DSP engineers who think in Q rather than resonance 0-1.

Parameters

q	Quality factor, floored at 0.01 (0.5 = critically damped, 0.707 = Butterworth, 10+ = narrow). Non-finite values are ignored.

Definition at line 257 of file StateVariableFilter.h.

◆ setResonance()

template<FloatType T>

void dspark::StateVariableFilter< T >::setResonance ( T resonance )

inlinenoexcept

Sets the resonance amount.

Parameters

resonance 0.0 maps to Q = 0.5 (critically damped, no peak) and 1.0 to Q = 50 (a strong resonant peak, near but not at self-oscillation). Non-finite values are ignored.

Definition at line 237 of file StateVariableFilter.h.

Member Data Documentation

◆ a1_

template<FloatType T>

T dspark::StateVariableFilter< T >::a1_ = T(1)

protected

Definition at line 318 of file StateVariableFilter.h.

◆ a2_

template<FloatType T>

T dspark::StateVariableFilter< T >::a2_ = T(0)

protected

Definition at line 318 of file StateVariableFilter.h.

◆ a3_

template<FloatType T>

T dspark::StateVariableFilter< T >::a3_ = T(0)

protected

Definition at line 318 of file StateVariableFilter.h.

◆ A_

template<FloatType T>

T dspark::StateVariableFilter< T >::A_ = T(1)

protected

Definition at line 312 of file StateVariableFilter.h.

◆ cutoff_

template<FloatType T>

T dspark::StateVariableFilter< T >::cutoff_ = T(1000)

protected

Definition at line 306 of file StateVariableFilter.h.

◆ effG_

template<FloatType T>

T dspark::StateVariableFilter< T >::effG_ = T(0)

protected

Definition at line 316 of file StateVariableFilter.h.

◆ effR_

template<FloatType T>

T dspark::StateVariableFilter< T >::effR_ = T(1)

protected

Definition at line 317 of file StateVariableFilter.h.

◆ g_

template<FloatType T>

T dspark::StateVariableFilter< T >::g_ = T(0)

protected

Definition at line 309 of file StateVariableFilter.h.

◆ gainDb_

template<FloatType T>

T dspark::StateVariableFilter< T >::gainDb_ = T(0)

protected

Definition at line 308 of file StateVariableFilter.h.

◆ kMaxChannels

template<FloatType T>

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

staticconstexprprotected

Definition at line 296 of file StateVariableFilter.h.

◆ mode_

template<FloatType T>

Mode dspark::StateVariableFilter< T >::mode_ = Mode::LowPass

protected

Definition at line 313 of file StateVariableFilter.h.

◆ R_

template<FloatType T>

T dspark::StateVariableFilter< T >::R_ = T(1)

protected

Definition at line 310 of file StateVariableFilter.h.

◆ Rbell_

template<FloatType T>

T dspark::StateVariableFilter< T >::Rbell_ = T(1)

protected

Definition at line 311 of file StateVariableFilter.h.

◆ resonance_

template<FloatType T>

T dspark::StateVariableFilter< T >::resonance_ = T(0)

protected

Definition at line 307 of file StateVariableFilter.h.

◆ spec_

template<FloatType T>

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

protected

Definition at line 305 of file StateVariableFilter.h.

◆ state_

template<FloatType T>

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

protected

Definition at line 304 of file StateVariableFilter.h.

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

Core/StateVariableFilter.h

Classes

Public Types

Public Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Mode

Constructor & Destructor Documentation

◆ ~StateVariableFilter()

Member Function Documentation

◆ getCutoff()

◆ getGain()

◆ getMode()

◆ getQ()

◆ getResonance()

◆ prepare()

◆ processBlock()

◆ processMultiOutput()

◆ processSample()

◆ reset()

◆ setCutoff()

◆ setGain()

◆ setMode()

◆ setQ()

◆ setResonance()

Member Data Documentation

◆ a1_

◆ a2_

◆ a3_

◆ A_

◆ cutoff_

◆ effG_

◆ effR_

◆ g_

◆ gainDb_

◆ kMaxChannels

◆ mode_

◆ R_

◆ Rbell_

◆ resonance_

◆ spec_

◆ state_