Generates dynamic mesh topology from sparse control points. More...

#include <TopologyGeneratorNode.hpp>

Inheritance diagram for MayaFlux::Nodes::GpuSync::TopologyGeneratorNode:

Collaboration diagram for MayaFlux::Nodes::GpuSync::TopologyGeneratorNode:

Public Types
using	CustomConnectionFunction = std::function< std::vector< std::pair< size_t, size_t > >(const Eigen::MatrixXd &)>

Public Member Functions
	TopologyGeneratorNode (Kinesis::ProximityMode mode=Kinesis::ProximityMode::SEQUENTIAL, bool auto_connect=true, size_t max_points=256)
	Create topology generator.

	TopologyGeneratorNode (CustomConnectionFunction custom_func, bool auto_connect=true, size_t max_points=256)
	Create with custom connection function.

void	add_point (const LineVertex &point)
	Add point to topology.

void	remove_point (size_t index)
	Remove point by index.

void	update_point (size_t index, const LineVertex &point)
	Update point data.

void	set_points (const std::vector< LineVertex > &points)
	Set all points at once.

void	clear ()
	Clear all points and connections.

void	regenerate_topology ()
	Manually trigger connection regeneration.

void	set_connection_mode (Kinesis::ProximityMode mode)
	Set connection mode.

void	set_auto_connect (bool enable)
	Enable/disable automatic connection regeneration.

void	set_k_neighbors (size_t k)
	Set K parameter for K_NEAREST mode.

void	set_connection_radius (float radius)
	Set radius for RADIUS_THRESHOLD mode.

void	set_line_color (const glm::vec3 &color, bool force_uniform=true)
	Set line color (applied to all connections)

glm::vec3	get_line_color () const
	Get current line color.

void	force_uniform_color (bool should_force)
	Force uniform color for all vertices.

bool	should_force_uniform_color () const
	Check if uniform color is forced.

void	set_line_thickness (float thickness, bool force_uniform=true)
	Set line thickness.

void	force_uniform_thickness (bool should_force)
	Force uniform thickness for all vertices.

size_t	get_point_count () const
	Get point count.

size_t	get_connection_count () const
	Get connection count (edge count)

size_t	get_vertex_count () const
	Get total vertex count (after interpolation)

const LineVertex &	get_point (size_t index) const
	Get point by index.

std::vector< LineVertex >	get_points () const
	Get all points.

const std::vector< std::pair< size_t, size_t > > &	get_connections () const
	Get connection edges (pairs of point indices)

void	compute_frame () override
	Compute frame - generates vertex data from points and connections.

void	set_path_interpolation_mode (Kinesis::InterpolationMode mode)
	Set custom connection function (for CUSTOM mode)

void	set_samples_per_segment (size_t samples)
	Set number of samples per segment for interpolation.

void	set_arc_length_reparameterization (bool enable)
	Enable or disable arc-length reparameterization for interpolation.

void	set_primitive_topology (Portal::Graphics::PrimitiveTopology topology)
	Set primitive topology for rendering.

Portal::Graphics::PrimitiveTopology	get_primitive_topology () const override
	Get primitive topology for rendering.

Public Member Functions inherited from MayaFlux::Nodes::GpuSync::GeometryWriterNode
	GeometryWriterNode (uint32_t initial_capacity=1024)
	Constructor.

	~GeometryWriterNode () override=default

std::vector< double >	process_batch (unsigned int num_samples) override
	Process batch for geometry generation.

std::span< const uint8_t >	get_vertex_data () const
	Get raw vertex buffer data.

size_t	get_vertex_buffer_size_bytes () const
	Get vertex buffer size in bytes.

uint32_t	get_vertex_count () const
	Get number of vertices.

size_t	get_vertex_stride () const
	Get stride (bytes per vertex)

void	set_vertex_stride (size_t stride)
	Set vertex stride (bytes per vertex)

void	resize_vertex_buffer (uint32_t vertex_count, bool preserve_data=false)
	Resize vertex buffer to hold specified number of vertices.

void	set_vertex_data (const void *data, size_t size_bytes)
	Copy raw vertex data into buffer.

void	set_vertex (uint32_t vertex_index, const void *data, size_t size_bytes)
	Set a single vertex by index.

std::span< const uint8_t >	get_vertex (uint32_t vertex_index) const
	Get a single vertex by index.

template<typename T >
void	set_vertices (std::span< const T > vertices)
	Set multiple vertices from typed array.

template<typename T >
void	set_vertex_typed (uint32_t index, const T &vertex)
	Set a single vertex by index from typed data.

template<typename T >
T	get_vertex_typed (uint32_t index) const
	Get a single vertex by index as typed data.

void	clear ()
	Clear vertex buffer and reset count.

void	clear_and_resize (uint32_t vertex_count)
	Clear vertex buffer and resize to specified count.

void	set_vertex_layout (const Kakshya::VertexLayout &layout)
	Set cached vertex layout.

std::optional< Kakshya::VertexLayout >	get_vertex_layout () const
	Get cached vertex layout.

bool	needs_layout_update () const
	Check if layout needs update.

void	clear_layout_update_flag ()
	Clear layout update flag.

void	save_state () override
	Save current geometry state.

void	restore_state () override
	Restore saved geometry state.

bool	needs_gpu_update () const override
	Check if vertex data or layout changed since last GPU sync.

bool	needs_vertex_data_update () const
	Check if vertex data has changed since last GPU sync.

void	mark_vertex_data_dirty (bool state)
	Set vertex data dirty flag.

void	clear_gpu_update_flag () override
	Clear the dirty flag after GPU upload completes.

NodeContext &	get_last_context () override
	Retrieves the last created context object.

void	update_context (double value) override
	Updates the context object with the current node state.

Public Member Functions inherited from MayaFlux::Nodes::GpuSync::GpuSync
	~GpuSync () override=default

double	process_sample (double) override
	Single sample processing hook.

std::vector< double >	process_batch (unsigned int num_samples) override
	Batch processing for GPU nodes.

Public Member Functions inherited from MayaFlux::Nodes::Node
virtual	~Node ()=default
	Virtual destructor for proper cleanup of derived classes.

virtual void	on_tick (const NodeHook &callback)
	Registers a callback to be called on each tick.

virtual void	on_tick_if (const NodeCondition &condition, const NodeHook &callback)
	Registers a conditional callback.

virtual bool	remove_hook (const NodeHook &callback)
	Removes a previously registered callback.

virtual bool	remove_conditional_hook (const NodeCondition &callback)
	Removes a previously registered conditional callback.

virtual void	remove_all_hooks ()
	Removes all registered callbacks.

virtual void	reset_processed_state ()
	Resets the processed state of the node and any attached input nodes.

virtual double	get_last_output ()
	Retrieves the most recent output value produced by the node.

void	register_channel_usage (uint32_t channel_id)
	Mark the specificed channel as a processor/user.

void	unregister_channel_usage (uint32_t channel_id)
	Removes the specified channel from the usage tracking.

bool	is_used_by_channel (uint32_t channel_id) const
	Checks if the node is currently used by a specific channel.

void	request_reset_from_channel (uint32_t channel_id)
	Requests a reset of the processed state from a specific channel.

const std::atomic< uint32_t > &	get_channel_mask () const
	Retrieves the current bitmask of active channels using this node.

void	set_gpu_compatible (bool compatible)
	Sets whether the node is compatible with GPU processing.

bool	is_gpu_compatible () const
	Checks if the node supports GPU processing.

std::span< const float >	get_gpu_data_buffer () const
	Provides access to the GPU data buffer.

void	set_sample_rate (uint32_t sample_rate)

uint32_t	get_sample_rate () const

bool	try_claim_snapshot_context (uint64_t context_id)
	Attempt to claim snapshot context for this processing cycle.

bool	is_in_snapshot_context (uint64_t context_id) const
	Check if currently in a snapshot context.

void	release_snapshot_context (uint64_t context_id)
	Release snapshot context.

bool	has_active_snapshot () const
	Check if node is currently being snapshotted by any context.

uint64_t	get_active_snapshot_context () const
	Get the active snapshot context ID.

void	add_buffer_reference ()
	Increments the buffer reference count This method is called when a new buffer starts using this node to ensure proper lifecycle management.

void	remove_buffer_reference ()
	Decrements the buffer reference count This method is called when a buffer stops using this node to ensure proper lifecycle management.

bool	mark_buffer_processed ()
	Marks the node as having been processed by a buffer.

void	request_buffer_reset ()
	Requests a reset of the buffer state.

bool	is_buffer_processed () const
	Checks if the buffer has been processed.

bool	is_in_network () const
	Sets whether the node is part of a NodeNetwork.

void	set_in_network (bool networked)
	Marks the node as being part of a NodeNetwork.

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

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

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

Private Member Functions
void	build_vertex_buffer ()

void	build_interpolated_path (std::span< LineVertex > points, size_t num_points)

void	build_direct_connections (std::span< LineVertex > points, size_t num_points)

Eigen::MatrixXd	points_to_eigen () const

Private Attributes
Kinesis::ProximityMode	m_mode

CustomConnectionFunction	m_custom_func

Memory::HistoryBuffer< LineVertex >	m_points

std::vector< LineVertex >	m_vertices

std::vector< std::pair< size_t, size_t > >	m_connections

Kinesis::InterpolationMode	m_path_interpolation_mode { Kinesis::InterpolationMode::CATMULL_ROM }

Portal::Graphics::PrimitiveTopology	m_primitive_topology { Portal::Graphics::PrimitiveTopology::LINE_LIST }

size_t	m_samples_per_segment { 20 }
	Controls smoothness vs performance.

bool	m_use_arc_length_reparameterization {}
	Optional constant-speed.

bool	m_auto_connect

size_t	m_k_neighbors { 3 }

float	m_connection_radius { 1.0F }

glm::vec3	m_line_color { 1.0F, 1.0F, 1.0F }

float	m_line_thickness { 1.0F }

bool	m_force_uniform_color {}
	If true, all vertices use m_line_color instead of per-vertex color.

bool	m_force_uniform_thickness {}
	If true, all vertices use m_line_thickness instead of per-vertex thickness.

Additional Inherited Members
Public Attributes inherited from MayaFlux::Nodes::Node
bool	m_fire_events_during_snapshot = false
	Internal flag controlling whether notify_tick fires during state snapshots Default: false (events don't fire during isolated buffer processing) Can be exposed in future if needed via concrete implementation in parent.

std::atomic< NodeState >	m_state { NodeState::INACTIVE }
	Atomic state flag tracking the node's processing status.

std::atomic< uint32_t >	m_modulator_count { 0 }
	Counter tracking how many other nodes are using this node as a modulator.

Protected Member Functions inherited from MayaFlux::Nodes::GpuSync::GpuSync
void	notify_tick (double) override
	GPU sync nodes don't emit tick callbacks.

Protected Member Functions inherited from MayaFlux::Nodes::Node
virtual void	reset_processed_state_internal ()
	Resets the processed state of the node directly.

Protected Attributes inherited from MayaFlux::Nodes::GpuSync::GeometryWriterNode
std::vector< uint8_t >	m_vertex_buffer
	Vertex data buffer (flat array of bytes)

uint32_t	m_vertex_count {}
	Number of vertices in buffer.

size_t	m_vertex_stride {}
	Bytes per vertex (stride for vertex buffer binding)

std::optional< Kakshya::VertexLayout >	m_vertex_layout
	Cached vertex layout for descriptor binding.

bool	m_needs_layout_update {}
	Flag indicating if layout needs update.

bool	m_vertex_data_dirty { true }
	Flag: vertex data or layout changed since last GPU upload.

GeometryContext	m_context { 0.0, {}, 0, 0 }

Protected Attributes inherited from MayaFlux::Nodes::Node
double	m_last_output { 0 }
	The most recent sample value generated by this oscillator.

bool	m_gpu_compatible {}
	Flag indicating if the node supports GPU processing This flag is set by derived classes to indicate whether the node can be processed on the GPU.

std::vector< float >	m_gpu_data_buffer
	GPU data buffer for context objects.

std::vector< NodeHook >	m_callbacks
	Collection of standard callback functions.

std::vector< std::pair< NodeHook, NodeCondition > >	m_conditional_callbacks
	Collection of conditional callback functions with their predicates.

bool	m_networked_node {}
	Flag indicating if the node is part of a NodeNetwork This flag is used to disable event firing when the node is managed within a NodeNetwork, preventing redundant or conflicting event notifications.

bool	m_state_saved {}
	tracks if the node's state has been saved by a snapshot operation

uint32_t	m_sample_rate { 48000 }
	Sample rate for audio processing, used for normalization.

Detailed Description

Generates dynamic mesh topology from sparse control points.

Core concept: Points define locations, ConnectionMode defines relationships. Every time points are added/removed/moved, topology is regenerated.

Philosophy:

Points are spatial anchors
Connections emerge from geometric relationships
Topology IS the content, not decoration

Extensions beyond connections:

Attractor mode: Points influence field, no lines
Gradient mode: Points define texture sampling positions
Emitter mode: Points spawn particles

Usage:

auto topo = std::make_shared<TopologyGenerator>(
    Kinesis::ProximityMode::K_NEAREST,
    true  // auto_connect
);
 
topo->add_point({glm::vec3(0.0f, 0.0f, 0.0f)});
topo->add_point({glm::vec3(1.0f, 0.0f, 0.0f)});
topo->add_point({glm::vec3(0.5f, 1.0f, 0.0f)});
// Delaunay triangulation automatically computed
 
auto buffer = std::make_shared<GeometryBuffer>(topo);
buffer->setup_rendering({
    .target_window = window,
    .topology = PrimitiveTopology::LINE_LIST  // or TRIANGLE_LIST
});

WARNING: Performance Characteristics

Connection algorithms vary significantly in computational complexity. Topology is fully regenerated when points change.

Complexity Overview:

Sequential Chain: O(n)
Radius Threshold: O(n²)
K-Nearest Neighbors: O(n² log k)
Minimum Spanning Tree: O(n² log n)
Gabriel Graph: O(n³)
Relative Neighborhood: O(n³)

Practical Real-Time Guidance (approximate):

Sequential: thousands of points
Radius / KNN: a few hundred points
Gabriel / RNG: tens of points for interactive updates

Batch Update Pattern for Expensive Modes:

std::vector<Point> points; for (...) { points.push_back({position, color}); } topo->set_points(points); // Single O(n³) rebuild

Interactive Drawing Note:

When adding points continuously (e.g. mouse-move drawing), prefer SEQUENTIAL, RADIUS_THRESHOLD, or small-k K_NEAREST modes.

TopologyGeneratorNode prioritizes correctness and determinism over incremental graph maintenance. Expensive modes are intended for moderate point counts or batch generation.

Definition at line 83 of file TopologyGeneratorNode.hpp.

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

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Complexity Overview:

Practical Real-Time Guidance (approximate):

Batch Update Pattern for Expensive Modes:

Interactive Drawing Note: