graph.hpp

Go to the documentation of this file.

// sbl/dsp/diagram/graph.hpp — A model's wiring, as data (AP-037)
//
// Physical-modeling components describe themselves into a Graph: the nodes a
// paper's block diagram would draw — delay lines, filters, reflections,
// junctions, sources, loads, taps — and the edges between them, each carrying
// a wave variable. A widget that wired components together describes the
// connections its lambdas made, because only it knows.
//
// This is a development tool. describe() is never called from audio code, so
// on the target it is never emitted; the Graph itself is fixed-capacity POD
// with no allocation, so it can sit in the library without a host-only
// guard. Rendering (mermaid.hpp) is where formatting lives.
//
// Groups nest: a widget's group holds its compositions' groups. The renderer
// can draw every node (Depth::Full, the paper) or fold each child group into
// one box (Depth::Components).
 
#ifndef SBL_DSP_DIAGRAM_GRAPH_HPP_
#define SBL_DSP_DIAGRAM_GRAPH_HPP_
 
#include <cstdint>
 
namespace sbl::dsp::diagram {
 
/// What a node is, in the paper's vocabulary.
enum class Kind : uint8_t {
    DelayLine,    ///< value: length in samples
    Loss,         ///< value: cutoff in Hz
    Allpass,      ///< value: delay in samples
    DcBlock,      ///< value: corner in Hz
    Reflection,   ///< value: coefficient (−1 wall, +1 free end)
    Junction,     ///< where waves scatter or a source meets the string
    Source,       ///< a driving signal (bow velocity, pluck)
    Load,         ///< a lumped body; value: Hz, value2: Q
    Resonator,    ///< a modal source; value: Hz, value2: Q
    Bandpass,     ///< a banded-waveguide band; value: Hz, value2: Q
    Gain,         ///< value: the factor
    Sum,          ///< where signals add
    Tap,          ///< an output
    Component,    ///< a folded group, made by the renderer
};
 
/// What travels along an edge.
enum class Wave : uint8_t { Velocity, Force, Signal };
 
constexpr uint8_t NO_GROUP = 0xFF;
constexpr uint8_t NO_NODE = 0xFF;
 
struct Node {
    Kind kind;
    const char* name;   ///< short label; string literals only, the graph does not own it
    float value;
    float value2;
    uint8_t group;
};
 
struct Edge {
    uint8_t from;
    uint8_t to;
    Wave wave;
};
 
struct Group {
    const char* name;
    uint8_t parent;
};
 
class Graph {
public:
    static constexpr uint8_t MAX_NODES = 64;    ///< a 32-mode bank and the string around it
    static constexpr uint8_t MAX_EDGES = 128;
    static constexpr uint8_t MAX_GROUPS = 16;
 
    /// Open a group (a component); returns its id. Nodes added with it belong to it.
    uint8_t add_group(const char* name, uint8_t parent = NO_GROUP) {
        if (group_count_ >= MAX_GROUPS) { dropped_ = true; return NO_GROUP; }
        groups_[group_count_] = Group{name, parent};
        return group_count_++;
    }
 
    uint8_t add_node(Kind kind, const char* name, uint8_t group,
                     float value = 0.0f, float value2 = 0.0f) {
        if (node_count_ >= MAX_NODES) { dropped_ = true; return NO_NODE; }
        nodes_[node_count_] = Node{kind, name, value, value2, group};
        return node_count_++;
    }
 
    void add_edge(uint8_t from, uint8_t to, Wave wave) {
        if (edge_count_ >= MAX_EDGES || from == NO_NODE || to == NO_NODE) { dropped_ = true; return; }
        edges_[edge_count_++] = Edge{from, to, wave};
    }
 
    uint8_t node_count() const { return node_count_; }
    uint8_t edge_count() const { return edge_count_; }
    uint8_t group_count() const { return group_count_; }
    const Node& node(uint8_t i) const { return nodes_[i]; }
    const Edge& edge(uint8_t i) const { return edges_[i]; }
    const Group& group(uint8_t i) const { return groups_[i]; }
 
    /// How many nodes of a kind the graph holds — the structural tests' question.
    uint8_t count(Kind kind) const {
        uint8_t n = 0;
        for (uint8_t i = 0; i < node_count_; ++i) {
            if (nodes_[i].kind == kind) ++n;
        }
        return n;
    }
 
    /// True if a describe() lost something: a node, edge or group was refused.
    bool overflowed() const { return dropped_; }
 
    void clear() {
        node_count_ = 0;
        edge_count_ = 0;
        group_count_ = 0;
        dropped_ = false;
    }
 
private:
    Node nodes_[MAX_NODES] = {};
    Edge edges_[MAX_EDGES] = {};
    Group groups_[MAX_GROUPS] = {};
    uint8_t node_count_ = 0;
    uint8_t edge_count_ = 0;
    uint8_t group_count_ = 0;
    bool dropped_ = false;
};
 
/// The ports a component exposes after describing itself, so an owner can wire them.
struct Ports {
    static constexpr uint8_t MAX_NAMED = 8;
 
    uint8_t in = NO_NODE;          ///< where a wave enters (the junction, the load)
    uint8_t out = NO_NODE;         ///< where a wave leaves (the pickup, the reflection)
    uint8_t group = NO_GROUP;
 
    /// Further ports by name, for a component with more ends than in and
    /// out: a loop's second end, an N-port junction's arms, a bank's per-mode taps.
    struct Named {
        const char* name;   ///< string literal
        uint8_t node;
    };
    Named named[MAX_NAMED] = {};
    uint8_t named_count = 0;
 
    /// Add a named port; a ninth is refused and find() answers NO_NODE for it.
    void add(const char* name, uint8_t node) {
        if (named_count >= MAX_NAMED) return;
        named[named_count++] = Named{name, node};
    }
 
    /// The node behind a name, or NO_NODE.
    uint8_t find(const char* name) const {
        for (uint8_t i = 0; i < named_count; ++i) {
            const char* a = named[i].name;
            const char* b = name;
            while (*a != '\0' && *a == *b) { ++a; ++b; }
            if (*a == '\0' && *b == '\0') return named[i].node;
        }
        return NO_NODE;
    }
};
 
} // namespace sbl::dsp::diagram
 
#endif // SBL_DSP_DIAGRAM_GRAPH_HPP_