fmod/studio/event_instance/
general.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::{EventDescription, EventInstance};
10
11#[cfg(doc)]
12use crate::studio::PlaybackState;
13
14#[cfg(fmod_2_3)]
15use crate::studio::System;
16use crate::{FmodResultExt, Result};
17
18impl EventInstance {
19    /// Retrieves the event description.
20    pub fn get_description(&self) -> Result<EventDescription> {
21        let mut description = std::ptr::null_mut();
22        unsafe {
23            FMOD_Studio_EventInstance_GetDescription(self.inner.as_ptr(), &raw mut description)
24                .to_result()?;
25            Ok(EventDescription::from_ffi(description))
26        }
27    }
28
29    /// Marks the event instance for release.
30    ///
31    /// This function marks the event instance to be released.
32    /// Event instances marked for release are destroyed by the asynchronous update when they are in the stopped state ([`PlaybackState::Stopped`]).
33    ///
34    /// Generally it is a best practice to release event instances immediately after calling [`EventInstance::start`],
35    /// unless you want to play the event instance multiple times or explicitly stop it and start it again later.
36    /// It is possible to interact with the instance after falling [`EventInstance::release`], however if the sound has stopped [`FMOD_RESULT::FMOD_ERR_INVALID_HANDLE`] will be returned.
37    pub fn release(&self) -> Result<()> {
38        // we don't actually release userdata here because there is a callback, and the user might interact with the instance while it's being released
39        unsafe { FMOD_Studio_EventInstance_Release(self.inner.as_ptr()).to_result() }
40    }
41
42    /// Checks that the [`EventInstance`] reference is valid.
43    pub fn is_valid(&self) -> bool {
44        unsafe { FMOD_Studio_EventInstance_IsValid(self.inner.as_ptr()).into() }
45    }
46
47    /// Retrieves the FMOD Studio [`System`].
48    #[cfg(fmod_2_3)]
49    pub fn get_system(&self) -> Result<System> {
50        let mut system = std::ptr::null_mut();
51        unsafe {
52            FMOD_Studio_EventInstance_GetSystem(self.inner.as_ptr(), &raw mut system)
53                .to_result()?;
54            Ok(System::from_ffi(system))
55        }
56    }
57}
fmod/studio/event_instance/general.rs

fmod/studio/event_instance/
general.rs
