bw_one_pole

One-pole (6 dB/oct) lowpass filter with unitary DC gain, separate attack and decay time constants, and sticky target-reach threshold.

This is better suited to implement smoothing than bw_lp1.

Version: 1.2.0

License:

GPLv3 for free software/open source projects, or
proprietary license for all other products.

Source code accessible here

Requires:

Included in Brickworks, which is:

FREE for free software/open source projects (GPLv3), or
3,000 € for all other products (proprietary license).

Details

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).

Description	Link
One-pole lowpass filter	Download

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

API

Module type: DSP

bw_one_pole_coeffs

typedef struct bw_one_pole_coeffs bw_one_pole_coeffs;

Coefficients and related.

bw_one_pole_state

typedef struct bw_one_pole_state bw_one_pole_state;

Internal state and related.

bw_one_pole_sticky_mode

typedef enum {
	bw_one_pole_sticky_mode_abs,
	bw_one_pole_sticky_mode_rel
} bw_one_pole_sticky_mode;

Distance metrics for sticky behavior:

bw_one_pole_sticky_mode_abs: absolute difference (|out - in|);
bw_one_pole_sticky_mode_rel: relative difference with respect to input (|out - in| / |in|).

bw_one_pole_init()

static inline void bw_one_pole_init(
	bw_one_pole_coeffs * BW_RESTRICT coeffs);

Initializes input parameter values in coeffs.

bw_one_pole_set_sample_rate()

static inline void bw_one_pole_set_sample_rate(
	bw_one_pole_coeffs * BW_RESTRICT coeffs,
	float                            sample_rate);

Sets the sample_rate (Hz) value in coeffs.

bw_one_pole_reset_coeffs()

static inline void bw_one_pole_reset_coeffs(
	bw_one_pole_coeffs * BW_RESTRICT coeffs);

Resets coefficients in coeffs to assume their target values.

bw_one_pole_reset_state()

static inline float bw_one_pole_reset_state(
	const bw_one_pole_coeffs * BW_RESTRICT coeffs,
	bw_one_pole_state * BW_RESTRICT        state,
	float                                  x_0);

Resets the given state to its initial values using the given coeffs and the initial input value x_0.

Returns the corresponding initial output value.

bw_one_pole_reset_state_multi()

static inline void bw_one_pole_reset_state_multi(
	const bw_one_pole_coeffs * BW_RESTRICT              coeffs,
	bw_one_pole_state * BW_RESTRICT const * BW_RESTRICT state,
	const float *                                       x_0,
	float *                                             y_0,
	size_t                                              n_channels);

Resets each of the n_channels states to its initial values using the given coeffs and the corresponding initial input value in the x_0 array.

The corresponding initial output values are written into the y_0 array, if not BW_NULL.

bw_one_pole_update_coeffs_ctrl()

static inline void bw_one_pole_update_coeffs_ctrl(
	bw_one_pole_coeffs * BW_RESTRICT coeffs);

Triggers control-rate update of coefficients in coeffs.

bw_one_pole_update_coeffs_audio()

static inline void bw_one_pole_update_coeffs_audio(
	bw_one_pole_coeffs * BW_RESTRICT coeffs);

Triggers audio-rate update of coefficients in coeffs.

bw_one_pole_process1*()

static inline float bw_one_pole_process1(
	const bw_one_pole_coeffs * BW_RESTRICT coeffs,
	bw_one_pole_state * BW_RESTRICT        state,
	float                                  x);

static inline float bw_one_pole_process1_sticky_abs(
	const bw_one_pole_coeffs * BW_RESTRICT coeffs,
	bw_one_pole_state * BW_RESTRICT        state,
	float                                  x);

static inline float bw_one_pole_process1_sticky_rel(
	const bw_one_pole_coeffs * BW_RESTRICT coeffs,
	bw_one_pole_state * BW_RESTRICT        state,
	float                                  x);

static inline float bw_one_pole_process1_asym(
	const bw_one_pole_coeffs * BW_RESTRICT coeffs,
	bw_one_pole_state * BW_RESTRICT        state,
	float                                  x);

static inline float bw_one_pole_process1_asym_sticky_abs(
	const bw_one_pole_coeffs * BW_RESTRICT coeffs,
	bw_one_pole_state * BW_RESTRICT        state,
	float                                  x);

static inline float bw_one_pole_process1_asym_sticky_rel(
	const bw_one_pole_coeffs * BW_RESTRICT coeffs,
	bw_one_pole_state * BW_RESTRICT        state,
	float                                  x);

These functions process one input sample x using coeffs, while using and updating state. They return the corresponding output sample.

In particular:

bw_one_pole_process1() assumes that upgoing and downgoing cutoff/tau are equal and the target-reach threshold is 0.f;
bw_one_pole_process1_sticky_abs() assumes that upgoing and downgoing cutoff/tau are equal, that the target-reach threshold is not 0.f, and that the distance metric for sticky behavior is set to bw_one_pole_sticky_mode_abs;
bw_one_pole_process1_sticky_rel() assumes that upgoing and downgoing cutoff/tau are equal, that the target-reach threshold is not 0.f, and that the distance metric for sticky behavior is set to bw_one_pole_sticky_mode_rel;
bw_one_pole_process1_asym() assumes that upgoing and downgoing cutoff/tau are different and the target-reach threshold is 0.f;
bw_one_pole_process1_asym_sticky_abs() assumes that upgoing and downgoing cutoff/tau are different, that the target-reach threshold is not 0.f, and that the distance metric for sticky behavior is set to bw_one_pole_sticky_mode_abs;
bw_one_pole_process1_asym_sticky_rel() assumes that upgoing and downgoing cutoff/tau are different, that the target-reach threshold is not 0.f, and that the distance metric for sticky behavior is set to bw_one_pole_sticky_mode_rel.

Such assumptions are unchecked even for debugging purposes.

bw_one_pole_process()

static inline void bw_one_pole_process(
	bw_one_pole_coeffs * BW_RESTRICT coeffs,
	bw_one_pole_state * BW_RESTRICT  state,
	const float *                    x,
	float *                          y,
	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 and updating both coeffs and state (control and audio rate).

y may be BW_NULL.

bw_one_pole_process_multi()

static inline void bw_one_pole_process_multi(
	bw_one_pole_coeffs * BW_RESTRICT                    coeffs,
	bw_one_pole_state * BW_RESTRICT const * BW_RESTRICT state,
	const float * const *                               x,
	float * const *                                     y,
	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 and updating both the common coeffs and each of the n_channels states (control and audio rate).

y or any element of y may be BW_NULL.

bw_one_pole_set_cutoff()

static inline void bw_one_pole_set_cutoff(
	bw_one_pole_coeffs * BW_RESTRICT coeffs,
	float                            value);

Sets both the upgoing (attack) and downgoing (decay) cutoff frequency to the given value (Hz) in coeffs.

This is equivalent to calling both bw_one_pole_set_cutoff_up() and bw_one_pole_set_cutoff_down() with same coeffs and value or calling bw_one_pole_set_tau() with same coeffs and value = 1 / (2 * pi * value) (net of numerical errors).

value must be non-negative.

Default value: INFINITY.

bw_one_pole_set_cutoff_up()

static inline void bw_one_pole_set_cutoff_up(
	bw_one_pole_coeffs * BW_RESTRICT coeffs,
	float                            value);

Sets the upgoing (attack) cutoff frequency to the given value (Hz) in coeffs.

This is equivalent to calling bw_one_pole_set_tau_up() with same coeffs and value = 1 / (2 * pi * value) (net of numerical errors).

value must be non-negative.

Default value: INFINITY.

bw_one_pole_set_cutoff_down()

static inline void bw_one_pole_set_cutoff_down(
	bw_one_pole_coeffs * BW_RESTRICT coeffs,
	float                            value);

Sets the downgoing (attack) cutoff frequency to the given value (Hz) in coeffs.

This is equivalent to calling bw_one_pole_set_tau_down() with same coeffs and value = 1 / (2 * pi * value) (net of numerical errors).

value must be non-negative.

Default value: INFINITY.

bw_one_pole_set_tau()

static inline void bw_one_pole_set_tau(
	bw_one_pole_coeffs * BW_RESTRICT coeffs,
	float                            value);

Sets both the upgoing (attack) and downgoing (decay) time constant to the given value (s) in coeffs.

This is equivalent to calling both bw_one_pole_set_tau_up() and bw_one_pole_set_tau_down() with same coeffs and value or calling bw_one_pole_set_cutoff() with same coeffs and value = 1 / (2 * pi * value) (net of numerical errors).

value must be non-negative.

Default value: 0.f.

bw_one_pole_set_tau_up()

static inline void bw_one_pole_set_tau_up(
	bw_one_pole_coeffs * BW_RESTRICT coeffs,
	float                            value);

Sets the upgoing (attack) time constant to the given value (s) in coeffs.

This is equivalent to calling bw_one_pole_set_cutoff_up() with same coeffs and value = 1 / (2 * pi * value) (net of numerical errors).

value must be non-negative.

Default value: 0.f.

bw_one_pole_set_tau_down()

static inline void bw_one_pole_set_tau_down(
	bw_one_pole_coeffs * BW_RESTRICT coeffs,
	float                            value);

Sets the downgoing (decay) time constant to the given value (s) in coeffs.

This is equivalent to calling bw_one_pole_set_cutoff_down() with same coeffs and value = 1 / (2 * pi * value) (net of numerical errors).

value must be non-negative.

Default value: 0.f.

bw_one_pole_set_sticky_thresh()

static inline void bw_one_pole_set_sticky_thresh(
	bw_one_pole_coeffs * BW_RESTRICT coeffs,
	float                            value);

Sets the target-reach threshold specified by value in coeffs.

When the difference between the output and the input would fall under such threshold according to the current distance metric (see bw_one_pole_set_sticky_mode()), the output is forcefully set to be equal to the input value.

Valid range: [0.f, 1e18f].

Default value: 0.f.

bw_one_pole_set_sticky_mode()

static inline void bw_one_pole_set_sticky_mode(
	bw_one_pole_coeffs * BW_RESTRICT coeffs,
	bw_one_pole_sticky_mode          value);

Sets the current distance metric for sticky behavior to value in coeffs.

Default value: bw_one_pole_sticky_mode_abs.

bw_one_pole_get_sticky_thresh()

static inline float bw_one_pole_get_sticky_thresh(
	const bw_one_pole_coeffs * BW_RESTRICT coeffs);

Returns the current target-reach threshold in coeffs.

bw_one_pole_get_sticky_thresh()

static inline bw_one_pole_sticky_mode bw_one_pole_get_sticky_mode(
	const bw_one_pole_coeffs * BW_RESTRICT coeffs);

Returns the current distance metric for sticky behavior in coeffs.

bw_one_pole_get_y_z1()

static inline float bw_one_pole_get_y_z1(
	const bw_one_pole_state * BW_RESTRICT state);

Returns the last output sample as stored in state.

bw_one_pole_coeffs_is_valid()

static inline char bw_one_pole_coeffs_is_valid(
	const bw_one_pole_coeffs * BW_RESTRICT coeffs);

Tries to determine whether coeffs is valid and returns non-0 if it seems to be the case and 0 if it is certainly not. False positives are possible, false negatives are not.

coeffs must at least point to a readable memory block of size greater than or equal to that of bw_one_pole_coeffs.

bw_one_pole_state_is_valid()

static inline char bw_one_pole_state_is_valid(
	const bw_one_pole_coeffs * BW_RESTRICT coeffs,
	const bw_one_pole_state * BW_RESTRICT  state);

Tries to determine whether state is valid and returns non-0 if it seems to be the case and 0 if it is certainly not. False positives are possible, false negatives are not.

If coeffs is not BW_NULL extra cross-checks might be performed (state is supposed to be associated to coeffs).

state must at least point to a readable memory block of size greater than or equal to that of bw_one_pole_state.

C++ wrapper

Brickworks::OnePole

template<size_t N_CHANNELS>
class OnePole {
public:
	OnePole();

	void setSampleRate(
		float sampleRate);

	void reset(
		float               x0 = 0.f,
		float * BW_RESTRICT y0 = nullptr);

# ifndef BW_CXX_NO_ARRAY
	void reset(
		float                                       x0,
		std::array<float, N_CHANNELS> * BW_RESTRICT y0);
# endif

	void reset(
		const float * x0,
		float *       y0 = nullptr);

# ifndef BW_CXX_NO_ARRAY
	void reset(
		std::array<float, N_CHANNELS>               x0,
		std::array<float, N_CHANNELS> * BW_RESTRICT y0 = nullptr);
# endif

	void process(
		const float * const * x,
		float * const *       y,
		size_t                nSamples);

# ifndef BW_CXX_NO_ARRAY
	void process(
		std::array<const float *, N_CHANNELS> x,
		std::array<float *, N_CHANNELS>       y,
		size_t                                nSamples);
# endif

	void setCutoff(
		float value);

	void setCutoffUp(
		float value);

	void setCutoffDown(
		float value);

	void setTau(
		float value);

	void setTauUp(
		float value);

	void setTauDown(
		float value);

	void setStickyThresh(
		float value);

	void setStickyMode(
		bw_one_pole_sticky_mode value);

	float getStickyThresh();

	bw_one_pole_sticky_mode getStickyMode();

	float getYZ1(
		size_t channel);
...
}

Changelog

Version 1.2.0:
- Added bw_one_pole_get_sticky_thresh() and bw_one_pole_get_sticky_mode() and related C++ API.
- Added support for BW_INCLUDE_WITH_QUOTES, BW_NO_CXX, and BW_CXX_NO_EXTERN_C.
- Added debugging checks from bw_one_pole_process() to bw_one_pole_process_multi().
- Added debugging checks in bw_one_pole_process_multi() to ensure that buffers used for both input and output appear at the same channel indices.
Version 1.1.0:
- Now using BW_NULL and BW_CXX_NO_ARRAY.
- Replaced GCC pragmas to suppress bogus uninitialized variable warnings with useless harmless statement.
Version 1.0.0:
- Added bw_one_pole_reset_state_multi() and updated C++ API in this regard.
- Now bw_one_pole_reset_state() returns the initial output value.
- Added overloaded C++ reset() functions taking arrays as arguments.
- Now using size_t instead of BW_SIZE_T.
- Added more const and BW_RESTRICT specifiers to input arguments and implementation.
- Moved C++ code to C header.
- Added overloaded C++ process() function taking C-style arrays as arguments.
- Removed usage of reserved identifiers.
- Now using backward Euler rather than impulse invariant method.
- Clearly specified parameter validity ranges.
- Added more debugging code and added coeffs argument to bw_one_pole_state_is_valid().
- Added pragmas to silence bogus GCC uninitialized variable warnings.
Version 0.6.0:
- bw_one_pole_process() and bw_one_pole_process_multi() now use BW_SIZE_T to count samples and channels.
- Added debugging code.
- Removed dependency on bw_config.
- Fixed bug when setting very high cutoff values.
Version 0.5.0:
- Added bw_one_pole_process_multi().
- Added C++ wrapper.
Version 0.4.0:
- Fixed unused parameter warnings.
Version 0.2.0:
- Refactored API.
Version 0.1.0:
- First release.