bw_iir1

Lightweight and fast first-order IIR filter in TDF-II form.

This is not a regular DSP module, as it exposes state and coefficients, and it's not appropriate for time-varying operation. If you need that, check out bw_ap1, bw_hp1, bw_hs1, bw_lp1, bw_ls1, bw_mm1, and bw_one_pole.

Examples

Here you can download one or more example VST3 plugins for Windows, macOS and Linux. Source code of the audio engine(s) is included in the archive(s).

VST® is a trademark of Steinberg Media Technologies GmbH, registered in Europe and other countries.

API

Module type: Utility

bw_iir1_reset()

static inline void bw_iir1_reset(
	float               x_0,
	float * BW_RESTRICT y_0,
	float * BW_RESTRICT s_0,
	float               b0,
	float               b1,
	float               a1);

Computes and puts the initial output in y_0 and the initial state in s_0, given the initial input x_0 and coefficients b0, b1, and a1.

The given coefficients must describe a stable filter.

bw_iir1_reset_multi()

static inline void bw_iir1_reset_multi(
	const float *       x_0,
	float *             y_0,
	float * BW_RESTRICT s_0, 
	float               b0,
	float               b1,
	float               a1,
	size_t              n_channels);

Computes and puts each of the n_channels initial outputs in y_0 and initial states in s_0, given the corresponding initial inputs x_0 and coefficients b0, b1, and a1.

y_0 and/or s_0 may be BW_NULL, in which case the corresponding values are not written anywhere.

The given coefficients must describe a stable filter.

bw_iir1_process1()

static inline void bw_iir1_process1(
	float               x,
	float * BW_RESTRICT y,
	float * BW_RESTRICT s,
	float               b0,
	float               b1,
	float               a1);

Processes one input sample x using coefficients b0, b1, and a1. The output sample and next state value are put in y and s respectively.

The given coefficients must describe a stable filter.

bw_iir1_process()

static inline void bw_iir1_process(
	const float *       x,
	float *             y,
	float * BW_RESTRICT s,
	float               b0,
	float               b1,
	float               a1,
	size_t              n_samples);

Processes the first n_samples of the input buffer x and fills the first n_samples of the output buffer y, while using coefficients b0, b1, and a1. The next state value is put in s.

The given coefficients must describe a stable filter.

bw_iir1_process_multi()

static inline void bw_iir1_process_multi(
	const float * const * x,
	float * const *       y,
	float * BW_RESTRICT   s,
	float                 b0,
	float                 b1,
	float                 a1,
	size_t                n_channels,
	size_t                n_samples);

Processes the first n_samples of the n_channels input buffers x and fills the first n_samples of the n_channels output buffers y, while using coefficients b0, b1, and a1. The next n_channels state values are put in s.

The given coefficients must describe a stable filter.

bw_iir1_coeffs_ap1()

static inline void bw_iir1_coeffs_ap1(
	float               sample_rate,
	float               cutoff,
	char                prewarp_at_cutoff,
	float               prewarp_freq,
	float * BW_RESTRICT b0,
	float * BW_RESTRICT b1,
	float * BW_RESTRICT a1);

Computes and puts coefficient values in b0, b1, and a1 resulting in a first-order allpass filter (90° shift at cutoff, approaching 180° shift at high frequencies) with unitary gain, using the bilinear transform with prewarping.

It takes the sample_rate (Hz, must be finite and positive) and the cutoff frequency (Hz, in [1e-6f, 1e12f]). If prewarp_at_cutoff is non-0, then the prewarping frequency matches cutoff, otherwise the value specified by prewarp_freq (Hz, in [1e-6f, 1e12f], however internally limited to avoid instability) is used.

bw_iir1_coeffs_hp1()

static inline void bw_iir1_coeffs_hp1(
	float               sample_rate,
	float               cutoff,
	char                prewarp_at_cutoff,
	float               prewarp_freq,
	float * BW_RESTRICT b0,
	float * BW_RESTRICT b1,
	float * BW_RESTRICT a1);

Computes and puts coefficient values in b0, b1, and a1 resulting in a first-order highpass filter (6 dB/oct) with gain asymptotically approaching unity as frequency increases, using the bilinear transform with prewarping.

It takes the sample_rate (Hz, must be finite and positive) and the cutoff frequency (Hz, in [1e-6f, 1e12f]). If prewarp_at_cutoff is non-0, then the prewarping frequency matches cutoff, otherwise the value specified by prewarp_freq (Hz, in [1e-6f, 1e12f], however internally limited to avoid instability) is used.

bw_iir1_coeffs_hs1()

static inline void bw_iir1_coeffs_hs1(
	float               sample_rate,
	float               cutoff,
	char                prewarp_at_cutoff,
	float               prewarp_freq,
	char                high_gain_dB,
	float               high_gain,
	float * BW_RESTRICT b0,
	float * BW_RESTRICT b1,
	float * BW_RESTRICT a1);

Computes and puts coefficient values in b0, b1, and a1 resulting in a first-order high shelf filter (6 dB/oct) with unitary DC gain, using the bilinear transform with prewarping.

It takes the sample_rate (Hz, must be finite and positive), the cutoff frequency (Hz, must be finite and positive), and the high-frequency gain high_gain, either as linear gain (in [1e-30f, 1e30f]) if high_gain_dB is 0, or otherwise in dB (in [-600.f, 600.f]). If prewarp_at_cutoff is non-0, then the prewarping frequency matches cutoff, otherwise the value specified by prewarp_freq (Hz, in [1e-6f, 1e12f], however internally limited to avoid instability) is used.

cutoff * bw_sqrtf(high_gain) must be in [1e-6f, 1e12f], where high_gain is expressed as linear gain.

bw_iir1_coeffs_lp1()

static inline void bw_iir1_coeffs_lp1(
	float               sample_rate,
	float               cutoff,
	char                prewarp_at_cutoff,
	float               prewarp_freq,
	float * BW_RESTRICT b0,
	float * BW_RESTRICT b1,
	float * BW_RESTRICT a1);

Computes and puts coefficient values in b0, b1, and a1 resulting in a first-order lowpass filter (6 dB/oct) with unitary DC gain, using the bilinear transform with prewarping.

It takes the sample_rate (Hz, must be finite and positive) and the cutoff frequency (Hz, in [1e-6f, 1e12f]). If prewarp_at_cutoff is non-0, then the prewarping frequency matches cutoff, otherwise the value specified by prewarp_freq (Hz, in [1e-6f, 1e12f], however internally limited to avoid instability) is used.

bw_iir1_coeffs_ls1()

static inline void bw_iir1_coeffs_ls1(
	float               sample_rate,
	float               cutoff,
	char                prewarp_at_cutoff,
	float               prewarp_freq,
	char                dc_gain_dB,
	float               dc_gain,
	float * BW_RESTRICT b0,
	float * BW_RESTRICT b1,
	float * BW_RESTRICT a1);

Computes and puts coefficient values in b0, b1, and a1 resulting in a first-order high shelf filter (6 dB/oct) with unitary DC gain, using the bilinear transform with prewarping.

It takes the sample_rate (Hz, must be finite and positive), the cutoff frequency (Hz, must be finite and positive), and the dc_gain, either as linear gain (in [1e-30f, 1e30f]) if dc_gain_dB is 0, or otherwise in dB (in [-600.f, 600.f]). If prewarp_at_cutoff is non-0, then the prewarping frequency matches cutoff, otherwise the value specified by prewarp_freq (Hz, in [1e-6f, 1e12f], however internally limited to avoid instability) is used.

cutoff * bw_rcpf(bw_sqrtf(dc_gain)) must be in [1e-6f, 1e12f], where dc_gain is expressed as linear gain.

bw_iir1_coeffs_mm1()

static inline void bw_iir1_coeffs_mm1(
	float               sample_rate,
	float               cutoff,
	char                prewarp_at_cutoff,
	float               prewarp_freq,
	float               coeff_x,
	float               coeff_lp,
	float * BW_RESTRICT b0,
	float * BW_RESTRICT b1,
	float * BW_RESTRICT a1);

Computes and puts coefficient values in b0, b1, and a1 resulting in a first-order filter implementing an approximation of the Laplace-domain transfer function

H(s) = coeff_x + (2 pi fc coeff_lp) / (s + 2 pi fc)

where fc is the cutoff frequency, using the bilinear transform with prewarping.

It takes the sample_rate (Hz, must be finite and positive), the cutoff frequency (Hz, in [1e-6f, 1e12f]), and output coefficients coeff_x and coeff_lp (both must be finite). If prewarp_at_cutoff is non-0, then the prewarping frequency matches cutoff, otherwise the value specified by prewarp_freq (Hz, in [1e-6f, 1e12f], however internally limited to avoid instability) is used.

bw_iir1_coeffs_is_valid()

static inline char bw_iir1_coeffs_is_valid(
	float b0,
	float b1,
	float a1);

Determines whether b0, b1, and a1 are valid and describe a stable or marginally stable filter.

It returns non-0 if it is the case and 0 otherwise.

C++ wrapper

Brickworks::iir1Reset

template<size_t N_CHANNELS = 1>
void iir1Reset(
	const float *       x0,
	float *             y0,
	float * BW_RESTRICT s0,
	float               b0,
	float               b1,
	float               a1);

# ifndef BW_CXX_NO_ARRAY
template<size_t N_CHANNELS = 1>
void iir1Reset(
	std::array<float, N_CHANNELS>               x0,
	std::array<float, N_CHANNELS> * BW_RESTRICT y0,
	std::array<float, N_CHANNELS> * BW_RESTRICT s0,
	float                                       b0,
	float                                       b1,
	float                                       a1);
# endif

template<size_t N_CHANNELS = 1>
void iir1Process(
	const float * const * x,
	float * const *       y,
	float * BW_RESTRICT   s,
	float                 b0,
	float                 b1,
	float                 a1,
	size_t                nSamples);

# ifndef BW_CXX_NO_ARRAY
template<size_t N_CHANNELS = 1>
void iir1Process(
	std::array<const float *, N_CHANNELS>       x,
	std::array<float *, N_CHANNELS>             y,
	std::array<float, N_CHANNELS> * BW_RESTRICT s,
	float                                       b0,
	float                                       b1,
	float                                       a1,
	size_t                                      nSamples);
# endif

Changelog

• Version 1.0.1:
  • Added bw_iir1_coeffs_is_valid().
  • Added default value for N_CHANNELS in C++ API.
  • Fixed bug which resulted in bad coefficients in bw_iir1_coeffs_hp1().
  • Fixed the documenation of bw_iir1_coeffs_*() w.r.t. prewarp_at_cutoff and typos.
  • Updated dependencies.
• Version 1.0.0:
  • First release.