Brickworks > API documentation

Brickworks API

Brickworks is a music DSP toolkit that offers a solid foundation for creating and enhancing audio engines on any platform.

This documentation contains technical information on using the Brickworks API. You can find background information on what Brickworks actually is on its official web page.

Technical background

Brickworks is written in plain C99 and only requires:

• definitions of NULL, INFINITY, and (U)INT{8,16,32,64}_{MIN/MAX};
• size_t and (u)int{8,16,32,64}_t types;
• IEEE 754 32-bit single-precision float type.

The API user is given some flexibility in supplying such definitions (see bw_config and bw_common).

The code is organized in separate modules which are as independent as possible but still may require (i.e., depend on) other modules. Each module consists of an header file having filename module.h.

Brickworks is not meant to be built and used as a static or shared library. You should rather just use the needed module files to develop your software (more below).

Both individual modules and the whole library are versioned according to the Semantic Versioning Specification 2.0.0. It follows that the library version will be equal to the version of the last modified module, while modules that were not modified will be tagged with a previous version number. Module dependencies are considered part of the API, therefore if a dependency is removed that would lead to MINOR version change, and if one is added that would cause a MAJOR version change.

Unless otherwise stated, the C API follows the following conventions:

• all functions are reentrant, RT-safe, NOT thread-safe, and have no side effects;
• all pointers as function arguments are required NOT to be NULL;
• when calling a processing function:
  • the same buffer pointer MAY be used for any number of input buffer arguments;
  • the same buffer pointer MAY be used for both an input and output buffer argument;
  • different buffer pointers MUST NEVER point to overlapping memory areas;
  • the same buffer pointer MUST NOT be used for more than one output buffer argument.

Conventions for C++ wrappers will be added when they are released.

Getting started

To be written, topics:

• usage
• build systems
• setting up examples
• tutorials
• ...

Modules

Foundation

These modules are required by most, if not all, other modules and just contain a few basic essential definitions. They provide a certain degree of consistency and adaptability to the rest of the code.

You can also directly use them to create your own modules, if you want.

List

• bw_config: Header file to allow overriding default definitions.
• bw_common: Basic common definitions.

Utility

Utility modules contain heterogeneous code that is repeatedly used by applications and other modules.

List

• bw_buf: Common operations on buffers.
• bw_math: Fast mathematical routines.
• bw_rand: Pseudo-random number generators.

DSP

These modules implement signal processing blocks (not necessarily audio-related).

Their APIs are not 100% uniform, but they tend to follow a common pattern described here.

Each signal processing block conceptually consists of:

• a number of signal inputs and outputs;
• a number of input and output parameters;
• a set of coefficients (derived from input parameters);
• its internal state;
• functions to make it work.

Signal inputs and outputs are not explicitly represented by any data structure, but you rather see them as arguments or return values of processing functions. Signal data is PCM-encoded as (buffers of) 32-bit floating point numbers, with values typically between -1.f and 1.f (these correspond to the 0 dBFS clipping points — lying within this range is not a strict requirement), and uniformly-sampled at a user-supplied sample rate, which is common to all signal inputs and outputs of a block instance. Signals that vary at such sample rate are also known as audio rate signals.

Parameters, on the other hand, can have different types and ranges and are asynchronously updated at a variable rate, also known as control rate, that is lower than the sample rate. You can set input parameter values and get output parameter values using specific functions. As long as input parameter values are valid and set properly, you can expect to freely change them without incurring in glitches or other artifacts.

Coefficients are calculated and kept up to date by various functions at control and/or audio rate on the basis of input parameter values. As an API user you don't directly interact with them. They are stored together with input parameter values and output parameter values that do not depend on state into a common data structure which can be either specific to one block instance or shared by more instances (in which case those instances act like they have all the same parameter settings). In the former case you can use buffer-based processing functions, which also take care of updating coefficients, otherwise you are forced to use sample-based processing functions and explicitly trigger control-rate and audio-rate coefficient updates.

As coefficients and output parameter values may be subject to smoothing or other dynamic updating patterns, their values may evolve over time even if input parameter values are constant from a certain moment on. However, they are required to converge towards fixed values given constant input parameter values and sample rate. This can be exploited by the API user to, e.g., completely avoid triggering updates when input parameter values are constant from the start, by invoking functions that force coefficients to assume their target values.

Each block instance is also uniquely characterized by a data structure containing its internal state and output parameter values that depend on state, whose contents are not normally accessible to API users. Such internal state and output parameter values are updated at audio rate by processing functions and can be reset by the API user to a set of initial values, which can depend on input parameter values, coefficient values, and sample rate, via specific functions.

Some modules require the API user to provide a chunk of contiguous memory to be used as part of the internal state of an instance. This arrangement avoids the need to directly rely on dynamic memory allocation and puts the burdens and the honours of managing memory in the hands of the API user. The size of the required memory chunk is typically dependent on the sample rate and eventual initialization-time variables. Functions are provided to retrieve the required memory chunk size and to associate a memory chunk to a given instance.

In each module you may find:

• the definition of the struct containing parameters and coefficients, typedefed as bw_module_coeffs;
• the definition of the struct containing the internal state, typedefed as bw_module_state;
• an initialization function, named bw_module_init(), which:
  • resets input parameters to their default values;
  • may take initialization-time variables as input arguments;
  • invalidates memory chunk sizes, current coefficient values, and the internal state(s) used in conjunction with them;
• a function to set the sample rate, named bw_module_set_sample_rate(), which:
  • MUST NOT be called before bw_module_init();
  • invalidates current coefficient values and the internal state(s) used in conjunction with them;
  • makes memory chunk sizes valid;
• a function to retrieve the size of the required memory chunk, named bw_module_mem_req(), which:
  • MUST NOT be called when memory chunk sizes are invalidated;
• a function to associate a memory chunk to a given instance, named bw_module_mem_set();
• a function to reset coefficients and force them to assume their target values, named bw_module_reset_coeffs(), which:
  • MUST NOT be called before bw_module_set_sample_rate();
  • makes current coefficient values valid;
• a function to reset the internal state to its initial values, named bw_module_reset_state(), which:
  • MUST NOT be called when coefficient values are invalidated or a memory chunk of the required size is not associated to the internal state;
  • makes internal state valid;
• a function that triggers control-rate coefficient update, named bw_module_update_coeffs_ctrl(), which:
  • MUST NOT be called when coefficient values are invalidated;
• a function that triggers audio-rate coefficient update, named bw_module_update_coeffs_audio(), which:
  • MUST NOT be called when coefficient values are invalidated;
• a function that triggers control-rate internal state update, named bw_module_update_state_ctrl(), which:
  • MUST NOT be called when coefficient values or internal state are invalidated;
• one or more functions that process one sample of each input and output signal and updates internal state and output parameter values (audio rate), named bw_module_process1*(), which:
  • MUST NOT be called when coefficient values or internal state are invalidated;
• a function that processes a buffer of each input output signal and updates coefficients, internal state, and output parameter values (control and audio rate), named bw_module_process(), which:
  • MUST NOT be called when coefficient values or internal state are invalidated;
• a number of functions to set input parameter values, named bw_module_set_parameter();
• a number of functions to get output parameter values, named bw_module_get_parameter(), which:
  • MUST NOT be called when coefficient values or internal state are invalidated.

Before bw_module_init() is called all parameters, coefficients, and states are considered invalid.

Any varations to the pattern above are indicated in the individual module's documentation.

List

• bw_ap1: First-order allpass filter.
• bw_ap2: Second-order allpass filter.
• bw_balance: Stereo balance.
• bw_bd_reduce: Bit depth reducer.
• bw_chorus: Chorus / vibrato / flanger.
• bw_comb: Comb filter / delay.
• bw_comp: Feedforward compressor/limiter.
• bw_delay: Interpolated delay line.
• bw_env_follow: Enevelope follower.
• bw_env_gen: Enevelope generator.
• bw_gain: Gain.
• bw_hp1: First-order highpass filter.
• bw_hs1: First-order high shelf filter.
• bw_hs2: Second-order high shelf filter.
• bw_lp1: First-order lowpass filter.
• bw_ls1: First-order low shelf filter.
• bw_ls2: Second-order low shelf filter.
• bw_mm1: First-order multimode filter.
• bw_mm2: Second-order multimode filter.
• bw_noise_gate: Noise gate.
• bw_noise_gen: White noise generator.
• bw_notch: Second-order notch filter.
• bw_one_pole: One-pole lowpass filter.
• bw_osc_filt: Post-filter to decolorate oscillator waveshapers.
• bw_osc_pulse: Pulse oscillator waveshaper.
• bw_osc_saw: Sawtooth oscillator waveshaper.
• bw_osc_sin: Sinusoidal oscillator waveshaper.
• bw_osc_tri: Triangle oscillator waveshaper.
• bw_pan: Stereo panner.
• bw_peak: Second-order peak filter.
• bw_phase_gen: Phase generator.
• bw_phaser: Phaser.
• bw_pink_filt: Pinking filter.
• bw_ppm: Digital peak programme meter.
• bw_ringmod: Ring modulator.
• bw_satur: Waveshaper saturation.
• bw_slew_lim: Slew-rate limiter.
• bw_sr_reduce: Sample rate reducer.
• bw_src: Arbitrary-ratio sample rate converter.
• bw_src_int: Integer-ratio sample rate converter.
• bw_svf: State variable filter.
• bw_trem: Tremolo.
• bw_wah: Wah effect.

Glossary

Definitions in this glossary are not meant to be general but only valid in the context of using the Brickworks API.

No side effects

A function has no side effects if it does not affect any external state (except data referenced by arguments).

Reentrant function

A function that does not read external variable data (beyond input data).

RT-safe function

A function that has finite and deterministic execution time (e.g., it doesn't block or loop undefinitely), with at worst linear time complexity w.r.t. input data.

Thread-safe function

A function that is safe to use concurrently by multiple threads operating on the same input and external data.