Struct System

pub struct System { /* private fields */ }

Available on crate feature studio only.

The main system object for FMOD Studio.

Initializing the FMOD Studio System object will also initialize the core System object.

Created with SystemBuilder, which handles initialization for you.

Implementations

impl System

pub fn load_bank_custom<F: FileSystemSync>( &self, userdata: LoadBankUserdata<'_>, load_flags: LoadBankFlags, ) -> Result<Bank>

Loads the metadata of a bank using custom read callbacks.

Sample data must be loaded separately see Sample Data Loading for details.

By default this function blocks until the load finishes.

Using the LoadBankFlags::NONBLOCKING flag causes the bank to be loaded asynchronously. In that case, this function always returns Ok and bank contains a valid bank handle. Load errors for asynchronous banks can be detected by calling Bank::get_loading_state. Failed asynchronous banks should be released by calling Bank::unload.

If a bank is split, separating out sample data and optionally streams from the metadata bank, all parts must be loaded before any APIs that use the data are called. We recommend you load each part one after another (the order in which they are loaded is not important), then proceed with dependent API calls such as Bank::load_sample_data or System::get_event.

pub fn load_bank_file( &self, filename: &Utf8CStr, load_flags: LoadBankFlags, ) -> Result<Bank>

Sample data must be loaded separately.

By default this function will block until the file load finishes.

Using the LoadBankFlags::NONBLOCKING flag will cause the bank to be loaded asynchronously. In that case this function will always return Ok and bank will contain a valid bank handle. Load errors for asynchronous banks can be detected by calling Bank::get_loading_state. Failed asynchronous banks should be released by calling Bank::unload.

If a bank has been split, separating out assets and optionally streams from the metadata bank, all parts must be loaded before any APIs that use the data are called. It is recommended you load each part one after another (order is not important), then proceed with dependent API calls such as Bank::load_sample_data or System::get_event.

pub fn load_bank_memory( &self, buffer: &[u8], flags: LoadBankFlags, ) -> Result<Bank>

Sample data must be loaded separately.

This function is the safe counterpart of System::load_bank_pointer. FMOD will allocate an internal buffer and copy the data from the passed in buffer before using it. The buffer passed to this function may be cleaned up at any time after this function returns.

By default this function will block until the load finishes.

Using the LoadBankFlags::NONBLOCKING flag will cause the bank to be loaded asynchronously. In that case this function will always return Ok and bank will contain a valid bank handle. Load errors for asynchronous banks can be detected by calling Bank::get_loading_state. Failed asynchronous banks should be released by calling Bank::unload.

This function is not compatible with AdvancedSettings::encryption_key, using them together will cause an error to be returned.

If a bank has been split, separating out assets and optionally streams from the metadata bank, all parts must be loaded before any APIs that use the data are called. It is recommended you load each part one after another (order is not important), then proceed with dependent API calls such as Bank::load_sample_data or System::get_event.

pub unsafe fn load_bank_pointer( &self, buffer: &[u8], flags: LoadBankFlags, ) -> Result<Bank>

Sample data must be loaded separately.

This function is the unsafe counterpart of System::load_bank_memory. FMOD will use the passed memory buffer directly.

By default this function will block until the load finishes.

Using the LoadBankFlags::NONBLOCKING flag will cause the bank to be loaded asynchronously. In that case this function will always return Ok and bank will contain a valid bank handle. Load errors for asynchronous banks can be detected by calling Bank::get_loading_state. Failed asynchronous banks should be released by calling Bank::unload.

This function is not compatible with AdvancedSettings::encryption_key, using them together will cause an error to be returned.

If a bank has been split, separating out assets and optionally streams from the metadata bank, all parts must be loaded before any APIs that use the data are called. It is recommended you load each part one after another (order is not important), then proceed with dependent API calls such as Bank::load_sample_data or System::get_event.

Safety

When using this function the buffer must be aligned to FMOD_STUDIO_LOAD_MEMORY_ALIGNMENT and the memory must persist until the bank has been fully unloaded, which can be some time after calling Bank::unload to unload the bank. You can ensure the memory is not being freed prematurely by only freeing it after receiving the FMOD_STUDIO_SYSTEM_CALLBACK_BANK_UNLOAD callback.

pub fn unload_all_banks(&self) -> Result<()>

Unloads all currently loaded banks.

pub fn get_bank(&self, path_or_id: &Utf8CStr) -> Result<Bank>

Retrieves a loaded bank

path_or_id may be a path, such as bank:/Weapons or an ID string such as {793cddb6-7fa1-4e06-b805-4c74c0fd625b}.

Note that path lookups will only succeed if the strings bank has been loaded.

pub fn get_bank_by_id(&self, id: Guid) -> Result<Bank>

Retrieves a loaded bank.

pub fn bank_count(&self) -> Result<c_int>

Retrieves the number of loaded banks.

pub fn get_bank_list(&self) -> Result<Vec<Bank>>

Retrieves a list of the currently-loaded banks.

pub fn get_bank_list_into(&self, slice: &mut [Option<Bank>]) -> Result<c_int>

Retrieves a list of the currently-loaded banks.

Fills in the provided slice instead of allocating a Vec, like System::get_bank_list does. Any banks not filled in are left as None.

Returns how many banks were fetched.

impl System

pub fn set_userdata(&self, userdata: *mut c_void) -> Result<()>

Sets the user data.

pub fn get_userdata(&self) -> Result<*mut c_void>

Retrieves the user data.

pub fn set_callback<C: SystemCallback>( &self, mask: SystemCallbackMask, ) -> Result<()>

Sets a callback for the Studio System.

impl System

pub fn start_command_capture( &self, filename: &Utf8CStr, flags: CommandCaptureFlags, ) -> Result<()>

Recording Studio commands to a file.

The commands generated by the FMOD Studio API can be captured and later replayed for debug and profiling purposes.

Unless the CommandCaptureFlags::SKIP_INITIAL_STATE flag is specified, the command capture will first record the set of all banks and event instances that currently exist.

pub fn stop_command_capture(&self) -> Result<()>

Stop recording Studio commands.

pub fn load_command_replay( &self, filename: &Utf8CStr, flags: CommandReplayFlags, ) -> Result<CommandReplay>

Load a command replay.

impl System

pub fn get_core_system(&self) -> Result<System>

Retrieves the Core System.

pub fn lookup_id(&self, path: &Utf8CStr) -> Result<Guid>

Retrieves the ID for a bank, event, snapshot, bus or VCA.

The strings bank must be loaded prior to calling this function, otherwise FMOD_RESULT::FMOD_ERR_EVENT_NOTFOUND is returned.

The path can be copied to the system clipboard from FMOD Studio using the “Copy Path” context menu command.

pub fn lookup_path(&self, id: Guid) -> Result<Utf8CString>

Retrieves the path for a bank, event, snapshot, bus or VCA.

The strings bank must be loaded prior to calling this function, otherwise FMOD_RESULT::FMOD_ERR_EVENT_NOTFOUND is returned.

pub fn is_valid(&self) -> bool

Checks that the System reference is valid and has been initialized.

impl System

pub unsafe fn new() -> Result<Self>

A convenience function over SystemBuilder with sane defaults.

Safety

See SystemBuilder::new for safety info.

pub unsafe fn release(&self) -> Result<()>

This function will free the memory used by the Studio System object and everything created under it.

Safety

Calling either of this function concurrently with any FMOD Studio API function (including this function) may cause undefined behavior. External synchronization must be used if calls to SystemBuilder::new or System::release could overlap other FMOD Studio API calls. All other FMOD Studio API functions are thread safe and may be called freely from any thread unless otherwise documented.

All handles or pointers to objects associated with a Studio System object become invalid when the Studio System object is released. 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.

This function is not safe to be called at the same time across multiple threads.

pub fn update(&self) -> Result<()>

Update the FMOD Studio System.

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. This is a fast operation since the commands are not processed on the calling thread. 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. If an error occurred during any asynchronous updates since the last call to this function then this function will return the error result.

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. This may block the calling thread for a substantial amount of time.

pub fn flush_commands(&self) -> Result<()>

This function blocks the calling thread until all pending commands have been executed and all non-blocking bank loads have been completed.

This is equivalent to calling System::update and then sleeping until the asynchronous thread has finished executing all pending commands.

pub fn flush_sample_loading(&self) -> Result<()>

Block until all sample loading and unloading has completed.

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.

impl System

pub fn set_listener_attributes( &self, listener: c_int, attributes: Attributes3D, attenuation_position: Option<Vector>, ) -> Result<()>

Sets the 3D attributes of the listener.

pub fn get_listener_attributes( &self, listener: c_int, ) -> Result<(Attributes3D, Vector)>

Retrieves listener 3D attributes.

pub fn set_listener_weight( &self, listener: c_int, weight: c_float, ) -> Result<()>

Sets the listener weighting.

Listener weighting is a factor which determines how much the listener influences the mix. It is taken into account for 3D panning, doppler, and the automatic distance event parameter. A listener with a weight of 0 has no effect on the mix.

Listener weighting can be used to fade in and out multiple listeners. For example to do a crossfade, an additional listener can be created with a weighting of 0 that ramps up to 1 while the old listener weight is ramped down to 0. After the crossfade is finished the number of listeners can be reduced to 1 again.

The sum of all the listener weights should add up to at least 1. It is a user error to set all listener weights to 0.

pub fn get_listener_weight(&self, listener: c_int) -> Result<c_float>

Retrieves listener weighting.

pub fn set_listener_count(&self, amount: c_int) -> Result<()>

Sets the number of listeners in the 3D sound scene.

If the number of listeners is set to more than 1 then FMOD uses a ‘closest sound to the listener’ method to determine what should be heard.

pub fn get_listener_count(&self) -> Result<c_int>

Sets the number of listeners in the 3D sound scene.

If the number of listeners is set to more than 1 then FMOD uses a ‘closest sound to the listener’ method to determine what should be heard.

impl System

pub fn get_bus(&self, path_or_id: &Utf8CStr) -> Result<Bus>

Retrieves a loaded Bus.

This function allows you to retrieve a handle for any bus in the global mixer.

path_or_id may be a path, such as bus:/SFX/Ambience, or an ID string, such as {d9982c58-a056-4e6c-b8e3-883854b4bffb}.

Note that path lookups will only succeed if the strings bank has been loaded.

pub fn get_bus_by_id(&self, id: Guid) -> Result<Bus>

Retrieves a loaded Bus.

This function allows you to retrieve a handle for any bus in the global mixer.

pub fn get_event(&self, path_or_id: &Utf8CStr) -> Result<EventDescription>

Retrieves an EventDescription.

This function allows you to retrieve a handle to any loaded event description.

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}.

Note that path lookups will only succeed if the strings bank has been loaded.

pub fn get_event_by_id(&self, id: Guid) -> Result<EventDescription>

Retrieves an EventDescription.

This function allows you to retrieve a handle to any loaded event description.

pub fn get_vca(&self, path_or_id: &Utf8CStr) -> Result<Vca>

Retrieves a loaded VCA.

This function allows you to retrieve a handle for any VCA in the global mixer.

path_or_id may be a path, such as vca:/MyVCA, or an ID string, such as {d9982c58-a056-4e6c-b8e3-883854b4bffb}.

Note that path lookups will only succeed if the strings bank has been loaded.

pub fn get_vca_by_id(&self, id: Guid) -> Result<Vca>

Retrieves a loaded VCA.

This function allows you to retrieve a handle for any VCA in the global mixer.

pub fn get_advanced_settings(&self) -> Result<AdvancedSettings>

Retrieves advanced settings.

pub unsafe fn get_sound_info<'a>(&self, key: &Utf8CStr) -> Result<SoundInfo<'a>>

Retrieves information for loading a sound from the audio table.

The SoundInfo structure contains information to be passed to crate::System::create_sound (which will create a parent sound), along with a subsound index to be passed to crate::Sound::get_sub_sound once the parent sound is loaded.

The user is expected to call crate::System::create_sound with the given information. 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.

When the banks have been loaded via System::load_bank_memory, the mode will be returned as FMOD_OPENMEMORY_POINT. This won’t work with the default FMOD_CREATESAMPLE mode. 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.

Safety

The returned SoundInfo structure has an unbounded lifetime as it is hard to represent. You MUST constrain its lifetime as quickly as possible.

impl System

pub fn get_parameter_by_id(&self, id: ParameterID) -> Result<(c_float, c_float)>

Retrieves a global parameter value by unique identifier.

The second tuple field is the final value of the parameter after applying adjustments due to automation, modulation, seek speed, and parameter velocity to value. This is calculated asynchronously when the Studio system updates.

pub fn set_parameter_by_id( &self, id: ParameterID, value: c_float, ignore_seek_speed: bool, ) -> Result<()>

Sets a global parameter value by unique identifier.

pub fn set_parameter_by_id_with_label( &self, id: ParameterID, label: &Utf8CStr, ignore_seek_speed: bool, ) -> Result<()>

Sets a global parameter value by unique identifier, looking up the value label.

If the specified label is not found, FMOD_RESULT::FMOD_ERR_EVENT_NOTFOUND is returned. This lookup is case sensitive.

pub fn set_parameters_by_ids( &self, ids: &[ParameterID], values: &mut [c_float], ignore_seek_speed: bool, ) -> Result<()>

Sets multiple global parameter values by unique identifier.

If any ID is set to all zeroes then the corresponding value will be ignored.

Panics

This function will panic if ids.len() != values.len().

pub fn get_parameter_by_name( &self, name: &Utf8CStr, ) -> Result<(c_float, c_float)>

Retrieves a global parameter value by name.

The second tuple field is the final value of the parameter after applying adjustments due to automation, modulation, seek speed, and parameter velocity to value. This is calculated asynchronously when the Studio system updates.

pub fn set_parameter_by_name( &self, name: &Utf8CStr, value: c_float, ignore_seek_speed: bool, ) -> Result<()>

Sets a global parameter value by name.

pub fn set_parameter_by_name_with_label( &self, name: &Utf8CStr, label: &Utf8CStr, ignore_seek_speed: bool, ) -> Result<()>

Sets a global parameter value by name, looking up the value label.

If the specified label is not found, FMOD_RESULT::FMOD_ERR_EVENT_NOTFOUND is returned. This lookup is case sensitive.

pub fn get_parameter_description_by_name( &self, name: &Utf8CStr, ) -> Result<ParameterDescription>

Retrieves a global parameter by name or path.

name can be the short name (such as Wind) or the full path (such as parameter:/Ambience/Wind). Path lookups will only succeed if the strings bank has been loaded.

pub fn get_parameter_description_by_id( &self, id: ParameterID, ) -> Result<ParameterDescription>

Retrieves a global parameter by ID.

pub fn parameter_description_count(&self) -> Result<c_int>

Retrieves the number of global parameters.

pub fn get_parameter_description_list( &self, ) -> Result<Vec<ParameterDescription>>

Retrieves a list of global parameters.

pub fn get_parameter_label_by_name( &self, name: &Utf8CStr, label_index: c_int, ) -> Result<Utf8CString>

Retrieves a global parameter label by name or path.

name can be the short name (such as Wind) or the full path (such as parameter:/Ambience/Wind). Path lookups will only succeed if the strings bank has been loaded.

pub fn get_parameter_label_by_id( &self, id: ParameterID, label_index: c_int, ) -> Result<Utf8CString>

Retrieves a global parameter label by ID.

impl System

pub unsafe fn register_plugin( &self, dsp_description: *const FMOD_DSP_DESCRIPTION, ) -> Result<()>

Registers a plugin DSP.

Plugin DSPs used by an event must be registered using this function before loading the bank containing the event.

Safety

This function provides no gaurdrails or safe API for registering a plugin. It can call into non-rust external code. Dsp descriptions are intended to be retrieved from a plugin’s C API, so it’s not feasible to provide a safe API for this function.

pub unsafe fn unregister_plugin(&self, name: &Utf8CStr) -> Result<()>

Unregisters a plugin DSP.

Safety

This function provides no gaurdrails or safe API for unregistering a plugin. It can call into non-rust external code.

impl System

pub fn get_buffer_usage(&self) -> Result<BufferUsage>

Retrieves buffer usage information.

Stall count and time values are cumulative. They can be reset by calling System::reset_buffer_usage.

Stalls due to the studio command queue overflowing can be avoided by setting a larger command queue size with SystemBuilder::settings.

pub fn reset_buffer_usage(&self) -> Result<()>

Resets memory buffer usage statistics.

This function resets the buffer usage data tracked by the FMOD Studio System.

pub fn get_cpu_usage(&self) -> Result<(CpuUsage, CpuUsage)>

Retrieves the amount of CPU used for different parts of the Studio engine.

For readability, the percentage values are smoothed to provide a more stable output.

pub fn get_memory_usage(&self) -> Result<MemoryUsage>

Retrieves memory usage statistics.

The memory usage sample_data field for the system is the total size of non-streaming sample data currently loaded.

Memory usage statistics are only available in logging builds, in release builds memoryusage will contain zero for all values after calling this function.

impl System

pub unsafe fn from_ffi(value: *mut FMOD_STUDIO_SYSTEM) -> Self

Safety

value must be a valid pointer either aquired from Self::as_ptr or FMOD.

Panics

Panics if value is null.

pub fn as_ptr(self) -> *mut FMOD_STUDIO_SYSTEM

Converts self into its raw representation.

Trait Implementations

impl Clone for System

fn clone(&self) -> System

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for System

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<System> for *mut FMOD_STUDIO_SYSTEM

Convert a System instance to its FFI equivalent.

This is safe, provided you don’t use the pointer.

fn from(value: System) -> Self

Converts to this type from the input type.

impl Hash for System

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for System

fn eq(&self, other: &System) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for System

impl Eq for System

impl Send for System

Available on non-crate feature thread-unsafe only.

Most of FMOD is thread safe. There are some select functions that are not thread safe to call, those are marked as unsafe.

impl StructuralPartialEq for System

impl Sync for System

Available on non-crate feature thread-unsafe only.