orastron/brickworks
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity

more doc fix + minimal API changes

Browse Source
This commit is contained in:
Stefano D'Angelo 2022-12-04 10:34:42 +01:00
parent 020fc7170e
commit d7b8146d48
5 changed files with 109 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
include/bw_env_follow.h
View File

@ -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); 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 * 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() * #### 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); static inline void bw_env_follow_set_attack_tau(bw_env_follow_coeffs *BW_RESTRICT coeffs, float value);
/*! <<<``` /*! <<<```
* Sets the upgoing (attack) * Sets the upgoing (attack) time constant in `coeffs` of the one-pole filter
* <a href="https://en.wikipedia.org/wiki/Time_constant" target="_blank">time * to `value` (s).
* constant</a> in `coeffs` of the one-pole filter to `value` (s).
* *
* Default value: `0.f`. * 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); static inline void bw_env_follow_set_release_tau(bw_env_follow_coeffs *BW_RESTRICT coeffs, float value);
/*! <<<``` /*! <<<```
* Sets the downgoing (release) * Sets the downgoing (release) time constant in `coeffs` of the one-pole
* <a href="https://en.wikipedia.org/wiki/Time_constant" target="_blank">time * filter to `value` (s).
* constant</a> in `coeffs` of the one-pole filter to `value` (s).
* *
* Default value: `0.f`. * Default value: `0.f`.
* *

8
include/bw_noise_gen.h
View File

@ -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(const bw_noise_gen_coeffs *BW_RESTRICT coeffs);
static inline float bw_noise_gen_process1_scaling(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()` assumes that sample rate scaling is disabled;
* * `bw_noise_gen_process1_scaling()` assumes that sample rate scaling is * * `bw_noise_gen_process1_scaling()` assumes that sample rate scaling is
* enabled. * 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); 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() * #### 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 * Returns the sample rate scaling factor that is applied or would be applied
* if sample rate scaling were enabled, as stored in `coeffs`. * 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; 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; return coeffs->scaling_k;
} }

3
include/bw_one_pole.h
View File

@ -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); 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 * These function process one input sample `x` using `coeffs`, while using
* and updating `state` (audio rate only). They return the corresponding * and updating `state`. They return the corresponding output sample.
* output sample.
* *
* In particular: * In particular:
* * `bw_one_pole_process1()` assumes that upgoing and downgoing cutoff/tau * * `bw_one_pole_process1()` assumes that upgoing and downgoing cutoff/tau

65
include/bw_phase_gen.h
View File

@ -56,71 +56,90 @@ extern "C" {
* ```>>> */ * ```>>> */
typedef struct _bw_phase_gen_coeffs bw_phase_gen_coeffs; typedef struct _bw_phase_gen_coeffs bw_phase_gen_coeffs;
/*! <<<``` /*! <<<```
* Coefficients. * Coefficients and related.
* *
* ### bw_phase_gen_state * ### bw_phase_gen_state
* ```>>> */ * ```>>> */
typedef struct _bw_phase_gen_state bw_phase_gen_state; typedef struct _bw_phase_gen_state bw_phase_gen_state;
/*! <<<``` /*! <<<```
* State. * Internal state and related.
* *
* #### bw_phase_gen_init() * #### bw_phase_gen_init()
* ```>>> */ * ```>>> */
static inline void bw_phase_gen_init(bw_phase_gen_coeffs *BW_RESTRICT coeffs); 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() * #### 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); 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); 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`. * Resets the given `state` to its initial values using the given `coeffs`.
* >>> */ *
* #### bw_phase_gen_update_coeffs_ctrl()
static inline void bw_phase_gen_reset_coeffs(bw_phase_gen_coeffs *BW_RESTRICT coeffs); * ```>>> */
static inline void bw_phase_gen_update_coeffs_ctrl(bw_phase_gen_coeffs *BW_RESTRICT coeffs); 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); 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(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); 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() * #### 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); 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 * Generates and fills the first `n_samples` of the output buffer `y`, while
* the output buffer `y`. * 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 * If `x_mod` is not `NULL`, it is used as a source of exponential frequency
* modulation (scale `1.f`/octave). * modulation (scale `1.f`/octave).
* *
* If `y_inc` is not `NULL`, it is filled with phase increment values. * If `y_inc` is not `NULL`, it is filled with phase increment values.
* >>> */ *
/*! ...
* #### bw_phase_gen_set_frequency() * #### bw_phase_gen_set_frequency()
* ```>>> */ * ```>>> */
static inline void bw_phase_gen_set_frequency(bw_phase_gen_coeffs *BW_RESTRICT coeffs, float value); 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`. * Default value: `1.f`.
* >>> */ *
/*! ...
* #### bw_phase_gen_set_portamento_tau() * #### bw_phase_gen_set_portamento_tau()
* ```>>> */ * ```>>> */
static inline void bw_phase_gen_set_portamento_tau(bw_phase_gen_coeffs *BW_RESTRICT coeffs, float value); 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`. * Default value: `0.f`.
* }}} */ * }}} */

79
include/bw_pink_filt.h
View File

@ -24,7 +24,12 @@
* description {{{ * description {{{
* Pinking filter. * 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 {{{ * changelog {{{
* <ul> * <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; 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); 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); static inline void bw_pink_filt_set_sample_rate(bw_pink_filt_coeffs *BW_RESTRICT coeffs, float sample_rate);
/*! <<<```
/*! ... * Sets the `sample_rate` (Hz) value in `coeffs`.
* #### bw_pink_filt_reset() *
* #### 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); 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(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); 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() * #### 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); 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 * Processes the first `n_samples` of the input buffer `x` and fills the
* buffer `x` and fills the corresponding `n_samples` samples in the output * first `n_samples` of the output buffer `y`, while using and updating both
* buffer `y`. * `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 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 ***/ /*** 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; 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; return coeffs->scaling_k;
} }