fmod/core/system/
lifetime.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::*;
8
9use crate::{InitFlags, System, SystemBuilder};
10
11impl System {
12    /// A convenience function over [`SystemBuilder`] with sane defaults.
13    ///
14    /// # Safety
15    ///
16    /// See [`SystemBuilder::new`] for safety info.
17    pub unsafe fn new() -> Result<Self> {
18        unsafe { SystemBuilder::new() }?.build(0, InitFlags::NORMAL)
19    }
20
21    /// Close the connection to the output and return to an uninitialized state without releasing the object.
22    ///
23    /// Closing renders objects created with this System invalid.
24    /// Make sure any Sound, [`crate::ChannelGroup`], Geometry and DSP objects are released before calling this.
25    ///
26    /// All pre-initialize configuration settings will remain and the System can be reinitialized as needed.
27    pub fn close(&self) -> Result<SystemBuilder> {
28        unsafe {
29            FMOD_System_Close(self.inner).to_result()?;
30            Ok(SystemBuilder { system: self.inner })
31        }
32    }
33
34    /// Closes and frees this object and its resources.
35    ///
36    /// This will internally call [`System::close`], so calling [`System::close`] before this function is not necessary.
37    ///
38    /// # Safety
39    ///
40    /// [`System::release`] is not thread-safe. Do not call this function simultaneously from multiple threads at once.
41    #[cfg_attr(
42        feature = "userdata-abstraction",
43        doc = "\n#### Note: This function will drop any associated userdata who's owner is no longer valid."
44    )]
45    pub unsafe fn release(&self) -> Result<()> {
46        unsafe {
47            FMOD_System_Release(self.inner).to_result()?;
48        }
49
50        #[cfg(feature = "userdata-abstraction")]
51        crate::userdata::cleanup_userdata();
52
53        Ok(())
54    }
55
56    /// Updates the FMOD system.
57    ///
58    /// Should be called once per 'game' tick, or once per frame in your application to perform actions such as:
59    /// - Panning and reverb from 3D attributes changes.
60    /// - Virtualization of Channels based on their audibility.
61    /// - Mixing for non-realtime output types. See comment below.
62    /// - Streaming if using [`InitFlags::STREAM_FROM_UPDATE`].
63    /// - Mixing if using [`InitFlags::MIX_FROM_UPDATE`]
64    /// - Firing callbacks that are deferred until Update.
65    /// - DSP cleanup.
66    ///
67    /// If [`OutputType::NoSoundNRT`] or  [`OutputType::WavWriterNRT`] output modes are used,
68    /// this function also drives the software / DSP engine, instead of it running asynchronously in a thread as is the default behavior.
69    /// This can be used for faster than realtime updates to the decoding or DSP engine which might be useful if the output is the wav writer for example.
70    ///
71    /// If [`InitFlags::STREAM_FROM_UPDATE`]. is used, this function will update the stream engine.
72    /// Combining this with the non realtime output will mean smoother captured output.
73    pub fn update(&self) -> Result<()> {
74        unsafe { FMOD_System_Update(self.inner).to_result() }
75    }
76
77    /// Suspend mixer thread and relinquish usage of audio hardware while maintaining internal state.
78    ///
79    /// Used on mobile platforms when entering a backgrounded state to reduce CPU to 0%.
80    ///
81    /// All internal state will be maintained, i.e. created [`Sound`] and [`Channel`]s will stay available in memory.
82    pub fn suspend_mixer(&self) -> Result<()> {
83        unsafe { FMOD_System_MixerSuspend(self.inner).to_result() }
84    }
85
86    /// Resume mixer thread and reacquire access to audio hardware.
87    ///
88    /// Used on mobile platforms when entering the foreground after being suspended.
89    ///
90    /// All internal state will resume, i.e. created [`Sound`] and [`Channel`]s are still valid and playback will continue.
91    pub fn resume_mixer(&self) -> Result<()> {
92        unsafe { FMOD_System_MixerResume(self.inner).to_result() }
93    }
94}
fmod/core/system/lifetime.rs

fmod/core/system/
lifetime.rs
