bw_peak

Brickworks > API documentation > bw_peak

Description

Second-order peak filter with unitary gain at DC and asymptotically as frequency increases.

The quality factor of the underlying bandpass filter can be either directly controlled via the Q parameter or indirectly through the bandwidth parameter, which designates the distance in octaves between midpoint gain frequencies, i.e., frequencies with gain = peak gain / 2 in dB terms. The use_bandiwdth parameter allows you to choose which parameterization to use.

Info

Module type: dsp

Version: 1.1.0

Requires:

API

bw_peak_coeffs

typedef struct bw_peak_coeffs bw_peak_coeffs;

Coefficients and related.

bw_peak_state

typedef struct bw_peak_state bw_peak_state;

Internal state and related.

bw_peak_init()

static inline void bw_peak_init(
	bw_peak_coeffs * BW_RESTRICT coeffs);

Initializes input parameter values in coeffs.

bw_peak_set_sample_rate()

static inline void bw_peak_set_sample_rate(
	bw_peak_coeffs * BW_RESTRICT coeffs,
	float                        sample_rate);

Sets the sample_rate (Hz) value in coeffs.

bw_peak_reset_coeffs()

static inline void bw_peak_reset_coeffs(
	bw_peak_coeffs * BW_RESTRICT coeffs);

Resets coefficients in coeffs to assume their target values.

bw_peak_reset_state()

static inline float bw_peak_reset_state(
	const bw_peak_coeffs * BW_RESTRICT coeffs,
	bw_peak_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_peak_reset_state_multi()

static inline void bw_peak_reset_state_multi(
	const bw_peak_coeffs * BW_RESTRICT              coeffs,
	bw_peak_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_peak_update_coeffs_ctrl()

static inline void bw_peak_update_coeffs_ctrl(
	bw_peak_coeffs * BW_RESTRICT coeffs);

Triggers control-rate update of coefficients in coeffs.

bw_peak_update_coeffs_audio()

static inline void bw_peak_update_coeffs_audio(
	bw_peak_coeffs * BW_RESTRICT coeffs);

Triggers audio-rate update of coefficients in coeffs.

bw_peak_process1()

static inline float bw_peak_process1(
	const bw_peak_coeffs * BW_RESTRICT coeffs,
	bw_peak_state * BW_RESTRICT        state,
	float                              x);

Processes one input sample x using coeffs, while using and updating state. Returns the corresponding output sample.

bw_peak_process()

static inline void bw_peak_process(
	bw_peak_coeffs * BW_RESTRICT coeffs,
	bw_peak_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).

bw_peak_process_multi()

static inline void bw_peak_process_multi(
	bw_peak_coeffs * BW_RESTRICT                    coeffs,
	bw_peak_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).

bw_peak_set_cutoff()

static inline void bw_peak_set_cutoff(
	bw_peak_coeffs * BW_RESTRICT coeffs,
	float                        value);

Sets the cutoff frequency value (Hz) in coeffs.

Valid range: [1e-6f, 1e12f].

Default value: 1e3f.

bw_peak_set_Q()

static inline void bw_peak_set_Q(
	bw_peak_coeffs * BW_RESTRICT coeffs,
	float                        value);

Sets the quality factor to the given value in coeffs.

Valid range: [1e-6f, 1e6f].

Default value: 0.5f.

bw_peak_set_prewarp_at_cutoff()

static inline void bw_peak_set_prewarp_at_cutoff(
	bw_peak_coeffs * BW_RESTRICT coeffs,
	char                         value);

Sets whether bilinear transform prewarping frequency should match the cutoff frequency (non-0) or not (0).

Default value: non-0 (on).

bw_peak_set_prewarp_freq()

static inline void bw_peak_set_prewarp_freq(
	bw_peak_coeffs * BW_RESTRICT coeffs,
	float                        value);

Sets the prewarping frequency value (Hz) in coeffs.

Only used when the prewarp_at_cutoff parameter is off and however internally limited to avoid instability.

Valid range: [1e-6f, 1e12f].

Default value: 1e3f.

bw_peak_set_peak_gain_lin()

static inline void bw_peak_set_peak_gain_lin(
	bw_peak_coeffs * BW_RESTRICT coeffs,
	float                        value);

Sets the peak gain parameter to the given value (linear gain) in coeffs.

Valid range: [1e-30f, 1e30f].

If actually using the bandwidth parameter to control Q, by the time bw_peak_reset_coeffs(), bw_peak_update_coeffs_ctrl(), bw_peak_update_coeffs_audio(), bw_peak_process1(), bw_peak_process(), or bw_peak_process_multi() is called, bw_sqrtf(bw_pow2f(bandwidth) * peak_gain) * bw_rcpf(bw_pow2f(bandwidth) - 1.f) must be in [1e-6f, 1e6f].

Default value: 1.f.

bw_peak_set_peak_gain_dB()

static inline void bw_peak_set_peak_gain_dB(
	bw_peak_coeffs * BW_RESTRICT coeffs,
	float                        value);

Sets the peak gain parameter to the given value (dB) in coeffs.

Valid range: [-600.f, 600.f].

Default value: 0.f.

bw_peak_set_bandiwdth()

static inline void bw_peak_set_bandwidth(
	bw_peak_coeffs * BW_RESTRICT coeffs,
	float                        value);

Sets the bandwidth value (octaves) in coeffs.

Valid range: [1e-6f, 90.f].

Default value: 2.543106606327224f.

bw_peak_set_use_bandwidth()

static inline void bw_peak_set_use_bandwidth(
	bw_peak_coeffs * BW_RESTRICT coeffs,
	char                         value);

Sets whether the quality factor should be controlled via the bandwidth parameter (value non-0) or via the Q parameter (0).

Default value: non-0 (use bandwidth parameter).

bw_peak_coeffs_is_valid()

static inline char bw_peak_coeffs_is_valid(
	const bw_peak_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_peak_coeffs.

bw_peak_state_is_valid()

static inline char bw_peak_state_is_valid(
	const bw_peak_coeffs * BW_RESTRICT coeffs,
	const bw_peak_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_peak_state.

C++ wrapper

Brickworks::Peak

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

	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 setQ(
		float value);

	void setPrewarpAtCutoff(
		bool value);

	void setPrewarpFreq(
		float value);

	void setPeakGainLin(
		float value);

	void setPeakGainDB(
		float value);

	void setBandwidth(
		float value);

	void setUseBandwidth(
		bool value);
...
}

ChangeLog

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_peak_reset_state_multi() and updated C++ API in this regard.
- Now bw_peak_reset_state() returns the initial output value.
- Added overloaded C++ reset() functions taking arrays as arguments.
- Added prewarp_at_cutoff and prewarp_freq parameters.
- bw_peak_process() and bw_peak_process_multi() now use size_t to count samples and channels.
- 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.
- Added pragmas to silence bogus GCC uninitialized variable warnings.
- Clearly specified parameter validity ranges.
- Added debugging code.
Version 0.6.0:
- Removed dependency on bw_config.
Version 0.5.0:
- Added bw_peak_process_multi().
- Fixed documentation for bw_peak_set_peak_gain_lin() and bw_peak_set_gain_dB().
- Added C++ wrapper.
Version 0.4.0:
- Added initial input value to bw_peak_reset_state().
Version 0.3.0:
- First release.