fmod/studio/system/
lifecycle.rs

1// Copyright (c) 2024 Melody Madeline 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::studio::{InitFlags, System, SystemBuilder};
10use crate::{FmodResultExt, Result};
11
12impl System {
13    /// A convenience function over [`SystemBuilder`] with sane defaults.
14    ///
15    /// # Safety
16    ///
17    /// See [`SystemBuilder::new`] for safety info.
18    pub unsafe fn new() -> Result<Self> {
19        unsafe { SystemBuilder::new() }?.build(0, InitFlags::NORMAL, crate::InitFlags::NORMAL)
20    }
21
22    ///This function will free the memory used by the Studio System object and everything created under it.
23    ///
24    /// # Safety
25    ///
26    /// Calling either of this function concurrently with any FMOD Studio API function (including this function) may cause undefined behavior.
27    /// External synchronization must be used if calls to [`SystemBuilder::new`] or [`System::release`] could overlap other FMOD Studio API calls.
28    /// All other FMOD Studio API functions are thread safe and may be called freely from any thread unless otherwise documented.
29    ///
30    /// All handles or pointers to objects associated with a Studio System object become invalid when the Studio System object is released.
31    /// The FMOD Studio API attempts to protect against stale handles and pointers being used with a different Studio System object but this protection cannot be guaranteed and attempting to use stale handles or pointers may cause undefined behavior.
32    ///
33    /// This function is not safe to be called at the same time across multiple threads.
34    pub unsafe fn release(&self) -> Result<()> {
35        unsafe { FMOD_Studio_System_Release(self.inner.as_ptr()).to_result() }
36    }
37
38    /// Update the FMOD Studio System.
39    ///
40    /// When Studio is initialized in the default asynchronous processing mode this function submits all buffered commands for execution on the Studio Update thread for asynchronous processing.
41    /// This is a fast operation since the commands are not processed on the calling thread.
42    /// If Studio is initialized with [`InitFlags::DEFERRED_CALLBACKS`] then any deferred callbacks fired during any asynchronous updates since the last call to this function will be called.
43    /// If an error occurred during any asynchronous updates since the last call to this function then this function will return the error result.
44    ///
45    /// When Studio is initialized with [`InitFlags::SYNCHRONOUS_UPDATE`] queued commands will be processed immediately when calling this function, the scheduling and update logic for the Studio system are executed and all callbacks are fired.
46    /// This may block the calling thread for a substantial amount of time.
47    pub fn update(&self) -> Result<()> {
48        unsafe { FMOD_Studio_System_Update(self.inner.as_ptr()) }.to_result()
49    }
50
51    /// This function blocks the calling thread until all pending commands have been executed and all non-blocking bank loads have been completed.
52    ///
53    /// This is equivalent to calling [`System::update`] and then sleeping until the asynchronous thread has finished executing all pending commands.
54    pub fn flush_commands(&self) -> Result<()> {
55        unsafe { FMOD_Studio_System_FlushCommands(self.inner.as_ptr()) }.to_result()
56    }
57
58    /// Block until all sample loading and unloading has completed.
59    ///
60    /// This function may stall for a long time if other threads are continuing to issue calls to load and unload sample data, e.g. by creating new event instances.
61    pub fn flush_sample_loading(&self) -> Result<()> {
62        unsafe { FMOD_Studio_System_FlushSampleLoading(self.inner.as_ptr()) }.to_result()
63    }
64}
fmod/studio/system/lifecycle.rs

fmod/studio/system/
lifecycle.rs
