fmod/studio/system/
general.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, Utf8CString};
9use std::mem::MaybeUninit;
10
11use crate::studio::System;
12use crate::Guid;
13
14impl System {
15    /// Retrieves the Core System.
16    pub fn get_core_system(&self) -> Result<crate::core::System> {
17        let mut system = std::ptr::null_mut();
18        unsafe {
19            FMOD_Studio_System_GetCoreSystem(self.inner, &mut system).to_result()?;
20        }
21        Ok(system.into())
22    }
23
24    /// Retrieves the ID for a bank, event, snapshot, bus or VCA.
25    ///
26    /// The strings bank must be loaded prior to calling this function, otherwise [`FMOD_RESULT::FMOD_ERR_EVENT_NOTFOUND`] is returned.
27    ///
28    /// The path can be copied to the system clipboard from FMOD Studio using the "Copy Path" context menu command.
29    pub fn lookup_id(&self, path: &Utf8CStr) -> Result<Guid> {
30        let mut guid = MaybeUninit::zeroed();
31        unsafe {
32            FMOD_Studio_System_LookupID(self.inner, path.as_ptr(), guid.as_mut_ptr())
33                .to_result()?;
34
35            let guid = guid.assume_init().into();
36            Ok(guid)
37        }
38    }
39
40    /// Retrieves the path for a bank, event, snapshot, bus or VCA.
41    ///
42    /// The strings bank must be loaded prior to calling this function, otherwise [`FMOD_RESULT::FMOD_ERR_EVENT_NOTFOUND`] is returned.
43    pub fn lookup_path(&self, id: Guid) -> Result<Utf8CString> {
44        let mut string_len = 0;
45
46        // retrieve the length of the string.
47        // this includes the null terminator, so we don't need to account for that.
48        unsafe {
49            let error = FMOD_Studio_System_LookupPath(
50                self.inner,
51                &id.into(),
52                std::ptr::null_mut(),
53                0,
54                &mut string_len,
55            )
56            .to_error();
57
58            // we expect the error to be fmod_err_truncated.
59            // if it isn't, we return the error.
60            match error {
61                Some(error) if error != FMOD_RESULT::FMOD_ERR_TRUNCATED => return Err(error),
62                _ => {}
63            }
64        };
65
66        let mut path = vec![0u8; string_len as usize];
67        let mut expected_string_len = 0;
68
69        unsafe {
70            FMOD_Studio_System_LookupPath(
71                self.inner,
72                &id.into(),
73                // u8 and i8 have the same layout, so this is ok
74                path.as_mut_ptr().cast(),
75                string_len,
76                &mut expected_string_len,
77            )
78            .to_result()?;
79
80            debug_assert_eq!(string_len, expected_string_len);
81
82            // all public fmod apis return UTF-8 strings. this should be safe.
83            // if i turn out to be wrong, perhaps we should add extra error types?
84            let path = Utf8CString::from_utf8_with_nul_unchecked(path);
85
86            Ok(path)
87        }
88    }
89
90    /// Checks that the [`System`] reference is valid and has been initialized.
91    pub fn is_valid(&self) -> bool {
92        unsafe { FMOD_Studio_System_IsValid(self.inner).into() }
93    }
94}
fmod/studio/system/general.rs

fmod/studio/system/
general.rs
