1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107

//! The audio listener is the point in the scene from where all the sounds are heard.
//!
//! The audio listener defines the global properties of the audio environment,
//! it defines where and how sounds and musics are heard.
//!
//! If [`View`] is the eyes of the user, then `listener` is his ears (by the way, they are often
//! linked together – same position, orientation, etc.).
//!
//! `listener` is a simple interface, which allows to setup the listener in the 3D audio environment
//! (position, direction and up vector), and to adjust the global volume.
//!
//! # Usage example
//!
//! ```
//! use sfml::audio::listener;
//!
//! // Move the listener to the position (1, 0, -5)
//! listener::set_position((1., 0., -5.));
//!
//! // Make it face the right axis (1, 0, 0)
//! listener::set_direction((1., 0., 0.));
//!
//! // Reduce the global volume
//! listener::set_global_volume(50.);
//! ```
//!
//! [`View`]: crate::graphics::View
//!

use crate::system::Vector3f;
use csfml_audio_sys as ffi;

/// Change the global volume of all the sounds and musics
///
/// The volume is a number between 0 and 100, it is combined with
/// the individual volume of each sound / music.
/// The default value for the volume is 100 (maximum).
///
/// # Arguments
/// * volume - The new global volume, in the range [0, 100]
pub fn set_global_volume(volume: f32) {
    unsafe { ffi::sfListener_setGlobalVolume(volume) }
}

/// Get the current value of the global volume
///
/// Return the current global volume, in the range [0, 100]
#[must_use]
pub fn global_volume() -> f32 {
    unsafe { ffi::sfListener_getGlobalVolume() }
}

/// Set the position of the listener in the scene
///
/// The default listener's position is (0, 0, 0).
///
/// # Arguments
///
/// * position - the New position of the listener
pub fn set_position<P: Into<Vector3f>>(position: P) {
    unsafe { ffi::sfListener_setPosition(position.into().raw()) }
}

/// Get the current position of the listener in the scene
///
/// Return the listener's position
#[must_use]
pub fn position() -> Vector3f {
    unsafe { Vector3f::from_raw(ffi::sfListener_getPosition()) }
}

/// Set the orientation of the listener in the scene
///
/// The orientation defines the 3D axes of the listener
/// (left, up, front) in the scene. The orientation vector
/// doesn't have to be normalized.
/// The default listener's orientation is (0, 0, -1).
///
/// # Arguments
/// * direction - New listener's orientation
pub fn set_direction<D: Into<Vector3f>>(direction: D) {
    unsafe { ffi::sfListener_setDirection(direction.into().raw()) }
}

/// Get the current orientation of the listener in the scene
///
/// Return the listener's direction
#[must_use]
pub fn direction() -> Vector3f {
    unsafe { Vector3f::from_raw(ffi::sfListener_getDirection()) }
}

/// Set the upward vector of the listener in the scene.
///
/// The up vector is the vector that points upward from the listener's perspective.
/// Together with the direction, it defines the 3D orientation of the listener in the scene.
/// The up vector doesn't have to be normalized. The default listener's up vector is (0, 1, 0).
/// It is usually not necessary to change it, especially in 2D scenarios.
pub fn set_up_vector(value: &Vector3f) {
    unsafe { ffi::sfListener_setUpVector(value.raw()) }
}

/// Get the current upward vector of the listener in the scene. (not normalized)
#[must_use]
pub fn up_vector() -> Vector3f {
    unsafe { Vector3f::from_raw(ffi::sfListener_getUpVector()) }
}