bow.hpp

Go to the documentation of this file.

// sbl/dsp/pm/bow.hpp — A bow: a speed, a weight, and a friction law at a string's junction (Physical modeling — composition)
//
// The exciter a bowed string is played with. It owns what a bow owns — how
// fast it travels and how hard it presses, both ports, smoothed here — and a
// friction law (TableFriction, ThermalFriction, HybridFriction, or a set of
// tables) that turns the relative velocity at the junction into a force. The
// string knows none of that: it hands the bow the junction's state and gets a
// force back (contracts.hpp, Exciter).
//
// Pressure zero is no contact: nothing rests on the string, so no force at
// all — not the lightest row of the table (physical-modeling.md §3.5). The
// lightest bow is the smallest pressure above zero.
//
// A bow does work on the string and has no passivity proof (RPT-029 Part 4
// rule 6), so its force passes a SoftLimiter here, at the source. The law
// speaks in wave units, F / 2Z; the bow returns a force, 2Z times that, and
// the guide takes the wave back out with its own Z.
 
#ifndef SBL_DSP_PM_BOW_HPP_
#define SBL_DSP_PM_BOW_HPP_
 
#include <cstdint>
 
#include <sbl/dsp/diagram/graph.hpp>
#include <sbl/dsp/math/clamp.hpp>
#include <sbl/dsp/pm/contracts.hpp>
#include <sbl/dsp/primitives/smoothed_port.hpp>
#include <sbl/dsp/primitives/soft_limiter.hpp>
#include <sbl/dsp/types/fixed.hpp>
 
namespace sbl::dsp::pm {
 
template<typename Law>
class Bow {
    static_assert(is_friction_law_v<Law>, "a Bow runs a friction law (physical-modeling.md §4.5)");
 
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    static constexpr float DEFAULT_VELOCITY_SU = 0.5f;
    static constexpr float DEFAULT_PRESSURE_SU = 0.5f;
    static constexpr float MAX_VELOCITY = 0.5f;    ///< wave units at full speed
    static constexpr float SMOOTH_MS = 20.0f;
    /// Below this the bow is off the string. A smoothed port only approaches
    /// zero, so "no pressure" has to be a threshold; the lightest bow is this.
    static constexpr float MIN_PRESSURE_SU = 0.001f;
 
    Bow() {
        velocity_.set(DEFAULT_VELOCITY_SU);
        pressure_port_.set(DEFAULT_PRESSURE_SU);
        reset();
    }
 
    /// The law, for its own parameters (a table, a rosin).
    Law& law() { return law_; }
    const Law& law() const { return law_; }
 
    // ─── Ports ───────────────────────────────────────────────────────
 
    /// How fast the bow travels across the string. Smoothed.
    void set_velocity_su(float su) { velocity_.set(math::clamp01(su)); }
 
    /// How hard it presses: which force slice the law reads. Zero is no contact. Smoothed.
    void set_pressure_su(float su) { pressure_port_.set(math::clamp01(su)); }
 
    // ─── Exciter ─────────────────────────────────────────────────────
 
    /// A block's worth of port movement.
    void advance(uint16_t n) {
        v_bow_ = velocity_.advance(n) * MAX_VELOCITY;
        pressure_ = pressure_port_.advance(n);
        if (pressure_ < MIN_PRESSURE_SU) pressure_ = 0.0f;   // lifted
        law_.set_force_su(pressure_);
    }
 
    /// One sample: the force on the string for the junction's state.
    float excite(const JunctionState& j) {
        if (pressure_ <= 0.0f) return last_force_ = 0.0f;   // nothing rests on the string
        const float wave = primitives::SoftLimiter::limit(law_.process(v_bow_ - j.velocity));
        last_force_ = wave;
        return TWO * j.impedance * wave;
    }
 
    /// A bow stores nothing: it only does work on the string.
    float energy() const { return 0.0f; }
 
    void reset() {
        for (primitives::SmoothedPort* port : {&velocity_, &pressure_port_}) {
            port->set_time_ms(SMOOTH_MS, types::SAMPLE_RATE_F);
            port->reset();
        }
        v_bow_ = velocity_.value() * MAX_VELOCITY;
        pressure_ = pressure_port_.value() < MIN_PRESSURE_SU ? 0.0f : pressure_port_.value();
        law_.set_force_su(pressure_);
        law_.reset();
        last_force_ = 0.0f;
    }
 
    // ─── For a scope ─────────────────────────────────────────────────
 
    /// True while the bow holds the string (with weight on it).
    bool sticking() const { return pressure_ > 0.0f && law_.sticking(); }
    /// The static limit the bow holds the string with right now, in wave units.
    float limit() const { return law_.limit(); }
    /// The force injected on the last sample, in wave units.
    float force() const { return last_force_; }
 
    /// The velocity source into the friction junction. Never called from audio code.
    diagram::Ports describe(diagram::Graph& g, uint8_t group, const char* name = "bow") const {
        const uint8_t source = g.add_node(diagram::Kind::Source, "bow velocity", group);
        diagram::Ports p = law_.describe(g, group, name);
        g.add_edge(source, p.in, diagram::Wave::Velocity);
        return p;
    }
 
private:
    static constexpr float TWO = 2.0f;
 
    Law law_;
    primitives::SmoothedPort velocity_;
    primitives::SmoothedPort pressure_port_;
    float v_bow_ = 0.0f;
    float pressure_ = DEFAULT_PRESSURE_SU;
    float last_force_ = 0.0f;
};
 
} // namespace sbl::dsp::pm
 
#endif // SBL_DSP_PM_BOW_HPP_