Struct FirewheelContext 

pub struct FirewheelContext { /* private fields */ }

A Firewheel context

Implementations

impl FirewheelContext

pub fn new(config: FirewheelConfig) -> Self

Create a new Firewheel context.

pub fn try_modify_graph<E: Error>( &mut self, f: impl FnOnce(&mut Self) -> Result<(), E>, ) -> Result<(), E>

Try to modify the graph. If the given closure returns an error (or if a cycle is detected), then any changes made to the graph inside the closure will be reverted.

Any custom error type can be used, though ModifyGraphError is provided for convenience.

pub fn proc_store(&self) -> Option<&ProcStore>

Get an immutable reference to the processor store.

If an audio stream is currently running, this will return None.

pub fn proc_store_mut(&mut self) -> Option<&mut ProcStore>

Get a mutable reference to the processor store.

If an audio stream is currently running, this will return None.

pub fn is_active(&self) -> bool

Returns true if the context is currently active (the FirewheelProcessor counterpart is still alive).

pub fn activate( &mut self, info: ActivateInfo, ) -> Result<FirewheelProcessor, ActivateError>

Activate the context with the given audio stream.

Use FirewheelContext::is_active to check if the context is ready to be activated.

Note, in rare cases where the audio thread crashes without cleanly dropping its contents, this may never succeed. Consider adding a timeout to avoid deadlocking.

pub fn request_deactivate(&mut self)

Request the context to be deactivated if it is active.

This does not block the current thread. It might take a while for the context to deactivate. Use FirewheelContext::is_active to check when the context has been deactivated.

Note, another way to deactivate the context is to drop the FirewheelProcessor counterpart in the audio thread.

pub fn deactivate_blocking( &mut self, timeout: Duration, ) -> Result<(), DeactivateError>

If the context is active, request the context to be deactivated and wait for the context to be deactivated before returning.

If the timeout duration has been reached and the context is still not deactivated, then an error is returned.

pub fn stream_info(&self) -> Option<&StreamInfo>

Information about the running audio stream.

Returns None if the context is not currently active.

pub fn audio_clock(&self) -> AudioClock

Get the current time of the audio clock, without accounting for the delay between when the clock was last updated and now.

For most use cases you probably want to use FirewheelContext::audio_clock_corrected instead, but this method is provided if needed.

Note, due to the nature of audio processing, this clock is is NOT synced with the system’s time (Instant::now). (Instead it is based on the amount of data that has been processed.) For applications where the timing of audio events is critical (i.e. a rhythm game), sync the game to this audio clock instead of the OS’s clock (Instant::now()).

Note, calling this method is not super cheap, so avoid calling it many times within the same game loop iteration if possible.

pub fn audio_clock_corrected(&self) -> AudioClock

Get the current time of the audio clock.

Unlike, FirewheelContext::audio_clock, this method accounts for the delay between when the audio clock was last updated and now, leading to a more accurate result for games and other applications.

If the delay could not be determined (i.e. an audio stream is not currently running), then this will assume there was no delay between when the audio clock was last updated and now.

Note, due to the nature of audio processing, this clock is is NOT synced with the system’s time (Instant::now). (Instead it is based on the amount of data that has been processed.) For applications where the timing of audio events is critical (i.e. a rhythm game), sync the game to this audio clock instead of the OS’s clock (Instant::now()).

Note, calling this method is not super cheap, so avoid calling it many times within the same game loop iteration if possible.

pub fn audio_clock_instant(&self) -> Option<Instant>

Get the instant the audio clock was last updated.

If the audio thread is not currently running, or if the instant could not be determined for any other reason, then this will return None.

Note, calling this method is not super cheap, so avoid calling it many times within the same game loop iteration if possible.

pub fn sync_transport( &mut self, transport: &TransportState, ) -> Result<(), UpdateError>

Sync the state of the musical transport.

If the message channel is full, then this will return an error.

pub fn transport_state(&self) -> &TransportState

Get the current transport state.

pub fn transport(&self) -> &TransportState

Get the current transport state.

pub fn flags(&self) -> &FirewheelFlags

The current configuration flags being used by this context.

pub fn set_flags(&mut self, flags: FirewheelFlags) -> Result<(), UpdateError>

Set the configuration flags.

This can be set while the context is active or inactive.

If the message channel is full, then this will return an error.

pub fn clipping_occurred(&self) -> bool

Returns true if both the FirewheelFlags::VALIDATE_OUTPUT_DOES_NOT_CLIP flag is set and a sample in the final output buffer fell outside the range [-1.0, 1.0].

Calling this method resets the internal flag.

pub fn profiling_data(&mut self) -> &ProfilingData

Retrieve the latest performance profiling data.

pub fn update(&mut self) -> Result<(), UpdateError>

Update the firewheel context.

This must be called regularly (i.e. once every frame).

pub fn graph_in_node_id(&self) -> NodeID

The ID of the graph input node

pub fn graph_out_node_id(&self) -> NodeID

The ID of the graph output node

pub fn add_node<T: AudioNode + 'static>( &mut self, node: T, config: Option<T::Configuration>, ) -> Result<NodeID, NodeError>

Add a node to the audio graph.

pub fn add_dyn_node<T: DynAudioNode + 'static>( &mut self, node: T, ) -> Result<NodeID, NodeError>

Add a node to the audio graph which implements the type-erased DynAudioNode trait.

pub fn add_node_bypassed<T: AudioNode + 'static>( &mut self, node: T, config: Option<T::Configuration>, bypassed: bool, ) -> Result<NodeID, NodeError>

Add a node to the audio graph with the given bypass state.

pub fn add_dyn_node_bypassed<T: DynAudioNode + 'static>( &mut self, node: T, bypassed: bool, ) -> Result<NodeID, NodeError>

Add a node with the given bypass state to the audio graph which implements the type-erased DynAudioNode trait.

pub fn remove_node( &mut self, node_id: NodeID, ) -> Result<SmallVec<[Edge; 4]>, RemoveNodeError>

Remove the given node from the audio graph.

This will automatically remove all edges from the graph that were connected to this node.

On success, this returns a list of all edges that were removed from the graph as a result of removing this node.

This will return an error if the ID is of the graph input or graph output node.

pub fn contains_node(&self, id: NodeID) -> bool

Returns true if the node exists in the graph.

pub fn node_info(&self, id: NodeID) -> Option<&NodeEntry>

Get information about a node in the graph.

If the node does not exist in the graph, then None will be returned.

pub fn node_channel_config(&self, id: NodeID) -> Option<ChannelConfig>

Get the ChannelConfig of a node in the graph.

If the node does not exist in the graph, then None will be returned.

pub fn node_state<T: 'static>(&self, id: NodeID) -> Option<&T>

Get an immutable reference to the custom state of a node.

If the node does not exist in the graph, then None will be returned.

pub fn node_state_dyn(&self, id: NodeID) -> Option<&dyn Any>

Get a type-erased, immutable reference to the custom state of a node.

If the node does not exist in the graph, then None will be returned.

pub fn node_state_mut<T: 'static>(&mut self, id: NodeID) -> Option<&mut T>

Get a mutable reference to the custom state of a node.

If the node does not exist in the graph, then None will be returned.

pub fn node_state_dyn_mut(&mut self, id: NodeID) -> Option<&mut dyn Any>

Get a type-erased, mutable reference to the custom state of a node.

If the node does not exist in the graph, then None will be returned.

pub fn nodes(&self) -> impl Iterator<Item = &NodeEntry>

Get a list of all the existing nodes in the graph.

pub fn edges(&self) -> impl Iterator<Item = &Edge>

Get a list of all the existing edges in the graph.

pub fn set_graph_channel_config( &mut self, channel_config: ChannelConfig, ) -> SmallVec<[Edge; 4]>

Set the number of input and output channels to and from the audio graph.

Returns the list of edges that were removed.

pub fn connect( &mut self, src_node: NodeID, dst_node: NodeID, ports_src_dst: &[(PortIdx, PortIdx)], check_for_cycles: bool, ) -> Result<SmallVec<[EdgeID; 4]>, AddEdgeError>

Add connections (edges) between two nodes to the graph.

• src_node - The ID of the source node.
• dst_node - The ID of the destination node.
• ports_src_dst - The port indices for each connection to make, where the first value in a tuple is the output port on src_node, and the second value in that tuple is the input port on dst_node.
• check_for_cycles - If true, then this will run a check to see if adding these edges will create a cycle in the graph, and return an error if it does. Note, checking for cycles can be quite expensive, so avoid enabling this when calling this method many times in a row.

If successful, then this returns a list of edge IDs in order.

If this returns an error, then the audio graph has not been modified.

pub fn auto_connect( &mut self, src_node: NodeID, dst_node: NodeID, check_for_cycles: bool, ) -> Result<SmallVec<[EdgeID; 4]>, AddEdgeError>

Connect two nodes in the graph, connecting output port 0 to input port 0, output port 1 to input port 1, etc.

If the number of output ports on src_node does not equal the number of input ports on dst_node, then only the first valid ports will be connected.

If successful, then this returns a list of edge IDs in order.

If this returns an error, then the audio graph has not been modified.

pub fn connect_stereo( &mut self, src_node: NodeID, dst_node: NodeID, check_for_cycles: bool, ) -> Result<SmallVec<[EdgeID; 4]>, AddEdgeError>

Connect the first two output ports of a node to the first two input ports of a second node.

• src_node - The ID of the source node.
• dst_node - The ID of the destination node.
• check_for_cycles - If true, then this will run a check to see if adding these edges will create a cycle in the graph, and return an error if it does. Note, checking for cycles can be quite expensive, so avoid enabling this when calling this method many times in a row.

Behavior

• If num_out_ports_on_src_node >= 2 && num_in_ports_on_dst_node >= 2, then src port 0 will be connected to dst port 0, and src port 1 will be connected to dst port 1.
• If num_out_ports_on_src_node == 1 && num_in_ports_on_dst_node >= 2, then src port 0 will be connected to both dst port 0 and dst port 1.
• In all other cases, an error will be returned. (Note that converting a stereo signal into a mono signal should be done with the StereoToMonoNode.)

If successful, then this returns a list of edge IDs in order.

If this returns an error, then the audio graph has not been modified.

pub fn disconnect( &mut self, src_node: NodeID, dst_node: NodeID, ports_src_dst: &[(PortIdx, PortIdx)], ) -> SmallVec<[Edge; 4]>

Remove connections (edges) between two nodes from the graph.

• src_node - The ID of the source node.
• dst_node - The ID of the destination node.
• ports_src_dst - The port indices for each connection to make, where the first value in a tuple is the output port on src_node, and the second value in that tuple is the input port on dst_node.

Returns the list of edges that were successfully removed.

pub fn disconnect_all_between( &mut self, src_node: NodeID, dst_node: NodeID, ) -> SmallVec<[Edge; 4]>

Remove all connections (edges) between two nodes in the graph.

• src_node - The ID of the source node.
• dst_node - The ID of the destination node.

Returns the list of edges that were successfully removed.

pub fn disconnect_by_edge_id(&mut self, edge_id: EdgeID) -> Option<Edge>

Remove a connection (edge) via the edge’s unique ID.

If the edge did not exist in this graph, then None will be returned.

pub fn edge(&self, edge_id: EdgeID) -> Option<&Edge>

Get information about the given Edge

pub fn cycle_detected(&mut self) -> Result<(), CompileGraphError>

Runs a check to see if a cycle exists in the audio graph. If a cycle exists, an error is returned.

Note, this method is expensive.

pub fn queue_event(&mut self, event: NodeEvent)

Queue an event to be sent to an audio node’s processor.

Note, this event will not be sent until the event queue is flushed in FirewheelContext::update.

pub fn queue_event_for(&mut self, node_id: NodeID, event: NodeEventType)

Queue an event to be sent to an audio node’s processor.

Note, this event will not be sent until the event queue is flushed in FirewheelContext::update.

pub fn queue_bypassed_for(&mut self, node_id: NodeID, bypassed: bool)

Queue a NodeEventType::SetBypassed event for the given node.

pub fn schedule_event_for( &mut self, node_id: NodeID, event: NodeEventType, time: Option<EventInstant>, )

Queue an event at a certain time, to be sent to an audio node’s processor.

If time is None, then the event will occur as soon as the node’s processor receives the event.

Note, this event will not be sent until the event queue is flushed in FirewheelContext::update.

pub fn event_queue(&mut self, id: NodeID) -> ContextQueue<'_>

Construct a ContextQueue for diffing.

Returns None if the node does not exist in the graph.

pub fn event_queue_scheduled( &mut self, id: NodeID, time: Option<EventInstant>, ) -> ContextQueue<'_>

Construct a ContextQueue for diffing, along with the event instant that any pushed events will be scheduled for.

Returns None if the node does not exist in the graph.

pub fn cancel_all_scheduled_events( &mut self, event_type: ClearScheduledEventsType, )

Cancel scheduled events for all nodes.

This will clear all events that have been scheduled since the last call to FirewheelContext::update. Any events scheduled between then and the next call to FirewheelContext::update will not be canceled.

This only takes effect once FirewheelContext::update is called.

pub fn cancel_scheduled_events_for( &mut self, node_id: NodeID, event_type: ClearScheduledEventsType, )

Cancel scheduled events for a specific node.

This will clear all events that have been scheduled since the last call to FirewheelContext::update. Any events scheduled between then and the next call to FirewheelContext::update will not be canceled.

This only takes effect once FirewheelContext::update is called.

Trait Implementations

impl Drop for FirewheelContext

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.