diff --git a/include/bw_env_follow.h b/include/bw_env_follow.h index 38c6d9d..3d97c4a 100644 --- a/include/bw_env_follow.h +++ b/include/bw_env_follow.h @@ -104,7 +104,7 @@ static inline void bw_env_follow_update_coeffs_audio(bw_env_follow_coeffs *BW_RE static inline float bw_env_follow_process1(const bw_env_follow_coeffs *BW_RESTRICT coeffs, bw_env_follow_state *BW_RESTRICT state, float x); /*! <<<``` * Processes one input sample `x` using `coeffs`, while using and updating - * `state` (audio rate only). Returns the corresponding output sample. + * `state`. Returns the corresponding output sample. * * #### bw_env_follow_process() * ```>>> */ @@ -120,9 +120,8 @@ static inline void bw_env_follow_process(bw_env_follow_coeffs *BW_RESTRICT coeff * ```>>> */ static inline void bw_env_follow_set_attack_tau(bw_env_follow_coeffs *BW_RESTRICT coeffs, float value); /*! <<<``` - * Sets the upgoing (attack) - * <a href="https://en.wikipedia.org/wiki/Time_constant" target="_blank">time - * constant</a> in `coeffs` of the one-pole filter to `value` (s). + * Sets the upgoing (attack) time constant in `coeffs` of the one-pole filter + * to `value` (s). * * Default value: `0.f`. * @@ -130,9 +129,8 @@ static inline void bw_env_follow_set_attack_tau(bw_env_follow_coeffs *BW_RESTRIC * ```>>> */ static inline void bw_env_follow_set_release_tau(bw_env_follow_coeffs *BW_RESTRICT coeffs, float value); /*! <<<``` - * Sets the downgoing (release) - * <a href="https://en.wikipedia.org/wiki/Time_constant" target="_blank">time - * constant</a> in `coeffs` of the one-pole filter to `value` (s). + * Sets the downgoing (release) time constant in `coeffs` of the one-pole + * filter to `value` (s). * * Default value: `0.f`. * diff --git a/include/bw_noise_gen.h b/include/bw_noise_gen.h index 42c9e2c..91d77e4 100644 --- a/include/bw_noise_gen.h +++ b/include/bw_noise_gen.h @@ -78,12 +78,12 @@ static inline void bw_noise_gen_set_sample_rate(bw_noise_gen_coeffs *BW_RESTRICT static inline float bw_noise_gen_process1(const bw_noise_gen_coeffs *BW_RESTRICT coeffs); static inline float bw_noise_gen_process1_scaling(const bw_noise_gen_coeffs *BW_RESTRICT coeffs); /*! <<<``` - * These functions generates and return one sample using `coeffs`, where: + * These functions generate and return one sample using `coeffs`, where: * * `bw_noise_gen_process1()` assumes that sample rate scaling is disabled; * * `bw_noise_gen_process1_scaling()` assumes that sample rate scaling is * enabled. * - * #### bw_env_gen_process() + * #### bw_noise_gen_process() * ```>>> */ static inline void bw_noise_gen_process(bw_noise_gen_coeffs *BW_RESTRICT coeffs, float *BW_RESTRICT y, int n_samples); /*! <<<``` @@ -106,7 +106,7 @@ static inline void bw_noise_gen_set_sample_rate_scaling(bw_noise_gen_coeffs *BW_ * * #### bw_noise_gen_get_scaling_k() * ```>>> */ -static inline float bw_noise_gen_get_scaling_k(bw_noise_gen_coeffs *BW_RESTRICT coeffs); +static inline float bw_noise_gen_get_scaling_k(const bw_noise_gen_coeffs *BW_RESTRICT coeffs); /*! <<<``` * Returns the sample rate scaling factor that is applied or would be applied * if sample rate scaling were enabled, as stored in `coeffs`. @@ -159,7 +159,7 @@ static inline void bw_noise_gen_set_sample_rate_scaling(bw_noise_gen_coeffs *BW_ coeffs->sample_rate_scaling = value; } -static inline float bw_noise_gen_get_scaling_k(bw_noise_gen_coeffs *BW_RESTRICT coeffs) { +static inline float bw_noise_gen_get_scaling_k(const bw_noise_gen_coeffs *BW_RESTRICT coeffs) { return coeffs->scaling_k; } diff --git a/include/bw_one_pole.h b/include/bw_one_pole.h index 4bd7b5c..12339b8 100644 --- a/include/bw_one_pole.h +++ b/include/bw_one_pole.h @@ -122,8 +122,7 @@ static inline float bw_one_pole_process1_asym_sticky_abs(const bw_one_pole_coeff static inline float bw_one_pole_process1_asym_sticky_rel(const bw_one_pole_coeffs *BW_RESTRICT coeffs, bw_one_pole_state *BW_RESTRICT state, float x); /*! <<<``` * These function process one input sample `x` using `coeffs`, while using - * and updating `state` (audio rate only). They return the corresponding - * output sample. + * and updating `state`. They return the corresponding output sample. * * In particular: * * `bw_one_pole_process1()` assumes that upgoing and downgoing cutoff/tau diff --git a/include/bw_phase_gen.h b/include/bw_phase_gen.h index a975305..f796df3 100644 --- a/include/bw_phase_gen.h +++ b/include/bw_phase_gen.h @@ -56,71 +56,90 @@ extern "C" { * ```>>> */ typedef struct _bw_phase_gen_coeffs bw_phase_gen_coeffs; /*! <<<``` - * Coefficients. + * Coefficients and related. * * ### bw_phase_gen_state * ```>>> */ typedef struct _bw_phase_gen_state bw_phase_gen_state; /*! <<<``` - * State. + * Internal state and related. * * #### bw_phase_gen_init() * ```>>> */ static inline void bw_phase_gen_init(bw_phase_gen_coeffs *BW_RESTRICT coeffs); /*! <<<``` - * Initializes `coeffs`. + * Initializes input parameter values in `coeffs`. * * #### bw_phase_gen_set_sample_rate() * ```>>> */ static inline void bw_phase_gen_set_sample_rate(bw_phase_gen_coeffs *BW_RESTRICT coeffs, float sample_rate); /*! <<<``` - * Sets the `sample_rate` (Hz) value for the given `coeffs`. + * Sets the `sample_rate` (Hz) value in `coeffs`. * - * #### bw_phase_gen_reset() + * #### bw_phase_gen_reset_coeffs() + * ```>>> */ +static inline void bw_phase_gen_reset_coeffs(bw_phase_gen_coeffs *BW_RESTRICT coeffs); +/*! <<<``` + * Resets coefficients in `coeffs` to assume their target values. + * + * #### bw_phase_gen_reset_state() * ```>>> */ static inline void bw_phase_gen_reset_state(const bw_phase_gen_coeffs *BW_RESTRICT coeffs, bw_phase_gen_state *BW_RESTRICT state, float phase_0); /*! <<<``` - * Resets the given `state` to the initial state using the given `coeffs`. - * >>> */ - -static inline void bw_phase_gen_reset_coeffs(bw_phase_gen_coeffs *BW_RESTRICT coeffs); - + * Resets the given `state` to its initial values using the given `coeffs`. + * + * #### bw_phase_gen_update_coeffs_ctrl() + * ```>>> */ static inline void bw_phase_gen_update_coeffs_ctrl(bw_phase_gen_coeffs *BW_RESTRICT coeffs); +/*! <<<``` + * Triggers control-rate update of coefficients in `coeffs`. + * + * #### bw_phase_gen_update_coeffs_audio() + * ```>>> */ static inline void bw_phase_gen_update_coeffs_audio(bw_phase_gen_coeffs *BW_RESTRICT coeffs); - +/*! <<<``` + * Triggers audio-rate update of coefficients in `coeffs`. + * + * #### bw_phase_gen_process1\*() + * ```>>> */ static inline void bw_phase_gen_process1(const bw_phase_gen_coeffs *BW_RESTRICT coeffs, bw_phase_gen_state *BW_RESTRICT state, float *y, float *y_phase_inc); static inline void bw_phase_gen_process1_mod(const bw_phase_gen_coeffs *BW_RESTRICT coeffs, bw_phase_gen_state *BW_RESTRICT state, float x_mod, float *y, float *y_phase_inc); - -/*! ... +/*! <<<``` + * These functions generate and return one sample using `coeffs`, while using + * and updating `state`, and put the corresponding phase increment value in + * `y_phase_inc`. + * + * In particular: + * * `bw_phase_gen_process1()` does not apply exponential frequency + * modulation; + * * `bw_phase_gen_process1_mod()` applies exponential frequency modulation + * using `x_mod` as modulation input (scale `1.f`/octave). + * * #### bw_phase_gen_process() * ```>>> */ static inline void bw_phase_gen_process(bw_phase_gen_coeffs *BW_RESTRICT coeffs, bw_phase_gen_state *BW_RESTRICT state, const float *x_mod, float* y, float *y_phase_inc, int n_samples); /*! <<<``` - * Lets the given `instance` generate `n_samples` samples and puts them in - * the output buffer `y`. + * Generates and fills the first `n_samples` of the output buffer `y`, while + * using and updating both `coeffs` and `state` (control and audio rate). * * If `x_mod` is not `NULL`, it is used as a source of exponential frequency * modulation (scale `1.f`/octave). * * If `y_inc` is not `NULL`, it is filled with phase increment values. - * >>> */ - -/*! ... + * * #### bw_phase_gen_set_frequency() * ```>>> */ static inline void bw_phase_gen_set_frequency(bw_phase_gen_coeffs *BW_RESTRICT coeffs, float value); /*! <<<``` - * Sets the base frequency to `value` (Hz) for the given `instance`. + * Sets the base frequency to `value` (Hz) in `coeffs`. * * Default value: `1.f`. - * >>> */ - -/*! ... + * * #### bw_phase_gen_set_portamento_tau() * ```>>> */ static inline void bw_phase_gen_set_portamento_tau(bw_phase_gen_coeffs *BW_RESTRICT coeffs, float value); /*! <<<``` - * Sets the portamento time constant `value` (s) for the given `instance`. + * Sets the portamento time constant `value` (s) in `coeffs`. * * Default value: `0.f`. * }}} */ diff --git a/include/bw_pink_filt.h b/include/bw_pink_filt.h index 0e783e0..f001044 100644 --- a/include/bw_pink_filt.h +++ b/include/bw_pink_filt.h @@ -24,7 +24,12 @@ * description {{{ * Pinking filter. * - * ... + * This is a + * <a href="https://en.wikipedia.org/wiki/Linear_time-invariant_system" + * target="_blank">linear time-invariant filter</a> approximately attenuating + * 3 dB/oct from about 0.000046 × Nyquist frequency to about 0.9 × Nyquist + * frequency. It can be used to turn white noise into pink noise (hence the + * name). * }}} * changelog {{{ * <ul> @@ -58,38 +63,68 @@ typedef struct _bw_pink_filt_coeffs bw_pink_filt_coeffs; * ```>>> */ typedef struct _bw_pink_filt_state bw_pink_filt_state; /*! <<<``` - * State - * >>> */ - + * Internal state and related. + * + * #### bw_pink_filt_init() + * ```>>> */ static inline void bw_pink_filt_init(bw_pink_filt_coeffs *BW_RESTRICT coeffs); - +/*! <<<``` + * Initializes input parameter values in `coeffs`. + * + * #### bw_pink_filt_set_sample_rate() + * ```>>> */ static inline void bw_pink_filt_set_sample_rate(bw_pink_filt_coeffs *BW_RESTRICT coeffs, float sample_rate); - -/*! ... - * #### bw_pink_filt_reset() +/*! <<<``` + * Sets the `sample_rate` (Hz) value in `coeffs`. + * + * #### bw_pink_filt_reset_state() * ```>>> */ static inline void bw_pink_filt_reset_state(const bw_pink_filt_coeffs *BW_RESTRICT coeffs, bw_pink_filt_state *BW_RESTRICT state); /*! <<<``` - * Resets the given `instance` to its initial state. - * >>> */ - + * Resets the given `state` to its initial values using the given `coeffs`. + * + * #### bw_pink_filt_process1() + * ```>>> */ static inline float bw_pink_filt_process1(const bw_pink_filt_coeffs *BW_RESTRICT coeffs, bw_pink_filt_state *BW_RESTRICT state, float x); - static inline float bw_pink_filt_process1_scaling(const bw_pink_filt_coeffs *BW_RESTRICT coeffs, bw_pink_filt_state *BW_RESTRICT state, float x); - -/*! ... +/*! <<<``` + * These function process one input sample `x` using `coeffs`, while using + * and updating `state`. They return the corresponding output sample. + * + * In particular: + * * `bw_pink_filt_process1()` assumes that sample rate scaling is disabled; + * * `bw_pink_filt_process1_scaling()` assumes that sample rate scaling is + * enabled. + * * #### bw_pink_filt_process() * ```>>> */ static inline void bw_pink_filt_process(bw_pink_filt_coeffs *BW_RESTRICT coeffs, bw_pink_filt_state *BW_RESTRICT state, const float *x, float* y, int n_samples); /*! <<<``` - * Lets the given `instance` process `n_samples` samples from the input - * buffer `x` and fills the corresponding `n_samples` samples in the output - * buffer `y`. - * }}} */ - + * 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_pink_filt_set_sample_rate_scaling() + * ```>>> */ static inline void bw_pink_filt_set_sample_rate_scaling(bw_noise_gen_coeffs *BW_RESTRICT coeffs, char value); - -static inline float bw_pink_filt_get_scaling_k(bw_noise_gen_coeffs *BW_RESTRICT coeffs); +/*! <<<``` + * Sets whether the output should be scaled (`value` non-`0`) or not (`0`) + * according to the sample rate in `coeffs`. + * + * In order to keep the magnitude response consistent at different sample + * rates, the output of this filter should be accordingly scaled. The 44100 + * Hz sample rate is used as a reference (that is, the scaling factor at that + * sample rate is `1.f`). + * + * Default value: `0` (off). + * + * #### bw_pink_filt_get_scaling_k() + * ```>>> */ +static inline float bw_pink_filt_get_scaling_k(const bw_noise_gen_coeffs *BW_RESTRICT coeffs); +/*! <<<``` + * Returns the sample rate scaling factor that is applied or would be applied + * if sample rate scaling were enabled, as stored in `coeffs`. + * }}} */ /*** Implementation ***/ @@ -155,7 +190,7 @@ static inline void bw_pink_filt_set_sample_rate_scaling(bw_noise_gen_coeffs *BW_ coeffs->sample_rate_scaling = value; } -static inline float bw_pink_filt_get_scaling_k(bw_noise_gen_coeffs *BW_RESTRICT coeffs) { +static inline float bw_pink_filt_get_scaling_k(const bw_noise_gen_coeffs *BW_RESTRICT coeffs) { return coeffs->scaling_k; }