frame.hpp

Go to the documentation of this file.

// sbl/signal/frame.hpp — Stereo buffer management (Signal layer)
//
// Manages the stereo float buffer pair that every audio callback needs.
// Eliminates manual buffer declaration, zeroing, gain staging, and DMA
// interleave boilerplate.
//
// Frame is the workhorse of the Signal layer — the connective tissue
// between widgets in a processing chain. Every method is a trivial loop
// that the compiler will vectorize. Zero abstraction cost.
//
// Part of the Audio Stack: Atoms → Signal → Widgets
// See FDP-031 for architecture rationale.
//
// Usage:
//   sbl::signal::Frame<48> frame;
//
//   void audio_callback(int32_t* tx, const int32_t* rx, uint16_t frames) {
//       uint16_t n = frame.begin(frames);
//
//       osc.process(frame.left, n);            // source → left channel
//       filter.process(frame.left, n);         // in-place filter
//       env.process(env_buf, n);
//       frame.apply(env_buf, n);               // VCA: L *= env, R *= env
//       frame.mix_mono(bass_buf, 0.5f, n);     // mix bass at -6 dB
//       delay.process(frame.left, frame.right, n);
//
//       frame.end(tx, n);                      // float → int32 stereo DMA
//   }
 
#pragma once
 
#include <cstdint>
 
#include <sbl/dsp/convert.hpp>
 
namespace sbl::signal {
 
template<uint16_t MaxFrames = 48>
struct Frame {
    float left[MaxFrames];
    float right[MaxFrames];
 
    /// Begin a processing block: clamp frame count and zero buffers.
    ///
    /// Call this at the top of every audio callback. Returns the actual
    /// frame count to use (clamped to MaxFrames).
    ///
    /// @param requested Frame count from DMA callback
    /// @return Actual frame count (min of requested and MaxFrames)
    uint16_t begin(uint16_t requested) {
        uint16_t n = (requested > MaxFrames) ? MaxFrames : requested;
        for (uint16_t i = 0; i < n; ++i) {
            left[i]  = 0.0f;
            right[i] = 0.0f;
        }
        return n;
    }
 
    /// Finalize block: float → int32 stereo interleave to DMA tx buffer.
    ///
    /// This is the DMA boundary — NaN guard, clamp to [-1.0, 1.0], and
    /// 24-bit scaling all happen inside interleave_from_float().
    ///
    /// @param tx DMA transmit buffer (interleaved stereo int32)
    /// @param n Frame count
    void end(int32_t* tx, uint16_t n) const {
        dsp::interleave_from_float(left, right, tx, n);
    }
 
    /// Scale both channels by a constant gain.
    ///
    /// Use for headroom management (e.g., 1/sqrt(N) for N summed voices).
    ///
    /// @param gain Gain factor
    /// @param n Frame count
    void scale(float gain, uint16_t n) {
        for (uint16_t i = 0; i < n; ++i) {
            left[i]  *= gain;
            right[i] *= gain;
        }
    }
 
    /// Apply per-sample modulation to both channels (stereo VCA).
    ///
    /// Multiplies both L and R by a control signal — typically an
    /// envelope output [0.0, 1.0].
    ///
    /// @param mod Control signal buffer (e.g., envelope output)
    /// @param n Frame count
    void apply(const float* mod, uint16_t n) {
        for (uint16_t i = 0; i < n; ++i) {
            left[i]  *= mod[i];
            right[i] *= mod[i];
        }
    }
 
    /// Mix a mono source into both channels at a given gain.
    ///
    /// Adds src * gain to both L and R. Use for mixing a mono sub-voice
    /// into a stereo frame (e.g., bass at -6 dB = gain 0.5).
    ///
    /// @param src Mono source buffer
    /// @param gain Mix gain (e.g., 0.5 for -6 dB)
    /// @param n Frame count
    void mix_mono(const float* src, float gain, uint16_t n) {
        for (uint16_t i = 0; i < n; ++i) {
            float s = src[i] * gain;
            left[i]  += s;
            right[i] += s;
        }
    }
 
    /// Mix another stereo frame into this one at a given gain.
    ///
    /// @param other Source frame
    /// @param gain Mix gain
    /// @param n Frame count
    void mix(const Frame& other, float gain, uint16_t n) {
        for (uint16_t i = 0; i < n; ++i) {
            left[i]  += other.left[i]  * gain;
            right[i] += other.right[i] * gain;
        }
    }
 
    /// Mix separate stereo buffers into this frame at a given gain.
    ///
    /// @param src_l Left source buffer
    /// @param src_r Right source buffer
    /// @param gain Mix gain
    /// @param n Frame count
    void mix_stereo(const float* src_l, const float* src_r, float gain,
                    uint16_t n) {
        for (uint16_t i = 0; i < n; ++i) {
            left[i]  += src_l[i] * gain;
            right[i] += src_r[i] * gain;
        }
    }
 
    /// Snapshot current buffer state into separate L/R buffers.
    ///
    /// Use for explicit feedback paths: tap the signal before effects,
    /// then mix the tapped (and possibly processed) signal back in on
    /// the next block.
    ///
    /// @param dst_l Destination left buffer
    /// @param dst_r Destination right buffer
    /// @param n Frame count
    void tap(float* dst_l, float* dst_r, uint16_t n) const {
        for (uint16_t i = 0; i < n; ++i) {
            dst_l[i] = left[i];
            dst_r[i] = right[i];
        }
    }
 
    /// Zero both channels.
    ///
    /// @param n Frame count
    void clear(uint16_t n) {
        for (uint16_t i = 0; i < n; ++i) {
            left[i]  = 0.0f;
            right[i] = 0.0f;
        }
    }
};
 
} // namespace sbl::signal