Skip to main content

SpatialSourceBuilder

rg3d_sound::source::spatial

Struct SpatialSourceBuilder 

Source 
pub struct SpatialSourceBuilder { /* private fields */ }
Expand description

Spatial source builder allows you to construct new spatial sound source with desired parameters.

Implementations§

Source§

impl SpatialSourceBuilder

Source

pub fn new(generic: GenericSource) -> Self

Creates new spatial source builder from given generic source which. Generic source can be created using GenericSourceBuilder. See module docs for example.

Examples found in repository?
examples/play_spatial_sound.rs (lines 31-38)
15fn main() {
16    // Initialize sound engine with default output device.
17    let engine = SoundEngine::new();
18
19    // Initialize new sound context.
20    let context = SoundContext::new();
21
22    engine.lock().unwrap().add_context(context.clone());
23
24    // Load sound buffer.
25    let drop_buffer = SoundBufferResource::new_generic(
26        block_on(DataSource::from_file("examples/data/drop.wav")).unwrap(),
27    )
28    .unwrap();
29
30    // Create spatial source - spatial sources can be positioned in space.
31    let source = SpatialSourceBuilder::new(
32        GenericSourceBuilder::new()
33            .with_buffer(drop_buffer)
34            .with_looping(true)
35            .with_status(Status::Playing)
36            .build()
37            .unwrap(),
38    )
39    .build_source();
40
41    // Each sound sound must be added to context, context takes ownership on source
42    // and returns pool handle to it by which it can be accessed later on if needed.
43    let source_handle: Handle<SoundSource> = context.state().add_source(source);
44
45    // Move sound around listener for some time.
46    let start_time = time::Instant::now();
47    let mut angle = 0.0f32;
48    while (time::Instant::now() - start_time).as_secs() < 11 {
49        if let SoundSource::Spatial(spatial) = context.state().source_mut(source_handle) {
50            let axis = Vector3::y_axis();
51            let rotation_matrix =
52                UnitQuaternion::from_axis_angle(&axis, angle.to_radians()).to_homogeneous();
53            spatial.set_position(
54                rotation_matrix
55                    .transform_point(&Point3::new(0.0, 0.0, 3.0))
56                    .coords,
57            );
58        }
59        angle += 3.6;
60
61        // Limit rate of updates.
62        thread::sleep(Duration::from_millis(100));
63    }
64}
More examples
Hide additional examples
examples/listener.rs (lines 31-38)
15fn main() {
16    // Initialize sound engine with default output device.
17    let engine = SoundEngine::new();
18
19    // Initialize new sound context.
20    let context = SoundContext::new();
21
22    engine.lock().unwrap().add_context(context.clone());
23
24    // Load sound buffer.
25    let drop_buffer = SoundBufferResource::new_generic(
26        block_on(DataSource::from_file("examples/data/drop.wav")).unwrap(),
27    )
28    .unwrap();
29
30    // Create spatial source - spatial sources can be positioned in space.
31    let source = SpatialSourceBuilder::new(
32        GenericSourceBuilder::new()
33            .with_buffer(drop_buffer)
34            .with_looping(true)
35            .with_status(Status::Playing)
36            .build()
37            .unwrap(),
38    )
39    .build_source();
40
41    // Each sound sound must be added to context, context takes ownership on source
42    // and returns pool handle to it by which it can be accessed later on if needed.
43    context.state().add_source(source);
44
45    // Rotate listener for some time.
46    let start_time = time::Instant::now();
47    let mut angle = 0.0f32;
48    while (time::Instant::now() - start_time).as_secs() < 20 {
49        // Separate scope for update to make sure that mutex lock will be released before
50        // thread::sleep will be called so context can actually work in background thread.
51        {
52            let mut context = context.state();
53
54            let listener = context.listener_mut();
55
56            // Define up-axis of listener.
57            let up = Vector3::y_axis();
58
59            // And rotate look axis.
60            let rotation_matrix =
61                UnitQuaternion::from_axis_angle(&up, angle.to_radians()).to_homogeneous();
62            let look = rotation_matrix
63                .transform_point(&Point3::new(0.0, 0.0, 1.0))
64                .coords;
65
66            // Finally combine axes. _lh suffix here means that we using left-handed coordinate system.
67            // there is also _rh (right handed) version. Also basis can be set directly by using `set_basis`
68            listener.set_orientation_lh(look, *up);
69
70            // Move listener a bit back from sound source.
71            listener.set_position(Vector3::new(0.0, 0.0, -2.0));
72
73            // Continue rotation.
74            angle += 2.0;
75        }
76
77        // Limit rate of updates.
78        thread::sleep(Duration::from_millis(100));
79    }
80}
examples/hrtf.rs (lines 39-45)
17fn main() {
18    // Initialize sound engine with default output device.
19    let engine = SoundEngine::new();
20
21    let hrir_sphere =
22        HrirSphere::from_file("examples/data/IRC_1002_C.bin", context::SAMPLE_RATE).unwrap();
23
24    // Initialize new sound context with default output device.
25    let context = SoundContext::new();
26
27    engine.lock().unwrap().add_context(context.clone());
28
29    // Set HRTF renderer instead of default.
30    context
31        .state()
32        .set_renderer(Renderer::HrtfRenderer(HrtfRenderer::new(hrir_sphere)));
33
34    // Create some sounds.
35    let sound_buffer = SoundBufferResource::new_generic(
36        block_on(DataSource::from_file("examples/data/door_open.wav")).unwrap(),
37    )
38    .unwrap();
39    let source = SpatialSourceBuilder::new(
40        GenericSourceBuilder::new()
41            .with_buffer(sound_buffer)
42            .with_status(Status::Playing)
43            .build()
44            .unwrap(),
45    )
46    .build_source();
47    context.state().add_source(source);
48
49    let sound_buffer = SoundBufferResource::new_generic(
50        block_on(DataSource::from_file("examples/data/helicopter.wav")).unwrap(),
51    )
52    .unwrap();
53    let source = SpatialSourceBuilder::new(
54        GenericSourceBuilder::new()
55            .with_buffer(sound_buffer)
56            .with_status(Status::Playing)
57            .with_looping(true)
58            .build()
59            .unwrap(),
60    )
61    .build_source();
62    let source_handle = context.state().add_source(source);
63
64    // Move source sound around listener for some time.
65    let start_time = time::Instant::now();
66    let mut angle = 0.0f32;
67    while (time::Instant::now() - start_time).as_secs() < 360 {
68        // Separate scope for update to make sure that mutex lock will be released before
69        // thread::sleep will be called so context can actually work in background thread.
70        {
71            if let SoundSource::Spatial(spatial) = context.state().source_mut(source_handle) {
72                let axis = Vector3::y_axis();
73                let rotation_matrix =
74                    UnitQuaternion::from_axis_angle(&axis, angle.to_radians()).to_homogeneous();
75                spatial.set_position(
76                    rotation_matrix
77                        .transform_point(&Point3::new(0.0, 0.0, 3.0))
78                        .coords,
79                );
80            }
81
82            angle += 1.6;
83
84            println!(
85                "Sound render time {:?}",
86                context.state().full_render_duration()
87            );
88        }
89
90        // Limit rate of updates.
91        thread::sleep(Duration::from_millis(100));
92    }
93}
examples/reverb.rs (lines 46-52)
17fn main() {
18    let hrir_sphere =
19        HrirSphere::from_file("examples/data/IRC_1002_C.bin", context::SAMPLE_RATE).unwrap();
20
21    // Initialize sound engine with default output device.
22    let engine = SoundEngine::new();
23
24    // Initialize new sound context.
25    let context = SoundContext::new();
26
27    engine.lock().unwrap().add_context(context.clone());
28
29    // Set HRTF renderer instead of default for binaural sound.
30    context
31        .state()
32        .set_renderer(Renderer::HrtfRenderer(HrtfRenderer::new(hrir_sphere)));
33
34    let base_effect = BaseEffect::default();
35
36    // Create reverb effect and set its decay time.
37    let mut reverb = Reverb::new(base_effect);
38    reverb.set_decay_time(Duration::from_secs_f32(10.0));
39    let reverb_handle = context.state().add_effect(Effect::Reverb(reverb));
40
41    // Create some sounds.
42    let sound_buffer = SoundBufferResource::new_generic(
43        block_on(DataSource::from_file("examples/data/door_open.wav")).unwrap(),
44    )
45    .unwrap();
46    let source = SpatialSourceBuilder::new(
47        GenericSourceBuilder::new()
48            .with_buffer(sound_buffer)
49            .with_status(Status::Playing)
50            .build()
51            .unwrap(),
52    )
53    .build_source();
54    let door_sound = context.state().add_source(source);
55
56    // Each sound source must be attached to effect, otherwise sound won't be passed to effect
57    // and you'll hear sound without any difference.
58    context
59        .state()
60        .effect_mut(reverb_handle)
61        .add_input(EffectInput::direct(door_sound));
62
63    let sound_buffer = SoundBufferResource::new_generic(
64        block_on(DataSource::from_file("examples/data/drop.wav")).unwrap(),
65    )
66    .unwrap();
67    let source = SpatialSourceBuilder::new(
68        GenericSourceBuilder::new()
69            .with_buffer(sound_buffer)
70            .with_status(Status::Playing)
71            .with_looping(true)
72            .build()
73            .unwrap(),
74    )
75    .build_source();
76    let drop_sound_handle = context.state().add_source(source);
77
78    context
79        .state()
80        .effect_mut(reverb_handle)
81        .add_input(EffectInput::direct(drop_sound_handle));
82
83    // Move sound around listener for some time.
84    let start_time = time::Instant::now();
85    let mut angle = 0.0f32;
86    while (time::Instant::now() - start_time).as_secs() < 360 {
87        if let SoundSource::Spatial(sound) = context.state().source_mut(drop_sound_handle) {
88            let axis = Vector3::y_axis();
89            let rotation_matrix =
90                UnitQuaternion::from_axis_angle(&axis, angle.to_radians()).to_homogeneous();
91            sound.set_position(
92                rotation_matrix
93                    .transform_point(&Point3::new(0.0, 0.0, 1.0))
94                    .coords,
95            );
96        }
97
98        angle += 1.6;
99
100        println!(
101            "Sound render time {:?}",
102            context.state().full_render_duration()
103        );
104
105        // Limit rate of context updates.
106        thread::sleep(Duration::from_millis(100));
107    }
108}
Source

pub fn with_position(self, position: Vector3<f32>) -> Self

See set_position of SpatialSource.

Source

pub fn with_radius(self, radius: f32) -> Self

See set_radius of SpatialSource.

Source

pub fn with_max_distance(self, max_distance: f32) -> Self

See set_max_distance of SpatialSource.

Source

pub fn with_rolloff_factor(self, rolloff_factor: f32) -> Self

See set_rolloff_factor of SpatialSource.

Source

pub fn build(self) -> SpatialSource

Creates new instance of spatial sound source.

Source

pub fn build_source(self) -> SoundSource

Creates new instance of sound source of Spatial variant.

Examples found in repository?
examples/play_spatial_sound.rs (line 39)
15fn main() {
16    // Initialize sound engine with default output device.
17    let engine = SoundEngine::new();
18
19    // Initialize new sound context.
20    let context = SoundContext::new();
21
22    engine.lock().unwrap().add_context(context.clone());
23
24    // Load sound buffer.
25    let drop_buffer = SoundBufferResource::new_generic(
26        block_on(DataSource::from_file("examples/data/drop.wav")).unwrap(),
27    )
28    .unwrap();
29
30    // Create spatial source - spatial sources can be positioned in space.
31    let source = SpatialSourceBuilder::new(
32        GenericSourceBuilder::new()
33            .with_buffer(drop_buffer)
34            .with_looping(true)
35            .with_status(Status::Playing)
36            .build()
37            .unwrap(),
38    )
39    .build_source();
40
41    // Each sound sound must be added to context, context takes ownership on source
42    // and returns pool handle to it by which it can be accessed later on if needed.
43    let source_handle: Handle<SoundSource> = context.state().add_source(source);
44
45    // Move sound around listener for some time.
46    let start_time = time::Instant::now();
47    let mut angle = 0.0f32;
48    while (time::Instant::now() - start_time).as_secs() < 11 {
49        if let SoundSource::Spatial(spatial) = context.state().source_mut(source_handle) {
50            let axis = Vector3::y_axis();
51            let rotation_matrix =
52                UnitQuaternion::from_axis_angle(&axis, angle.to_radians()).to_homogeneous();
53            spatial.set_position(
54                rotation_matrix
55                    .transform_point(&Point3::new(0.0, 0.0, 3.0))
56                    .coords,
57            );
58        }
59        angle += 3.6;
60
61        // Limit rate of updates.
62        thread::sleep(Duration::from_millis(100));
63    }
64}
More examples
Hide additional examples
examples/listener.rs (line 39)
15fn main() {
16    // Initialize sound engine with default output device.
17    let engine = SoundEngine::new();
18
19    // Initialize new sound context.
20    let context = SoundContext::new();
21
22    engine.lock().unwrap().add_context(context.clone());
23
24    // Load sound buffer.
25    let drop_buffer = SoundBufferResource::new_generic(
26        block_on(DataSource::from_file("examples/data/drop.wav")).unwrap(),
27    )
28    .unwrap();
29
30    // Create spatial source - spatial sources can be positioned in space.
31    let source = SpatialSourceBuilder::new(
32        GenericSourceBuilder::new()
33            .with_buffer(drop_buffer)
34            .with_looping(true)
35            .with_status(Status::Playing)
36            .build()
37            .unwrap(),
38    )
39    .build_source();
40
41    // Each sound sound must be added to context, context takes ownership on source
42    // and returns pool handle to it by which it can be accessed later on if needed.
43    context.state().add_source(source);
44
45    // Rotate listener for some time.
46    let start_time = time::Instant::now();
47    let mut angle = 0.0f32;
48    while (time::Instant::now() - start_time).as_secs() < 20 {
49        // Separate scope for update to make sure that mutex lock will be released before
50        // thread::sleep will be called so context can actually work in background thread.
51        {
52            let mut context = context.state();
53
54            let listener = context.listener_mut();
55
56            // Define up-axis of listener.
57            let up = Vector3::y_axis();
58
59            // And rotate look axis.
60            let rotation_matrix =
61                UnitQuaternion::from_axis_angle(&up, angle.to_radians()).to_homogeneous();
62            let look = rotation_matrix
63                .transform_point(&Point3::new(0.0, 0.0, 1.0))
64                .coords;
65
66            // Finally combine axes. _lh suffix here means that we using left-handed coordinate system.
67            // there is also _rh (right handed) version. Also basis can be set directly by using `set_basis`
68            listener.set_orientation_lh(look, *up);
69
70            // Move listener a bit back from sound source.
71            listener.set_position(Vector3::new(0.0, 0.0, -2.0));
72
73            // Continue rotation.
74            angle += 2.0;
75        }
76
77        // Limit rate of updates.
78        thread::sleep(Duration::from_millis(100));
79    }
80}
examples/hrtf.rs (line 46)
17fn main() {
18    // Initialize sound engine with default output device.
19    let engine = SoundEngine::new();
20
21    let hrir_sphere =
22        HrirSphere::from_file("examples/data/IRC_1002_C.bin", context::SAMPLE_RATE).unwrap();
23
24    // Initialize new sound context with default output device.
25    let context = SoundContext::new();
26
27    engine.lock().unwrap().add_context(context.clone());
28
29    // Set HRTF renderer instead of default.
30    context
31        .state()
32        .set_renderer(Renderer::HrtfRenderer(HrtfRenderer::new(hrir_sphere)));
33
34    // Create some sounds.
35    let sound_buffer = SoundBufferResource::new_generic(
36        block_on(DataSource::from_file("examples/data/door_open.wav")).unwrap(),
37    )
38    .unwrap();
39    let source = SpatialSourceBuilder::new(
40        GenericSourceBuilder::new()
41            .with_buffer(sound_buffer)
42            .with_status(Status::Playing)
43            .build()
44            .unwrap(),
45    )
46    .build_source();
47    context.state().add_source(source);
48
49    let sound_buffer = SoundBufferResource::new_generic(
50        block_on(DataSource::from_file("examples/data/helicopter.wav")).unwrap(),
51    )
52    .unwrap();
53    let source = SpatialSourceBuilder::new(
54        GenericSourceBuilder::new()
55            .with_buffer(sound_buffer)
56            .with_status(Status::Playing)
57            .with_looping(true)
58            .build()
59            .unwrap(),
60    )
61    .build_source();
62    let source_handle = context.state().add_source(source);
63
64    // Move source sound around listener for some time.
65    let start_time = time::Instant::now();
66    let mut angle = 0.0f32;
67    while (time::Instant::now() - start_time).as_secs() < 360 {
68        // Separate scope for update to make sure that mutex lock will be released before
69        // thread::sleep will be called so context can actually work in background thread.
70        {
71            if let SoundSource::Spatial(spatial) = context.state().source_mut(source_handle) {
72                let axis = Vector3::y_axis();
73                let rotation_matrix =
74                    UnitQuaternion::from_axis_angle(&axis, angle.to_radians()).to_homogeneous();
75                spatial.set_position(
76                    rotation_matrix
77                        .transform_point(&Point3::new(0.0, 0.0, 3.0))
78                        .coords,
79                );
80            }
81
82            angle += 1.6;
83
84            println!(
85                "Sound render time {:?}",
86                context.state().full_render_duration()
87            );
88        }
89
90        // Limit rate of updates.
91        thread::sleep(Duration::from_millis(100));
92    }
93}
examples/reverb.rs (line 53)
17fn main() {
18    let hrir_sphere =
19        HrirSphere::from_file("examples/data/IRC_1002_C.bin", context::SAMPLE_RATE).unwrap();
20
21    // Initialize sound engine with default output device.
22    let engine = SoundEngine::new();
23
24    // Initialize new sound context.
25    let context = SoundContext::new();
26
27    engine.lock().unwrap().add_context(context.clone());
28
29    // Set HRTF renderer instead of default for binaural sound.
30    context
31        .state()
32        .set_renderer(Renderer::HrtfRenderer(HrtfRenderer::new(hrir_sphere)));
33
34    let base_effect = BaseEffect::default();
35
36    // Create reverb effect and set its decay time.
37    let mut reverb = Reverb::new(base_effect);
38    reverb.set_decay_time(Duration::from_secs_f32(10.0));
39    let reverb_handle = context.state().add_effect(Effect::Reverb(reverb));
40
41    // Create some sounds.
42    let sound_buffer = SoundBufferResource::new_generic(
43        block_on(DataSource::from_file("examples/data/door_open.wav")).unwrap(),
44    )
45    .unwrap();
46    let source = SpatialSourceBuilder::new(
47        GenericSourceBuilder::new()
48            .with_buffer(sound_buffer)
49            .with_status(Status::Playing)
50            .build()
51            .unwrap(),
52    )
53    .build_source();
54    let door_sound = context.state().add_source(source);
55
56    // Each sound source must be attached to effect, otherwise sound won't be passed to effect
57    // and you'll hear sound without any difference.
58    context
59        .state()
60        .effect_mut(reverb_handle)
61        .add_input(EffectInput::direct(door_sound));
62
63    let sound_buffer = SoundBufferResource::new_generic(
64        block_on(DataSource::from_file("examples/data/drop.wav")).unwrap(),
65    )
66    .unwrap();
67    let source = SpatialSourceBuilder::new(
68        GenericSourceBuilder::new()
69            .with_buffer(sound_buffer)
70            .with_status(Status::Playing)
71            .with_looping(true)
72            .build()
73            .unwrap(),
74    )
75    .build_source();
76    let drop_sound_handle = context.state().add_source(source);
77
78    context
79        .state()
80        .effect_mut(reverb_handle)
81        .add_input(EffectInput::direct(drop_sound_handle));
82
83    // Move sound around listener for some time.
84    let start_time = time::Instant::now();
85    let mut angle = 0.0f32;
86    while (time::Instant::now() - start_time).as_secs() < 360 {
87        if let SoundSource::Spatial(sound) = context.state().source_mut(drop_sound_handle) {
88            let axis = Vector3::y_axis();
89            let rotation_matrix =
90                UnitQuaternion::from_axis_angle(&axis, angle.to_radians()).to_homogeneous();
91            sound.set_position(
92                rotation_matrix
93                    .transform_point(&Point3::new(0.0, 0.0, 1.0))
94                    .coords,
95            );
96        }
97
98        angle += 1.6;
99
100        println!(
101            "Sound render time {:?}",
102            context.state().full_render_duration()
103        );
104
105        // Limit rate of context updates.
106        thread::sleep(Duration::from_millis(100));
107    }
108}

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<SS, SP> SupersetOf<SS> for SP
where SS: SubsetOf<SP>,

Source§

fn to_subset(&self) -> Option<SS>

The inverse inclusion map: attempts to construct self from the equivalent element of its superset. Read more
Source§

fn is_in_subset(&self) -> bool

Checks if self is actually part of its subset T (and can be converted to it).
Source§

fn to_subset_unchecked(&self) -> SS

Use with care! Same as self.to_subset but without any property checks. Always succeeds.
Source§

fn from_subset(element: &SS) -> SP

The inclusion map: converts self to the equivalent element of its superset.
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V