Struct AudioBusGraph 

pub struct AudioBusGraph { /* private fields */ }

Audio bus graph is a complex audio data processing entity; it allows you to route samples from audio sources through a chain of audio buses or directly to an audio playback device. To get a better understanding of how the audio graph works take a look the data flow diagram below:

┌────────────┐                                                        ┌────────────┐
│            │                                                        │            │
│   Source1  ├────────────┐                                ┌──────────┤   Source2  │
│            │            │                                │          │            │
└────────────┘            │                                │          └────────────┘
                          ▼                                ▼
┌────────────┐      ┌────────────┐                  ┌────────────┐    ┌────────────┐
│            │      │            │                  │            │    │            │
│   Source3  ├─────►│    Bus1    │                  │    BusN    │◄───┤   Source4  │
│            │      ├────────────┤                  ├────────────┤    │            │
└────────────┘      │            │                  │            │    └────────────┘
                    │  Effect1 │ │   ┌───────────┐  │  Effect1 │ │
                    │          │ │   │           │  │          │ │
                    │  Effect2 │ │   │  SourceN  │  │  Effect2 │ │
                    │          │ │   │           │  │          │ │
                    │  EffectN ▼ │   └─────┬─────┘  │  EffectN ▼ │
                    │            │         │        │            │
                    └─────┬──────┘         │        └─────┬──────┘
                          │                │              │
                          │                ▼              │
                          │          ┌────────────┐       │
                          │          │            │       │
                          └─────────►│   Primary  │◄──────┘
                                     ├────────────┤
                                     │            │
                                     │  Effect1 │ │
                                     │          │ │
                                     │  Effect2 │ │
                                     │          │ │
                                     │  EffectN ▼ │
                                     │            │
                                     └─────┬──────┘
                                           │
                                           │
                                           ▼
                              ┌───────────────────────────┐
                              │                           │
                              │       Output Device       │
                              │                           │
                              └───────────────────────────┘

Each audio bus is backed with data (samples) by a set of sound sources (Source1, Source2, ..) of current audio context. This data is then passed through a set of effects, which could include various filters (lowpass, highpass, bandpass, shelf filters, etc.) and complex effects such as reverberation.

By default, each audio bus graph has a single audio bus called Primary. It is mandatory to at least one audio bus. Primary bus is responsible for outputting the data to an audio playback device.

Sound source binding

Each sound source binds to an audio bus using its name; this is so called implicit binding. While it may look weird, it is actually very useful. Explicit binding requires you to know the exact handle of an audio bus to which a sound is “attached”. This makes it less convenient to re-route data from one bus to another. Implicit binding is as much more effective: all you need to do is to set a new name of a bus to which output the samples from a sound source and the engine will do the rest for you. A simple example of a such binding is something like this:

let context = SoundContext::new();
let mut state = context.state();

let sfx_bus = AudioBus::new("SFX".to_string());
let bus_graph = state.bus_graph_mut();
let primary_bus = bus_graph.primary_bus_handle();
bus_graph.add_bus(sfx_bus, primary_bus);

// Create a source and implicitly bind to the SFX audio bus. By default each source
// is bound to the primary audio bus.
state.add_source(SoundSourceBuilder::new().with_bus("SFX").build().unwrap());

If you delete an audio bus to which a bunch of sound sources is bound, then they will simply stop playing.

Implementations

impl AudioBusGraph

pub const BUSES: &'static str = "buses"

pub const ROOT: &'static str = "root"

impl AudioBusGraph

pub const PRIMARY_BUS: &'static str = "Primary"

The name of the audio bus that output samples directly to an audio playback device.

pub fn new() -> AudioBusGraph

Creates a new audio bus graph. Sound context already has an audio graph instance, so calling this method is needed only for very specific cases (mostly tests).

pub fn add_bus( &mut self, bus: AudioBus, parent: Handle<AudioBus>, ) -> Handle<AudioBus>

Adds a new audio bus to the graph and attaches it to the given parent. parent handle must be valid, otherwise the method will panic. In most cases you can use primary bus as a parent.

Examples

use fyrox_sound::bus::{AudioBus, AudioBusGraph};

// By default it has one primary audio bus.
let mut graph = AudioBusGraph::new();

// Add another bus to the graph and attach it to the primary bus.
let primary_bus_handle = graph.primary_bus_handle();
graph.add_bus(AudioBus::new("SFX".to_owned()), primary_bus_handle);

pub fn link_buses(&mut self, child: Handle<AudioBus>, parent: Handle<AudioBus>)

Attaches the child audio bus to the parent audio bus. Important: this method does not checks for any loops, adding any loops to the graph will cause infinite loop in the mixer thread.

pub fn remove_bus(&mut self, handle: Handle<AudioBus>) -> AudioBus

Removes an audio bus at the given handle.

pub fn primary_bus_handle(&self) -> Handle<AudioBus>

Returns a handle of the primary audio bus. Primary bus outputs its samples directly to an audio playback device.

pub fn primary_bus_ref(&self) -> &AudioBus

Returns a reference to the primary audio bus.

pub fn primary_bus_mut(&mut self) -> &mut AudioBus

Returns a reference to the primary audio bus.

pub fn try_get_bus_ref(&self, handle: Handle<AudioBus>) -> Option<&AudioBus>

Tries to borrow an audio bus by its handle.

pub fn try_get_bus_mut( &mut self, handle: Handle<AudioBus>, ) -> Option<&mut AudioBus>

Tries to borrow an audio bus by its handle.

pub fn len(&self) -> usize

Returns total amount of audio buses in the graph.

pub fn is_empty(&self) -> bool

Checks if the graph is empty.

pub fn try_take_reserve_bus( &mut self, handle: Handle<AudioBus>, ) -> Option<(Ticket<AudioBus>, AudioBus)>

Tries to move out an audio bus with a promise that it will be returned back. See Pool::try_take_reserve method docs for more info.

pub fn put_bus_back( &mut self, ticket: Ticket<AudioBus>, bus: AudioBus, ) -> Handle<AudioBus>

Puts the audio bus back to graph on its previous place by the given ticket. See Pool::put_back method docs for more info.

pub fn forget_bus_ticket(&mut self, ticket: Ticket<AudioBus>)

Forget an audio bus ticket making the respective handle free again. See Pool::forget_ticket method docs for more info.

pub fn buses_iter(&self) -> impl Iterator<Item = &AudioBus>

Returns an iterator over each audio bus in the graph.

pub fn buses_iter_mut(&mut self) -> impl Iterator<Item = &mut AudioBus>

Returns an iterator over each audio bus in the graph.

pub fn buses_pair_iter( &self, ) -> impl Iterator<Item = (Handle<AudioBus>, &AudioBus)>

Returns an iterator yielding a pair of handle and a reference to each audio bus in the graph.

pub fn buses_pair_iter_mut( &mut self, ) -> impl Iterator<Item = (Handle<AudioBus>, &mut AudioBus)>

Returns an iterator yielding a pair of handle and a reference to each audio bus in the graph.

Trait Implementations

impl Clone for AudioBusGraph

fn clone(&self) -> AudioBusGraph

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AudioBusGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for AudioBusGraph

fn default() -> AudioBusGraph

Returns the “default value” for a type.

impl Reflect for AudioBusGraph

where AudioBusGraph: 'static, Pool<AudioBus>: Reflect, Handle<AudioBus>: Reflect,

fn source_path() -> &'static str

fn type_name(&self) -> &'static str

fn doc(&self) -> &'static str

fn assembly_name(&self) -> &'static str

Returns a parent assembly name of the type that implements this trait. WARNING: You should use proc-macro (#[derive(Reflect)]) to ensure that this method will return correct assembly name. In other words - there’s no guarantee, that any implementation other than proc-macro will return a correct name of the assembly. Alternatively, you can use env!("CARGO_PKG_NAME") as an implementation.

fn type_assembly_name() -> &'static str

Returns a parent assembly name of the type that implements this trait. WARNING: You should use proc-macro (#[derive(Reflect)]) to ensure that this method will return correct assembly name. In other words - there’s no guarantee, that any implementation other than proc-macro will return a correct name of the assembly. Alternatively, you can use env!("CARGO_PKG_NAME") as an implementation.

fn fields_info(&self, func: &mut dyn FnMut(&[FieldInfo<'_, '_>]))

fn into_any(self: Box<AudioBusGraph>) -> Box<dyn Any>

fn set( &mut self, value: Box<dyn Reflect>, ) -> Result<Box<dyn Reflect>, Box<dyn Reflect>>

fn as_any(&self, func: &mut dyn FnMut(&(dyn Any + 'static)))

fn as_any_mut(&mut self, func: &mut dyn FnMut(&mut (dyn Any + 'static)))

fn as_reflect(&self, func: &mut dyn FnMut(&(dyn Reflect + 'static)))

fn as_reflect_mut(&mut self, func: &mut dyn FnMut(&mut (dyn Reflect + 'static)))

fn fields(&self, func: &mut dyn FnMut(&[&(dyn Reflect + 'static)]))

fn fields_mut( &mut self, func: &mut dyn FnMut(&mut [&mut (dyn Reflect + 'static)]), )

fn field( &self, name: &str, func: &mut dyn FnMut(Option<&(dyn Reflect + 'static)>), )

fn field_mut( &mut self, name: &str, func: &mut dyn FnMut(Option<&mut (dyn Reflect + 'static)>), )

fn set_field( &mut self, field: &str, value: Box<dyn Reflect>, func: &mut dyn FnMut(Result<Box<dyn Reflect>, Box<dyn Reflect>>), )

Calls user method specified with #[reflect(setter = ..)] or falls back to Reflect::field_mut

fn as_array(&self, func: &mut dyn FnMut(Option<&(dyn ReflectArray + 'static)>))

fn as_array_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectArray + 'static)>), )

fn as_list(&self, func: &mut dyn FnMut(Option<&(dyn ReflectList + 'static)>))

fn as_list_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectList + 'static)>), )

fn as_inheritable_variable( &self, func: &mut dyn FnMut(Option<&(dyn ReflectInheritableVariable + 'static)>), )

fn as_inheritable_variable_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectInheritableVariable + 'static)>), )

fn as_hash_map( &self, func: &mut dyn FnMut(Option<&(dyn ReflectHashMap + 'static)>), )

fn as_hash_map_mut( &mut self, func: &mut dyn FnMut(Option<&mut (dyn ReflectHashMap + 'static)>), )

impl Visit for AudioBusGraph

where Pool<AudioBus>: Visit, Handle<AudioBus>: Visit,

fn visit(&mut self, name: &str, visitor: &mut Visitor) -> Result<(), VisitError>

Read or write this value, depending on whether Visitor::is_reading() is true or false.