MayaFlux::Nodes::ParticleNetwork Class Reference

Network of particles with physics simulation. More...

#include <ParticleNetwork.hpp>

Inheritance diagram for MayaFlux::Nodes::ParticleNetwork:

Collaboration diagram for MayaFlux::Nodes::ParticleNetwork:

Classes
struct	ParticleNode
	Single particle with physics state. More...

Public Types
enum class	BoundsMode : uint8_t {   NONE , BOUNCE , WRAP , CLAMP ,   DESTROY }
	How particles behave at spatial bounds. More...
enum class	InitializationMode : uint8_t {   RANDOM_VOLUME , RANDOM_SURFACE , GRID , SPHERE_VOLUME ,   SPHERE_SURFACE , CUSTOM }
	Particle spawn distribution. 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
	ParticleNetwork (size_t num_particles, const glm::vec3 &bounds_min=glm::vec3(-10.0F), const glm::vec3 &bounds_max=glm::vec3(10.0F), InitializationMode init_mode=InitializationMode::RANDOM_VOLUME)
	Create particle network with spatial bounds.
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.
std::optional< double >	get_node_output (size_t index) const override
	Get output of specific internal node (for ONE_TO_ONE mapping)
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.
const std::vector< ParticleNode > &	get_particles () const
	Get all particles (read-only for NetworkGeometryBuffer)
const ParticleNode &	get_particle (size_t index) const
	Get specific particle.
ParticleNode &	get_particle_mut (size_t index)
	Get mutable particle (for custom manipulation)
void	set_gravity (const glm::vec3 &gravity)
	Set global gravity vector.
glm::vec3	get_gravity () const
	Get current gravity.
void	set_drag (float drag)
	Set drag coefficient (0.0 = no drag, 1.0 = full drag)
float	get_drag () const
	Get current drag.
void	set_bounds (const glm::vec3 &min, const glm::vec3 &max)
	Set spatial bounds.
void	set_bounds_mode (BoundsMode mode)
	Set bounds behavior.
void	set_interaction_radius (float radius)
	Set interaction radius (for SPATIAL topology)
void	set_spring_stiffness (float stiffness)
	Set spring stiffness (for SPATIAL/GRID topologies)
void	set_repulsion_strength (float strength)
	Set repulsion strength (for SPATIAL topology)
void	set_attraction_point (const glm::vec3 &point)
	Set attraction point (particles pulled toward this point)
void	disable_attraction_point ()
	Disable attraction point.
void	set_timestep (float dt)
	Set time step for physics integration.
void	apply_global_impulse (const glm::vec3 &impulse)
	Apply impulse to all particles.
void	apply_impulse (size_t index, const glm::vec3 &impulse)
	Apply impulse to specific particle.
void	reinitialize_positions (InitializationMode mode)
	Reinitialize all particle positions.
void	reset_velocities ()
	Reset all velocities to zero.
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	clear_forces ()
	Clear accumulated forces.
void	apply_gravity ()
	Apply gravity to all particles.
void	apply_drag ()
	Apply drag forces.
void	apply_interaction_forces ()
	Apply interaction forces based on topology.
void	apply_attraction_force ()
	Apply attraction point force.
void	integrate (float dt)
	Integrate forces → velocities → positions.
void	handle_bounds ()
	Handle boundary conditions.
void	update_point_nodes ()
	Update PointNode states from physics.
void	rebuild_spatial_neighbors ()
	Rebuild neighbor map for SPATIAL topology.
std::vector< size_t >	get_neighbors (size_t index) const
	Get neighbors for a particle based on current topology.
void	initialize_particle_positions (InitializationMode mode)
	Initialize particles based on mode.
glm::vec3	random_position_volume () const
	Random position in bounds volume.
glm::vec3	random_position_surface () const
	Random position on bounds surface.
glm::vec3	random_position_sphere (float radius) const
	Random position in sphere.
glm::vec3	random_position_sphere_surface (float radius) const
	Random position on sphere surface.
void	update_mapped_parameters ()
	Update mapped parameters before physics step.
void	apply_broadcast_parameter (const std::string &param, double value)
	Apply broadcast parameter to all particles.
void	apply_one_to_one_parameter (const std::string &param, const std::shared_ptr< NodeNetwork > &source)
	Apply one-to-one parameter from another network.

Private Attributes
std::vector< ParticleNode >	m_particles
glm::vec3	m_gravity { 0.0F, -9.8F, 0.0F }
float	m_drag = 0.01F
float	m_timestep = 0.016F
glm::vec3	m_bounds_min { -10.0F }
glm::vec3	m_bounds_max { 10.0F }
BoundsMode	m_bounds_mode = BoundsMode::BOUNCE
float	m_interaction_radius = 2.0F
float	m_spring_stiffness = 0.1F
float	m_repulsion_strength = 0.5F
glm::vec3	m_attraction_point { 0.0F }
bool	m_has_attraction_point = false
float	m_attraction_strength = 1.0F
InitializationMode	m_init_mode
std::unordered_map< size_t, std::vector< size_t > >	m_neighbor_map
bool	m_neighbor_map_dirty = true

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 particles with physics simulation.

CONCEPT:

N-body particle system where each particle is a PointNode (GeometryWriterNode). Particles can interact based on topology (spatial forces, springs, etc.) or remain independent (ballistic motion).

TOPOLOGY USAGE:

• INDEPENDENT: No inter-particle forces (pure ballistic motion)
• SPATIAL: Particles within radius interact (flocking, springs, repulsion)
• GRID_2D/3D: Fixed neighbor relationships (cloth, lattice)
• RING/CHAIN: Sequential connections (rope, chain simulation)
• CUSTOM: User-defined force topology

PARAMETER MAPPING:

External nodes can control particle behavior:

BROADCAST (one node → all particles):

• "gravity": Global gravity strength
• "drag": Air resistance coefficient
• "turbulence": Chaos/noise strength
• "attraction": Global attraction point strength

ONE_TO_ONE (network → per-particle control):

• "force_x/y/z": Per-particle force application
• "color": Per-particle color (from audio spectrum, etc.)
• "size": Per-particle size modulation
• "mass": Per-particle mass override

USAGE:

// Create 1000 particles with spatial interaction
auto particles = std::make_shared<ParticleNetwork>(
    1000,
    glm::vec3(-10, -10, -10),  // bounds min
    glm::vec3(10, 10, 10)       // bounds max
);
particles->set_topology(Topology::SPATIAL);
particles->set_interaction_radius(2.0F);
particles->set_output_mode(OutputMode::GRAPHICS_BIND);
 
// Audio-reactive turbulence
auto mic = vega.AudioInput();
auto amplitude = vega.Envelope(mic);
particles->map_parameter("turbulence", amplitude, MappingMode::BROADCAST);
 
node_graph_manager->add_network(particles, ProcessingToken::VISUAL_RATE);

Definition at line 63 of file ParticleNetwork.hpp.

---

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

• ParticleNetwork.hpp
• ParticleNetwork.cpp