fmod/core/channel_control/
volume.rs

1// Copyright (c) 2024 Lily Lyons
2//
3// This Source Code Form is subject to the terms of the Mozilla Public
4// License, v. 2.0. If a copy of the MPL was not distributed with this
5// file, You can obtain one at https://mozilla.org/MPL/2.0/.
6
7use fmod_sys::*;
8use std::ffi::c_float;
9
10use crate::ChannelControl;
11
12impl ChannelControl {
13    /// Retrieves an estimation of the output volume.
14    ///
15    /// Estimated volume is calculated based on 3D spatialization, occlusion, API volume levels and DSPs used.
16    ///
17    /// While this does not represent the actual waveform, [`Channel`]s playing FSB files will take into consideration the overall peak level of the file (if available).
18    ///
19    /// This value is used to determine which [`Channel`]s should be audible and which [`Channel`]s to virtualize when resources are limited.
20    ///
21    /// See the Virtual Voice System white paper for more details about how audibility is calculated.
22    pub fn get_audibility(&self) -> Result<c_float> {
23        let mut audibility = 0.0;
24        unsafe {
25            FMOD_ChannelControl_GetAudibility(self.inner, &mut audibility).to_result()?;
26        }
27        Ok(audibility)
28    }
29
30    /// Sets the volume level.
31    ///
32    /// To define the volume per Sound use Sound::setDefaults.
33    ///
34    /// Setting volume at a level higher than 1 can lead to distortion/clipping.
35    pub fn set_volume(&self, volume: c_float) -> Result<()> {
36        unsafe { FMOD_ChannelControl_SetVolume(self.inner, volume).to_result() }
37    }
38
39    /// Retrieves the volume level.
40    pub fn get_volume(&self) -> Result<c_float> {
41        let mut volume = 0.0;
42        unsafe {
43            FMOD_ChannelControl_GetVolume(self.inner, &mut volume).to_result()?;
44        }
45        Ok(volume)
46    }
47
48    /// Sets whether volume changes are ramped or instantaneous.
49    ///
50    /// Volume changes when not paused will be ramped to the target value to avoid a pop sound,
51    /// this function allows that setting to be overridden and volume changes to be applied immediately.
52    pub fn set_volume_ramp(&self, ramp: bool) -> Result<()> {
53        unsafe { FMOD_ChannelControl_SetVolumeRamp(self.inner, ramp).to_result() }
54    }
55
56    /// Retrieves whether volume changes are ramped or instantaneous.
57    pub fn get_volume_ramp(&self) -> Result<bool> {
58        let mut ramp = false;
59        unsafe {
60            FMOD_ChannelControl_GetVolumeRamp(self.inner, &mut ramp).to_result()?;
61        }
62        Ok(ramp)
63    }
64
65    /// Sets the mute state.
66    ///
67    /// Mute is an additional control for volume, the effect of which is equivalent to setting the volume to zero.
68    ///
69    /// An individual mute state is kept for each object,
70    /// muting a parent ChannelGroup will effectively mute this object however when queried the individual mute state is returned.
71    /// ChannelControl::getAudibility can be used to calculate overall audibility for a Channel or ChannelGroup.
72    pub fn set_mute(&self, mute: bool) -> Result<()> {
73        unsafe { FMOD_ChannelControl_SetMute(self.inner, mute).to_result() }
74    }
75
76    /// Retrieves the mute state.
77    ///
78    /// An individual mute state is kept for each object,
79    /// muting a parent ChannelGroup will effectively mute this object however when queried the individual mute state is returned.
80    /// ChannelControl::getAudibility can be used to calculate overall audibility for a Channel or ChannelGroup.
81    pub fn get_mute(&self) -> Result<bool> {
82        let mut mute = false;
83        unsafe {
84            FMOD_ChannelControl_GetMute(self.inner, &mut mute).to_result()?;
85        }
86        Ok(mute)
87    }
88}
fmod/core/channel_control/volume.rs

fmod/core/channel_control/
volume.rs
