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

#include <ModalNetwork.hpp>

Inheritance diagram for MayaFlux::Nodes::ModalNetwork:

Collaboration diagram for MayaFlux::Nodes::ModalNetwork:

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

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

Public Types inherited from MayaFlux::Nodes::NodeNetwork
enum class	Topology : uint8_t { INDEPENDENT , CHAIN , RING , GRID_2D , GRID_3D , SPATIAL , CUSTOM }
	Defines the structural relationships between nodes in the network. More...

enum class	OutputMode : uint8_t { NONE , AUDIO_SINK , GRAPHICS_BIND , CUSTOM }
	Defines how the network's computational results are exposed. More...

enum class	MappingMode : uint8_t { BROADCAST , ONE_TO_ONE }
	Defines how nodes map to external entities (e.g., audio channels, graphics objects) More...

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

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

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

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

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

void	reset () override
	Reset network to initial state.

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

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)

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

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

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

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

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

double	get_fundamental () const
	Get current fundamental frequency.

void	set_decay_multiplier (double multiplier)
	Set global decay multiplier.

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

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

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

Public Member Functions inherited from MayaFlux::Nodes::NodeNetwork
virtual	~NodeNetwork ()=default

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

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

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

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

Topology	get_topology () const
	Get the current topology.

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

bool	is_enabled () const
	Check if network is enabled.

void	add_channel_usage (uint32_t channel_id)
	Register network usage on a specific channel.

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

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

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

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

void	set_channel_mask (uint32_t mask)
	Set channel mask directly.

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

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

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

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

Private Member Functions
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.

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.

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

Private Attributes
std::vector< ModalNode >	m_modes

Spectrum	m_spectrum

double	m_fundamental

double	m_decay_multiplier = 1.0

double	m_last_output = 0.0

Additional Inherited Members
Protected Member Functions inherited from MayaFlux::Nodes::NodeNetwork
void	ensure_initialized ()
	Ensure initialize() is called exactly once.

Static Protected Member Functions inherited from MayaFlux::Nodes::NodeNetwork
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.

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

Protected Attributes inherited from MayaFlux::Nodes::NodeNetwork
Topology	m_topology = Topology::INDEPENDENT

OutputMode	m_output_mode = OutputMode::NONE

bool	m_enabled = true

bool	m_initialized = false

std::vector< ParameterMapping >	m_parameter_mappings

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

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

std::atomic< bool >	m_processed_this_cycle { false }

std::vector< double >	m_last_audio_buffer

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 58 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: