bow_set.hpp

Go to the documentation of this file.

// sbl/dsp/pm/bow_set.hpp — Several table laws behind one select, and the bow that plays them (Physical modeling — composition)
//
// TableSet is a friction law: a set of BowTables and a select position across
// them. Two TableFrictions run — the one the select sits on and the next —
// and the force is the crossfade between them. Both run every sample so the
// one fading in carries current stick/slip state rather than a stale one.
// With one table the set is that law and nothing is crossfaded.
//
// BowSet is a Bow over a TableSet with the select as a third port, smoothed
// like the other two.
 
#ifndef SBL_DSP_PM_BOW_SET_HPP_
#define SBL_DSP_PM_BOW_SET_HPP_
 
#include <cstdint>
 
#include <sbl/dsp/diagram/graph.hpp>
#include <sbl/dsp/math/clamp.hpp>
#include <sbl/dsp/pm/bow.hpp>
#include <sbl/dsp/pm/contracts.hpp>
#include <sbl/dsp/pm/table_friction.hpp>
 
namespace sbl::dsp::pm {
 
class TableSet {
public:
    /// @note All public methods are ISR-safe — bounded computation, no I/O.
 
    static constexpr uint8_t MAX_TABLES = 8;
 
    /// The tables, in the order the select sweeps them. The array must outlive the set.
    void set_tables(const BowTable* tables, uint8_t count) {
        tables_ = tables;
        count_ = count > MAX_TABLES ? MAX_TABLES : count;
        a_index_ = NO_TABLE;
        b_index_ = NO_TABLE;
        apply_select(select_su_);
    }
 
    uint8_t count() const { return count_; }
    const BowTable* tables() const { return tables_; }
 
    /// Which table: 0 the first, 1 the last, a crossfade between neighbours. Applied at once.
    void set_select_su(float su) {
        select_su_ = math::clamp01(su);
        apply_select(select_su_);
    }
 
    void set_force_su(float su) {
        a_.set_force_su(su);
        b_.set_force_su(su);
    }
 
    /// One sample: relative velocity in, the crossfaded force out (wave units).
    float process(float dv_free) {
        if (count_ == 0) return 0.0f;
        float force = a_.process(dv_free);
        if (count_ > 1) {
            const float other = b_.process(dv_free);
            force += blend_ * (other - force);
        }
        return force;
    }
 
    /// The table you hear — the one with the larger crossfade weight — holds the string.
    bool sticking() const { return blend_ > HALF_BLEND ? b_.sticking() : a_.sticking(); }
    float limit() const { return blend_ > HALF_BLEND ? b_.limit() : a_.limit(); }
 
    void reset() {
        a_.reset();
        b_.reset();
    }
 
    /// One junction per running table. `in`/`out` is the first; the second is the named port "table B".
    diagram::Ports describe(diagram::Graph& g, uint8_t group, const char* name = "friction") const {
        diagram::Ports p = a_.describe(g, group, count_ > 1 ? "friction A" : name);
        if (count_ > 1) {
            const diagram::Ports other = b_.describe(g, group, "friction B");
            p.add("table B", other.in);
        }
        return p;
    }
 
private:
    static constexpr float HALF_BLEND = 0.5f;
    static constexpr uint8_t NO_TABLE = 0xFF;
 
    void apply_select(float select_su) {
        if (tables_ == nullptr || count_ == 0) return;
 
        const float pos = select_su * static_cast<float>(count_ - 1);
        uint8_t a = static_cast<uint8_t>(pos);
        if (count_ > 1 && a >= count_ - 1) a = static_cast<uint8_t>(count_ - 2);
        blend_ = count_ > 1 ? pos - static_cast<float>(a) : 0.0f;
 
        // A law that changes table is at the far end of the crossfade, so its
        // stick state is inaudible; starting it stuck is the clean state.
        if (a != a_index_) {
            a_.set_bow(tables_[a]);
            a_.reset();
            a_index_ = a;
        }
        const uint8_t b = count_ > 1 ? static_cast<uint8_t>(a + 1) : a;
        if (b != b_index_) {
            b_.set_bow(tables_[b]);
            b_.reset();
            b_index_ = b;
        }
    }
 
    TableFriction a_;
    TableFriction b_;
    const BowTable* tables_ = nullptr;
    uint8_t count_ = 0;
    uint8_t a_index_ = NO_TABLE;
    uint8_t b_index_ = NO_TABLE;
    float select_su_ = 0.0f;
    float blend_ = 0.0f;
};
 
static_assert(is_friction_law_v<TableSet>, "TableSet is a friction law (physical-modeling.md §4.5)");
 
/// A bow over a set of tables: velocity, pressure and select, all smoothed.
class BowSet : public Bow<TableSet> {
public:
    static constexpr float DEFAULT_SELECT_SU = 0.0f;
 
    BowSet() {
        select_.set(DEFAULT_SELECT_SU);
        select_.set_time_ms(SMOOTH_MS, types::SAMPLE_RATE_F);
        select_.reset();
    }
 
    /// The tables this bow can be played with (TableSet::set_tables).
    void set_tables(const BowTable* tables, uint8_t count) { law().set_tables(tables, count); }
 
    /// Which table: crossfades across the set. Smoothed.
    void set_select_su(float su) { select_.set(math::clamp01(su)); }
 
    void advance(uint16_t n) {
        law().set_select_su(select_.advance(n));
        Bow<TableSet>::advance(n);
    }
 
    void reset() {
        select_.set_time_ms(SMOOTH_MS, types::SAMPLE_RATE_F);
        select_.reset();
        law().set_select_su(select_.value());
        Bow<TableSet>::reset();
    }
 
private:
    primitives::SmoothedPort select_;
};
 
static_assert(is_exciter_v<BowSet>, "BowSet is an Exciter (physical-modeling.md §4.2)");
 
} // namespace sbl::dsp::pm
 
#endif // SBL_DSP_PM_BOW_SET_HPP_