Struct FirewheelCtx 

pub struct FirewheelCtx<B: AudioBackend> { /* private fields */ }

A Firewheel context

Implementations

impl<B: AudioBackend> FirewheelCtx<B>

pub fn new(config: FirewheelConfig) -> Self

Create a new Firewheel context.

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 active_backend(&self) -> Option<&B>

Get a reference to the currently active instance of the backend. Returns None if the backend has not yet been initialized with start_stream.

pub fn active_backend_mut(&mut self) -> Option<&mut B>

Get a mutable reference to the currently active instance of the backend. Returns None if the backend has not yet been initialized with start_stream.

pub fn available_input_devices(&self) -> Vec<DeviceInfo>

Get a list of the available audio input devices.

pub fn available_output_devices(&self) -> Vec<DeviceInfo>

Get a list of the available audio output devices.

pub fn can_start_stream(&self) -> bool

Returns true if an audio stream can be started right now.

When calling FirewheelCtx::stop_stream(), it may take some time for the old stream to be fully stopped. This method is used to check if it has been dropped yet.

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

pub fn start_stream( &mut self, config: B::Config, ) -> Result<(), StartStreamError<B::StartStreamError>>

Start an audio stream for this context. Only one audio stream can exist on a context at a time.

When calling FirewheelCtx::stop_stream(), it may take some time for the old stream to be fully stopped. Use FirewheelCtx::can_start_stream to check if it has been dropped yet.

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 stop_stream(&mut self)

Stop the audio stream in this context.

pub fn is_audio_stream_running(&self) -> bool

Returns true if there is currently a running audio stream.

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

Information about the running audio stream.

Returns None if no audio stream is currently running.

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 FirewheelCtx::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 rythm 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, FirewheelCtx::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 rythm 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.

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 audio thread is not currently running, or if the delay 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<B::StreamError>>

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 hard_clip_outputs(&self) -> bool

Whether or not outputs are being hard clipped at 0dB.

pub fn set_hard_clip_outputs( &mut self, hard_clip_outputs: bool, ) -> Result<(), UpdateError<B::StreamError>>

Set whether or not outputs should be hard clipped at 0dB to help protect the system’s speakers.

Note that most operating systems already hard clip the output, so this is usually not needed (TODO: Do research to see if this assumption is true.)

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

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

Update the firewheel context.

This must be called reguarly (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>, ) -> NodeID

Add a node to the audio graph.

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

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

pub fn remove_node( &mut self, node_id: NodeID, ) -> Result<SmallVec<[EdgeID; 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 node_info(&self, id: NodeID) -> Option<&NodeEntry>

Get information about a node in the graph.

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

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

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

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

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.

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

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

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

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

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

pub fn set_graph_channel_config( &mut self, channel_config: ChannelConfig, ) -> SmallVec<[EdgeID; 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 disconnect( &mut self, src_node: NodeID, dst_node: NodeID, ports_src_dst: &[(PortIdx, PortIdx)], ) -> bool

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.

If none of the edges existed in the graph, then false will be returned.

pub fn disconnect_all_between( &mut self, src_node: NodeID, dst_node: NodeID, ) -> SmallVec<[EdgeID; 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.

pub fn disconnect_by_edge_id(&mut self, edge_id: EdgeID) -> bool

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

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

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

Get information about the given Edge

pub fn cycle_detected(&mut self) -> bool

Runs a check to see if a cycle exists in the audio graph.

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 FirewheelCtx::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 FirewheelCtx::update.

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 FirewheelCtx::update.

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 FirewheelCtx::update. Any events scheduled between then and the next call to FirewheelCtx::update will not be canceled.

This only takes effect once FirewheelCtx::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 FirewheelCtx::update. Any events scheduled between then and the next call to FirewheelCtx::update will not be canceled.

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

impl<B: AudioBackend> FirewheelCtx<B>

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

Construct an ContextQueue for diffing.

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

Trait Implementations

impl<B: AudioBackend> Drop for FirewheelCtx<B>

fn drop(&mut self)

Executes the destructor for this type.