Brickworks > API documentation > bw_comb

bw_comb

Description

Comb filter / delay effect with feedforward and feedback paths.

Essentially an implementation of the structure described in

J. Dattorro, "Effect Design, Part 2: Delay-Line Modulation and Chorus", J. Audio Eng. Soc., vol. 45, no. 10, pp. 764-788, October 1997.

Unlike in the original paper, the feedback signal is not subtracted but rather added to the input.

Info

Module type: dsp

Version: 1.1.0

Requires:

API

bw_comb_coeffs

typedef struct bw_comb_coeffs bw_comb_coeffs;

Coefficients and related.

bw_comb_state

typedef struct bw_comb_state bw_comb_state;

Internal state and related.

bw_comb_init()

static inline void bw_comb_init(
	bw_comb_coeffs * BW_RESTRICT coeffs,
	float                        max_delay);

Initializes input parameter values in coeffs using max_delay (s) as the maximum delay time.

max_delay must be finite and non-negative.

bw_comb_set_sample_rate()

static inline void bw_comb_set_sample_rate(
	bw_comb_coeffs * BW_RESTRICT coeffs,
	float                        sample_rate);

Sets the sample_rate (Hz) value in coeffs.

bw_comb_mem_req()

static inline size_t bw_comb_mem_req(
	const bw_comb_coeffs * BW_RESTRICT coeffs);

Returns the size, in bytes, of contiguous memory to be supplied to bw_comb_mem_set() using coeffs.

bw_comb_mem_set()

static inline void bw_comb_mem_set(
	const bw_comb_coeffs * BW_RESTRICT coeffs,
	bw_comb_state * BW_RESTRICT        state,
	void * BW_RESTRICT                 mem);

Associates the contiguous memory block mem to the given state using coeffs.

bw_comb_reset_coeffs()

static inline void bw_comb_reset_coeffs(
	bw_comb_coeffs * BW_RESTRICT coeffs);

Resets coefficients in coeffs to assume their target values.

bw_comb_reset_state()

static inline float bw_comb_reset_state(
	const bw_comb_coeffs * BW_RESTRICT coeffs,
	bw_comb_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.

If parameter coeff_fb has value -1.f or 1.f, then x_0 must be 0.f.

bw_comb_reset_state_multi()

static inline void bw_comb_reset_state_multi(
	const bw_comb_coeffs * BW_RESTRICT              coeffs,
	bw_comb_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.

If parameter coeff_fb has value -1.f or 1.f, then x_0 must only contain 0.f.

bw_comb_update_coeffs_ctrl()

static inline void bw_comb_update_coeffs_ctrl(
	bw_comb_coeffs * BW_RESTRICT coeffs);

Triggers control-rate update of coefficients in coeffs.

bw_comb_update_coeffs_audio()

static inline void bw_comb_update_coeffs_audio(
	bw_comb_coeffs * BW_RESTRICT coeffs);

Triggers audio-rate update of coefficients in coeffs.

bw_comb_process1()

static inline float bw_comb_process1(
	const bw_comb_coeffs * BW_RESTRICT coeffs,
	bw_comb_state * BW_RESTRICT        state,
	float                              x);

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

bw_comb_process()

static inline void bw_comb_process(
	bw_comb_coeffs * BW_RESTRICT coeffs,
	bw_comb_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_comb_process_multi()

static inline void bw_comb_process_multi(
	bw_comb_coeffs * BW_RESTRICT                    coeffs,
	bw_comb_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_comb_set_delay_ff()

static inline void bw_comb_set_delay_ff(
	bw_comb_coeffs * BW_RESTRICT coeffs,
	float                        value);

Sets the feedforward delay time value (s) in coeffs.

This parameter is internally limited to avoid buffer overflows.

value must be finite.

Default value: 0.f.

bw_comb_set_delay_fb()

static inline void bw_comb_set_delay_fb(
	bw_comb_coeffs * BW_RESTRICT coeffs,
	float                        value);

Sets the feedback delay time value (s) in coeffs.

This parameter is internally limited to avoid buffer overflows.

value must be finite.

Default value: 0.f.

bw_comb_set_coeff_blend()

static inline void bw_comb_set_coeff_blend(
	bw_comb_coeffs * BW_RESTRICT coeffs,
	float                        value);

Sets the blend coefficient value in coeffs.

value must be finite.

Default value: 1.f.

bw_comb_set_coeff_ff()

static inline void bw_comb_set_coeff_ff(
	bw_comb_coeffs * BW_RESTRICT coeffs,
	float                        value);

Sets the feedforward coefficient value in coeffs.

value must be finite.

Default value: 0.f.

bw_comb_set_coeff_fb()

static inline void bw_comb_set_coeff_fb(
	bw_comb_coeffs * BW_RESTRICT coeffs,
	float                        value);

Sets the feedback coefficient value in coeffs.

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

Default value: 0.f.

bw_comb_coeffs_is_valid()

static inline char bw_comb_coeffs_is_valid(
	const bw_comb_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_comb_coeffs.

bw_comb_state_is_valid()

static inline char bw_comb_state_is_valid(
	const bw_comb_coeffs * BW_RESTRICT coeffs,
	const bw_comb_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_comb_state.

C++ wrapper

Brickworks::Comb
template<size_t N_CHANNELS>
class Comb {
public:
	Comb(
		float maxDelay = 1.f);

	~Comb();

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

	void setDelayFB(
		float value);

	void setCoeffBlend(
		float value);

	void setCoeffFF(
		float value);

	void setCoeffFB(
		float value);
...
}

ChangeLog

  • Version 0.4.0:
    • First release.