bw_env_gen

Linear ADSR envelope generator.

• In the off phase (gate off and possible previous release phase ended), the output is 0.f;
• in the attack phase the output increases from 0.f to 1.f;
• in the decay phase the output decreases from 1.f to the given sustain level;
• in the sustain phase the output stays constant;
• in the release phase the output decreases from the current level to 0.f.

Attack, decay, and release time parameters are not actually controlling times but rather slopes. If all phases of the ADSR fully execute, then the actual times will match the parameter settings.

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_env_gen_coeffs

typedef struct bw_env_gen_coeffs bw_env_gen_coeffs;

Coefficients and related.

bw_env_gen_state

typedef struct bw_env_gen_state bw_env_gen_state;

Internal state and related.

bw_env_gen_phase

typedef enum {
	bw_env_gen_phase_off,
	bw_env_gen_phase_attack,
	bw_env_gen_phase_decay,
	bw_env_gen_phase_sustain,
	bw_env_gen_phase_release
} bw_env_gen_phase;

Envelope generator phase:

• bw_env_gen_phase_off: off phase;
• bw_env_gen_phase_attack: attack phase;
• bw_env_gen_phase_decay: decay phase;
• bw_env_gen_phase_sustain: sustain phase;
• bw_env_gen_phase_release: release phase.

bw_env_gen_init()

static inline void bw_env_gen_init(
	bw_env_gen_coeffs * BW_RESTRICT coeffs);

Initializes input parameter values in coeffs.

bw_env_gen_set_sample_rate()

static inline void bw_env_gen_set_sample_rate(
	bw_env_gen_coeffs * BW_RESTRICT coeffs,
	float                           sample_rate);

Sets the sample_rate (Hz) value in coeffs.

bw_env_gen_reset_coeffs()

static inline void bw_env_gen_reset_coeffs(
	bw_env_gen_coeffs * BW_RESTRICT coeffs);

Resets coefficients in coeffs to assume their target values.

bw_env_gen_reset_state()

static inline float bw_env_gen_reset_state(
	const bw_env_gen_coeffs * BW_RESTRICT coeffs,
	bw_env_gen_state * BW_RESTRICT        state,
	char                                  gate_0);

Resets the given state to its initial values using the given coeffs and the initial gate value (0 for off, non-0 for on) gate_0.

Returns the corresponding initial output value.

bw_env_gen_reset_state_multi()

static inline void bw_env_gen_reset_state_multi(
	const bw_env_gen_coeffs * BW_RESTRICT              coeffs,
	bw_env_gen_state * BW_RESTRICT const * BW_RESTRICT state,
	const char * BW_RESTRICT                           gate_0,
	float * BW_RESTRICT                                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 gate values (0 for off, non-0 for on) in the gate_0 array.

The corresponding initial output values are written into the y_0 array, if not BW_NULL.

bw_env_gen_update_coeffs_ctrl()

static inline void bw_env_gen_update_coeffs_ctrl(
	bw_env_gen_coeffs * BW_RESTRICT coeffs);

Triggers control-rate update of coefficients in coeffs.

bw_env_gen_update_coeffs_audio()

static inline void bw_env_gen_update_coeffs_audio(
	bw_env_gen_coeffs * BW_RESTRICT coeffs);

Triggers audio-rate update of coefficients in coeffs.

bw_env_gen_process_ctrl()

static inline void bw_env_gen_process_ctrl(
	const bw_env_gen_coeffs * BW_RESTRICT coeffs,
	bw_env_gen_state * BW_RESTRICT        state,
	char                                  gate);

Triggers control-rate update of the internal state using coeffs and the given gate value (0 for off, non-0 for on).

bw_env_gen_process1()

static inline float bw_env_gen_process1(
	const bw_env_gen_coeffs * BW_RESTRICT coeffs,
	bw_env_gen_state * BW_RESTRICT        state);

Generates and returns one sample using coeffs, while using and updating state (audio rate only).

bw_env_gen_process()

static inline void bw_env_gen_process(
	bw_env_gen_coeffs * BW_RESTRICT coeffs,
	bw_env_gen_state * BW_RESTRICT  state,
	char                            gate,
	float * BW_RESTRICT             y,
	size_t                          n_samples);

Generates and fills the first n_samples of the output buffer y using the given gate value (0 for off, non-0 for on), while using and updating both coeffs and state (control and audio rate).

y may be BW_NULL.

bw_env_gen_process_multi()

static inline void bw_env_gen_process_multi(
	bw_env_gen_coeffs * BW_RESTRICT                    coeffs,
	bw_env_gen_state * BW_RESTRICT const * BW_RESTRICT state,
	const char * BW_RESTRICT                           gate,
	float * BW_RESTRICT const * BW_RESTRICT            y,
	size_t                                             n_channels,
	size_t                                             n_samples);

Generates and fills the first n_samples of the n_channels output buffers y using the given n_channels gate values (0 for off, non-0 for on), 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_env_gen_set_attack()

static inline void bw_env_gen_set_attack(
	bw_env_gen_coeffs * BW_RESTRICT coeffs,
	float                           value);

Sets the attack time to value (s) in coeffs.

Valid range: [0.f, 60.f].

Default value: 0.f.

bw_env_gen_set_decay()

static inline void bw_env_gen_set_decay(
	bw_env_gen_coeffs * BW_RESTRICT coeffs,
	float                           value);

Sets the decay time to value (s) in coeffs.

Valid range: [0.f, 60.f].

Default value: 0.f.

bw_env_gen_set_sustain()

static inline void bw_env_gen_set_sustain(
	bw_env_gen_coeffs * BW_RESTRICT coeffs,
	float                           value);

Sets the sustain level to value in coeffs.

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

Default value: 1.f.

bw_env_gen_set_release()

static inline void bw_env_gen_set_release(
	bw_env_gen_coeffs * BW_RESTRICT coeffs,
	float                           value);

Sets the release time to value (s) in coeffs.

Valid range: [0.f, 60.f].

Default value: 0.f.

bw_env_gen_set_skip_sustain()

static inline void bw_env_gen_set_skip_sustain(
	bw_env_gen_coeffs * BW_RESTRICT coeffs,
	char                            value);

Sets whether the sustain phase should be skipped (non-0) or not (0).

Default value: 0 (do not skip).

bw_env_gen_set_always_reach_sustain()

static inline void bw_env_gen_set_always_reach_sustain(
	bw_env_gen_coeffs * BW_RESTRICT coeffs,
	char                            value);

Sets whether the sustain phase should be reached even if gate goes off before (non-0) or not (0).

Default value: 0 (off).

bw_env_gen_get_phase()

static inline bw_env_gen_phase bw_env_gen_get_phase(
	const bw_env_gen_state * BW_RESTRICT state);

Returns the current envelope generator phase as stored in state.

bw_env_gen_get_y_z1()

static inline float bw_env_gen_get_y_z1(
	const bw_env_gen_state * BW_RESTRICT state);

Returns the last output sample as stored in state.

bw_env_gen_coeffs_is_valid()

static inline char bw_env_gen_coeffs_is_valid(
	const bw_env_gen_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_env_gen_coeffs.

bw_env_gen_state_is_valid()

static inline char bw_env_gen_state_is_valid(
	const bw_env_gen_coeffs * BW_RESTRICT coeffs,
	const bw_env_gen_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_env_gen_state.

C++ wrapper

Brickworks::EnvGen

template<size_t N_CHANNELS = 1>
class EnvGen {
public:
	EnvGen();

	void setSampleRate(
		float sampleRate);

	void reset(
		char                gate0 = 0,
		float * BW_RESTRICT y0 = BW_NULL);

# ifndef BW_CXX_NO_ARRAY
	void reset(
		char                                        gate0,
		std::array<float, N_CHANNELS> * BW_RESTRICT y0);
# endif

	void reset(
		const char * BW_RESTRICT gate0,
		float * BW_RESTRICT      y0 = BW_NULL);

# ifndef BW_CXX_NO_ARRAY
	void reset(
		std::array<char, N_CHANNELS>                gate0,
		std::array<float, N_CHANNELS> * BW_RESTRICT y0 = BW_NULL);
# endif

	void process(
		const char * BW_RESTRICT                gate,
		float * BW_RESTRICT const * BW_RESTRICT y,
		size_t                                  nSamples);

# ifndef BW_CXX_NO_ARRAY
	void process(
		std::array<char, N_CHANNELS>                gate,
		std::array<float * BW_RESTRICT, N_CHANNELS> y,
		size_t                                      nSamples);
# endif

	void setAttack(
		float value);

	void setDecay(
		float value);

	void setSustain(
		float value);

	void setRelease(
		float value);

	void setSkipSustain(
		bool value);

	void setAlwaysReachSustain(
		bool value);

	bw_env_gen_phase getPhase(
		size_t channel);

	float getYZ1(
		size_t channel);
...
}

Changelog

• Version 1.2.2:
  • Added default value for N_CHANNELS in C++ API.
  • Fixed bug which caused looping behavior when skip sustain was active and gate was kept on.
  • Updated dependencies.
• Version 1.2.1:
  • Now using BW_NULL in the C++ API and implementation.
• Version 1.2.0:
  • Added support for BW_INCLUDE_WITH_QUOTES, BW_NO_CXX, and BW_CXX_NO_EXTERN_C.
  • More robust implementation.
  • Fixed bw_env_reset_state() and bw_env_reset_state_multi() to take into account skip_sustain parameter value.
  • Added debugging checks from bw_env_gen_process() to bw_env_gen_process_multi().
  • Added debugging check in bw_env_gen_process1() to ensure that output is in [0.f, 1.f].
• Version 1.1.0:
  • Added skip_sustain and always_reach_sustain parameters.
  • 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:
  • Renamed bw_env_gen_update_state_ctrl() as bw_env_gen_process_ctrl().
  • Added initial gate value to bw_env_gen_reset_state().
  • Added bw_env_gen_reset_state_multi() and updated C++ API in this regard.
  • Now bw_env_gen_reset_state() returns the initial output value.
  • Added overloaded C++ reset() functions taking arrays as arguments.
  • bw_env_gen_process() and bw_env_gen_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.
  • Faster and more robust implementation.
  • 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_env_follow_process_multi().
  • Added gate argument to bw_env_gen_update_state_ctrl() and bw_env_gen_process(), and removed gate parameter.
  • Added C++ wrapper.
• Version 0.4.0:
  • Fixed unused parameter warnings.
• Version 0.3.0:
  • Avoid a warning related to a potentially uninitialized variable.
• Version 0.2.0:
  • Refactored API.
• Version 0.1.0:
  • First release.