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);
/*! <<<```
* 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`.
*

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_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;
}

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);
/*! <<<```
* 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

65
include/bw_phase_gen.h
View File

@ -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`.
* }}} */

79
include/bw_pink_filt.h
View File

@ -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;
}