Class thl::graph::Graph#

class Graph : public thl::dsp::BaseProcessor#

Inheritance diagram for thl::graph::Graph:

digraph { graph [bgcolor="#00000000"] node [shape=rectangle style=filled fillcolor="#FFFFFF" font=Helvetica padding=2] edge [color="#1414CE"] "2" [label="thl::dsp::BaseProcessor" tooltip="thl::dsp::BaseProcessor"] "1" [label="thl::graph::Graph" tooltip="thl::graph::Graph" fillcolor="#BFBFBF"] "1" -> "2" [dir=forward tooltip="public-inheritance"] }

Collaboration diagram for thl::graph::Graph:

digraph { graph [bgcolor="#00000000"] node [shape=rectangle style=filled fillcolor="#FFFFFF" font=Helvetica padding=2] edge [color="#1414CE"] "2" [label="thl::dsp::BaseProcessor" tooltip="thl::dsp::BaseProcessor"] "1" [label="thl::graph::Graph" tooltip="thl::graph::Graph" fillcolor="#BFBFBF"] "1" -> "2" [dir=forward tooltip="public-inheritance"] }

A graph of BaseProcessors that is itself a BaseProcessor.

process() feeds the incoming buffer to graph_input() and overwrites it with what reaches graph_output(). Every node runs with the channel count given to prepare().

Edits are made on the control thread and take effect at commit(). The audio thread then fades out the current version, switches to the committed one and, once its latency has passed, fades it in. Every edit that changes the structure therefore goes silent for the fade and the graph’s latency, also where it does not touch the latent path. Input and wet mixes are live: they ramp without a commit.

Latency compensation: a node’s latency_samples() is followed per block; the faster sources of every node and a node’s dry path are delayed to match, up to the max_latency_samples() each node had at the last commit.

A Graph’s own dry signal (process_with_dry(), as a nested graph) is its input, not yet built from its nodes’ dry signals: blending a nested graph whose nodes shift the phase can comb.

Public Types

enum class InputMix : uint8_t#

How a node combines its sources: their sum (the default, as a mixer), or their sum divided by their number.

Values:

enumerator Sum#
enumerator Average#
enum class MixLaw : uint8_t#

How a node’s wet mix m (0 dry, 1 wet) sets the gains of its dry signal (its processor’s process_with_dry(), delayed by the node’s latency) and of its processor’s output (wet).

Values:

enumerator Linear#

dry 1 - m, wet m (the default): constant level when the wet signal is correlated with the dry (EQ, compression, saturation, phaser and comb effects).

enumerator ConstantPower#

dry cos(m pi/2), wet sin(m pi/2): constant power when it is not (reverb, delay, chorus); -3 dB each at 0.5.

enumerator Compromise#

The geometric mean of Linear and ConstantPower, -4.5 dB each at 0.5: for a partly correlated wet signal (modulated delays, short rooms, multiband processing).

enumerator Parallel#

dry 1, wet m: parallel processing (parallel compression, sends); the mix only adds.

enumerator DryHeld#

dry 1 up to 0.5 then down to 0, wet up to 1 by 0.5: full level in the middle, a send below it and an insert above.

enum class ProbePoint : uint8_t#

Where a probe watches a node: what reaches it (its sources mixed) or what it sends on (its processor’s output, blended with its dry signal by the wet mix).

Values:

enumerator Input#
enumerator Output#

Public Functions

Graph()#
~Graph() override#
Graph(const Graph&) = delete#
Graph &operator=(const Graph&) = delete#
Graph(Graph&&) = delete#
Graph &operator=(Graph&&) = delete#
template<typename T, typename ...Args>
inline std::optional<NodeId> add_node(Args&&... args)#

A new node running a T made from args; see add_node(std::unique_ptr).

std::optional<NodeId> add_node(std::unique_ptr<thl::dsp::BaseProcessor> processor)#

A new node running processor, unconnected, until the next commit() not processed.

A prepared graph prepares the processor here, on the calling thread. Nothing for a null processor.

std::optional<NodeId> add_prepared_node(std::unique_ptr<thl::dsp::BaseProcessor> processor, double sample_rate, size_t samples_per_block, size_t num_channels)#

A processor the caller already prepared, e.g.

a heavy one on its own background thread, for sample_rate, samples_per_block and num_channels. The graph prepares it again only if they differ from its own, and always in prepare(), so before the graph is prepared this is add_node().

bool remove_node(NodeId id)#

Removes the node and its connections; its processor is freed once no version that ran it is left (collect_garbage()).

False for graph_input(), graph_output() and unknown ids.

bool connect(NodeId from, NodeId to)#

Feeds from's output into to.

False for unknown ids, into graph_input(), out of graph_output(), a connection that exists or one that would close a cycle.

bool disconnect(NodeId from, NodeId to)#

False if there is no such connection.

bool set_input_mix(NodeId id, InputMix input_mix)#

Live (no commit): how node id, or graph_output(), combines its sources; ramps over 20 ms.

False for graph_input() and unknown ids.

bool set_wet_mix(NodeId id, float wet_mix)#

Live (no commit): 1 runs the node, 0 bypasses it (its sources pass, delayed by its latency), between them a blend of its output with its dry signal (process_with_dry(): phase-matched, then delayed by its latency); ramps over 20 ms, clamped to [0, 1].

Towards 0 the dry signal glides from the phase-matched one to the sources, and back from 0 the other way, so a node that turns the phase goes into bypass and back without a step. A node coming back from 0 is reset() first. False for graph_input(), graph_output(), unknown ids and NaN.

bool set_mix_law(NodeId id, MixLaw law)#

Live (no commit): how node id's wet mix sets its dry and wet gains; a change crossfades from the old law over 20 ms.

False for graph_input(), graph_output() and unknown ids.

bool commit()#

Hands the edited graph and every graph nested in it to the audio thread (a short fade out and in).

Without changes since the last commit it does nothing; it also rebuilds when a node’s max_latency_samples() changed. Commit the outermost graph: a nested graph’s own commit() takes effect inside it, but if it raises its maximum latency, the graph containing it compensates at the old maximum until that graph commits (has_uncommitted_changes()). False if a graph has a cycle, which connect() prevents.

bool has_uncommitted_changes() const#

True after an edit, or when a node’s max_latency_samples() changed, here or in a nested graph, since the last commit().

inline uint32_t committed_latency_samples() const#

Control thread: the latency the version prepare() or commit() handed over last will have, from its nodes’ current latency_samples() (a nested graph: its own committed latency; a node whose max_latency_samples() changed since the last commit: that maximum, until it runs and tells its own), so a host can be told right after commit().

The graph never pads: its output has the least latency its nodes allow, and max_latency_samples() only sizes the delays. A node that changes its latency between commits changes latency_samples() at the next block; tell the host then too (e.g. JUCE’s setLatencySamples() from the message thread).

template<typename Probe, typename ...Args>
inline std::optional<std::pair<ProbeId, Probe*>> add_probe(NodeId id, ProbePoint point, Args&&... args)#

Control thread, live (no commit, no fade): a new probe of type Probe (made from args) watches node id at point from the next block on.

graph_input() has only an Output (what process() is given), graph_output() only an Input (what process() returns). The graph owns the probe: it prepares it now if the graph is prepared and with every prepare(), resets it with reset() and when a newly committed version starts, and deletes it in remove_probe() or remove_node(). The pointer is for reading it (meters, a reader thread) and is valid until then. Nothing for an unknown node, the missing point of graph_input() or graph_output(), or a point with k_max_probes_per_point probes. A probe never changes the signal or its latency.

std::optional<ProbeId> add_probe(NodeId id, ProbePoint point, std::unique_ptr<thl::dsp::probe::ProbeBase> probe)#

add_probe() for a probe made elsewhere; the graph takes it over.

bool remove_probe(ProbeId id)#

Control thread: stops probe id, waits until the audio thread no longer uses it (the block in progress, if any) and deletes it.

Never from the audio thread. False for an unknown id.

thl::dsp::probe::ProbeBase *probe(ProbeId id) const#

The probe id, or nullptr for an unknown id.

void collect_garbage()#

Frees the versions the audio thread handed back and the removed nodes no running version uses, also in nested graphs.

commit() calls it; call it from a timer (e.g. 30 Hz on the message thread) so removed processors go away without another edit. A nested graph that does not run (wet 0) keeps its old version until it runs again.

inline NodeId graph_input() const#

The node that holds what process() is given.

inline NodeId graph_output() const#

The node whose sources make what process() returns.

thl::dsp::BaseProcessor *node(NodeId id)#

The processor of node id; nullptr for graph_input(), graph_output() and unknown ids.

const thl::dsp::BaseProcessor *node(NodeId id) const#
std::optional<float> wet_mix(NodeId id) const#

The wet mix set for node id; nothing for graph_input(), graph_output() and unknown ids.

std::optional<MixLaw> mix_law(NodeId id) const#

The mix law set for node id; nothing for graph_input(), graph_output() and unknown ids.

std::vector<NodeId> nodes() const#

Every node, graph_input() and graph_output() included, as edited (not as committed).

std::vector<Connection> connections() const#

Every connection, as edited.

std::vector<NodeId> sources_of(NodeId id) const#

The nodes connected into id, as edited.

virtual void prepare(const double &sample_rate, const size_t &samples_per_block, const size_t &num_channels) override#

Prepares every node and commits, including pending edits.

Call only while process() is not running.

virtual void process(thl::core::BufferView buffer, uint32_t modulation_offset = 0) override#

modulation_offset: the position of buffer in the block when the caller runs the block in parts; every node gets it, so it reads its modulation at the block position.

virtual void reset() override#

Audio thread: resets every node of the running version and clears the latency delays, e.g.

when the graph is itself a bypassed node coming back.

Public Static Attributes

static constexpr size_t k_max_probes_per_point = 8#