Brickworks > API documentation > 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.
Module type: dsp
Version: 1.1.0
Requires:
typedef struct bw_one_pole_coeffs bw_one_pole_coeffs;
Coefficients and related.
typedef struct bw_one_pole_state bw_one_pole_state;
Internal state and related.
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|).static inline void bw_one_pole_init(
bw_one_pole_coeffs * BW_RESTRICT coeffs);
Initializes input parameter values in coeffs.
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.
static inline void bw_one_pole_reset_coeffs(
bw_one_pole_coeffs * BW_RESTRICT coeffs);
Resets coefficients in coeffs to assume their target values.
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.
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.
static inline void bw_one_pole_update_coeffs_ctrl(
bw_one_pole_coeffs * BW_RESTRICT coeffs);
Triggers control-rate update of coefficients in coeffs.
static inline void bw_one_pole_update_coeffs_audio(
bw_one_pole_coeffs * BW_RESTRICT coeffs);
Triggers audio-rate update of coefficients in coeffs.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 getYZ1(
size_t channel);
...
}
BW_NULL and BW_CXX_NO_ARRAY.bw_one_pole_reset_state_multi() and updated C++ API in this regard.bw_one_pole_reset_state() returns the initial output value.reset() functions taking arrays as arguments.size_t instead of BW_SIZE_T.const and BW_RESTRICT specifiers to input arguments and implementation.process() function taking C-style arrays as arguments.coeffs argument to bw_one_pole_state_is_valid().bw_one_pole_process() and bw_one_pole_process_multi() now use BW_SIZE_T to count samples and channels.bw_one_pole_process_multi().