Struct SoundEngine 

pub struct SoundEngine { /* private fields */ }

Internal state of sound engine.

Implementations

impl SoundEngine

pub fn new() -> Arc<Mutex<Self>>

Creates new instance of a sound engine. It is possible to have multiple engine running at the same time, but you shouldn’t do this because you can create multiple contexts which should cover 99% of use cases.

Examples found in repository

examples/raw_streaming.rs (line 55)

fn main() {
    // Initialize sound engine with default output device.
    let engine = SoundEngine::new();

    // Initialize new sound context.
    let context = SoundContext::new();

    engine.lock().unwrap().add_context(context.clone());

    // Create sine wave generator
    let sine_wave = DataSource::RawStreaming(Box::new(SamplesGenerator::new()));

    let sine_wave_buffer = SoundBufferResource::new_streaming(sine_wave).unwrap();

    // Create generic source (without spatial effects) using that buffer.
    let source = GenericSourceBuilder::new()
        .with_buffer(sine_wave_buffer)
        .with_status(Status::Playing)
        .build_source()
        .unwrap();

    context.state().add_source(source);

    // Play sound for some time.
    thread::sleep(Duration::from_secs(10));
}

examples/streaming.rs (line 13)

fn main() {
    // Initialize sound engine with default output device.
    let engine = SoundEngine::new();

    // Initialize new sound context.
    let context = SoundContext::new();

    engine.lock().unwrap().add_context(context.clone());

    // Load sound buffer.
    let waterfall_buffer = SoundBufferResource::new_streaming(
        block_on(DataSource::from_file("examples/data/waterfall.ogg")).unwrap(),
    )
    .unwrap();

    // Create flat source (without spatial effects) using that buffer.
    let source = GenericSourceBuilder::new()
        .with_buffer(waterfall_buffer)
        .with_status(Status::Playing)
        .with_looping(true)
        .build_source()
        .unwrap();

    // Each sound sound must be added to context, context takes ownership on source
    // and returns pool handle to it by which it can be accessed later on if needed.
    let _source_handle: Handle<SoundSource> = context.state().add_source(source);

    thread::sleep(Duration::from_secs(30))
}

examples/play_sound.rs (line 12)

fn main() {
    // Initialize sound engine with default output device.
    let engine = SoundEngine::new();

    // Create new context.
    let context = SoundContext::new();

    // Register context in the engine.
    engine.lock().unwrap().add_context(context.clone());

    // Load sound buffer.
    let door_open_buffer = SoundBufferResource::new_generic(
        rg3d_sound::futures::executor::block_on(DataSource::from_file(
            "examples/data/door_open.wav",
        ))
        .unwrap(),
    )
    .unwrap();

    // Create generic source (without spatial effects) using that buffer.
    let source = GenericSourceBuilder::new()
        .with_buffer(door_open_buffer)
        .with_status(Status::Playing)
        .build_source()
        .unwrap();

    // Each sound sound must be added to context, context takes ownership on source
    // and returns pool handle to it by which it can be accessed later on if needed.
    let _source_handle: Handle<SoundSource> = context.state().add_source(source);

    // Wait until sound will play completely.
    thread::sleep(Duration::from_secs(3));
}

examples/raw_samples.rs (line 11)

fn main() {
    // Initialize sound engine with default output device.
    let engine = SoundEngine::new();

    // Initialize new sound context.
    let context = SoundContext::new();

    engine.lock().unwrap().add_context(context.clone());

    // Create sine wave.
    let sample_rate = 44100;
    let sine_wave = DataSource::Raw {
        sample_rate,
        channel_count: 1,
        samples: {
            let frequency = 440.0;
            let amplitude = 0.75;
            (0..44100)
                .map(|i| {
                    amplitude
                        * ((2.0 * std::f32::consts::PI * i as f32 * frequency) / sample_rate as f32)
                            .sin()
                })
                .collect()
        },
    };

    let sine_wave_buffer = SoundBufferResource::new_generic(sine_wave).unwrap();

    // Create generic source (without spatial effects) using that buffer.
    let source = GenericSourceBuilder::new()
        .with_buffer(sine_wave_buffer)
        .with_status(Status::Playing)
        .with_looping(true)
        .build_source()
        .unwrap();

    context.state().add_source(source);

    // Play sound for some time.
    thread::sleep(Duration::from_secs(10));
}

examples/play_spatial_sound.rs (line 17)

fn main() {
    // Initialize sound engine with default output device.
    let engine = SoundEngine::new();

    // Initialize new sound context.
    let context = SoundContext::new();

    engine.lock().unwrap().add_context(context.clone());

    // Load sound buffer.
    let drop_buffer = SoundBufferResource::new_generic(
        block_on(DataSource::from_file("examples/data/drop.wav")).unwrap(),
    )
    .unwrap();

    // Create spatial source - spatial sources can be positioned in space.
    let source = SpatialSourceBuilder::new(
        GenericSourceBuilder::new()
            .with_buffer(drop_buffer)
            .with_looping(true)
            .with_status(Status::Playing)
            .build()
            .unwrap(),
    )
    .build_source();

    // Each sound sound must be added to context, context takes ownership on source
    // and returns pool handle to it by which it can be accessed later on if needed.
    let source_handle: Handle<SoundSource> = context.state().add_source(source);

    // Move sound around listener for some time.
    let start_time = time::Instant::now();
    let mut angle = 0.0f32;
    while (time::Instant::now() - start_time).as_secs() < 11 {
        if let SoundSource::Spatial(spatial) = context.state().source_mut(source_handle) {
            let axis = Vector3::y_axis();
            let rotation_matrix =
                UnitQuaternion::from_axis_angle(&axis, angle.to_radians()).to_homogeneous();
            spatial.set_position(
                rotation_matrix
                    .transform_point(&Point3::new(0.0, 0.0, 3.0))
                    .coords,
            );
        }
        angle += 3.6;

        // Limit rate of updates.
        thread::sleep(Duration::from_millis(100));
    }
}

examples/listener.rs (line 17)

fn main() {
    // Initialize sound engine with default output device.
    let engine = SoundEngine::new();

    // Initialize new sound context.
    let context = SoundContext::new();

    engine.lock().unwrap().add_context(context.clone());

    // Load sound buffer.
    let drop_buffer = SoundBufferResource::new_generic(
        block_on(DataSource::from_file("examples/data/drop.wav")).unwrap(),
    )
    .unwrap();

    // Create spatial source - spatial sources can be positioned in space.
    let source = SpatialSourceBuilder::new(
        GenericSourceBuilder::new()
            .with_buffer(drop_buffer)
            .with_looping(true)
            .with_status(Status::Playing)
            .build()
            .unwrap(),
    )
    .build_source();

    // Each sound sound must be added to context, context takes ownership on source
    // and returns pool handle to it by which it can be accessed later on if needed.
    context.state().add_source(source);

    // Rotate listener for some time.
    let start_time = time::Instant::now();
    let mut angle = 0.0f32;
    while (time::Instant::now() - start_time).as_secs() < 20 {
        // Separate scope for update to make sure that mutex lock will be released before
        // thread::sleep will be called so context can actually work in background thread.
        {
            let mut context = context.state();

            let listener = context.listener_mut();

            // Define up-axis of listener.
            let up = Vector3::y_axis();

            // And rotate look axis.
            let rotation_matrix =
                UnitQuaternion::from_axis_angle(&up, angle.to_radians()).to_homogeneous();
            let look = rotation_matrix
                .transform_point(&Point3::new(0.0, 0.0, 1.0))
                .coords;

            // Finally combine axes. _lh suffix here means that we using left-handed coordinate system.
            // there is also _rh (right handed) version. Also basis can be set directly by using `set_basis`
            listener.set_orientation_lh(look, *up);

            // Move listener a bit back from sound source.
            listener.set_position(Vector3::new(0.0, 0.0, -2.0));

            // Continue rotation.
            angle += 2.0;
        }

        // Limit rate of updates.
        thread::sleep(Duration::from_millis(100));
    }
}

Additional examples can be found in:

• examples/hrtf.rs
• examples/reverb.rs

pub fn without_device() -> Arc<Mutex<Self>>

Creates new instance of a sound engine without running a device thread. The user must periodically run Self::render.

Examples found in repository

examples/write_wav.rs (line 11)

fn main() {
    // Initialize sound engine without output device.
    let engine = SoundEngine::without_device();

    // Create new context.
    let context = SoundContext::new();

    // Register context in the engine.
    engine.lock().unwrap().add_context(context.clone());

    // Load sound buffer.
    let door_open_buffer = SoundBufferResource::new_generic(
        rg3d_sound::futures::executor::block_on(DataSource::from_file(
            "examples/data/door_open.wav",
        ))
        .unwrap(),
    )
    .unwrap();

    // Create generic source (without spatial effects) using that buffer.
    let source = GenericSourceBuilder::new()
        .with_buffer(door_open_buffer)
        .with_status(Status::Playing)
        .build_source()
        .unwrap();

    // Each sound sound must be added to context, context takes ownership on source
    // and returns pool handle to it by which it can be accessed later on if needed.
    let _source_handle: Handle<SoundSource> = context.state().add_source(source);

    // Create output wav file. The sample rate is currently fixed.
    let wav_spec = hound::WavSpec {
        channels: 2,
        sample_rate: rg3d_sound::context::SAMPLE_RATE,
        bits_per_sample: 32,
        sample_format: hound::SampleFormat::Float,
    };
    let mut wav_writer = hound::WavWriter::create("output.wav", wav_spec).unwrap();

    // Create an output buffer.
    let buf_len = SoundEngine::render_buffer_len();
    let mut buf = vec![(0.0f32, 0.0f32); buf_len];
    let mut samples_written = 0;

    // Wait until sound will play completely.
    while samples_written < 3 * rg3d_sound::context::SAMPLE_RATE {
        engine.lock().unwrap().render(&mut buf);
        for &(l, r) in buf.iter() {
            wav_writer.write_sample(l).unwrap();
            wav_writer.write_sample(r).unwrap();
        }
        samples_written += buf_len as u32;
    }

    wav_writer.finalize().unwrap();
}

pub fn add_context(&mut self, context: SoundContext)

Adds new context to the engine. Each context must be added to the engine to emit sounds.

Examples found in repository

examples/raw_streaming.rs (line 60)

fn main() {
    // Initialize sound engine with default output device.
    let engine = SoundEngine::new();

    // Initialize new sound context.
    let context = SoundContext::new();

    engine.lock().unwrap().add_context(context.clone());

    // Create sine wave generator
    let sine_wave = DataSource::RawStreaming(Box::new(SamplesGenerator::new()));

    let sine_wave_buffer = SoundBufferResource::new_streaming(sine_wave).unwrap();

    // Create generic source (without spatial effects) using that buffer.
    let source = GenericSourceBuilder::new()
        .with_buffer(sine_wave_buffer)
        .with_status(Status::Playing)
        .build_source()
        .unwrap();

    context.state().add_source(source);

    // Play sound for some time.
    thread::sleep(Duration::from_secs(10));
}

examples/streaming.rs (line 18)

fn main() {
    // Initialize sound engine with default output device.
    let engine = SoundEngine::new();

    // Initialize new sound context.
    let context = SoundContext::new();

    engine.lock().unwrap().add_context(context.clone());

    // Load sound buffer.
    let waterfall_buffer = SoundBufferResource::new_streaming(
        block_on(DataSource::from_file("examples/data/waterfall.ogg")).unwrap(),
    )
    .unwrap();

    // Create flat source (without spatial effects) using that buffer.
    let source = GenericSourceBuilder::new()
        .with_buffer(waterfall_buffer)
        .with_status(Status::Playing)
        .with_looping(true)
        .build_source()
        .unwrap();

    // Each sound sound must be added to context, context takes ownership on source
    // and returns pool handle to it by which it can be accessed later on if needed.
    let _source_handle: Handle<SoundSource> = context.state().add_source(source);

    thread::sleep(Duration::from_secs(30))
}

examples/play_sound.rs (line 18)

fn main() {
    // Initialize sound engine with default output device.
    let engine = SoundEngine::new();

    // Create new context.
    let context = SoundContext::new();

    // Register context in the engine.
    engine.lock().unwrap().add_context(context.clone());

    // Load sound buffer.
    let door_open_buffer = SoundBufferResource::new_generic(
        rg3d_sound::futures::executor::block_on(DataSource::from_file(
            "examples/data/door_open.wav",
        ))
        .unwrap(),
    )
    .unwrap();

    // Create generic source (without spatial effects) using that buffer.
    let source = GenericSourceBuilder::new()
        .with_buffer(door_open_buffer)
        .with_status(Status::Playing)
        .build_source()
        .unwrap();

    // Each sound sound must be added to context, context takes ownership on source
    // and returns pool handle to it by which it can be accessed later on if needed.
    let _source_handle: Handle<SoundSource> = context.state().add_source(source);

    // Wait until sound will play completely.
    thread::sleep(Duration::from_secs(3));
}

examples/raw_samples.rs (line 16)

fn main() {
    // Initialize sound engine with default output device.
    let engine = SoundEngine::new();

    // Initialize new sound context.
    let context = SoundContext::new();

    engine.lock().unwrap().add_context(context.clone());

    // Create sine wave.
    let sample_rate = 44100;
    let sine_wave = DataSource::Raw {
        sample_rate,
        channel_count: 1,
        samples: {
            let frequency = 440.0;
            let amplitude = 0.75;
            (0..44100)
                .map(|i| {
                    amplitude
                        * ((2.0 * std::f32::consts::PI * i as f32 * frequency) / sample_rate as f32)
                            .sin()
                })
                .collect()
        },
    };

    let sine_wave_buffer = SoundBufferResource::new_generic(sine_wave).unwrap();

    // Create generic source (without spatial effects) using that buffer.
    let source = GenericSourceBuilder::new()
        .with_buffer(sine_wave_buffer)
        .with_status(Status::Playing)
        .with_looping(true)
        .build_source()
        .unwrap();

    context.state().add_source(source);

    // Play sound for some time.
    thread::sleep(Duration::from_secs(10));
}

examples/play_spatial_sound.rs (line 22)

fn main() {
    // Initialize sound engine with default output device.
    let engine = SoundEngine::new();

    // Initialize new sound context.
    let context = SoundContext::new();

    engine.lock().unwrap().add_context(context.clone());

    // Load sound buffer.
    let drop_buffer = SoundBufferResource::new_generic(
        block_on(DataSource::from_file("examples/data/drop.wav")).unwrap(),
    )
    .unwrap();

    // Create spatial source - spatial sources can be positioned in space.
    let source = SpatialSourceBuilder::new(
        GenericSourceBuilder::new()
            .with_buffer(drop_buffer)
            .with_looping(true)
            .with_status(Status::Playing)
            .build()
            .unwrap(),
    )
    .build_source();

    // Each sound sound must be added to context, context takes ownership on source
    // and returns pool handle to it by which it can be accessed later on if needed.
    let source_handle: Handle<SoundSource> = context.state().add_source(source);

    // Move sound around listener for some time.
    let start_time = time::Instant::now();
    let mut angle = 0.0f32;
    while (time::Instant::now() - start_time).as_secs() < 11 {
        if let SoundSource::Spatial(spatial) = context.state().source_mut(source_handle) {
            let axis = Vector3::y_axis();
            let rotation_matrix =
                UnitQuaternion::from_axis_angle(&axis, angle.to_radians()).to_homogeneous();
            spatial.set_position(
                rotation_matrix
                    .transform_point(&Point3::new(0.0, 0.0, 3.0))
                    .coords,
            );
        }
        angle += 3.6;

        // Limit rate of updates.
        thread::sleep(Duration::from_millis(100));
    }
}

examples/write_wav.rs (line 17)

fn main() {
    // Initialize sound engine without output device.
    let engine = SoundEngine::without_device();

    // Create new context.
    let context = SoundContext::new();

    // Register context in the engine.
    engine.lock().unwrap().add_context(context.clone());

    // Load sound buffer.
    let door_open_buffer = SoundBufferResource::new_generic(
        rg3d_sound::futures::executor::block_on(DataSource::from_file(
            "examples/data/door_open.wav",
        ))
        .unwrap(),
    )
    .unwrap();

    // Create generic source (without spatial effects) using that buffer.
    let source = GenericSourceBuilder::new()
        .with_buffer(door_open_buffer)
        .with_status(Status::Playing)
        .build_source()
        .unwrap();

    // Each sound sound must be added to context, context takes ownership on source
    // and returns pool handle to it by which it can be accessed later on if needed.
    let _source_handle: Handle<SoundSource> = context.state().add_source(source);

    // Create output wav file. The sample rate is currently fixed.
    let wav_spec = hound::WavSpec {
        channels: 2,
        sample_rate: rg3d_sound::context::SAMPLE_RATE,
        bits_per_sample: 32,
        sample_format: hound::SampleFormat::Float,
    };
    let mut wav_writer = hound::WavWriter::create("output.wav", wav_spec).unwrap();

    // Create an output buffer.
    let buf_len = SoundEngine::render_buffer_len();
    let mut buf = vec![(0.0f32, 0.0f32); buf_len];
    let mut samples_written = 0;

    // Wait until sound will play completely.
    while samples_written < 3 * rg3d_sound::context::SAMPLE_RATE {
        engine.lock().unwrap().render(&mut buf);
        for &(l, r) in buf.iter() {
            wav_writer.write_sample(l).unwrap();
            wav_writer.write_sample(r).unwrap();
        }
        samples_written += buf_len as u32;
    }

    wav_writer.finalize().unwrap();
}

Additional examples can be found in:

• examples/listener.rs
• examples/hrtf.rs
• examples/reverb.rs

pub fn remove_context(&mut self, context: SoundContext)

Removes a context from the engine. Removed context will no longer produce any sound.

pub fn has_context(&self, context: &SoundContext) -> bool

Checks if a context is registered in the engine.

pub fn contexts(&self) -> &[SoundContext]

Returns a reference to context container.

pub fn set_master_gain(&mut self, master_gain: f32)

Set global sound volume in [0; 1] range.

pub fn master_gain(&self) -> f32

Returns global sound volume in [0; 1] range.

pub fn render_buffer_len() -> usize

Returns the length of buf to be passed to Self::render().

Examples found in repository

examples/write_wav.rs (line 49)

fn main() {
    // Initialize sound engine without output device.
    let engine = SoundEngine::without_device();

    // Create new context.
    let context = SoundContext::new();

    // Register context in the engine.
    engine.lock().unwrap().add_context(context.clone());

    // Load sound buffer.
    let door_open_buffer = SoundBufferResource::new_generic(
        rg3d_sound::futures::executor::block_on(DataSource::from_file(
            "examples/data/door_open.wav",
        ))
        .unwrap(),
    )
    .unwrap();

    // Create generic source (without spatial effects) using that buffer.
    let source = GenericSourceBuilder::new()
        .with_buffer(door_open_buffer)
        .with_status(Status::Playing)
        .build_source()
        .unwrap();

    // Each sound sound must be added to context, context takes ownership on source
    // and returns pool handle to it by which it can be accessed later on if needed.
    let _source_handle: Handle<SoundSource> = context.state().add_source(source);

    // Create output wav file. The sample rate is currently fixed.
    let wav_spec = hound::WavSpec {
        channels: 2,
        sample_rate: rg3d_sound::context::SAMPLE_RATE,
        bits_per_sample: 32,
        sample_format: hound::SampleFormat::Float,
    };
    let mut wav_writer = hound::WavWriter::create("output.wav", wav_spec).unwrap();

    // Create an output buffer.
    let buf_len = SoundEngine::render_buffer_len();
    let mut buf = vec![(0.0f32, 0.0f32); buf_len];
    let mut samples_written = 0;

    // Wait until sound will play completely.
    while samples_written < 3 * rg3d_sound::context::SAMPLE_RATE {
        engine.lock().unwrap().render(&mut buf);
        for &(l, r) in buf.iter() {
            wav_writer.write_sample(l).unwrap();
            wav_writer.write_sample(r).unwrap();
        }
        samples_written += buf_len as u32;
    }

    wav_writer.finalize().unwrap();
}

pub fn render(&mut self, buf: &mut [(f32, f32)])

Renders the sound into buf. The buf must have at least Self::render_buffer_len() elements. This method must be used if and only if the engine was created via Self::without_device.

Deadlocks

This method internally locks added sound contexts so it must be called when all the contexts are unlocked or you’ll get a deadlock.

Examples found in repository

examples/write_wav.rs (line 55)

fn main() {
    // Initialize sound engine without output device.
    let engine = SoundEngine::without_device();

    // Create new context.
    let context = SoundContext::new();

    // Register context in the engine.
    engine.lock().unwrap().add_context(context.clone());

    // Load sound buffer.
    let door_open_buffer = SoundBufferResource::new_generic(
        rg3d_sound::futures::executor::block_on(DataSource::from_file(
            "examples/data/door_open.wav",
        ))
        .unwrap(),
    )
    .unwrap();

    // Create generic source (without spatial effects) using that buffer.
    let source = GenericSourceBuilder::new()
        .with_buffer(door_open_buffer)
        .with_status(Status::Playing)
        .build_source()
        .unwrap();

    // Each sound sound must be added to context, context takes ownership on source
    // and returns pool handle to it by which it can be accessed later on if needed.
    let _source_handle: Handle<SoundSource> = context.state().add_source(source);

    // Create output wav file. The sample rate is currently fixed.
    let wav_spec = hound::WavSpec {
        channels: 2,
        sample_rate: rg3d_sound::context::SAMPLE_RATE,
        bits_per_sample: 32,
        sample_format: hound::SampleFormat::Float,
    };
    let mut wav_writer = hound::WavWriter::create("output.wav", wav_spec).unwrap();

    // Create an output buffer.
    let buf_len = SoundEngine::render_buffer_len();
    let mut buf = vec![(0.0f32, 0.0f32); buf_len];
    let mut samples_written = 0;

    // Wait until sound will play completely.
    while samples_written < 3 * rg3d_sound::context::SAMPLE_RATE {
        engine.lock().unwrap().render(&mut buf);
        for &(l, r) in buf.iter() {
            wav_writer.write_sample(l).unwrap();
            wav_writer.write_sample(r).unwrap();
        }
        samples_written += buf_len as u32;
    }

    wav_writer.finalize().unwrap();
}

Trait Implementations

impl Default for SoundEngine

fn default() -> SoundEngine

Returns the “default value” for a type.

impl Visit for SoundEngine

fn visit(&mut self, name: &str, visitor: &mut Visitor) -> VisitResult