|
DSPark 1.8.0
Header-only C++20 DSP for real-time and offline audio
|
Professional multi-mode filter with cascaded biquad stages. More...
#include <Filters.h>

Classes | |
| struct | ButterworthCascade |
| struct | CascadeInfo |
| Per-stage Butterworth cascade layout for an LP/HP slope (for analysis). More... | |
Public Types | |
| enum class | Shape { LowPass , HighPass , BandPass , Peak , LowShelf , HighShelf , Notch , AllPass , Tilt } |
| Supported filter shapes. More... | |
Public Member Functions | |
| ~FilterEngine ()=default | |
| void | prepare (const AudioSpec &spec) |
| Initializes the filter engine with the current audio specification. | |
| void | reset () noexcept |
| Resets the internal state of all cascaded biquads and smoothers. Prevents clicks when relocating playback or enabling the effect. | |
| void | setLowPass (float freq, float Q=0.707f, int slopeDb=12) |
| Configures a low-pass filter. | |
| void | setHighPass (float freq, float Q=0.707f, int slopeDb=12) |
| Configures a high-pass filter. | |
| void | setBandPass (float freq, float Q=0.707f) |
| Configures a band-pass filter (fixed 12 dB/oct). | |
| void | setPeaking (float freq, float gainDb, float Q=1.0f) |
| Configures a peaking / bell EQ filter. | |
| void | setLowShelf (float freq, float gainDb, float slope=1.0f) |
| Configures a low-shelf EQ filter. | |
| void | setHighShelf (float freq, float gainDb, float slope=1.0f) |
| Configures a high-shelf EQ filter. | |
| void | setNotch (float freq, float Q=10.0f) |
| Configures a notch (band-reject) filter. | |
| void | setAllPass (float freq, float Q=0.707f) |
| Configures an all-pass filter (shifts phase, flat frequency response). | |
| void | setTilt (float centerFreq, float gainDb) |
| Configures a tilt EQ filter (boost highs/cut lows or vice versa). | |
| void | setMatchedPeak (bool enabled) noexcept |
| Selects the analog-matched (de-cramped) design for Peak bells. | |
| bool | isMatchedPeak () const noexcept |
| Returns whether Peak bells use the matched (de-cramped) design. | |
| void | setShelfSlope (float slope) noexcept |
| Sets the shelf slope S on its own (LowShelf/HighShelf shapes). | |
| float | getShelfSlope () const noexcept |
| Returns the shelf slope S used by the shelf shapes. | |
| Shape | getShape () const noexcept |
| Returns the active filter shape. | |
| int | getSlopeDb () const noexcept |
| Returns the active slope in dB/oct (LP/HP only - others = 12). | |
| void | setShape (Shape newShape, int slopeDb=12) noexcept |
| Switches the filter topology while keeping the current frequency, resonance, and gain unchanged. | |
| void | setFrequency (float freq) noexcept |
| Sets the target cutoff/center frequency. Thread-safe. | |
| void | setResonance (float Q) noexcept |
| Sets the target resonance/Q. Thread-safe. | |
| void | setGain (float dB) noexcept |
| Sets the target gain in dB. Thread-safe. | |
| void | setNonlinearity (T amount) noexcept |
| Sets the nonlinearity amount. Thread-safe. | |
| void | enableAnalogDrift (AnalogRandom::AnalogComponent component, float intensity=0.5f) |
| Enables analog-style low-frequency modulation of the cutoff. | |
| void | disableAnalogDrift () noexcept |
| Disables analog-style drift modulation. Thread-safe. | |
| void | setDriftSeed (std::uint64_t seed) noexcept |
| Makes the analog drift reproducible. | |
| std::uint64_t | getDriftSeed () const noexcept |
| The drift seed set by setDriftSeed(); 0 when the drift uses the instance's own unique seed. | |
| void | processBlock (AudioBufferView< T > buffer) noexcept |
| Processes an entire block of audio data. Internally branches into static, smoothed, or nonlinear processing paths to optimize CPU usage and allow auto-vectorization when possible. | |
| T | processSample (T input, int channel) noexcept |
| Processes a single sample without parameter smoothing or coefficient updates. | |
| void | applyParametersNow () noexcept |
| Applies pending parameter targets immediately and rebuilds the coefficients (no smoothing: values jump). | |
| std::vector< uint8_t > | getState () const |
| Serializes the parameter state (setup/UI threads; allocates). | |
| bool | setState (const uint8_t *data, size_t size) |
| Restores parameters from a blob (tolerant; rejects foreign ids). | |
Static Public Member Functions | |
| static CascadeInfo | cascadeForSlope (int slopeDb, float userQ=0.707f) noexcept |
| Returns the exact Butterworth cascade (first-order flag + per-stage Q values) used internally for a given LP/HP slope. Lets callers reproduce the true cascade magnitude instead of approximating with a single Q. | |
Protected Member Functions | |
| void | updateCoefficients (float freq, float Q, float gainDb) noexcept |
Static Protected Member Functions | |
| static ButterworthCascade | computeCascade (int slopeDb) noexcept |
| static int | slopeToStages (int slopeDb) noexcept |
Protected Attributes | |
| AudioSpec | spec_ {} |
| std::atomic< Shape > | shape_ { Shape::LowPass } |
| std::atomic< int > | numStages_ { 1 } |
| std::atomic< int > | slopeDb_ { 12 } |
| std::atomic< float > | shelfSlope_ { 1.0f } |
| std::atomic< bool > | matchedPeak_ { false } |
| std::array< Biquad< T, MaxChannels >, kMaxStages > | stages_ {} |
| Smoothers::StateVariableSmoother | freqSmoother_ |
| Smoothers::LinearSmoother | resSmoother_ |
| Smoothers::LinearSmoother | gainSmoother_ |
| std::atomic< float > | targetFreq_ {1000.0f} |
| std::atomic< float > | targetRes_ {0.707f} |
| std::atomic< float > | targetGain_ {0.0f} |
| std::atomic< float > | targetNonlinearity_ {0.0f} |
| std::atomic< bool > | driftEnabled_ { false } |
| std::atomic< float > | driftIntensity_ { 0.0f } |
| std::atomic< std::uint64_t > | driftSeed_ { 0 } |
| 0 = the instance's unique seed. | |
| AnalogRandom::Generator< float > | driftGen_ |
| float | lastFreq_ = -1.0f |
| float | lastQ_ = -1.0f |
| float | lastGain_ = -1e9f |
| Shape | lastShape_ = Shape::LowPass |
| int | lastSlopeDb_ = -1 |
| bool | lastMatched_ = false |
| float | lastShelfSlope_ = -1.0f |
| Shelf S: a slope-only change must rebuild coeffs. | |
Static Protected Attributes | |
| static constexpr int | kMaxStages = 4 |
| static constexpr int | kMaxOrder = 8 |
Professional multi-mode filter with cascaded biquad stages.
Utilizes SIMD-friendly branching and atomic parameter states for thread-safe real-time manipulation.
| T | Sample type (float or double). |
| MaxChannels | Maximum number of audio channels allowed. |
|
strong |
|
default |
|
inlinenoexcept |
Applies pending parameter targets immediately and rebuilds the coefficients (no smoothing: values jump).
For per-sample workflows where processBlock() never runs, so the atomic parameter targets would otherwise never reach the biquad stages. Owner (audio) thread only, like processSample().
|
inlinestaticnoexcept |
Returns the exact Butterworth cascade (first-order flag + per-stage Q values) used internally for a given LP/HP slope. Lets callers reproduce the true cascade magnitude instead of approximating with a single Q.
| slopeDb | Slope in dB/octave (6..48). |
| userQ | The engine's resonance parameter: scales the final stage exactly as updateCoefficients() does (neutral at the 0.707 default, resonant peak above it). |
|
inlinestaticprotectednoexcept |
|
inlinenoexcept |
|
inline |
Enables analog-style low-frequency modulation of the cutoff.
| component | The analog component profile to simulate. |
| intensity | Modulation depth (0.0 to 1.0). Non-finite values are ignored. |
|
inlinenoexcept |
The drift seed set by setDriftSeed(); 0 when the drift uses the instance's own unique seed.
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
|
inline |
|
inlinenoexcept |
|
inline |
|
inlinenoexcept |
|
inlinenoexcept |
Processes a single sample without parameter smoothing or coefficient updates.
| input | Input sample value. |
| channel | Index of the audio channel being processed. Out-of-range channels return the input unprocessed (the per-channel biquad state is bounded to MaxChannels). |
|
inlinenoexcept |
|
inline |
|
inline |
|
inlinenoexcept |
Makes the analog drift reproducible.
By default every instance draws its drift from its own unique seed, so two filters never wander together and no two renders of the same session drift alike. A non-zero seed pins the drift instead: from the next block, and again after every reset() and prepare(), the drift sequence restarts from that seed, so rendering the same input twice with the same settings produces the same output sample for sample. Zero returns to the default unique seed, and the drift carries on from wherever it is. Thread-safe, lock free; applied on the audio thread's next block.
|
inlinenoexcept |
|
inlinenoexcept |
|
inline |
|
inline |
|
inline |
|
inline |
|
inlinenoexcept |
Selects the analog-matched (de-cramped) design for Peak bells.
Bilinear bells cramp near Nyquist; the matched design (BiquadCoeffs::makePeakMatched) keeps high bells on their analog shape. Off by default (bit-compatible with previous output). Thread-safe. Not serialized by getState()/setState(); owners that persist it must re-apply it on restore (Equalizer does).
|
inlinenoexcept |
|
inline |
|
inline |
|
inlinenoexcept |
Sets the target resonance/Q. Thread-safe.
For LowPass/HighPass the cascade stays an exact Butterworth at the default Q (0.707) and larger values scale the final (most resonant) stage, adding the classic resonant peak at the cutoff. The 6 dB/oct slope is first-order and has no Q.
| Q | Quality factor. Non-finite values are ignored. |
|
inlinenoexcept |
Switches the filter topology while keeping the current frequency, resonance, and gain unchanged.
Useful for UI dropdowns where the user expects the existing slider values to carry over when they pick a different filter type. For one-shot setup with explicit parameters, the setLowPass()/setPeaking()/etc. helpers are still preferred.
| newShape | Target filter shape. Out-of-range values (a wild cast or corrupt state blob) are clamped into the enum range. |
| slopeDb | Slope in dB/octave (only used by LP/HP, default 12). |
|
inlinenoexcept |
Sets the shelf slope S on its own (LowShelf/HighShelf shapes).
The granular counterpart of the slope argument of setLowShelf() / setHighShelf(), for parameter models with one setter per parameter. RBJ semantics: 1.0 is the steepest shelf without overshoot, smaller values are gentler. Clamped to [0.0001, 1]; non-finite values are ignored (a NaN slope would otherwise pass the design clamp and turn every coefficient into NaN). Thread-safe; applied at the next block.
| slope | Shelf slope S in (0, 1]. |
|
inline |
|
inline |
|
inlinestaticprotectednoexcept |
|
inlineprotectednoexcept |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
staticconstexprprotected |
|
staticconstexprprotected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |