Detailed Description

Definition at line 84 of file string_loop.hpp.

#include <string_loop.hpp>

Public Member Functions
void	init (float a_buffer, uint32_t a_max, float b_buffer, uint32_t b_max)
	Install the two segments' buffers.

void	set_period_samples (float period)
	Loop period in samples — the pitch. Sample rate over frequency.

void	set_junction (float beta)
	Excitation point along the string, 0 at end a, 1 at end b (a string: nut and bridge).

void	set_damping_su (float su)
	Loss filter cutoff: how fast the high partials give up. Signal units.

void	set_impedance (float z)
	The wave impedance Z the junction reports and converts forces with.

float	impedance () const

float	displacement () const
	The junction's displacement right now (wave units × samples).

void	set_loop_gain (float gain)
	Round-trip gain, the passivity margin.

template<typename Excite , typename EndB >
float	tick (Excite &&excite, EndB &&end_b)
	Advance one sample.

template<typename Excite >
float	tick (Excite &&excite)
	Advance one sample against a rigid end b: reflection −1.

float	tick ()
	Advance one sample with nothing injected: the string rings on alone.

JunctionState	junction_state (float v_free) const
	What the exciter sees this sample, for a scope.

float	period_samples () const

float	junction () const

float	delay_a_samples () const
	Segment lengths actually read — the split the junction makes, clamped to the buffers.

float	delay_b_samples () const

float	allpass_delay_samples () const
	The allpass's share of the period: its nominal sample plus the rounding residual.

float	energy () const
	Energy in the two segments, in wave units: the sum of squares of every sample in flight (physical-modeling.md §5.1, §8.3)

void	reset ()

diagram::Ports	describe (diagram::Graph &g, uint8_t parent=diagram::NO_GROUP, bool external_end_b=false) const
	The loop's wiring as data (AP-037). Never called from audio code.

Static Public Member Functions
static float	rigid_end (float arriving)
	An end with nothing on it: a wall.

Static Public Attributes
static constexpr float	MIN_PERIOD = 8.0f
	Shortest loop: eight samples, 6 kHz at 48 kHz. Pitch requests above it play this.

static constexpr float	DEFAULT_IMPEDANCE = 1.0f
	The loop's wave impedance unless told otherwise: the unit the laws and loads are written in.

static constexpr float	DISPLACEMENT_LEAK_HZ = 5.0f
	The junction displacement forgets DC below this: a leaky integrator.

Member Function Documentation

◆ init()

void sbl::dsp::pm::StringLoop::init	(	float *	a_buffer,
		uint32_t	a_max,
		float *	b_buffer,
		uint32_t	b_max
	)

inline

Install the two segments' buffers.

Each buffer bounds its own segment, so the longest period depends on the junction: the nut segment needs period * beta samples and the bridge segment the rest. A segment asked for more than its buffer is clamped to the buffer, and the loop then plays sharp of the request; delay_a_samples() / delay_b_samples() report the lengths actually read, so a caller can tell.

Definition at line 105 of file string_loop.hpp.

References sbl::dsp::primitives::DelayLine::init(), sbl::dsp::primitives::OnePole::set_cutoff_su(), and sbl::dsp::primitives::OnePole::set_range().

Referenced by sbl::dsp::pm::StringBase< Exciter, Load, MaxPeriod >::StringBase().

◆ set_period_samples()

void sbl::dsp::pm::StringLoop::set_period_samples ( float period )

inline

Loop period in samples — the pitch. Sample rate over frequency.

Definition at line 118 of file string_loop.hpp.

References MIN_PERIOD.

Referenced by sbl::dsp::pm::StringBase< Exciter, Load, MaxPeriod >::update_period().

◆ set_junction()

void sbl::dsp::pm::StringLoop::set_junction ( float beta )

inline

Excitation point along the string, 0 at end a, 1 at end b (a string: nut and bridge).

Definition at line 124 of file string_loop.hpp.

References sbl::dsp::math::clamp().

Referenced by sbl::dsp::pm::StringBase< Exciter, Load, MaxPeriod >::apply_position().

◆ set_damping_su()

void sbl::dsp::pm::StringLoop::set_damping_su ( float su )

inline

Loss filter cutoff: how fast the high partials give up. Signal units.

Definition at line 131 of file string_loop.hpp.

References sbl::dsp::math::clamp01(), and sbl::dsp::primitives::OnePole::set_cutoff_su().

Referenced by sbl::dsp::pm::StringBase< Exciter, Load, MaxPeriod >::apply_damping().

◆ set_impedance()

void sbl::dsp::pm::StringLoop::set_impedance ( float z )

inline

The wave impedance Z the junction reports and converts forces with.

Definition at line 136 of file string_loop.hpp.

References DEFAULT_IMPEDANCE.

◆ impedance()

float sbl::dsp::pm::StringLoop::impedance ( ) const

inline

Definition at line 137 of file string_loop.hpp.

Referenced by sbl::dsp::pm::StringBase< Exciter, Load, MaxPeriod >::reset().

◆ displacement()

float sbl::dsp::pm::StringLoop::displacement ( ) const

inline

The junction's displacement right now (wave units × samples).

Definition at line 140 of file string_loop.hpp.

◆ set_loop_gain()

void sbl::dsp::pm::StringLoop::set_loop_gain ( float gain )

inline

Round-trip gain, the passivity margin.

Below 1 the loop decays; at 1 it is lossless and only the damping filter removes energy. Clamped at 1 so the loop can never generate.

Definition at line 148 of file string_loop.hpp.

References sbl::dsp::math::clamp01().

Referenced by sbl::dsp::pm::StringBase< Exciter, Load, MaxPeriod >::StringBase().

◆ tick() [1/3]

template<typename Excite , typename EndB >

float sbl::dsp::pm::StringLoop::tick	(	Excite &&	excite,
		EndB &&	end_b
	)

inline

Advance one sample.

Parameters

excite	an Exciter (excite(const JunctionState&) → force), or a callable of the arriving velocity returning the wave to inject
end_b	called with the wave arriving at end b (after the loop's loss and allpass); returns the reflection

Returns: the wave arriving at end b — the pickup

Definition at line 163 of file string_loop.hpp.

References sbl::dsp::primitives::OnePole::process(), sbl::dsp::primitives::ThiranAllpass< N >::process(), sbl::dsp::primitives::DelayLine::read(), and sbl::dsp::primitives::DelayLine::write().

Referenced by sbl::dsp::pm::StringBase< Exciter, Load, MaxPeriod >::process().

◆ tick() [2/3]

template<typename Excite >

float sbl::dsp::pm::StringLoop::tick ( Excite && excite )

inline

Advance one sample against a rigid end b: reflection −1.

Definition at line 185 of file string_loop.hpp.

References rigid_end(), and tick().

◆ tick() [3/3]

float sbl::dsp::pm::StringLoop::tick ( )

inline

Advance one sample with nothing injected: the string rings on alone.

Definition at line 190 of file string_loop.hpp.

References rigid_end(), and tick().

Referenced by tick(), and tick().

◆ rigid_end()

static float sbl::dsp::pm::StringLoop::rigid_end ( float arriving )

inlinestatic

An end with nothing on it: a wall.

Definition at line 195 of file string_loop.hpp.

Referenced by tick(), and tick().

◆ junction_state()

JunctionState sbl::dsp::pm::StringLoop::junction_state ( float v_free ) const

inline

What the exciter sees this sample, for a scope.

Definition at line 198 of file string_loop.hpp.

◆ period_samples()

float sbl::dsp::pm::StringLoop::period_samples ( ) const

inline

Definition at line 200 of file string_loop.hpp.

Referenced by sbl::dsp::pm::StringBase< Exciter, Load, MaxPeriod >::period_samples().

◆ junction()

float sbl::dsp::pm::StringLoop::junction ( ) const

inline

Definition at line 201 of file string_loop.hpp.

Referenced by describe().

◆ delay_a_samples()

float sbl::dsp::pm::StringLoop::delay_a_samples ( ) const

inline

Segment lengths actually read — the split the junction makes, clamped to the buffers.

Definition at line 204 of file string_loop.hpp.

◆ delay_b_samples()

float sbl::dsp::pm::StringLoop::delay_b_samples ( ) const

inline

Definition at line 205 of file string_loop.hpp.

◆ allpass_delay_samples()

float sbl::dsp::pm::StringLoop::allpass_delay_samples ( ) const

inline

The allpass's share of the period: its nominal sample plus the rounding residual.

Definition at line 208 of file string_loop.hpp.

References sbl::dsp::primitives::ThiranAllpass< N >::group_delay_samples().

◆ energy()

float sbl::dsp::pm::StringLoop::energy ( ) const

inline

Energy in the two segments, in wave units: the sum of squares of every sample in flight (physical-modeling.md §5.1, §8.3)

The loss filter's and allpass's one-sample states are left out; they are a sample each against hundreds in the lines. Never called from audio code.

Definition at line 218 of file string_loop.hpp.

References sbl::dsp::primitives::DelayLine::read().

Referenced by sbl::dsp::pm::StringBase< Exciter, Load, MaxPeriod >::energy().

◆ reset()

void sbl::dsp::pm::StringLoop::reset ( )

inline

Definition at line 227 of file string_loop.hpp.

References DISPLACEMENT_LEAK_HZ, sbl::dsp::primitives::DelayLine::reset(), sbl::dsp::primitives::OnePole::reset(), sbl::dsp::primitives::ThiranAllpass< N >::reset(), sbl::dsp::types::SAMPLE_RATE_F, and sbl::dsp::math::TWO_PI.

Referenced by sbl::dsp::pm::StringBase< Exciter, Load, MaxPeriod >::reset().

◆ describe()

diagram::Ports sbl::dsp::pm::StringLoop::describe	(	diagram::Graph &	g,
		uint8_t	parent = `diagram::NO_GROUP`,
		bool	external_end_b = `false`
	)		const

inline

The loop's wiring as data (AP-037). Never called from audio code.

Parameters

external_end_b true when an owner supplies the bridge callable: the wall is left out and the named ports "to end b" and "from end b" are the two ends the owner's termination connects to. in is the excitation junction; out is the pickup (the wave arriving at the bridge).

Definition at line 244 of file string_loop.hpp.

References sbl::dsp::diagram::Ports::add(), sbl::dsp::diagram::Graph::add_edge(), sbl::dsp::diagram::Graph::add_group(), sbl::dsp::diagram::Graph::add_node(), sbl::dsp::diagram::Ports::group, sbl::dsp::primitives::ThiranAllpass< N >::group_delay_samples(), sbl::dsp::diagram::Ports::in, junction(), and sbl::dsp::diagram::Ports::out.

Referenced by sbl::dsp::pm::StringBase< Exciter, Load, MaxPeriod >::describe().

Member Data Documentation

◆ MIN_PERIOD

constexpr float sbl::dsp::pm::StringLoop::MIN_PERIOD = 8.0f

staticconstexpr

Shortest loop: eight samples, 6 kHz at 48 kHz. Pitch requests above it play this.

Note: All public methods are ISR-safe — bounded computation, no I/O.

Definition at line 89 of file string_loop.hpp.

Referenced by set_period_samples().

◆ DEFAULT_IMPEDANCE

constexpr float sbl::dsp::pm::StringLoop::DEFAULT_IMPEDANCE = 1.0f

staticconstexpr

The loop's wave impedance unless told otherwise: the unit the laws and loads are written in.

Definition at line 91 of file string_loop.hpp.

Referenced by set_impedance().

◆ DISPLACEMENT_LEAK_HZ

constexpr float sbl::dsp::pm::StringLoop::DISPLACEMENT_LEAK_HZ = 5.0f

staticconstexpr

The junction displacement forgets DC below this: a leaky integrator.

Definition at line 93 of file string_loop.hpp.

Referenced by reset().

The documentation for this class was generated from the following file:

src/sbl/dsp/pm/string_loop.hpp

Detailed Description

Public Member Functions

Static Public Member Functions

Static Public Attributes

Member Function Documentation

◆ init()

◆ set_period_samples()

◆ set_junction()

◆ set_damping_su()

◆ set_impedance()

◆ impedance()

◆ displacement()

◆ set_loop_gain()

◆ tick() [1/3]

◆ tick() [2/3]

◆ tick() [3/3]

◆ rigid_end()

◆ junction_state()

◆ period_samples()

◆ junction()

◆ delay_a_samples()

◆ delay_b_samples()

◆ allpass_delay_samples()

◆ energy()

◆ reset()

◆ describe()

Member Data Documentation

◆ MIN_PERIOD

◆ DEFAULT_IMPEDANCE

◆ DISPLACEMENT_LEAK_HZ