Brickworks > API documentation > bw_env_gen
Linear ADSR envelope generator.
0.f;0.f to 1.f;1.f to the given sustain level;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.
Module type: dsp
Version: 1.1.0
Requires:
typedef struct bw_env_gen_coeffs bw_env_gen_coeffs;
Coefficients and related.
typedef struct bw_env_gen_state bw_env_gen_state;
Internal state and related.
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.static inline void bw_env_gen_init(
bw_env_gen_coeffs * BW_RESTRICT coeffs);
Initializes input parameter values in coeffs.
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.
static inline void bw_env_gen_reset_coeffs(
bw_env_gen_coeffs * BW_RESTRICT coeffs);
Resets coefficients in coeffs to assume their target values.
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.
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.
static inline void bw_env_gen_update_coeffs_ctrl(
bw_env_gen_coeffs * BW_RESTRICT coeffs);
Triggers control-rate update of coefficients in coeffs.
static inline void bw_env_gen_update_coeffs_audio(
bw_env_gen_coeffs * BW_RESTRICT coeffs);
Triggers audio-rate update of coefficients in coeffs.
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).
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).
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.
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.
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.
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.
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.
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.
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).
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).
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.
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.
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.
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.
template<size_t N_CHANNELS>
class EnvGen {
public:
EnvGen();
void setSampleRate(
float sampleRate);
void reset(
char gate0 = 0,
float * BW_RESTRICT y0 = nullptr);
#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 = nullptr);
#ifndef BW_CXX_NO_ARRAY
void reset(
std::array<char, N_CHANNELS> gate0,
std::array<float, N_CHANNELS> * BW_RESTRICT y0 = nullptr);
#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);
...
}
BW_NULL and BW_CXX_NO_ARRAY.bw_env_gen_update_state_ctrl() as bw_env_gen_process_ctrl().bw_env_gen_reset_state().bw_env_gen_reset_state_multi() and updated C++ API in this regard.bw_env_gen_reset_state() returns the initial output value.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.const and BW_RESTRICT specifiers to input arguments and implementation.process() function taking C-style arrays as arguments.bw_env_follow_process_multi().gate argument to bw_env_gen_update_state_ctrl() and bw_env_gen_process(), and removed gate parameter.