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.

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: 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_mode()

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 = 1>
class OnePole {
public:
	OnePole();

	void setSampleRate(
		float sampleRate);

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

# 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 = BW_NULL);

# ifndef BW_CXX_NO_ARRAY
	void reset(
		std::array<float, N_CHANNELS>               x0,
		std::array<float, N_CHANNELS> * BW_RESTRICT y0 = BW_NULL);
# 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.2:
  • Added default value for N_CHANNELS in C++ API.
  • Updated dependencies.
• Verison 1.2.1:
  • Now using BW_NULL in the C++ API and implementation.
  • Fixed typo in the documentation of bw_one_pole_get_sticky_mode().
• 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.