pan.hpp

Go to the documentation of this file.

// sbl/dsp/comp/pan.hpp — Stereo pan composition with smoothing
//
// Places a mono signal in the stereo field using constant-power panning.
// Smoothed per-sample to avoid clicks/zipper noise on position changes.
//
// Domain: Stereo placement — maps a mono signal to a position in the L/R field.
// See docs/design-philosophy.md for the domain manipulation framework.
//
// Usage:
//   sbl::dsp::comp::Pan pan;
//   pan.set_position_su(0.75f);                    // 75% right
//   pan.process(mono_in, left_out, right_out, n);  // mono → stereo
//
//   // Or scale an existing stereo pair in-place:
//   pan.process(left_buf, right_buf, n);
 
#ifndef SBL_DSP_COMP_PAN_HPP_
#define SBL_DSP_COMP_PAN_HPP_
 
#include <cstdint>
#include <sbl/dsp/primitives/parameter_smoother.hpp>
#include <sbl/dsp/math/stereo.hpp>
#include <sbl/dsp/types/fixed.hpp>
 
namespace sbl::dsp::comp {
 
class Pan {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    Pan() {
        smoother_.set_time_ms(15.0f, sbl::dsp::types::SAMPLE_RATE_F);
        smoother_.reset(0.5f);
    }
 
    /**
     * @brief Set pan position. Port — accepts normalized [0,1] signal.
     *
     * 0.0 = hard left, 0.5 = center, 1.0 = hard right.
     * Input is clamped to [0,1]. Smoothing is applied per-sample in process().
     *
     * @param su Pan position in normalized units
     */
    void set_position_su(float su) {
        if (su < 0.0f) su = 0.0f;
        if (su > 1.0f) su = 1.0f;
        target_ = su;
    }
 
    /**
     * @brief Apply panning to a mono input, writing to stereo output buffers.
     *
     * Output buffers are overwritten (= semantics, not +=).
     * For accumulating multiple sources, use sbl::dsp::stereo::pan_mix().
     *
     * @param in    Mono input buffer
     * @param out_l Left output buffer (overwritten)
     * @param out_r Right output buffer (overwritten)
     * @param n     Number of samples
     */
    void process(const float* in, float* out_l, float* out_r, uint16_t n) {
        for (uint16_t i = 0; i < n; ++i) {
            float pos = smoother_.process(target_);
            auto gain = sbl::dsp::stereo::constant_power(pos);
            out_l[i] = in[i] * gain.left;
            out_r[i] = in[i] * gain.right;
        }
    }
 
    /**
     * @brief Apply panning in-place to a stereo pair (scales existing L/R).
     *
     * Multiplies existing left samples by the left pan gain and right samples
     * by the right pan gain. Useful for adjusting stereo balance of an
     * already-stereo signal.
     *
     * @param buf_l Left buffer (modified in-place)
     * @param buf_r Right buffer (modified in-place)
     * @param n     Number of samples
     */
    void process(float* buf_l, float* buf_r, uint16_t n) {
        for (uint16_t i = 0; i < n; ++i) {
            float pos = smoother_.process(target_);
            auto gain = sbl::dsp::stereo::constant_power(pos);
            buf_l[i] *= gain.left;
            buf_r[i] *= gain.right;
        }
    }
 
    /**
     * @brief Current smoothed position [0,1]
     * @return The smoother's current value, not the target
     */
    float position() const { return smoother_.value(); }
 
    /** @brief Reset smoother to center (0.5) */
    void reset() {
        target_ = 0.5f;
        smoother_.reset(0.5f);
    }
 
    /** @brief Reset smoother to a specific position */
    void reset(float position) {
        if (position < 0.0f) position = 0.0f;
        if (position > 1.0f) position = 1.0f;
        target_ = position;
        smoother_.reset(position);
    }
 
private:
    float target_ = 0.5f;
    sbl::dsp::primitives::ParameterSmoother smoother_;
};
 
} // namespace sbl::dsp::comp
 
#endif // SBL_DSP_COMP_PAN_HPP_