bw_gain

Smoothed gain module with optional sticky gain-reach threshold.

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_gain_coeffs

typedef struct bw_gain_coeffs bw_gain_coeffs;

Coefficients and related.

bw_gain_sticky_mode

typedef enum {
	bw_gain_sticky_mode_abs,
	bw_gain_sticky_mode_rel
} bw_gain_sticky_mode;

Distance metrics for sticky behavior:

• bw_gain_sticky_mode_abs: absolute gain difference (|current - target|, with current and target linear);
• bw_gain_sticky_mode_rel: relative gain difference with respect to target gain (|current - target| / |target|, with current and target linear).

bw_gain_init()

static inline void bw_gain_init(
	bw_gain_coeffs * BW_RESTRICT coeffs);

Initializes input parameter values in coeffs.

bw_gain_set_sample_rate()

static inline void bw_gain_set_sample_rate(
	bw_gain_coeffs * BW_RESTRICT coeffs,
	float                        sample_rate);

Sets the sample_rate (Hz) value in coeffs.

bw_gain_reset_coeffs()

static inline void bw_gain_reset_coeffs(
	bw_gain_coeffs * BW_RESTRICT coeffs);

Resets coefficients in coeffs to assume their target values.

bw_gain_update_coeffs_ctrl()

static inline void bw_gain_update_coeffs_ctrl(
	bw_gain_coeffs * BW_RESTRICT coeffs);

Triggers control-rate update of coefficients in coeffs.

bw_gain_update_coeffs_audio()

static inline void bw_gain_update_coeffs_audio(
	bw_gain_coeffs * BW_RESTRICT coeffs);

static inline void bw_gain_update_coeffs_audio_sticky_abs(
	bw_gain_coeffs * BW_RESTRICT coeffs);

static inline void bw_gain_update_coeffs_audio_sticky_rel(
	bw_gain_coeffs * BW_RESTRICT coeffs);

These functions trigger audio-rate update of coefficients in coeffs.

In particular:

• bw_gain_update_coeffs_audio assumes that the gain-reach threshold is 0.f;
• bw_gain_update_coeffs_audio_sticky_abs assumes that the gain-reach threshold is not 0.f and the distance metric for sticky behavior is set to bw_gain_sticky_mode_abs;
• bw_gain_update_coeffs_audio_sticky_rel assumes that the gain-reach threshold is not 0.f and the distance metric for sticky behavior is set to bw_gain_sticky_mode_rel.

Such assumptions are unchecked even for debugging purposes.

bw_gain_process1()

static inline float bw_gain_process1(
	const bw_gain_coeffs * BW_RESTRICT coeffs,
	float                              x);

Processes one input sample x using coeffs and returns the corresponding output sample.

bw_gain_process()

static inline void bw_gain_process(
	bw_gain_coeffs * BW_RESTRICT coeffs,
	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 coeffs (control and audio rate).

bw_gain_process_multi()

static inline void bw_gain_process_multi(
	bw_gain_coeffs * BW_RESTRICT coeffs,
	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 the common coeffs (control and audio rate).

bw_gain_set_gain_lin()

static inline void bw_gain_set_gain_lin(
	bw_gain_coeffs * BW_RESTRICT coeffs,
	float                        value);

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

value must be finite.

Default value: 1.f.

bw_gain_set_gain_dB()

static inline void bw_gain_set_gain_dB(
	bw_gain_coeffs * BW_RESTRICT coeffs,
	float                        value);

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

value must be less than or equal to 770.630f.

Default value: 0.f.

bw_gain_set_smooth_tau()

static inline void bw_gain_set_smooth_tau(
	bw_gain_coeffs * BW_RESTRICT coeffs,
	float                        value);

Sets the smoothing time constant value (s) in coeffs.

value must be non-negative.

Default value: 0.05f.

bw_gain_set_sticky_thresh()

static inline void bw_gain_set_sticky_thresh(
	bw_gain_coeffs * BW_RESTRICT coeffs,
	float                        value);

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

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

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

Default value: 0.f.

bw_gain_set_sticky_mode()

static inline void bw_gain_set_sticky_mode(
	bw_gain_coeffs * BW_RESTRICT coeffs,
	bw_gain_sticky_mode          value);

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

Default value: bw_gain_sticky_mode_abs.

bw_gain_get_gain_lin()

static inline float bw_gain_get_gain_lin(
	const bw_gain_coeffs * BW_RESTRICT coeffs);

Returns the current gain parameter value (linear gain) in coeffs.

bw_gain_get_gain_cur()

static inline float bw_gain_get_gain_cur(
	const bw_gain_coeffs * BW_RESTRICT coeffs);

Returns the actual current gain coefficient (linear gain) in coeffs.

coeffs must be at least in the "reset" state.

bw_gain_coeffs_is_valid()

static inline char bw_gain_coeffs_is_valid(
	const bw_gain_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_gain_coeffs.

C++ wrapper

Brickworks::Gain

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

	void setSampleRate(
		float sampleRate);

	void reset();

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

	void setGainDB(
		float value);

	void setSmoothTau(
		float value);

	void setStickyThresh(
		float value);

	void setStickyMode(
		bw_gain_sticky_mode value);

	float getGainLin();

	float getGainCur();
...
}

Changelog

• Version 1.2.0:
  • Added optional sticky gain-reach threshold and related API.
  • Added support for BW_INCLUDE_WITH_QUOTES, BW_NO_CXX, and BW_CXX_NO_EXTERN_C.
  • Added debugging checks from bw_ap1_process() to bw_ap1_process_multi().
  • Added debugging checks in bw_gain_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.
• Version 1.0.0:
  • Added bw_gain_get_gain_lin().
  • Renamed bw_gain_get_gain() as bw_gain_get_gain_cur().
  • Simplified implementation to use less memory.
  • bw_gain_process() and bw_gain_process_multi() now use size_t to count samples and channels.
  • Added more const specifiers to input arguments.
  • Moved C++ code to C header.
  • Added overloaded C++ process() function taking C-style arrays as arguments.
  • Removed usage of reserved identifiers.
  • Clearly specified parameter validity ranges.
  • Added debugging code.
• Version 0.6.0:
  • Removed dependency on bw_config.
• Version 0.5.0:
  • Added bw_gain_process_multi().
  • Added bw_gain_get_gain().
• Version 0.3.0:
  • Renamed as bw_gain.
  • Added new smooth_tau parameter.
  • Changed gain parameter API to express values in linear gain and dB.
  • Added C++ wrapper.
• Version 0.2.0:
  • Refactored API.
• Version 0.1.0:
  • First release.