Network of resonant modes for modal synthesis. More...

#include <ModalNetwork.hpp>

Inheritance diagram for MayaFlux::Nodes::Network::ModalNetwork:

Collaboration diagram for MayaFlux::Nodes::Network::ModalNetwork:

Classes
struct	ModalNode
	Represents a single resonant mode. More...

struct	ModeCoupling

Public Types
enum class	ExciterType : uint8_t { IMPULSE , NOISE_BURST , FILTERED_NOISE , SAMPLE , CONTINUOUS }
	Excitation signal types for modal synthesis. More...

enum class	Spectrum : uint8_t { HARMONIC , INHARMONIC , STRETCHED , CUSTOM }
	Predefined frequency relationship patterns. More...

Public Member Functions
void	clear_couplings ()
	Clear all mode couplings.

void	damp (double damping_factor=0.1)
	Damp all modes (rapidly reduce amplitude)

void	excite (double strength=1.0)
	Excite all modes (strike/pluck)

void	excite_at_position (double position, double strength=1.0)
	Excite modes based on normalized strike position.

void	excite_mode (size_t mode_index, double strength=1.0)
	Excite specific mode.

const auto &	get_couplings () const
	Get all active couplings.

ExciterType	get_exciter_type () const

double	get_fundamental () const
	Get current fundamental frequency.

std::unordered_map< std::string, std::string >	get_metadata () const override
	Get network metadata for debugging/visualization.

const ModalNode &	get_mode (size_t index) const
	Get specific mode.

const std::vector< ModalNode > &	get_modes () const
	Get mode data (read-only access for visualization)

std::optional< std::span< const double > >	get_node_audio_buffer (size_t index) const override
	Get output of specific internal node as audio buffer (for ONE_TO_ONE mapping)

size_t	get_node_count () const override
	Get the number of nodes in the network.

std::optional< double >	get_node_output (size_t index) const override
	Get output of specific internal node (for ONE_TO_ONE mapping)

const std::vector< double > &	get_spatial_distribution () const
	Get current spatial distribution.

void	initialize () override
	Called once before first process_batch()

bool	is_coupling_enabled () const
	Check if coupling is enabled.

void	map_parameter (const std::string &param_name, const std::shared_ptr< Node > &source, MappingMode mode=MappingMode::BROADCAST) override
	Map external node output to network parameter.

void	map_parameter (const std::string &param_name, const std::shared_ptr< NodeNetwork > &source_network) override
	Map external node network to network parameters (ONE_TO_ONE)

	ModalNetwork (const std::vector< double > &frequency_ratios, double fundamental=220.0, double base_decay=1.0)
	Create modal network with custom frequency ratios.

	ModalNetwork (size_t num_modes, double fundamental=220.0, Spectrum spectrum=Spectrum::HARMONIC, double base_decay=1.0)
	Create modal network with predefined spectrum.

void	process_batch (unsigned int num_samples) override
	Process the network for the given number of samples.

void	remove_mode_coupling (size_t mode_a, size_t mode_b)
	Remove specific coupling.

void	reset () override
	Reset network to initial state.

void	set_coupling_enabled (bool enable)
	Enable/disable modal coupling.

void	set_decay_multiplier (double multiplier)
	Set global decay multiplier.

void	set_exciter_duration (double seconds)
	Set noise burst duration.

void	set_exciter_filter (const std::shared_ptr< Filters::Filter > &filter)
	Set filter for shaped noise excitation.

void	set_exciter_node (const std::shared_ptr< Node > &node)
	Set continuous exciter node.

void	set_exciter_sample (const std::vector< double > &sample)
	Set custom excitation sample.

void	set_exciter_type (ExciterType type)
	Set exciter type.

void	set_fundamental (double frequency)
	Set base frequency (fundamental)

void	set_mode_coupling (size_t mode_a, size_t mode_b, double strength)
	Define bidirectional coupling between two modes.

void	set_spatial_distribution (const std::vector< double > &distribution)
	Set custom spatial amplitude distribution.

void	unmap_parameter (const std::string &param_name) override
	Remove parameter mapping.

Public Member Functions inherited from MayaFlux::Nodes::Network::NodeNetwork
void	add_channel_usage (uint32_t channel_id)
	Register network usage on a specific channel.

virtual std::optional< std::vector< double > >	get_audio_buffer () const
	Get cached audio buffer from last process_batch()

uint32_t	get_block_size () const

uint32_t	get_channel_mask () const
	Get channel mask (bitfield of registered channels)

virtual NetworkOperator *	get_operator ()

virtual const NetworkOperator *	get_operator () const

std::shared_ptr< OperatorChain >	get_operator_chain () const
	Access the secondary operator chain.

OutputMode	get_output_mode () const
	Get the current output routing mode.

double	get_output_scale () const
	Get the current output scale factor.

std::vector< uint32_t >	get_registered_channels () const
	Get all channels this network is registered on.

RoutingState &	get_routing_state ()
	Retrieves the current routing state of the network (non-const)

const RoutingState &	get_routing_state () const
	Retrieves the current routing state of the network.

uint32_t	get_sample_rate () const

Topology	get_topology () const
	Get the current topology.

virtual bool	has_operator () const

bool	is_enabled () const
	Check if network is enabled.

bool	is_processed_this_cycle () const
	Check if network has been processed this cycle (lock-free)

bool	is_processing () const
	Check if network is currently processing (lock-free)

bool	is_registered_on_channel (uint32_t channel_id) const
	Check if network is registered on a channel.

void	mark_processed (bool processed)
	Mark network as processed this cycle (lock-free)

void	mark_processing (bool processing)
	Mark network as processing or not (lock-free)

bool	needs_channel_routing () const
	Checks if the network is currently in a routing transition phase.

void	remove_channel_usage (uint32_t channel_id)
	Unregister network from a specific channel.

void	request_reset_from_channel (uint32_t channel_id)
	Request a reset from a specific channel.

void	set_block_size (uint32_t block_size)

void	set_channel_mask (uint32_t mask)
	Set channel mask directly.

void	set_enabled (bool enabled)
	Enable/disable the network.

void	set_output_mode (OutputMode mode)
	Set the network's output routing mode.

void	set_output_scale (double scale)
	Set the scalar multiplier applied to the network's output buffer after processing.

void	set_sample_rate (uint32_t sample_rate)

virtual void	set_topology (Topology topology)
	Set the network's topology.

virtual	~NodeNetwork ()=default

Private Member Functions
void	apply_broadcast_parameter (const std::string &param, double value)
	Apply broadcast parameter to all modes.

void	apply_one_to_one_parameter (const std::string &param, const std::shared_ptr< NodeNetwork > &source)
	Apply one-to-one parameter from another network.

void	compute_mode_coupling ()
	Apply modal coupling energy transfer.

void	compute_spatial_distribution ()
	Compute spatial amplitude distribution.

double	generate_exciter_sample ()
	Generate exciter signal for current sample.

void	initialize_exciter (double strength)
	Initialize exciter for new excitation event.

void	initialize_modes (const std::vector< double > &ratios, double base_decay)
	Initialize modes with given frequency ratios.

void	update_mapped_parameters ()
	Update mapped parameters before processing.

Static Private Member Functions
static std::vector< double >	generate_spectrum_ratios (Spectrum spectrum, size_t count)
	Generate frequency ratios for predefined spectra.

Private Attributes
bool	m_coupling_enabled { false }

std::vector< ModeCoupling >	m_couplings

double	m_decay_multiplier = 1.0

bool	m_exciter_active { false }

double	m_exciter_duration { 0.01 }

std::shared_ptr< Filters::Filter >	m_exciter_filter

std::shared_ptr< Node >	m_exciter_node

std::vector< double >	m_exciter_sample

size_t	m_exciter_sample_position { 0 }

size_t	m_exciter_samples_remaining { 0 }

ExciterType	m_exciter_type { ExciterType::IMPULSE }

double	m_fundamental

std::vector< ModalNode >	m_modes

std::vector< std::vector< double > >	m_node_buffers
	Per-mode sample buffers populated each process_batch()

Kinesis::Stochastic::Stochastic	m_random_generator

std::vector< double >	m_spatial_distribution

Spectrum	m_spectrum

Additional Inherited Members
Protected Member Functions inherited from MayaFlux::Nodes::Network::NodeNetwork
void	apply_output_scale ()
	Apply m_output_scale to m_last_audio_buffer.

void	ensure_initialized ()
	Ensure initialize() is called exactly once.

Static Protected Member Functions inherited from MayaFlux::Nodes::Network::NodeNetwork
static std::unordered_map< size_t, std::vector< size_t > >	build_chain_neighbors (size_t count)
	Build neighbor map for CHAIN topology.

static std::unordered_map< size_t, std::vector< size_t > >	build_grid_2d_neighbors (size_t width, size_t height)
	Build neighbor map for GRID_2D topology.

static std::unordered_map< size_t, std::vector< size_t > >	build_grid_3d_neighbors (size_t width, size_t height, size_t depth)
	Build neighbor map for GRID_3D topology.

static std::unordered_map< size_t, std::vector< size_t > >	build_ring_neighbors (size_t count)
	Build neighbor map for RING topology.

Protected Attributes inherited from MayaFlux::Nodes::Network::NodeNetwork
std::atomic_flag	m_audio_buffer_lock = ATOMIC_FLAG_INIT
	Spinlock guarding m_last_audio_buffer.

uint32_t	m_block_size { 512 }

std::atomic< uint32_t >	m_channel_mask { 0 }
	Bitfield of channels this network is registered on.

bool	m_enabled = true

bool	m_initialized = false

std::vector< double >	m_last_audio_buffer

std::shared_ptr< OperatorChain >	m_operator_chain

OutputMode	m_output_mode = OutputMode::NONE

double	m_output_scale { 1.0 }
	Post-processing scalar applied to m_last_audio_buffer each batch.

std::vector< ParameterMapping >	m_parameter_mappings

std::atomic< uint32_t >	m_pending_reset_mask { 0 }

std::atomic< bool >	m_processed_this_cycle { false }

std::atomic< bool >	m_processing_state { false }
	Per-channel processing state (lock-free atomic flags)

uint32_t	m_sample_rate { 48000 }

Topology	m_topology = Topology::INDEPENDENT

Detailed Description

Network of resonant modes for modal synthesis.

CONCEPT:

Modal synthesis models physical objects as collections of resonant modes, each with its own frequency, decay rate, and amplitude. The sum of all modes produces rich, organic timbres characteristic of struck/plucked instruments (bells, marimbas, strings, membranes).

STRUCTURE:

Each mode is an independent oscillator (typically Sine) with:

Frequency: Resonant frequency of the mode
Decay: Exponential amplitude envelope
Amplitude: Initial strike/excitation strength

Modes can follow various frequency relationships:

HARMONIC: f, 2f, 3f, 4f... (ideal strings)
INHARMONIC: f, 2.76f, 5.40f, 8.93f... (bells, bars)
STRETCHED: f, 2.01f, 3.02f, 4.04f... (stiff strings, piano)
CUSTOM: User-defined frequency ratios

USAGE:

// Bell-like inharmonic spectrum
auto bell = std::make_shared<ModalNetwork>(
    16,                          // 16 modes
    220.0,                       // Base frequency
    ModalNetwork::Spectrum::INHARMONIC
);
bell->set_output_mode(OutputMode::AUDIO_SINK);
bell->excite(1.0);  // Strike the bell
 
node_graph_manager->add_network(bell, ProcessingToken::AUDIO_RATE);

PARAMETER MAPPING:

External nodes can control:

"frequency": Base frequency (BROADCAST)
"decay": Global decay multiplier (BROADCAST)
"amplitude": Per-mode amplitude (ONE_TO_ONE)
"detune": Per-mode frequency offset (ONE_TO_ONE)

Definition at line 63 of file ModalNetwork.hpp.

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

Classes

Public Types

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

CONCEPT:

STRUCTURE:

USAGE:

PARAMETER MAPPING: