stereo.hpp

Go to the documentation of this file.

// sbl/dsp/stereo.hpp — Stereo panning and mixing (Audio Stack — Atoms)
//
// Constant-power panning and stereo accumulation for float audio pipelines.
// All functions are ISR-safe with bounded computation.
//
// Usage:
//   // Precompute pan gains (init-time)
//   auto pan_l = sbl::dsp::stereo::constant_power(0.25f);  // slightly left
//   auto pan_c = sbl::dsp::stereo::constant_power(0.5f);   // center
//   auto pan_r = sbl::dsp::stereo::constant_power(0.75f);  // slightly right
//
//   // In audio callback: mix voices into stereo field
//   float left[48] = {}, right[48] = {};
//   sbl::dsp::stereo::pan_mix(voice1, left, right, pan_l, frames);
//   sbl::dsp::stereo::pan_mix(voice2, left, right, pan_c, frames);
//   sbl::dsp::stereo::pan_mix(voice3, left, right, pan_r, frames);
//
//   // DMA interleave/deinterleave: see dsp/convert.hpp
 
#ifndef SBL_DSP_MATH_STEREO_HPP_
#define SBL_DSP_MATH_STEREO_HPP_
 
#include <cstdint>
#include <cmath>
 
namespace sbl::dsp::stereo {
 
/**
 * @brief Stereo pan gains (float)
 *
 * Gains are 0.0–1.0 where 0 = silence and 1.0 = unity.
 * Computed via constant-power pan law: L^2 + R^2 = 1.
 */
struct PanGain {
    float left;
    float right;
};
 
/**
 * @brief Compute constant-power pan gains (-3 dB at center)
 *
 * Uses sqrt-based constant-power pan law:
 *   L = sqrt(1 - p), R = sqrt(p)
 *
 * This ensures L^2 + R^2 = 1 for any position, maintaining
 * constant power across the stereo field.
 *
 * @param position Pan position: 0.0 = hard left, 0.5 = center, 1.0 = hard right
 * @return PanGain with left and right gains [0.0, 1.0]
 *
 * @note Uses sqrtf internally. Intended for init-time precomputation,
 *       not per-sample use. On Cortex-M7 with FPU, cost is ~10 cycles.
 */
inline PanGain constant_power(float position) {
    float p = position;
    if (p < 0.0f) p = 0.0f;
    if (p > 1.0f) p = 1.0f;
    return {
        sqrtf(1.0f - p),
        sqrtf(p),
    };
}
 
/**
 * @brief Apply pan gains to a mono buffer and accumulate into stereo buffers
 *
 * Multiplies each mono sample by the left and right gains, and ADDS
 * the result to the left[] and right[] buffers. Caller must zero the
 * stereo buffers before the first call when mixing multiple sources.
 *
 * @param mono   Input mono buffer (read-only)
 * @param left   Left output buffer (accumulated, += semantics)
 * @param right  Right output buffer (accumulated, += semantics)
 * @param gain   Precomputed pan gains from constant_power()
 * @param frames Number of samples
 *
 * @note ISR-safe — bounded computation, no I/O
 */
inline void pan_mix(const float* mono, float* left, float* right,
                    PanGain gain, uint16_t frames) {
    for (uint16_t i = 0; i < frames; ++i) {
        left[i]  += mono[i] * gain.left;
        right[i] += mono[i] * gain.right;
    }
}
 
} // namespace sbl::dsp::stereo
 
#endif // SBL_DSP_MATH_STEREO_HPP_