Class thl::dsp::utils::Mixer#

class Mixer#

Mixes num_inputs() buffer views into one, each input scaled by a gain g from its weight w.

In Mode::Sum the gains are the weights: g = w. In Mode::Mix the weights are normalised to their p-norm, g = w / (sum of w^p)^(1/p), so the gains always have a p-norm of 1: only the ratios of the weights matter, and p sets what the mix keeps constant. k_amplitude suits correlated inputs, k_power uncorrelated ones, and k_peak keeps the largest weight’s gain at 1. All weights 0 give silence.

Weights, p and the mode glide over the ramp time given to prepare(). In Mode::Mix the gains are normalised after the glide, so the mix keeps its level while it glides. A change of mode crossfades from the gains of one mode to those of the other.

Real-Time Safety

Everything but prepare() is real-time safe: no allocation, no locks. prepare() allocates.

Threads

Not thread-safe: one thread at a time calls every member (e.g. the audio thread, with the settings handed to it through atomics).

Public Types

enum class Mode : uint8_t#

How the weights become gains.

Values:

enumerator Sum#

the gains are the weights

enumerator Mix#

the weights normalised to their p-norm: only their ratios matter

Public Functions

void prepare(double sample_rate, size_t num_inputs, double ramp_seconds = 0.02)#

Room for num_inputs inputs.

Inputs it already had keep their weights, new ones get weight 1; every glide ends at its target. A ramp_seconds shorter than one sample (0 included) glides over one sample.

inline size_t num_inputs() const#

The number of inputs prepare() made room for.

void set_mode(Mode mode)#

Glides from the gains of the current mode to those of mode.

inline Mode get_mode() const#

The mode set last (the target of a glide).

void set_p(float p)#

The p of the norm in Mode::Mix, clamped to [1, infinity]; glides. NaN is ignored.

inline float get_p() const#

The p set last (the target of a glide).

void set_weight(size_t input, float weight)#

The target weight of input input, clamped to 0 or more; glides.

A non-finite weight is ignored.

void set_weights(std::span<const float> weights)#

The target weights of inputs 0 to weights.size() - 1, as set_weight(); the others keep theirs.

float get_weight(size_t input) const#

The target weight of input input (< num_inputs()).

void reset()#

Ends every glide at its target.

bool passes_only(size_t input) const#

The mix is input input unchanged: it passes at gain 1, the others at 0, and nothing glides that could change that (a glide of p, or of the mode where the gain is 1 in both, changes nothing).

A caller may then skip process(); a glide it skips resumes where it was when process() runs again.

void process(std::span<const thl::core::ConstBufferView> inputs, thl::core::BufferView output)#

Writes the mix of inputs (one per input, each with the channels and samples of output) into output.

output may be one of inputs, but must not overlap any other way.

Public Static Attributes

static constexpr float k_amplitude = 1.0f#

p for correlated inputs: the gains sum to 1, the amplitude stays.

static constexpr float k_compromise = 4.0f / 3.0f#

p between amplitude and power: -4.5 dB each for two equal weights, for partly correlated inputs.

static constexpr float k_power = 2.0f#

p for uncorrelated inputs: the squares of the gains sum to 1, the power stays.

static constexpr float k_peak = std::numeric_limits<float>::infinity()#

p = infinity: the largest weight’s gain is 1, the others keep their ratio to it.