fmod/studio/system/
misc.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 lanyard::Utf8CStr;
9use std::mem::MaybeUninit;
10
11use crate::Guid;
12
13use crate::studio::{AdvancedSettings, Bus, EventDescription, SoundInfo, System, Vca};
14
15impl System {
16    /// Retrieves a loaded [`Bus`].
17    ///
18    /// This function allows you to retrieve a handle for any bus in the global mixer.
19    ///
20    /// `path_or_id` may be a path, such as `bus:/SFX/Ambience`, or an ID string, such as `{d9982c58-a056-4e6c-b8e3-883854b4bffb}`.
21    ///
22    /// Note that path lookups will only succeed if the strings bank has been loaded.
23    pub fn get_bus(&self, path_or_id: &Utf8CStr) -> Result<Bus> {
24        let mut bus = std::ptr::null_mut();
25        unsafe {
26            FMOD_Studio_System_GetBus(self.inner, path_or_id.as_ptr(), &mut bus).to_result()?;
27        }
28        Ok(bus.into())
29    }
30
31    /// Retrieves a loaded [`Bus`].
32    ///
33    /// This function allows you to retrieve a handle for any bus in the global mixer.
34    pub fn get_bus_by_id(&self, id: Guid) -> Result<Bus> {
35        let mut bus = std::ptr::null_mut();
36        unsafe {
37            FMOD_Studio_System_GetBusByID(self.inner, &id.into(), &mut bus).to_result()?;
38        }
39        Ok(bus.into())
40    }
41
42    /// Retrieves an [`EventDescription`].
43    ///
44    /// This function allows you to retrieve a handle to any loaded event description.
45    ///
46    /// `path+or_id` may be a path, such as `event:/UI/Cancel` or `snapshot:/IngamePause`, or an ID string, such as `{2a3e48e6-94fc-4363-9468-33d2dd4d7b00}`.
47    ///
48    /// Note that path lookups will only succeed if the strings bank has been loaded.
49    pub fn get_event(&self, path_or_id: &Utf8CStr) -> Result<EventDescription> {
50        let mut event = std::ptr::null_mut();
51        unsafe {
52            FMOD_Studio_System_GetEvent(self.inner, path_or_id.as_ptr(), &mut event).to_result()?;
53            Ok(EventDescription::from(event))
54        }
55    }
56
57    /// Retrieves an [`EventDescription`].
58    ///
59    /// This function allows you to retrieve a handle to any loaded event description.
60    pub fn get_event_by_id(&self, id: Guid) -> Result<EventDescription> {
61        let mut event = std::ptr::null_mut();
62        unsafe {
63            FMOD_Studio_System_GetEventByID(self.inner, &id.into(), &mut event).to_result()?;
64            Ok(EventDescription::from(event))
65        }
66    }
67
68    /// Retrieves a loaded VCA.
69    ///
70    /// This function allows you to retrieve a handle for any VCA in the global mixer.
71    ///
72    /// `path_or_id` may be a path, such as `vca:/MyVCA`, or an ID string, such as `{d9982c58-a056-4e6c-b8e3-883854b4bffb`}.
73    ///
74    /// Note that path lookups will only succeed if the strings bank has been loaded.
75    pub fn get_vca(&self, path_or_id: &Utf8CStr) -> Result<Vca> {
76        let mut vca = std::ptr::null_mut();
77        unsafe {
78            FMOD_Studio_System_GetVCA(self.inner, path_or_id.as_ptr(), &mut vca).to_result()?;
79        }
80        Ok(vca.into())
81    }
82
83    /// Retrieves a loaded VCA.
84    ///
85    /// This function allows you to retrieve a handle for any VCA in the global mixer.
86    pub fn get_vca_by_id(&self, id: Guid) -> Result<Vca> {
87        let mut vca = std::ptr::null_mut();
88        unsafe {
89            FMOD_Studio_System_GetVCAByID(self.inner, &id.into(), &mut vca).to_result()?;
90        }
91        Ok(vca.into())
92    }
93
94    /// Retrieves advanced settings.
95    pub fn get_advanced_settings(&self) -> Result<AdvancedSettings> {
96        let mut advanced_settings = MaybeUninit::zeroed();
97
98        unsafe {
99            FMOD_Studio_System_GetAdvancedSettings(self.inner, advanced_settings.as_mut_ptr())
100                .to_result()?;
101
102            let advanced_settings = AdvancedSettings::from_ffi(advanced_settings.assume_init());
103
104            Ok(advanced_settings)
105        }
106    }
107
108    /// Retrieves information for loading a sound from the audio table.
109    ///
110    /// The [`SoundInfo`] structure contains information to be passed to [`crate::System::create_sound`] (which will create a parent sound),
111    /// along with a subsound index to be passed to [`crate::Sound::get_sub_sound`] once the parent sound is loaded.
112    ///
113    /// The user is expected to call [`crate::System::create_sound`] with the given information.
114    /// It is up to the user to combine in any desired loading flags, such as [`FMOD_CREATESTREAM`], [`FMOD_CREATECOMPRESSEDSAMPLE`] or [`FMOD_NONBLOCKING`] with the flags in [`FMOD_STUDIO_SOUND_INFO::mode`].
115    ///
116    /// When the banks have been loaded via [`System::load_bank_memory`], the mode will be returned as [`FMOD_OPENMEMORY_POINT`].
117    /// This won't work with the default [`FMOD_CREATESAMPLE`] mode.
118    /// For memory banks, you should add in the [`FMOD_CREATECOMPRESSEDSAMPLE`] or [`FMOD_CREATESTREAM`] flag, or remove [`FMOD_OPENMEMORY_POINT`] and add [`FMOD_OPENMEMORY`] to decompress the sample into a new allocation.
119    ///
120    /// # Safety
121    ///
122    /// The returned [`SoundInfo`] structure has an unbounded lifetime as it is hard to represent. You MUST constrain its lifetime as quickly as possible.
123    pub unsafe fn get_sound_info<'a>(&self, key: &Utf8CStr) -> Result<SoundInfo<'a>> {
124        let mut sound_info = MaybeUninit::zeroed();
125        unsafe {
126            FMOD_Studio_System_GetSoundInfo(self.inner, key.as_ptr(), sound_info.as_mut_ptr())
127                .to_result()?;
128
129            let sound_info = SoundInfo::from_ffi(sound_info.assume_init());
130            Ok(sound_info)
131        }
132    }
133}
fmod/studio/system/misc.rs

fmod/studio/system/
misc.rs
