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

fix doc for bw_osc_* + aesthetic doc adjustments

Browse Source
This commit is contained in:
Stefano D'Angelo 2022-12-04 09:30:16 +01:00
parent 33222e3a37
commit 020fc7170e
8 changed files with 158 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
include/bw_env_follow.h
View File

@ -103,8 +103,8 @@ 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` and updating `state` (audio
* rate only). Returns the corresponding output sample.
* Processes one input sample `x` using `coeffs`, while using and updating
* `state` (audio rate only). Returns the corresponding output sample.
*
* #### bw_env_follow_process()
* ```>>> */

4
include/bw_env_gen.h
View File

@ -138,8 +138,8 @@ static inline void bw_env_gen_update_state_ctrl(const bw_env_gen_coeffs *BW_REST
* ```>>> */
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` and updating `state`
* (audio rate only).
* Generates and returns one sample using `coeffs`, while using and updating
* `state` (audio rate only).
*
* #### bw_env_gen_process()
* ```>>> */

5
include/bw_one_pole.h
View File

@ -121,8 +121,9 @@ static inline float bw_one_pole_process1_asym(const bw_one_pole_coeffs *BW_RESTR
static inline float bw_one_pole_process1_asym_sticky_abs(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` and updating
* `state` (audio rate only). They return the corresponding output sample.
* These function process one input sample `x` using `coeffs`, while using
* and updating `state` (audio rate only). They return the corresponding
* output sample.
*
* In particular:
* * `bw_one_pole_process1()` assumes that upgoing and downgoing cutoff/tau

34
include/bw_osc_filt.h
View File

@ -24,10 +24,11 @@
* description {{{
* Post-filter to decolorate oscillator waveshapers when antialiasing is on.
*
* This filter can be added in series of oscillator waveshapers that use
* PolyBLEP antialiasing (i.e., [bw_osc_saw](bw_osc_saw),
* [bw_osc_pulse](bw_osc_pulse), [bw_osc_tri](bw_osc_tri)) to compensate for
* high-frequency attenuation.
* This <a href="https://en.wikipedia.org/wiki/Linear_time-invariant_system"
* target="_blank">linear time-invariant filter</a> can be added in series of
* oscillator waveshapers that use PolyBLEP antialiasing
* (i.e., [bw_osc_saw](bw_osc_saw), [bw_osc_pulse](bw_osc_pulse),
* [bw_osc_tri](bw_osc_tri)) to compensate for high-frequency attenuation.
* }}}
* changelog {{{
* <ul>
@ -59,27 +60,28 @@ extern "C" {
* ```>>> */
typedef struct _bw_osc_filt_state bw_osc_filt_state;
/*! <<<```
* State
* >>> */
/*! ...
* Internal state and related.
*
* #### bw_osc_filt_reset()
* ```>>> */
static inline void bw_osc_filt_reset_state(bw_osc_filt_state *BW_RESTRICT state);
/*! <<<```
* Resets the given `instance` to its initial state.
* >>> */
* Resets the given `state` to its initial values.
*
* #### bw_osc_filt_process1()
* ```>>> */
static inline float bw_osc_filt_process1(bw_osc_filt_state *BW_RESTRICT state, float x);
/*! ...
/*! <<<```
* Processes one input sample `x` usign and updating `state`. Returns the
* corresponding output sample.
*
* #### bw_osc_filt_process()
* ```>>> */
static inline void bw_osc_filt_process(bw_osc_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
* `state`.
* }}} */
/*** Implementation ***/

69
include/bw_osc_pulse.h
View File

@ -24,6 +24,9 @@
* description {{{
* Pulse oscillator waveshaper with variable pulse width (actually, duty
* cycle) and PolyBLEP antialiasing.
*
* It turns a normalized phase signal, such as that geneated by
* [bw\_phase\_gen](bw_phase_gen), into a pulse wave.
* }}}
* changelog {{{
* <ul>
@ -55,60 +58,78 @@ extern "C" {
* ```>>> */
typedef struct _bw_osc_pulse_coeffs bw_osc_pulse_coeffs;
/*! <<<```
* Coefficients.
* Coefficients and related.
*
* #### bw_osc_pulse_init()
* ```>>> */
static inline void bw_osc_pulse_init(bw_osc_pulse_coeffs *BW_RESTRICT coeffs);
/*! <<<```
* Initializes the `coeffs`.
* Initializes input parameter values in `coeffs`.
*
* #### bw_osc_pulse_set_sample_rate()
* ```>>> */
static inline void bw_osc_pulse_set_sample_rate(bw_osc_pulse_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_osc_pulse_reset_coeffs()
* ```>>> */
static inline void bw_osc_pulse_reset_coeffs(bw_osc_pulse_coeffs *BW_RESTRICT coeffs);
/*! <<<```
* Resets coefficients in `coeffs` to assume their target values.
*
* #### bw_osc_pulse_update_coeffs_ctrl()
* ```>>> */
static inline void bw_osc_pulse_update_coeffs_ctrl(bw_osc_pulse_coeffs *BW_RESTRICT coeffs);
/*! <<<```
* Triggers control-rate update of coefficients in `coeffs`.
*
* #### bw_osc_pulse_update_coeffs_audio()
* ```>>> */
static inline void bw_osc_pulse_update_coeffs_audio(bw_osc_pulse_coeffs *BW_RESTRICT coeffs);
/*! <<<```
* Triggers audio-rate update of coefficients in `coeffs`.
*
* #### bw_osc_pulse_process1\*()
* ```>>> */
static inline float bw_osc_pulse_process1(const bw_osc_pulse_coeffs *BW_RESTRICT coeffs, float x);
static inline float bw_osc_pulse_process1_antialias(const bw_osc_pulse_coeffs *BW_RESTRICT coeffs, float x, float x_phase_inc);
/*! ...
/*! <<<```
* These function process one input sample `x`, indicating the normalized
* phase, using `coeffs`. They return the corresponding output sample.
*
* In particular:
* * `bw_osc_pulse_process1()` assumes that antialiasing is disabled;
* * `bw_osc_pulse_process1_antialias()` assumes that antialiasing is
* enabled and requires the corresponding phase increment value to be
* passed via `x_phase_inc`.
*
* #### bw_osc_pulse_process()
* ```>>> */
static inline void bw_osc_pulse_process(bw_osc_pulse_coeffs *BW_RESTRICT coeffs, const float *x, const float *x_phase_inc, float *y, int n_samples);
/*! <<<```
* Lets the given `instance` process `n_samples` samples from the input
* buffer `x` containing the normalized phase signal and fills the
* corresponding `n_samples` samples in the output buffer `y`.
* Processes the first `n_samples` of the input buffer `x`, containing the
* normalized phase signal, and fills the first `n_samples` of the output
* buffer `y`, while using and updating `coeffs`.
*
* If antialiasing is enabled, `x_phase_inc` must contain phase increment
* values, otherwise it is ignored and can be `NULL`.
*
* If antialiasing is on, `x_phase_inc` must contain phase increment values,
* otherwise it is ignored and can be `NULL`.
* >>> */
/*! ...
* #### bw_osc_pulse_set_antialiasing()
* ```>>> */
static inline void bw_osc_pulse_set_antialiasing(bw_osc_pulse_coeffs *BW_RESTRICT coeffs, char value);
/*! <<<```
* Sets whether the antialiasing is on (`value` non-`0`) or off (`0`) for the
* given `instance`.
* Sets whether the antialiasing is on (`value` non-`0`) or off (`0`) in
* `coeffs`.
*
* Default value: `0` (off).
*
* Default value: `0`.
* >>> */
/*! ...
* #### bw_osc_pulse_set_pulse_width()
* ```>>> */
static inline void bw_osc_pulse_set_pulse_width(bw_osc_pulse_coeffs *BW_RESTRICT coeffs, float value);
/*! <<<```
* Sets the pulse width (actually, the duty cycle) to `value` (range
* [`0.f`, `1.f`]) for the given `instance`.
* [`0.f`, `1.f`]) in `coeffs`.
*
* Default value: `0.5f`.
* }}} */

43
include/bw_osc_saw.h
View File

@ -23,6 +23,9 @@
* requires {{{ bw_config bw_common bw_math }}}
* description {{{
* Sawtooth oscillator waveshaper with PolyBLEP antialiasing.
*
* It turns a normalized phase signal, such as that geneated by
* [bw\_phase\_gen](bw_phase_gen), into a sawtooth wave.
* }}}
* changelog {{{
* <ul>
@ -54,37 +57,47 @@ extern "C" {
* ```>>> */
typedef struct _bw_osc_saw_coeffs bw_osc_saw_coeffs;
/*! <<<```
* Coefficients.
* Coefficients and related.
*
* #### bw_osc_saw_init()
* ```>>> */
static inline void bw_osc_saw_init(bw_osc_saw_coeffs *BW_RESTRICT coeffs);
/*! <<<```
* Initializes the `coeffs`.
* >>> */
* Initializes input parameter values in `coeffs`.
*
* #### bw_osc_saw_process1\*()
* ```>>> */
static inline float bw_osc_saw_process1(const bw_osc_saw_coeffs *BW_RESTRICT coeffs, float x);
static inline float bw_osc_saw_process1_antialias(const bw_osc_saw_coeffs *BW_RESTRICT coeffs, float x, float x_phase_inc);
/*! ...
/*! <<<```
* These function process one input sample `x`, indicating the normalized
* phase, using `coeffs`. They return the corresponding output sample.
*
* In particular:
* * `bw_osc_saw_process1()` assumes that antialiasing is disabled;
* * `bw_osc_saw_process1_antialias()` assumes that antialiasing is enabled
* and requires the corresponding phase increment value to be passed via
* `x_phase_inc`.
*
* #### bw_osc_saw_process()
* ```>>> */
static inline void bw_osc_saw_process(bw_osc_saw_coeffs *BW_RESTRICT coeffs, const float *x, const float *x_phase_inc, float *y, int n_samples);
/*! <<<```
* Lets the given `instance` process `n_samples` samples from the input
* buffer `x` containing the normalized phase signal and fills the
* corresponding `n_samples` samples in the output buffer `y`.
* >>> */
/*! ...
* Processes the first `n_samples` of the input buffer `x`, containing the
* normalized phase signal, and fills the first `n_samples` of the output
* buffer `y`, while using and updating `coeffs`.
*
* If antialiasing is enabled, `x_phase_inc` must contain phase increment
* values, otherwise it is ignored and can be `NULL`.
*
* #### bw_osc_saw_set_antialiasing()
* ```>>> */
static inline void bw_osc_saw_set_antialiasing(bw_osc_saw_coeffs *BW_RESTRICT coeffs, char value);
/*! <<<```
* Sets whether the antialiasing is on (`value` non-`0`) or off (`0`) for the
* given `instance`.
* Sets whether the antialiasing is on (`value` non-`0`) or off (`0`) in
* `coeffs`.
*
* Default value: `0`.
* Default value: `0` (off).
* }}} */
/*** Implementation ***/

21
include/bw_osc_sin.h
View File

@ -23,8 +23,9 @@
* requires {{{ bw_config bw_common bw_math }}}
* description {{{
* Sinusoidal oscillator waveshaper.
*
* This module only consists of signal processing functions.
*
* It turns a normalized phase signal, such as that geneated by
* [bw\_phase\_gen](bw_phase_gen), into a sinusoidal wave.
* }}}
* changelog {{{
* <ul>
@ -51,16 +52,22 @@ extern "C" {
#include <bw_common.h>
static inline float bw_osc_sin_process1(float x);
/*! api {{{
* #### bw_osc_sin_process1()
* ```>>> */
static inline float bw_osc_sin_process1(float x);
/*! <<<```
* Processes one input sample `x`, indicating the normalized phase, and
* returns the corresponding output
* sample.
*
* #### bw_osc_sin_process()
* ```>>> */
static inline void bw_osc_sin_process(const float *x, float* y, int n_samples);
/*! <<<```
* Turns `n_samples` samples of the normalized phase signal in the `x` buffer
* into a sinusoidal signal, filling the corresponding `n_samples` in the
* output buffer `y`.
* Processes the first `n_samples` of the input buffer `x`, containing the
* normalized phase signal, and fills the first `n_samples` of the output
* buffer `y`.
* }}} */
/*** Implementation ***/

73
include/bw_osc_tri.h
View File

@ -24,6 +24,9 @@
* description {{{
* Triangle oscillator waveshaper with variable slope (increasing time over
* period) and PolyBLEP antialiasing.
*
* It turns a normalized phase signal, such as that geneated by
* [bw\_phase\_gen](bw_phase_gen), into a triangle wave.
* }}}
* changelog {{{
* <ul>
@ -55,62 +58,78 @@ extern "C" {
* ```>>> */
typedef struct _bw_osc_tri_coeffs bw_osc_tri_coeffs;
/*! <<<```
* Coefficients.
* Coefficients and related.
*
* #### bw_osc_tri_init()
* ```>>> */
static inline void bw_osc_tri_init(bw_osc_tri_coeffs *BW_RESTRICT coeffs);
/*! <<<```
* Initializes the `coeffs`.
* Initializes input parameter values in `coeffs`.
*
* #### bw_osc_tri_set_sample_rate()
* ```>>> */
static inline void bw_osc_tri_set_sample_rate(bw_osc_tri_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_osc_tri_reset_coeffs()
* ```>>> */
static inline void bw_osc_tri_reset_coeffs(bw_osc_tri_coeffs *BW_RESTRICT coeffs);
/*! <<<```
* Resets coefficients in `coeffs` to assume their target values.
*
* #### bw_osc_tri_update_coeffs_ctrl()
* ```>>> */
static inline void bw_osc_tri_update_coeffs_ctrl(bw_osc_tri_coeffs *BW_RESTRICT coeffs);
/*! <<<```
* Triggers control-rate update of coefficients in `coeffs`.
*
* #### bw_osc_tri_update_coeffs_audio()
* ```>>> */
static inline void bw_osc_tri_update_coeffs_audio(bw_osc_tri_coeffs *BW_RESTRICT coeffs);
/*! <<<```
* Triggers audio-rate update of coefficients in `coeffs`.
*
* #### bw_osc_pulse_process1\*()
* ```>>> */
static inline float bw_osc_tri_process1(const bw_osc_tri_coeffs *BW_RESTRICT coeffs, float x);
static inline float bw_osc_tri_process1_antialias(const bw_osc_tri_coeffs *BW_RESTRICT coeffs, float x, float x_phase_inc);
/*! ...
/*! <<<```
* These function process one input sample `x`, indicating the normalized
* phase, using `coeffs`. They return the corresponding output sample.
*
* In particular:
* * `bw_osc_tri_process1()` assumes that antialiasing is disabled;
* * `bw_osc_tri_process1_antialias()` assumes that antialiasing is enabled
* and requires the corresponding phase increment value to be passed via
* `x_phase_inc`.
*
* #### bw_osc_tri_process()
* ```>>> */
static inline void bw_osc_tri_process(bw_osc_tri_coeffs *BW_RESTRICT coeffs, const float *x, const float *x_phase_inc, float *y, int n_samples);
/*! <<<```
* Lets the given `instance` process `n_samples` samples from the input
* buffer `x` containing the normalized phase signal and fills the
* corresponding `n_samples` samples in the output buffer `y`.
* Processes the first `n_samples` of the input buffer `x`, containing the
* normalized phase signal, and fills the first `n_samples` of the output
* buffer `y`, while using and updating `coeffs`.
*
* If antialiasing is enabled, `x_phase_inc` must contain phase increment
* values, otherwise it is ignored and can be `NULL`.
*
* If antialiasing is on, `x_phase_inc` must contain phase increment values,
* otherwise it is ignored and can be `NULL`.
* >>> */
/*! ...
* #### bw_osc_tri_set_antialiasing()
* ```>>> */
static inline void bw_osc_tri_set_antialiasing(bw_osc_tri_coeffs *BW_RESTRICT coeffs, char value);
/*! <<<```
* Sets whether the antialiasing is on (`value` non-`0`) or off (`0`) for the
* given `instance`.
* Sets whether the antialiasing is on (`value` non-`0`) or off (`0`) in
* `coeffs`.
*
* Default value: `0` (off).
*
* Default value: `0`.
* >>> */
/*! ...
* #### bw_osc_tri_set_slope()
* ```>>> */
static inline void bw_osc_tri_set_slope(bw_osc_tri_coeffs *BW_RESTRICT coeffs, float value);
/*! <<<```
* Sets the slope (increasing time over period) to `value` (range [`0.f`,
* `1.f`]) for the given `instance`.
*
* NOT TOO CLOSE TO TO 0.f and 1.f!!!
* Sets the slope (increasing time over period) to `value` (range [`0.001f`,
* `0.999f`]) in `coeffs`.
*
* Default value: `0.5f`.
* }}} */