Trait AudioNode 

pub trait AudioNode {
    type Configuration: Default;

    // Required methods
    fn info(&self, configuration: &Self::Configuration) -> AudioNodeInfo;
    fn construct_processor(
        &self,
        configuration: &Self::Configuration,
        cx: ConstructProcessorContext<'_>,
    ) -> impl AudioNodeProcessor;

    // Provided method
    fn update(
        &mut self,
        configuration: &Self::Configuration,
        cx: UpdateContext<'_>,
    ) { ... }
}

A trait representing a node in a Firewheel audio graph.

Notes about ECS

In order to be friendlier to ECS’s (entity component systems), it is encouraged that any struct deriving this trait be POD (plain ol’ data). If you want your audio node to be usable in the Bevy game engine, also derive bevy_ecs::prelude::Component. (You can hide this derive behind a feature flag by using #[cfg_attr(feature = "bevy", derive(bevy_ecs::prelude::Component))]).

Audio Node Lifecycle

1. The user constructs the node as POD or from a custom constructor method for that node.
2. The user adds the node to the graph using FirewheelCtx::add_node. If the node has any custom configuration, then the user passes that configuration to this method as well. In this method, the Firewheel context calls AudioNode::info to get information about the node. The node can also store any custom state in the AudioNodeInfo struct.
3. At this point the user may now call FirewheelCtx::node_state and FirewheelCtx::node_state_mut to retrieve the node’s custom state.
4. If AudioNodeInfo::call_update_method was set to true, then AudioNode::update will be called every time the Firewheel context updates. The node’s custom state is also accessible in this method.
5. When the Firewheel context is ready for the node to start processing data, it calls AudioNode::construct_processor to retrieve the realtime AudioNodeProcessor counterpart of the node. This processor counterpart is then sent to the audio thread.
6. The Firewheel processor calls AudioNodeProcessor::process whenever there is a new block of audio data to process.

WARNING: Audio nodes MUST either completely fill all output buffers with data, or return ProcessStatus::ClearAllOutputs/ProcessStatus::Bypass. Failing to do this will result in audio glitches.

7. (Graceful shutdown)

   7a. The Firewheel processor calls AudioNodeProcessor::stream_stopped. The processor is then sent back to the main thread.

   7b. If a new audio stream is started, then the context will call AudioNodeProcessor::new_stream on the main thread, and then send the processor back to the audio thread for processing.

   7c. If the Firewheel context is dropped before a new stream is started, then both the node and the processor counterpart are dropped.

8. (Audio thread crashes or stops unexpectedly) - The node’s processor counterpart may or may not be dropped. The user may try to create a new audio stream, in which case AudioNode::construct_processor might be called again. If a second processor instance is not able to be created, then the node may panic.

Required Associated Types

type Configuration: Default

A type representing this constructor’s configuration.

This is intended as a one-time configuration to be used when constructing an audio node. When no configuration is required, EmptyConfig should be used.

Required Methods

fn info(&self, configuration: &Self::Configuration) -> AudioNodeInfo

Get information about this node.

This method is only called once after the node is added to the audio graph.

fn construct_processor( &self, configuration: &Self::Configuration, cx: ConstructProcessorContext<'_>, ) -> impl AudioNodeProcessor

Construct a realtime processor for this node.

• configuration - The custom configuration of this node.
• cx - A context for interacting with the Firewheel context. This context also includes information about the audio stream.

Provided Methods

fn update(&mut self, configuration: &Self::Configuration, cx: UpdateContext<'_>)

If AudioNodeInfo::call_update_method was set to true, then the Firewheel context will call this method on every update cycle.

• configuration - The custom configuration of this node.
• cx - A context for interacting with the Firewheel context.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors