Brickworks > API documentation > bw_dist

## bw_dist

### Description

Distortion effect.

Loosely inspired to the "rodent" distortion pedal.

Module type: dsp

Version: 1.0.0

Requires:

### API

#### bw_dist_coeffs

``````typedef struct bw_dist_coeffs bw_dist_coeffs;
``````

Coefficients and related.

#### bw_dist_state

``````typedef struct bw_dist_state bw_dist_state;
``````

Internal state and related.

#### bw_dist_init()

``````static inline void bw_dist_init(
bw_dist_coeffs * BW_RESTRICT coeffs);
``````

Initializes input parameter values in `coeffs`.

#### bw_dist_set_sample_rate()

``````static inline void bw_dist_set_sample_rate(
bw_dist_coeffs * BW_RESTRICT coeffs,
float                        sample_rate);
``````

Sets the `sample_rate` (Hz) value in `coeffs`.

#### bw_dist_reset_coeffs()

``````static inline void bw_dist_reset_coeffs(
bw_dist_coeffs * BW_RESTRICT coeffs);
``````

Resets coefficients in `coeffs` to assume their target values.

#### bw_dist_reset_state()

``````static inline float bw_dist_reset_state(
const bw_dist_coeffs * BW_RESTRICT coeffs,
bw_dist_state * BW_RESTRICT        state,
float                              x_0);
``````

Resets the given `state` to its initial values using the given `coeffs` and the initial input value `x_0`.

Returns the corresponding initial output value.

#### bw_dist_reset_state_multi()

``````static inline void bw_dist_reset_state_multi(
const bw_dist_coeffs * BW_RESTRICT              coeffs,
bw_dist_state * BW_RESTRICT const * BW_RESTRICT state,
const float *                                   x_0,
float *                                         y_0,
size_t                                          n_channels);
``````

Resets each of the `n_channels` `state`s to its initial values using the given `coeffs` and the corresponding initial input value in the `x_0` array.

The corresponding initial output values are written into the `y_0` array, if not `NULL`.

#### bw_dist_update_coeffs_ctrl()

``````static inline void bw_dist_update_coeffs_ctrl(
bw_dist_coeffs * BW_RESTRICT coeffs);
``````

Triggers control-rate update of coefficients in `coeffs`.

#### bw_dist_update_coeffs_audio()

``````static inline void bw_dist_update_coeffs_audio(
bw_dist_coeffs * BW_RESTRICT coeffs);
``````

Triggers audio-rate update of coefficients in `coeffs`.

#### bw_dist_process1()

``````static inline float bw_dist_process1(
const bw_dist_coeffs * BW_RESTRICT coeffs,
bw_dist_state * BW_RESTRICT        state,
float                              x);
``````

Processes one input sample `x` using `coeffs`, while using and updating `state`. Returns the corresponding output sample.

#### bw_dist_process()

``````static inline void bw_dist_process(
bw_dist_coeffs * BW_RESTRICT coeffs,
bw_dist_state * BW_RESTRICT  state,
const float *                x,
float *                      y,
size_t                       n_samples);
``````

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_dist_process_multi()

``````static inline void bw_dist_process_multi(
bw_dist_coeffs * BW_RESTRICT                    coeffs,
bw_dist_state * BW_RESTRICT const * BW_RESTRICT state,
const float * const *                           x,
float * const *                                 y,
size_t                                          n_channels,
size_t                                          n_samples);
``````

Processes the first `n_samples` of the `n_channels` input buffers `x` and fills the first `n_samples` of the `n_channels` output buffers `y`, while using and updating both the common `coeffs` and each of the `n_channels` `state`s (control and audio rate).

#### bw_dist_set_distortion()

``````static inline void bw_dist_set_distortion(
bw_dist_coeffs * BW_RESTRICT coeffs,
float                        value);
``````

Sets the distortion (input gain, approximately) to the given `value` in `coeffs`.

Valid range: [`0.f` (low distortion), `1.f` (high distortion)].

Default value: `0.f`.

#### bw_dist_set_tone()

``````static inline void bw_dist_set_tone(
bw_dist_coeffs * BW_RESTRICT coeffs,
float                        value);
``````

Sets the tone (filter) to the given `value` in `coeffs`.

Valid range: [`0.f` (low cutoff), `1.f` (high cutoff)].

Default value: `0.5f`.

#### bw_dist_set_volume()

``````static inline void bw_dist_set_volume(
bw_dist_coeffs * BW_RESTRICT coeffs,
float                        value);
``````

Sets the volume (output gain) to the given `value` in `coeffs`.

Valid range: [`0.f` (silence), `1.f` (max volume)].

Default value: `1.f`.

#### bw_dist_coeffs_is_valid()

``````static inline char bw_dist_coeffs_is_valid(
const bw_dist_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_dist_coeffs`.

#### bw_dist_state_is_valid()

``````static inline char bw_dist_state_is_valid(
const bw_dist_coeffs * BW_RESTRICT coeffs,
const bw_dist_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 `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_dist_state`.

#### C++ wrapper

##### Brickworks::Dist
``````template<size_t N_CHANNELS>
class Dist {
public:
Dist();

void setSampleRate(
float sampleRate);

void reset(
float               x0 = 0.f,
float * BW_RESTRICT y0 = nullptr);

void reset(
float                                       x0,
std::array<float, N_CHANNELS> * BW_RESTRICT y0);

void reset(
const float * x0,
float *       y0 = nullptr);

void reset(
std::array<float, N_CHANNELS>               x0,
std::array<float, N_CHANNELS> * BW_RESTRICT y0 = nullptr);

void process(
const float * const * x,
float * const *       y,
size_t                nSamples);

void process(
std::array<const float *, N_CHANNELS> x,
std::array<float *, N_CHANNELS>       y,
size_t                                nSamples);

void setDistortion(
float value);

void setTone(
float value);

void setVolume(
float value);
...
}
``````

### ChangeLog

• Version 1.0.0:
• Adjusted internal peak cutoff to more sensible value.
• Added initial input value to `bw_dist_reset_state()`.
• Added `bw_dist_reset_state_multi()` and updated C++ API in this regard.
• Now `bw_dist_reset_state()` returns the initial output value.
• Added overloaded C++ `reset()` functions taking arrays as arguments.
• `bw_dist_process()` and `bw_dist_process_multi()` now use `size_t` to count samples and channels.
• Added more `const` and `BW_RESTRICT` specifiers to input arguments and implementation.
• Moved C++ code to C header.
• Added overloaded C++ `process()` function taking C-style arrays as arguments.
• Removed usage of reserved identifiers.
• Clearly specified parameter validity ranges.
{"ft_lang_label":"__label__en","ft_lang_prob":0.6565795,"math_prob":0.9644075,"size":5368,"snap":"2023-40-2023-50","text_gpt3_token_len":1302,"char_repetition_ratio":0.21140939,"word_repetition_ratio":0.2989418,"special_character_ratio":0.24012667,"punctuation_ratio":0.16818182,"nsfw_num_words":0,"has_unicode_error":false,"math_prob_llama3":0.99358237,"pos_list":[0],"im_url_duplicate_count":[null],"WARC_HEADER":"{\"WARC-Type\":\"response\",\"WARC-Date\":\"2023-10-02T07:11:31Z\",\"WARC-Record-ID\":\"<urn:uuid:fedf930a-efdc-4b7a-8cd3-594e5d16ee7e>\",\"Content-Length\":\"21515\",\"Content-Type\":\"application/http; msgtype=response\",\"WARC-Warcinfo-ID\":\"<urn:uuid:f8b0a5ee-badb-4f08-adc9-a97a34c90ac6>\",\"WARC-Concurrent-To\":\"<urn:uuid:f127ded1-73b3-48d6-b54a-7a2b5d4c8c81>\",\"WARC-IP-Address\":\"93.95.221.124\",\"WARC-Target-URI\":\"https://www.orastron.com/brickworks/bw_dist\",\"WARC-Payload-Digest\":\"sha1:YDOSK3TAF5VQTJJVKBKM7ZMSMT6NKOZM\",\"WARC-Block-Digest\":\"sha1:S35R35PIDVCK3EZGA7XBAJISVMRKHJ5Z\",\"WARC-Identified-Payload-Type\":\"text/html\",\"warc_filename\":\"/cc_download/warc_2023/CC-MAIN-2023-40/CC-MAIN-2023-40_segments_1695233510983.45_warc_CC-MAIN-20231002064957-20231002094957-00849.warc.gz\"}"}