+
+
+
System
+
+FMOD Object: System
+
+
+
This module holds functionality related to FMOD's System object, which is a management object from which all resources are created and played.
+
Create this object with fmod_system_create.
+
Functions
+
This module offers a collection of functions designed to address specific tasks and provide utilities for various purposes. Explore the available functions to make the most of the functionalities provided by this module.
+
+
+
+
Back To Top
+
+
fmod_system_create
+
+FMOD Function: System_Create
+
+
+
This function creates an instance of the FMOD system.
+
It must be called first to create an FMOD System object before any other API calls (except for fmod_debug_initialize). Use this function to create 1 or multiple instances of FMOD System objects.
+
If the new FMOD system is created successfully, the function returns a reference to the system and makes it the selected system.
+
+
Note
+
All function calls that you make to the fmod_system_* functions work on the selected system. You can call fmod_system_select to change this.
+
+
Use fmod_system_release to free the system object.
+
+
Syntax:
+
+fmod_system_create()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_select
+
This function selects the FMOD system the fmod_system_* functions work on.
+
+
Syntax:
+
+fmod_system_select(system_ref)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| system_ref |
+Real |
+The reference to the system to be selected. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_count
+
This function returns the number of FMOD Systems.
+
+
Note
+
Every successful call to fmod_system_create creates an instance of an FMOD system object that's included in the count.
+
+
+
Syntax:
+
+fmod_system_count()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_init
+
+FMOD Function: System::init
+
+
+
This function initializes the system object and prepares FMOD for playback.
+
+Important
+A system object must first be created with fmod_system_create.
+
+
Most API functions require an initialized System object before they will succeed, otherwise they will return FMOD_RESULT.ERR_UNINITIALIZED. Some can only be called before initialization. These are:
+
+
+
See Getting Started for examples on initialising and updating FMOD systems.
+
+
Syntax:
+
+fmod_system_init(max_channels, flags)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| max_channels |
+Real |
+The maximum number of Channels available for playback, also known as virtual voices. A value in the range [0, 4095]. Virtual voices will play with minimal overhead, with a subset of 'real' voices that are mixed, and selected based on priority and audibility. See the Virtual Voices guide for more information. |
+
+
+| flags |
+FMOD_INIT |
+The initialization flags. More than one mode can be set at once by combining them with the OR operator. |
+
+
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_release
+
+FMOD Function: System::release
+
+
+
This function closes and frees the given FMOD System object and its resources.
+
+
+
Syntax:
+
+fmod_system_release()
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_close
+
+FMOD Function: System::close
+
+
+
This function close the connections to the output and returns to an uninitialized state without releasing the object.
+
Closing renders FMOD objects created with this System invalid. You should make sure any Sound, ChannelGroup, Geometry and DSP objects are released before calling this.
+
All pre-initialize configuration settings will remain and the System can be reinitialized as needed.
+
+
Syntax:
+
+fmod_system_close(system_ref)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| system_ref |
+Real |
+A reference to a system. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_update
+
+FMOD Function: System::update
+
+
+
This function updates the FMOD system.
+
+Important
+This function updates the selected system. To update another FMOD system instance use fmod_system_select to select it and call fmod_system_update again.
+
+
It should be called once per frame in your application (for example in a Step event) to perform actions such as:
+
+- Panning and reverb from 3D attributes changes.
+- The virtualization of Channels based on their audibility.
+- Mixing for non-realtime output types. See comment below.
+- Streaming if using
FMOD_INIT.STREAM_FROM_UPDATE.
+- Mixing if using
FMOD_INIT.MIX_FROM_UPDATE.
+- Firing callbacks that are deferred until update.
+- DSP cleanup.
+
+
If FMOD_OUTPUTTYPE.NOSOUND_NRT or FMOD_OUTPUTTYPE.WAVWRITER_NRT output modes are used, this function also drives the software / DSP engine, instead of it running asynchronously in a thread as is the default behavior.
+This can be used for faster than realtime updates to the decoding or DSP engine which might be useful if the output is the wav writer for example.
+
If FMOD_INIT.STREAM_FROM_UPDATE is used, this function will update the stream engine. Combining this with the non realtime output will mean smoother captured output.
+
See Getting Started for examples on initialising and updating FMOD systems.
+
+
Syntax:
+
+fmod_system_update()
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_mixer_suspend
+
+FMOD Function: System::mixerSuspend
+
+
+
This function suspends the mixer thread and relinquishes usage of audio hardware while maintaining internal state.
+
It is used on mobile platforms when entering a backgrounded state to reduce CPU to 0%.
+
All internal state will be maintained, i.e. created Sounds and Channels will stay available in memory.
+
+
Syntax:
+
+fmod_system_mixer_suspend()
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_mixer_resume
+
+FMOD Function: System::mixerResume
+
+
+
This function resumes the mixer thread and reacquires access to audio hardware.
+
It is used on mobile platforms when entering the foreground after being suspended.
+
All internal state will resume, i.e. created Sounds and Channels are still valid and playback will continue.
+
+
Note
+
On HTML5, this function is used to start audio from a user interaction event, like a mouse click or screen touch event. Without this call audio may not start on some browsers.
+
+
+
Syntax:
+
+fmod_system_mixer_resume()
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_set_output
+
+FMOD Function: System::setOutput
+
+
+
This function sets the type of output interface used to run the mixer.
+
The function is typically used to select between different OS-specific audio APIs which may have different features.
+
It is only necessary to call this function if you want to specifically switch away from the default output mode for the operating system. The most optimal mode is selected by default for the operating system.
+
+
Note
+
(Windows, UWP, GameCore, Android, MacOS, iOS, Linux Only) This function can be called after fmod_system_init to perform special handling of driver disconnections, see FMOD_SYSTEM_CALLBACK.DEVICELISTCHANGED.
+
+
+
Note
+
When using the Studio API, switching to an NRT (non-realtime) output type after FMOD is already initialized will not behave correctly unless the Studio API was initialized with FMOD_STUDIO_INIT.SYNCHRONOUS_UPDATE.
+
+
+
Syntax:
+
+fmod_system_set_output(output)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| output |
+FMOD_OUTPUTTYPE |
+The output type. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_output
+
+FMOD Function: System::getOutput
+
+
+
This function retrieves the type of output interface used to run the mixer.
+
+
Syntax:
+
+fmod_system_get_output()
+
+
+
+
+
Returns:
+
+FMOD_OUTPUTTYPE
+
+
+
+
+
Back To Top
+
+
fmod_system_get_num_drivers
+
+FMOD Function: System::getNumDrivers
+
+
+
This function retrieves the number of output drivers available for the selected output type.
+
If fmod_system_set_output has not been called, this function will return the number of drivers available for the default output type.
+A possible use for this function is to iterate through available sound devices for the current output type, and use fmod_system_get_driver_info to get the device's name and other attributes.
+
+
Syntax:
+
+fmod_system_get_num_drivers()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_get_driver_info
+
+FMOD Function: System::getDriverInfo
+
+
+
This function retrieves identification information about a sound device specified by its index, and specific to the selected output mode.
+
+
Syntax:
+
+fmod_system_get_driver_info(driver_index)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| driver_index |
+Real |
+The index of the sound driver device. A value in the range [0, fmod_system_get_num_drivers]. |
+
+
+
+
+
+
+
Returns:
+
+FmodSystemDriverInfo
+
+
+
+
+
Back To Top
+
+
fmod_system_set_driver
+
+FMOD Function: System::setDriver
+
+
+
This function sets the output driver for the selected output type.
+
When an output type has more than one driver available, this function can be used to select between them.
+
If this function is called after fmod_system_init, the current driver will be shutdown and the newly selected driver will be initialized / started.
+
+
Syntax:
+
+fmod_system_set_driver(driver)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| driver |
+Real |
+The driver index where 0 represents the default for the output type. A value in the range [0, fmod_system_get_num_drivers]. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_driver
+
+FMOD Function: System::getDriver
+
+
+
This function retrieves the output driver for the selected output type.
+
It returns the driver index where 0 represents the default for the output type.
+
+
Syntax:
+
+fmod_system_get_driver()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_set_software_channels
+
+FMOD Function: System::setSoftwareChannels
+
+
+
This function sets the maximum number of software mixed Channels possible.
+
This function cannot be called after FMOD is already activated, it must be called before fmod_system_init, or after fmod_system_close.
+'Software Channels' refers to real Channels that will play, with software_channels refering to the maximum number of Channels before successive Channels start becoming virtual. For differences between real and virtual Channels see the Virtual Voices guide.
+
+
Syntax:
+
+fmod_system_set_software_channels(software_channels)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| software_channels |
+Real |
+The maximum number of real Channels to be allocated by FMOD. The default is 64. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_software_channels
+
+FMOD Function: System::getSoftwareChannels
+
+
+
This function retrieves the maximum number of software mixed Channels possible.
+
'Software Channels' refers to real Channels that will play, with software_channels refering to the maximum number of Channels before successive Channels start becoming virtual. For differences between real and virtual Channels see the Virtual Voices guide.
+
+
Syntax:
+
+fmod_system_get_software_channels()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
+
+FMOD Function: System::setSoftwareFormat
+
+
+
This function sets the output format for the software mixer.
+
If loading Studio banks, this must be called with speaker_mode corresponding to the project output format if there is a possibility of the output audio device not matching the project format. Any differences between the project format and speaker_mode will cause the mix to sound wrong.
+
By default, speaker_mode will assume the setup the OS / output prefers.
+
Altering the sample_rate from the OS / output preferred rate may incur extra latency. Altering the speaker_mode from the OS / output preferred mode may cause an upmix/downmix which can alter the sound.
+
On lower power platforms such as mobile sample_rate will default to 24kHz to reduce CPU cost.
+
+
+
Syntax:
+
+fmod_system_set_software_format(sample_rate, speaker_mode, num_raw_speakers)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| sample_rate |
+Real |
+The sample rate of the mixer, in Hertz. A value in the range [8000, 192000]. Default is 48000. |
+
+
+| speaker_mode |
+FMOD_SPEAKERMODE |
+The speaker setup of the mixer. |
+
+
+| num_raw_speakers |
+Real |
+The number of speakers for FMOD_SPEAKERMODE.RAW mode. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
+
+FMOD Function: System::getSoftwareFormat
+
+
+
This function retrieves the output format for the software mixer.
+
+
Syntax:
+
+fmod_system_get_software_format()
+
+
+
+
+
Returns:
+
+FmodSystemSoftwareFormat
+
+
+
+
+
Back To Top
+
+
fmod_system_set_dsp_buffer_size
+
+FMOD Function: System::setDSPBufferSize
+
+
+
This function sets the buffer size for the FMOD software mixing engine.
+
This function is used if you need to control mixer latency or granularity. Smaller buffer sizes lead to smaller latency, but can lead to stuttering/skipping/unstable sound on slower machines or soundcards with bad drivers.
+
To get the buffer size in milliseconds, divide it by the output rate and multiply the result by 1000. For a buff_size of 1024 and an output rate of 48kHz (see fmod_system_set_software_format), milliseconds = 1024 / 48000 * 1000 = 21.33ms. This means the mixer updates every 21.33ms.
+
To get the total buffer size multiply the buff_size by the num_buffers value. By default this would be 4 * 1024 = 4096 samples, or 4 * 21.33ms = 85.33ms. This would generally be the total latency of the software mixer, but in reality due to one of the buffers being written to constantly, and the cursor position of the buffer that is audible, the latency is typically more like the (number of buffers - 1.5) multiplied by the buffer length.
+
To convert from milliseconds back to 'samples', simply multiply the value in milliseconds by the sample rate of the output (i.e. 48000 if that is what it is set to), then divide by 1000.
+
The FMOD software mixer mixes to a ringbuffer (a buffer_wrap Buffer in GameMaker). The size of this ringbuffer is determined here. It mixes a block of sound data every 'bufferlength' number of samples, and there are num_buffers number of these blocks that make up the entire ringbuffer. Adjusting these values can lead to extremely low latency performance (smaller values), or greater stability in sound output (larger values).
+
+
Warning
+
The buff_size is generally best left alone. Making the granularity smaller will just increase CPU usage (cache misses and DSP network overhead). Making it larger affects how often you hear commands update such as volume/pitch/pan changes. Anything above 20ms will be noticeable and sound parameter changes will be obvious instead of smooth.
+
+
FMOD chooses the most optimal size by default for best stability, depending on the output type. It is not recommended changing this value unless you really need to. You may get worse performance than the default settings chosen by FMOD. If you do set the size manually, the buff_size argument must be a multiple of four, typically 256, 480, 512, 1024 or 2048 depending on your latency requirements.
+
The values in milliseconds and average latency expected from the settings can be calculated using the following code:
+
var _dsp_buffer_info = fmod_system_get_dsp_buffer_size();
+var _sw_format_info = fmod_system_get_software_format();
+// Note that you can check for errors here with two calls to fmod_last_result(), one after each function.
+
+var _buff_size = _dsp_buffer_info.buff_size;
+var _num_buffers = _dsp_buffer_info.num_buffers;
+var _sample_rate = _sw_format_info.sample_rate;
+
+var _ms = dsp_buffer_info.buff_size * 1000 / _sample_rate;
+
+show_debug_message("Mixer buffer size = {0}", _ms);
+show_debug_message("Mixer Total buffer size = {0}", _ms * _num_buffers);
+show_debug_message("Mixer Average Latency = {0}", _ms * (_num_buffers - 1.5));
+
+
+
Syntax:
+
+fmod_system_set_dsp_buffer_size(buff_size, num_buffers)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| buff_size |
+Real |
+The mixer engine block size, in samples. The default is 1024. Use this to adjust mixer update granularity. See the description for more information on buffer length vs latency. |
+
+
+| num_buffers |
+Real |
+The mixer engine number of buffers used. The default is 4. Use this to adjust mixer latency. See the description for more information on number of buffers vs latency. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_dsp_buffer_size
+
+FMOD Function: System::getDSPBufferSize
+
+
+
This function retrieves the buffer size settings for the FMOD software mixing engine.
+
To get the buff_size in milliseconds, divide it by the output rate and multiply the result by 1000. For a buff_size of 1024 and an output rate of 48kHz (see fmod_system_set_software_format), milliseconds = 1024 / 48000 * 1000 = 21.33ms. This means the mixer updates every 21.33ms.
+
To get the total buffer size multiply the buff_size by the num_buffers value. By default this would be 41024 = 4096 samples, or 421.33ms = 85.33ms. This would generally be the total latency of the software mixer, but in reality due to one of the buffers being written to constantly, and the cursor position of the buffer that is audible, the latency is typically more like the (number of buffers - 1.5) multiplied by the buffer length.
+
To convert from milliseconds back to 'samples', simply multiply the value in milliseconds by the sample rate of the output (i.e. 48000 if that is what it is set to), then divide by 1000.
+
+
Syntax:
+
+fmod_system_get_dsp_buffer_size()
+
+
+
+
+
Returns:
+
+FmodSystemDSPBufferSize
+
+
+
+
+
Back To Top
+
+
fmod_system_set_stream_buffer_size
+
+FMOD Function: System::setStreamBufferSize
+
+
+
This function sets the default file buffer size for newly opened streams.
+
Valid units for the FMOD_TIMEUNIT of file_buffer_size_type are:
+
FMOD_TIMEUNIT.MS
+FMOD_TIMEUNIT.PCM
+FMOD_TIMEUNIT.PCMBYTES
+FMOD_TIMEUNIT.RAWBYTES
+
Larger values will consume more memory, whereas smaller values may cause buffer under-run / starvation / stuttering caused by large delays in disk access (i.e. netstream), or CPU usage in slow machines, or by trying to play too many streams at once.
+
This does not affect streams created with FMOD_MODE.OPENUSER, as the buffer size is specified in fmod_system_create_sound.
+
This does not affect latency of playback. All streams are pre-buffered (unless opened with FMOD_MODE.OPENONLY), so they will always start immediately.
+
Seek and Play operations can sometimes cause a reflush of this buffer.
+
If FMOD_TIMEUNIT.RAWBYTES is used, the memory allocated is two times the size passed in, because FMOD allocates a double buffer.
+
If FMOD_TIMEUNIT.MS, FMOD_TIMEUNIT.PCM or FMOD_TIMEUNIT.PCMBYTES is used, and the stream is infinite (such as a shoutcast netstream), or VBR, then FMOD cannot calculate an accurate compression ratio to work with when the file is opened. This means it will then base the buffersize on FMOD_TIMEUNIT.PCMBYTES, or in other words the number of PCM bytes, but this will be incorrect for some compressed formats. Use FMOD_TIMEUNIT.RAWBYTES for these type (infinite / undetermined length) of streams for more accurate read sizes.
+
To determine the actual memory usage of a stream, including sound buffer and other overhead, use fmod_memory_get_stats before and after creating a sound.
+
The stream may still stutter if the codec uses a large amount of cpu time, which impacts the smaller, internal 'decode' buffer. The decode buffer size is changeable via FmodSystemCreateSoundExInfo.
+
+
Syntax:
+
+fmod_system_set_stream_buffer_size(file_buffer_size, file_buffer_size_type)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| file_buffer_size |
+Real |
+The file buffer size. The default is 16384. |
+
+
+| file_buffer_size_type |
+FMOD_TIMEUNIT |
+The type of units for file_buffer_size. The default is FMOD_TIMEUNIT.RAWBYTES. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_stream_buffer_size
+
+FMOD Function: System::getStreamBufferSize
+
+
+
This function retrieves the default file buffer size for newly opened streams.
+
Valid units for the FMOD_TIMEUNIT of file_buffer_size_type are:
+
FMOD_TIMEUNIT.MS
+FMOD_TIMEUNIT.PCM
+FMOD_TIMEUNIT.PCMBYTES
+FMOD_TIMEUNIT.RAWBYTES
+
+
Syntax:
+
+fmod_system_get_stream_buffer_size()
+
+
+
+
+
Returns:
+
+FmodSystemStreamBufferSize
+
+
+
+
+
Back To Top
+
+
fmod_system_set_advanced_settings
+
+FMOD Function: System::setAdvancedSettings
+
+
+
This function sets advanced settings for the system object, typically to allow adjusting of settings related to resource usage or audio quality.
+
+
Syntax:
+
+fmod_system_set_advanced_settings(settings)
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_advanced_settings
+
+FMOD Function: System::getAdvancedSettings
+
+
+
This function retrieves the advanced settings for the system object.
+
+
Syntax:
+
+fmod_system_get_advanced_settings()
+
+
+
+
+
Returns:
+
+FmodSystemAdvancedSettings
+
+
+
+
+
Back To Top
+
+
fmod_system_set_speaker_position
+
+FMOD Function: System::setSpeakerPosition
+
+
+
This function sets the position of the specified speaker for the current speaker mode.
+
This function allows the user to specify the position of their speaker to account for non standard setups.
+It also allows the user to disable speakers from 3D consideration in a game.
+
This allows you to customize the position of the speakers for the current FMOD_SPEAKERMODE by giving X (left to right) and Y (front to back) coordinates.
+When disabling a speaker, 3D spatialization will be redistributed around the missing speaker so the signal isn't lost.
+
A stereo setup would look like this:
+
fmod_system_set_speaker_position(system, FMOD_SPEAKERMODE.FRONT_LEFT, -1, 0, true);
+fmod_system_set_speaker_position(system, FMOD_SPEAKERMODE.FRONT_RIGHT, 1, 0, true);
+
A 7.1 setup would look like this:
+
fmod_system_set_speaker_position(system, FMOD_SPEAKERMODE.FRONT_LEFT, dsin( -30), dcos( -30), true);
+fmod_system_set_speaker_position(system, FMOD_SPEAKERMODE.FRONT_RIGHT, dsin( 30), dcos( 30), true);
+fmod_system_set_speaker_position(system, FMOD_SPEAKERMODE.FRONT_CENTER, dsin( 0), dcos( 0), true);
+fmod_system_set_speaker_position(system, FMOD_SPEAKERMODE.LOW_FREQUENCY, dsin( 0), dcos( 0), true);
+fmod_system_set_speaker_position(system, FMOD_SPEAKERMODE.SURROUND_LEFT, dsin( -90), dcos( -90), true);
+fmod_system_set_speaker_position(system, FMOD_SPEAKERMODE.SURROUND_RIGHT, dsin( 90), dcos( 90), true);
+fmod_system_set_speaker_position(system, FMOD_SPEAKERMODE.BACK_LEFT, dsin(-150), dcos(-150), true);
+fmod_system_set_speaker_position(system, FMOD_SPEAKERMODE.BACK_RIGHT, dsin( 150), dcos( 150), true);
+
Calling fmod_system_set_software_format will override any customization made with this function.
+
Users of the Studio API should be aware this function does not affect the speaker positions used by the Spatializer DSPs, it is purely for Core API spatialization via fmod_channel_control_set_3d_attributes.
+
+
Syntax:
+
+fmod_system_set_speaker_position(speaker, x, y, active)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| speaker |
+FMOD_SPEAKER |
+The speaker. |
+
+
+| x |
+Real |
+The 2D X position relative to the listener. A value in the range [-1, 1], where: -1 = left, 0 = middle, +1 = right. |
+
+
+| y |
+Real |
+2D Y position relative to the listener. A value in the range [-1, 1], where: -1 = back, 0 = middle, +1 = front. |
+
+
+| active |
+Boolean |
+The active state of a speaker. true = included in 3D calculations, false = ignored. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_speaker_position
+
+FMOD Function: System::getSpeakerPosition
+
+
+
This function retrieves the position of the specified speaker for the current speaker mode.
+
+
Syntax:
+
+fmod_system_get_speaker_position(speaker)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| speaker |
+FMOD_SPEAKER |
+The speaker. |
+
+
+
+
+
+
+
Returns:
+
+FmodSystemSpeakerPosition
+
+
+
+
+
Back To Top
+
+
fmod_system_set_3d_settings
+
+FMOD Function: System::set3DSettings
+
+
+
This function sets the global doppler scale, distance factor and log roll-off scale for all 3D sound in FMOD.
+
The doppler_scale is a general scaling factor for how much the pitch varies due to doppler shifting in 3D sound. Doppler is the pitch bending effect when a sound comes towards the listener or moves away from it, much like the effect you hear when a train goes past you with its horn sounding. With "dopplerscale" you can exaggerate or diminish the effect. FMOD's effective speed of sound at a doppler factor of 1.0 is 340 m/s.
+
The distance_factor is the FMOD 3D engine relative distance factor, compared to 1.0 meters. Another way to put it is that it equates to "how many units per meter does your engine have". For example, if you are using feet then "scale" would equal 3.28.
+This only affects doppler. If you keep your min/max distance, custom roll-off curves, and positions in scale relative to each other, the volume roll-off will not change. If you set this, the mindistance of a sound will automatically set itself to this value when it is created in case the user forgets to set the mindistance to match the new distance_factor.
+
The rolloff_scale is a global factor applied to the roll-off of sounds using roll-off modes other than FMOD_MODE.AS_3D_CUSTOMROLLOFF. When a sound uses a roll-off mode other than FMOD_MODE.AS_3D_CUSTOMROLLOFF and the distance is greater than the sound's minimum distance, the distance for the purposes of distance attenuation is calculated according to the formula distance = (distance - minDistance) * rolloffscale + minDistance.
+
+
Syntax:
+
+fmod_system_set_3d_settings(doppler_scale, distance_factor, rolloff_scale)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| doppler_scale |
+Real |
+A scaling factor for doppler shift. Default is 1. |
+
+
+| distance_factor |
+Real |
+A factor for converting game distance units to FMOD distance units. Default is 1. |
+
+
+| rolloff_scale |
+Real |
+A scaling factor for distance attenuation. When a sound uses a roll-off mode other than FMOD_MODE.AS_3D_CUSTOMROLLOFF and the distance is greater than the sound's minimum distance, the distance is scaled by the roll-off scale. Default is 1. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_3d_settings
+
+FMOD Function: System::get3DSettings
+
+
+
This function retrieves the global doppler scale, distance factor and roll-off scale for all 3D sounds.
+
+
Syntax:
+
+fmod_system_get_3d_settings()
+
+
+
+
+
Returns:
+
+FmodSystem3DSettings
+
+
+
+
+
Back To Top
+
+
fmod_system_set_3d_num_listeners
+
+FMOD Function: System::set3DNumListeners
+
+
+
This function sets the number of 3D 'listeners' in the 3D sound scene.
+
This function is useful mainly for split-screen game purposes.
+
If the number of listeners is set to more than 1, then panning and doppler are turned off. All sound effects will be mono. FMOD uses a 'closest sound to the listener' method to determine what should be heard in this case.
+
+
+
Syntax:
+
+fmod_system_set_3d_num_listeners(num)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| num |
+Real |
+The number of listeners in the scene. A value in the range [1, FMOD_MAX_LISTENERS]. The default is 1. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_3d_num_listeners
+
+FMOD Function: System::get3DNumListeners
+
+
+
This function retrieves the number of 3D listeners.
+
+
+
Syntax:
+
+fmod_system_get_3d_num_listeners()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_set_3d_rolloff_callback
+
+FMOD Function: System::set3DRolloffCallback
+
+
+
This function enables callbacks for custom calculation of distance attenuation.
+
This function overrides FMOD_MODE.AS_3D_INVERSEROLLOFF, FMOD_MODE.AS_3D_LINEARROLLOFF, FMOD_MODE.AS_3D_LINEARSQUAREROLLOFF, FMOD_MODE.AS_3D_INVERSETAPEREDROLLOFF and FMOD_MODE.AS_3D_CUSTOMROLLOFF.
+
See also: Callback behavior
+
This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.
+
+
Syntax:
+
+fmod_system_set_3d_rolloff_callback()
+
+
+
+
+
Returns:
+
+N/A
+
+
+
Triggers:
+
+Social Async Event
+
+
+
+
+| Key |
+Type |
+Description |
+
+
+
+
+| type |
+String |
+The string value "fmod_system_set_3d_rolloff_callback". |
+
+
+| distance |
+Real |
+The distance. |
+
+
+| channel_ref |
+Real |
+The reference to the channel for which this event is triggered. |
+
+
+
+
+
+
+
Back To Top
+
+
fmod_system_set_network_proxy
+
+FMOD Function: System::setNetworkProxy
+
+
+
This function sets a proxy server to use for all subsequent internet connections.
+
You should specify the proxy in host:port format e.g. www.fmod.com:8888 (defaults to port 80 if no port is specified).
+
Basic authentication is supported using user:password@host:port format e.g. bob:sekrit123@www.fmod.com:8888
+
+
Syntax:
+
+fmod_system_set_network_proxy(proxy)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| proxy |
+String |
+The proxy server URL. (as a UTF-8 string) |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_network_proxy
+
+FMOD Function: System::getNetworkProxy
+
+
+
This function retrieves the URL of the proxy server used in internet streaming.
+
+
Syntax:
+
+fmod_system_get_network_proxy()
+
+
+
+
+
Returns:
+
+String
+
+
+
+
+
Back To Top
+
+
fmod_system_set_network_timeout
+
+FMOD Function: System::setNetworkTimeout
+
+
+
This function sets the timeout for network streams.
+
+
Syntax:
+
+fmod_system_set_network_timeout(timeout)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| timeout |
+Real |
+The timeout value, expressed in milliseconds. Default is 5000. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_network_timeout
+
+FMOD Function: System::getNetworkTimeout
+
+
+
This function retrieves the timeout value (in milliseconds) for network streams.
+
+
Syntax:
+
+fmod_system_get_network_timeout()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_get_version
+
+FMOD Function: System::getVersion
+
+
+
This function retrieves the FMOD version number.
+
The FMOD version is a 32 bit hexadecimal value formatted as 16:8:8, with the upper 16 bits being the product version, the middle 8 bits being the major version and the bottom 8 bits being the minor version. For example a value of 0x00010203 is equal to 1.02.03.
+
+
Note
+
You should compare this against the FMOD_VERSION macro to make sure header and runtime library versions match.
+
+
+
Syntax:
+
+fmod_system_get_version()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_get_channels_playing
+
+FMOD Function: System::getChannelsPlaying
+
+
+
This function retrieves the number of currently playing Channels.
+
For differences between real and virtual voices see the Virtual Voices guide for more information.
+
+
Syntax:
+
+fmod_system_get_channels_playing()
+
+
+
+
+
Returns:
+
+FmodSystemChannelsPlaying
+
+
+
+
+
Back To Top
+
+
fmod_system_get_cpu_usage
+
+FMOD Function: System::getCPUUsage
+
+
+
This function retrieves the amount of CPU used for different parts of the FMOD Core engine.
+
For readability, the percentage values are smoothed to provide a more stable output.
+
+
Syntax:
+
+fmod_system_get_cpu_usage()
+
+
+
+
+
Returns:
+
+FmodCPUUsage
+
+
+
+
+
Back To Top
+
+
fmod_system_get_file_usage
+
+FMOD Function: System::getFileUsage
+
+
+
This function retrieves information about file reads.
+
+
Note
+
The values returned are running totals that never reset.
+
+
+
Syntax:
+
+fmod_system_get_file_usage()
+
+
+
+
+
Returns:
+
+FmodSystemFileUsage
+
+
+
+
+
Back To Top
+
+
fmod_system_get_default_mix_matrix
+
+FMOD Function: System::getDefaultMixMatrix
+
+
+
This function retrieves the default matrix used to convert from one speaker mode to another.
+
The matrix is returned as an Array.
+
The gain for source channel 's' to target channel 't' is matrix[t * matrixhop + s].
+
If source_speaker_mode or target_speaker_mode is FMOD_SPEAKERMODE.RAW, this function will return FMOD_RESULT.ERR_INVALID_PARAM.
+
+
Syntax:
+
+fmod_system_get_default_mix_matrix(source_speaker_mode, target_speaker_mode, matrix_hop)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| source_speaker_mode |
+FMOD_SPEAKERMODE |
+The speaker mode being converted from. |
+
+
+| target_speaker_mode |
+FMOD_SPEAKERMODE |
+The speaker mode being converted to. |
+
+
+| matrix_hop |
+Real |
+The number of source channels in the matrix. If this is 0, the number of source channels will be derived from source_speaker_mode. A maximum value of FMOD_MAX_CHANNEL_WIDTH. |
+
+
+
+
+
+
+
Returns:
+
+Array of Real
+
+
+
+
+
Back To Top
+
+
fmod_system_get_speaker_mode_channels
+
+FMOD Function: System::getSpeakerModeChannels
+
+
+
This function retrieves the channel count for a given speaker mode.
+
+
Syntax:
+
+fmod_system_get_speaker_mode_channels(mode)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| mode |
+FMOD_SPEAKERMODE |
+The speaker mode to query. |
+
+
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_create_sound
+
+FMOD Function: System::createSound
+
+
+
This function loads a sound into memory, opens it for streaming or sets it up for callback-based sounds.
+
It returns a reference to the newly created Sound.
+
FMOD_MODE.CREATESAMPLE will try to load and decompress the whole sound into memory, use FMOD_MODE.CREATESTREAM to open it as a stream and have it play back in realtime from disk or another medium. FMOD_MODE.CREATECOMPRESSEDSAMPLE can also be used for certain formats to play the sound directly in its compressed format from the mixer.
+
+- To open a file or URL as a stream, so that it decompresses / reads at runtime, instead of loading / decompressing into memory all at the time of this call, use the
FMOD_MODE.CREATESTREAM flag.
+- To open a file or URL as a compressed sound effect that is not streamed and is not decompressed into memory at load time, use
FMOD_MODE.CREATECOMPRESSEDSAMPLE. This is supported with MPEG (mp2/mp3), ADPCM/FADPCM, XMA, AT9 and FSB Vorbis files only. This is useful for those who want realtime compressed sound effects, but not the overhead of disk access.
+- To open a sound as 2D, so that it is not affected by 3D processing, use the
FMOD_MODE.AS_2D flag. 3D sound commands will be ignored on these types of sounds.
+- To open a sound as 3D, so that it is treated as a 3D sound, use the
FMOD_MODE.AS_3D flag.
+
+
+
Note
+
FMOD_MODE.OPENRAW, FMOD_MODE.OPENMEMORY, FMOD_MODE.OPENMEMORY_POINT and FMOD_MODE.OPENUSER will not work here without the exinfo structure present, as more information is needed.
+
+
Use FMOD_MODE.NONBLOCKING to have the sound open or load in the background. You can use fmod_sound_get_open_state to determine if it has finished loading / opening or not. While it is loading (not ready), sound functions are not accessible for that sound. Do not free memory provided with FMOD_MODE.OPENMEMORY if the sound is not in a ready state, as it will most likely lead to a crash.
+
To account for slow media that might cause buffer underrun (skipping / stuttering / repeating blocks of audio) with sounds created with FMOD_MODE.CREATESTREAM, use fmod_system_set_stream_buffer_size to increase read ahead.
+
As using FMOD_MODE.OPENUSER causes FMOD to ignore whatever is passed as the first argument name_or_buffer, recommended practice is to pass 0 or equivalent.
+
Specifying FMOD_MODE.OPENMEMORY_POINT will POINT to the Buffer that you pass as name_or_buff, rather than allocating its own sound buffers and duplicating it internally, this means you cannot free the memory while FMOD is using it, until after fmod_sound_release is called.
+
With FMOD_MODE.OPENMEMORY_POINT, only PCM formats and compressed formats using FMOD_MODE.CREATECOMPRESSEDSAMPLE are supported.
+
+
Warning
+
Use of FMOD_MODE.NONBLOCKING is currently not supported for JavaScript.
+
+
+
Syntax:
+
+fmod_system_create_sound(name_or_buff, mode, extra)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| name_or_buff |
+String or Buffer |
+The name of the file or URL to open or a buffer to a preloaded sound memory block if FMOD_MODE.OPENMEMORY / FMOD_MODE.OPENMEMORY_POINT is used. |
+
+
+| mode |
+FMOD_MODE |
+The behavior modifier for opening the sound. |
+
+
+| extra |
+FmodSystemCreateSoundExInfo |
+OPTIONAL Extended information for creating the sound. Defaults to an empty struct. |
+
+
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_create_stream
+
+FMOD Function: System::createStream
+
+
+
This function opens a sound for streaming.
+
It returns a reference to the newly created Sound.
+
This is a convenience function for fmod_system_create_sound with the FMOD_MODE.CREATESTREAM flag added.
+
A stream only has one decode buffer and file handle, and therefore can only be played once. It cannot play multiple times at once because it cannot share a stream buffer if the stream is playing at different positions. Open multiple streams to have them play concurrently.
+
+
Syntax:
+
+fmod_system_create_stream(name_or_buff, mode, extra)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| name_or_buff |
+String or Buffer |
+The name of the file or URL to open or a Buffer storing a preloaded sound memory block if FMOD_MODE.OPENMEMORY / FMOD_MODE.OPENMEMORY_POINT is used. |
+
+
+| mode |
+FMOD_MODE |
+The behavior modifier for opening the sound. |
+
+
+| extra |
+FmodSystemCreateSoundExInfo |
+OPTIONAL Extended information while playing the sound. |
+
+
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_create_dsp
+
+FMOD Function: System::createDSP
+
+
+
This function creates a DSP object.
+
It returns a reference to the newly created DSP unit.
+
A DSP object is a module that can be inserted into the mixing graph to allow sound filtering or sound generation. See the DSP architecture guide for more information.
+
DSPs must be attached to the DSP graph before they become active, either via fmod_channel_control_add_dsp or fmod_dsp_add_input.
+
+
Syntax:
+
+fmod_system_create_dsp()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_create_dsp_by_type
+
+FMOD Function: System::createDSPByType
+
+
+
This function creates a DSP object given a built-in type index.
+
It returns a reference to the newly created DSP unit.
+
A DSP object is a module that can be inserted into the mixing graph to allow sound filtering or sound generation. See the FMOD DSP architecture guide for more information.
+
DSPs must be attached to the DSP graph before they become active, either via fmod_channel_control_add_dsp or fmod_dsp_add_input.
+
Using FMOD_DSP_TYPE.VSTPLUGIN or FMOD_DSP_TYPE.WINAMPPLUGIN will return the first loaded plugin of this type.
+
+
Warning
+
The extension currently doesn't support plugins.
+
+
+
Syntax:
+
+fmod_system_create_dsp_by_type(type)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| type |
+FMOD_DSP_TYPE |
+The type of built-in DSP unit to create. |
+
+
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_create_channel_group
+
+FMOD Function: System::createChannelGroup
+
+
+
This function creates a ChannelGroup object.
+
The function returns a reference to the newly created ChannelGroup.
+
ChannelGroups can be used to assign / group Channels, for things such as volume scaling. ChannelGroups are also used for sub-mixing. Any Channels that are assigned to a ChannelGroup get submixed into that ChannelGroup's 'tail' DSP. See FMOD_CHANNELCONTROL_DSP_INDEX.TAIL.
+
If a ChannelGroup has an effect added to it, the effect is processed post-mix from the Channels and ChannelGroups below it in the mix hierarchy. See the DSP architecture guide for more information.
+
All ChannelGroups will initially output directly to the master ChannelGroup (See fmod_system_get_master_channel_group). ChannelGroups can be re-parented with fmod_channel_group_add_group.
+
+
Syntax:
+
+fmod_system_create_channel_group(name)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| name |
+String |
+A label for the ChannelGroup, for identification purposes. |
+
+
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_create_sound_group
+
+FMOD Function: System::createSoundGroup
+
+
+
This function creates a SoundGroup object.
+
It returns a reference to the newly created SoundGroup.
+
A SoundGroup is a way to address multiple Sounds at once with group level commands, such as:
+
+
Once a SoundGroup is created, fmod_sound_set_sound_group is used to put a Sound in a SoundGroup.
+
+
Syntax:
+
+fmod_system_create_sound_group(name)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| name |
+String |
+The name of the SoundGroup. |
+
+
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_create_reverb_3d
+
+FMOD Function: System::createReverb3D
+
+
+
This function creates a 'virtual reverb' object. This object reacts to 3D location and morphs the reverb environment based on how close it is to the reverb object's center.
+
The function returns a reference to the newly created virtual reverb object.
+
Multiple reverb objects can be created to achieve a multi-reverb environment. 1 reverb object is used for all 3D reverb objects (slot 0 by default).
+
The 3D reverb object is a sphere having 3D attributes (position, minimum distance, maximum distance) and reverb properties.
+
The properties and 3D attributes of all reverb objects collectively determine, along with the listener's position, the settings of and input gains into a single 3D reverb DSP.
+
When the listener is within the sphere of effect of one or more 3D reverbs, the listener's 3D reverb properties are a weighted combination of such 3D reverbs.
+
When the listener is outside all of the reverbs, no reverb is applied.
+
fmod_system_set_reverb_properties can be used to create an alternative reverb that can be used for 2D and background global reverb.
+
To avoid this reverb interfering with the reverb slot used by the 3D reverb, 2D reverb should use a different slot ID with fmod_system_set_reverb_properties, otherwise FmodSystemAdvancedSettings's reverb_3d_instance property can also be used to place 3D reverb on a different reverb slot.
+
Use fmod_channel_control_set_reverb_properties to turn off reverb for 2D sounds (i.e. set wet = 0).
+
Creating multiple reverb objects does not impact performance. These are 'virtual reverbs'. There will still be only one reverb DSP running that just morphs between the different virtual reverbs.
+
Note about reverb DSP unit allocation. To remove the DSP unit and the associated CPU cost, first make sure all 3D reverb objects are released. Then call fmod_system_set_reverb_properties with the 3D reverb's slot ID (default is 0) with a property point of 0, to signal that the reverb instance should be deleted.
+
If a 3D reverb is still present, and fmod_system_set_reverb_properties function is called to free the reverb, the 3D reverb system will immediately recreate it upon the next fmod_system_update call.
+
+
+
Syntax:
+
+fmod_system_create_reverb_3d()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_play_sound
+
+FMOD Function: System::playSound
+
+
+
This function plays a Sound on a Channel.
+
It returns the newly playing Channel.
+
When a sound is played, it will use the sound's default frequency and priority. See fmod_sound_set_defaults.
+
A sound defined as FMOD_MODE.AS_3D will by default play at the 3D position of the listener. To set the 3D position of the Channel before the sound is audible, start the Channel paused by setting the pause parameter to true, and call fmod_channel_control_set_3d_attributes.
+
Specifying a channel_group_ref as part of fmod_system_play_sound is more efficient than using fmod_channel_set_channel_group after fmod_system_play_sound, and could avoid audible glitches if the sound is not in a paused state.
+
Channels are reference counted to handle dead or stolen Channel handles. See the white paper on Channel handles for more information.
+
Playing more Sounds than physical Channels allow is handled with virtual voices. See the white paper on Virtual Voices for more information.
+
+
Syntax:
+
+fmod_system_play_sound(sound_ref, channel_group_ref, pause)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| sound_ref |
+Real |
+A reference to the sound to play. |
+
+
+| channel_group_ref |
+Real |
+A reference to the ChannelGroup to output to instead of the master. |
+
+
+| pause |
+Boolean |
+Whether to start in the paused state. Start a Channel paused to allow altering attributes without it being audible, then follow it up with a call to fmod_channel_control_set_paused with pause = false. |
+
+
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_play_dsp
+
+FMOD Function: System::playDSP
+
+
+
This function plays a DSP along with any of its inputs on a Channel.
+
It returns the newly playing Channel.
+
Specifying a channelgroup as part of fmod_system_play_dsp is more efficient than using fmod_channel_set_channel_group after fmod_system_play_dsp, and could avoid audible glitches if the fmod_system_play_dsp is not in a paused state.
+
Channels are reference counted to handle dead or stolen Channel handles. See the white paper on Channel handles for more information.
+
Playing more Sounds or DSPs than physical Channels allow is handled with virtual voices. See the white paper on Virtual Voices for more information.
+
+
Syntax:
+
+fmod_system_play_dsp(dsp_ref, channel_group_ref, pause)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| dsp_ref |
+Real |
+A reference to the DSP unit to play. |
+
+
+| channel_group_ref |
+Real |
+A reference to the ChannelGroup to output to instead of the master. |
+
+
+| pause |
+Boolean |
+Whether to start in the paused state. Start a Channel paused to allow altering attributes without it being audible, then follow it up with a call to fmod_channel_control_set_paused with pause = false. |
+
+
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_get_channel
+
+FMOD Function: System::getChannel
+
+
+
This function retrieves a reference to a Channel by ID.
+
This function is mainly for getting handles to existing (playing) Channels and setting their attributes. The only way to 'create' an instance of a Channel for playback is to use fmod_system_play_sound or fmod_system_play_dsp.
+
+
Syntax:
+
+fmod_system_get_channel(index)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| index |
+Real |
+The channel's index in the FMOD Channel pool. Specify a Channel number from 0 to the max_channels value specified in fmod_system_init minus 1. |
+
+
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_get_master_channel_group
+
+FMOD Function: System::getMasterChannelGroup
+
+
+
This function retrieves the master ChannelGroup that all sounds ultimately route to.
+
This is the default ChannelGroup that Channels play on, unless a different ChannelGroup is specified with fmod_system_play_sound, fmod_system_play_dsp or fmod_channel_set_channel_group.
+A master ChannelGroup can be used to do things like set the 'master volume' for all playing Channels. See fmod_channel_control_set_volume.
+
+
Syntax:
+
+fmod_system_get_master_channel_group()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_get_master_sound_group
+
+FMOD Function: System::getMasterSoundGroup
+
+
+
This function retrieves the default SoundGroup, where all sounds are placed when they are created.
+
If a SoundGroup is released, the Sounds in it will be put back into this SoundGroup.
+
+
Syntax:
+
+fmod_system_get_master_sound_group()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_set_3d_listener_attributes
+
+FMOD Function: System::set3DListenerAttributes
+
+
+
This function sets the position, velocity and orientation of the specified 3D sound listener.
+
The forward and up vectors must be perpendicular and be of unit length (magnitude of each vector should be 1).
+
Vectors must be provided in the correct handedness.
+
For velocity, remember to use units per second, and not units per frame. This is a common mistake and will make the doppler effect sound wrong if velocity is based on movement per frame rather than a fixed time period.
+If velocity per frame is calculated, it can be converted to velocity per second by dividing it by the time taken between frames as a fraction of a second.
+i.e.
+
velocity_units_per_second = (position_currentframe - position_lastframe) / time_taken_since_last_frame_in_seconds;
+
At 60 FPS the formula would look like velocity_units_per_second = (position_currentframe - position_lastframe) / 0.0166667.
+
+
+
Syntax:
+
+fmod_system_set_3d_listener_attributes(listener_index, position, velocity, forward, up)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| listener_index |
+Real |
+The index of the listener to set 3D attributes on. Listeners are indexed from 0, to FMOD_MAX_LISTENERS - 1, in a multi-listener environment. |
+
+
+| position |
+FmodVector |
+The position in 3D world space used for panning and attenuation, in Distance units. |
+
+
+| velocity |
+FmodVector |
+The velocity in 3D space used for doppler, in Distance units per second. |
+
+
+| forward |
+FmodVector |
+The forwards orientation. |
+
+
+| up |
+FmodVector |
+The upwards orientation. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_3d_listener_attributes
+
+FMOD Function: System::get3DListenerAttributes
+
+
+
This function retrieves the position, velocity and orientation of the specified 3D sound listener.
+
+
+
Syntax:
+
+fmod_system_get_3d_listener_attributes(listener_index)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| listener_index |
+Real |
+The index of the listener to get 3D attributes for. Listeners are indexed from 0, to FMOD_MAX_LISTENERS - 1, in a multi-listener environment. |
+
+
+
+
+
+
+
Returns:
+
+Fmod3DAttributes
+
+
+
+
+
Back To Top
+
+
fmod_system_set_reverb_properties
+
+FMOD Function: System::setReverbProperties
+
+
+
This function sets parameters for the global reverb environment.
+
To assist in defining reverb properties there are several presets available, see FMOD_REVERB_PRESETS.
+
When using each instance for the first time, FMOD will create an SFX reverb DSP unit that takes up several hundred kilobytes of memory and some CPU.
+
+
Syntax:
+
+fmod_system_set_reverb_properties(reverb_instance_index, properties)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| reverb_instance_index |
+Real |
+The index of the particular reverb instance to target. A value in the range [0, FMOD_REVERB_MAXINSTANCES]. |
+
+
+| properties |
+FmodReverbProperties |
+The reverb environment description. Passing 0 to this function will delete the reverb. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_reverb_properties
+
+FMOD Function: System::getReverbProperties
+
+
+
This function retrieves the current reverb environment for the specified reverb instance.
+
+
Syntax:
+
+fmod_system_get_reverb_properties(reverb_instance_index)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| reverb_instance_index |
+Real |
+The index of the particular reverb instance to target. |
+
+
+
+
+
+
+
Returns:
+
+FmodReverbProperties
+
+
+
+
+
Back To Top
+
+
fmod_system_attach_channel_group_to_port
+
+FMOD Function: System::attachChannelGroupToPort
+
+
+
This function connects the output of the specified ChannelGroup to an audio port on the output driver.
+
Ports are additional outputs supported by some FMOD_OUTPUTTYPE plugins and can include things like controller headsets or dedicated background music streams. See the Port Support section (where applicable) of each platform's getting started guide found in the platform details chapter.
+
+
Syntax:
+
+fmod_system_attach_channel_group_to_port(port_type, port_index, channel_group_ref, pass_thru)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| port_type |
+FMOD_PORT_TYPE |
+The port type (output mode specific). |
+
+
+| port_index |
+FMOD_PORT_INDEX |
+The index to specify which instance of the specified port_type to use (output mode specific). |
+
+
+| channel_group_ref |
+Real |
+The ChannelGroup to attach the port to. |
+
+
+| pass_thru |
+Boolean |
+Whether the signal should additionally route to the existing ChannelGroup output. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_detach_channel_group_from_port
+
+FMOD Function: System::detachChannelGroupFromPort
+
+
+
This function disconnects the output of the specified ChannelGroup from an audio port on the output driver.
+
Removing a ChannelGroup from a port will reroute the audio back to the main mix.
+
+
Syntax:
+
+fmod_system_detach_channel_group_from_port(channel_group_ref)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| channel_group_ref |
+Real |
+The ChannelGroup to detach the port from. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_record_num_drivers
+
+FMOD Function: System::getRecordNumDrivers
+
+
+
This function retrieves the number of recording devices available for this output mode. Use this to enumerate all recording devices possible so that the user can select one.
+
+
Syntax:
+
+fmod_system_get_record_num_drivers()
+
+
+
+
+
Returns:
+
+FmodSystemRecordNumDrivers
+
+
+
+
+
Back To Top
+
+
fmod_system_get_record_driver_info
+
+FMOD Function: System::getRecordDriverInfo
+
+
+
This function retrieves identification information about an audio device specified by its index, and specific to the output mode.
+
+
Syntax:
+
+fmod_system_get_record_driver_info(record_driver_index)
+
+
+
+
+
+
Returns:
+
+FmodSystemRecordDriverInfo
+
+
+
+
+
Back To Top
+
+
fmod_system_get_record_position
+
+FMOD Function: System::getRecordPosition
+
+
+
This function retrieves the current recording position of the record buffer in PCM samples.
+
fmod_last_result will return FMOD_RESULT.ERR_RECORD_DISCONNECTED if the driver is unplugged.
+
The position will return to 0 when fmod_system_record_stop is called or when a non-looping recording reaches the end.
+
+
Note
+
on PS4, record devices are virtual so 'position' will continue to update if the device is unplugged (the OS is generating silence). fmod_last_result will still report FMOD_RESULT.ERR_RECORD_DISCONNECTED for your information though.
+
+
+
Syntax:
+
+fmod_system_get_record_position(device_index)
+
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_record_start
+
+FMOD Function: System::recordStart
+
+
+
This function starts the recording engine recording to a pre-created Sound object.
+
fmod_last_result will return FMOD_RESULT.ERR_RECORD_DISCONNECTED if the driver is unplugged.
+
The sound must be created as FMOD_MODE.CREATESAMPLE. Raw PCM data can be accessed with fmod_sound_lock, fmod_sound_unlock and fmod_system_get_record_position.
+
Recording from the same driver a second time will stop the first recording.
+
For lowest latency set the Sound sample rate to the rate returned by fmod_system_get_record_driver_info, otherwise a resampler will be allocated to handle the difference in frequencies, which adds latency.
+
+
Syntax:
+
+fmod_system_record_start(device_index, sound_ref, loop)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| device_index |
+Real |
+The index of the recording device. A value in the range [0, fmod_system_get_record_num_drivers]. |
+
+
+| sound_ref |
+Real |
+A reference to a user-created sound for the user to record to. |
+
+
+| loop |
+Boolean |
+A flag to tell the recording engine whether to continue recording to the provided sound from the start again, after it has reached the end. If this is set to true the data will be continually be overwritten once every loop. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_record_stop
+
+FMOD Function: System::recordStop
+
+
+
This function stops the recording engine from recording to a pre-created Sound object.
+
fmod_last_result returns no error if unplugged or already stopped.
+
+
Syntax:
+
+fmod_system_record_stop(device_index)
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_is_recording
+
+FMOD Function: System::isRecording
+
+
+
This function retrieves the state of the FMOD recording API, i.e. if it is currently recording or not.
+
Recording can be started with fmod_system_record_start and stopped with fmod_system_record_stop.
+
fmod_last_result will return FMOD_RESULT.ERR_RECORD_DISCONNECTED if the driver is unplugged.
+
+
Note
+
On PS4, record devices are virtual so 'position' will continue to update if the device is unplugged (the OS is generating silence). fmod_last_result will still report FMOD_RESULT.ERR_RECORD_DISCONNECTED for your information though.
+
+
+
Syntax:
+
+fmod_system_is_recording(device_index)
+
+
+
+
+
+
Returns:
+
+Boolean
+
+
+
+
+
Back To Top
+
+
fmod_system_create_geometry
+
+FMOD Function: System::createGeometry
+
+
+
This is a geometry creation function. This function will create a base geometry object which can then have polygons added to it.
+
It returns a reference to the newly created Geometry object.
+
Polygons can be added to a geometry object using fmod_geometry_add_polygon. For best efficiency, avoid overlapping of polygons and long thin polygons.
+
A geometry object stores its polygons in a group to allow optimization for line testing, insertion and updating of geometry in real-time.
+Geometry objects also allow for efficient rotation, scaling and translation of groups of polygons.
+
It is important to set the value of max_world_size to an appropriate value using fmod_system_set_geometry_settings.
+
+
Syntax:
+
+fmod_system_create_geometry(max_polygons, max_vertices)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| max_polygons |
+Real |
+The maximum number of polygons within this object. |
+
+
+| max_vertices |
+Real |
+The maximum number of vertices within this object. |
+
+
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_set_geometry_settings
+
+FMOD Function: System::setGeometrySettings
+
+
+
This function sets the maximum world size for the geometry engine for performance / precision reasons.
+
FMOD uses an efficient spatial partitioning system to store polygons for ray casting purposes.
+The maximum size of the world (max_world_size) should be set to allow processing within a known range.
+Outside of this range, objects and polygons will not be processed as efficiently.
+Excessive world size settings can also cause loss of precision and efficiency.
+
Setting max_world_size should be done first before creating any geometry. It can be done any time afterwards but may be slow in this case.
+
+
Syntax:
+
+fmod_system_set_geometry_settings(max_world_size)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| max_world_size |
+Real |
+The maximum size of the world from the centerpoint to the edge using the same units used in other 3D functions. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_geometry_settings
+
+FMOD Function: System::getGeometrySettings
+
+
+
This function retrieves the maximum world size for the geometry engine.
+
FMOD uses an efficient spatial partitioning system to store polygons for ray casting purposes.
+The maximum size of the world should be set to allow processing within a known range.
+Outside of this range, objects and polygons will not be processed as efficiently.
+Excessive world size settings can also cause loss of precision and efficiency.
+
+
Syntax:
+
+fmod_system_get_geometry_settings()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_load_geometry
+
+FMOD Function: System::loadGeometry
+
+
+
This function creates a geometry object from a block of memory which contains pre-saved geometry data.
+
It creates a reference to the newly created Geometry object.
+
This function avoids the need to manually create and add geometry for faster start time.
+
+
Syntax:
+
+fmod_system_load_geometry(buff, length)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| buff |
+Buffer |
+A buffer storing pre-saved geometry data from an earlier call to fmod_geometry_save. |
+
+
+| length |
+Real |
+The size of the data in buff, in bytes. |
+
+
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
Back To Top
+
+
fmod_system_get_geometry_occlusion
+
+FMOD Function: System::getGeometryOcclusion
+
+
+
This function calculates geometry occlusion between a listener and a sound source.
+
If single-sided polygons have been created, it is important to get the source and listener positions around the right way, as the occlusion from point A to point B may not be the same as the occlusion from point B to point A.
+
+
Syntax:
+
+fmod_system_get_geometry_occlusion()
+
+
+
+
+
Returns:
+
+FmodSystemGeometryOcclusion
+
+
+
+
+
Back To Top
+
+
fmod_system_lock_dsp
+
+FMOD Function: System::lockDSP
+
+
+
This is a mutual exclusion function to lock the FMOD DSP engine (which runs asynchronously in another thread), so that it will not execute.
+
If the FMOD DSP engine is already executing, this function will block until it has completed.
+
The function may be used to synchronize DSP network operations carried out.
+
An example of using this function may be for when you want to construct a DSP sub-network, without the DSP engine executing in the background while the sub-network is still under construction.
+
Once the DSP engine no longer needs to be locked, it must be unlocked with fmod_system_unlock_dsp.
+
+
Note
+
The DSP engine should not be locked for a significant amount of time, otherwise inconsistency in the audio output may result. (audio skipping / stuttering).
+
+
+
Syntax:
+
+fmod_system_lock_dsp()
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_unlock_dsp
+
+FMOD Function: System::unlockDSP
+
+
+
This is a mutual exclusion function to unlock the FMOD DSP engine (which runs asynchronously in another thread) and let it continue executing.
+
The DSP engine must be locked with fmod_system_lock_dsp before this function is called.
+
+
Syntax:
+
+fmod_system_unlock_dsp()
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_set_callback
+
+FMOD Function: System::setCallback
+
+
+
This function enables callbacks for System level notifications.
+
+
See also: Callback Behavior
+
This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.
+
+
Syntax:
+
+fmod_system_set_callback(type)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| type |
+FMOD_SYSTEM_CALLBACK |
+A bitfield specifying which callback types are required, to filter out unwanted callbacks. Use FMOD_SYSTEM_CALLBACK.ALL to receive all supported callback kinds. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
Triggers:
+
+Social Async Event
+
+
+
+
+| Key |
+Type |
+Description |
+
+
+
+
+| type |
+String |
+the string "fmod_system_set_callback" |
+
+
+| kind |
+FMOD_SYSTEM_CALLBACK |
+The kind of callback triggered. |
+
+
+
+
+
+
+
Back To Top
+
+
fmod_system_set_user_data
+
+FMOD Function: System::setUserData
+
+
+
This function sets a user value associated with the currently selected System object.
+
+
Note
+
While FMOD supports arbitrary User Data, this function only allows you to set a real value (a double-precision floating-point value).
+
+
+
Note
+
If you've created multiple systems, use fmod_system_select to select the FMOD system for which you want to set the user data and then call this function. After that, you can switch back using another call to fmod_system_select.
+
+
+
Syntax:
+
+fmod_system_set_user_data(data)
+
+
+
+
+| Argument |
+Type |
+Description |
+
+
+
+
+| data |
+Real |
+The user-specified data to be stored within the System object. |
+
+
+
+
+
+
+
Returns:
+
+N/A
+
+
+
+
+
Back To Top
+
+
fmod_system_get_user_data
+
+FMOD Function: System::getUserData
+
+
+
This function retrieves the user value associated with the currently selected System object.
+
+
Note
+
While FMOD allows arbitrary User Data, this function only allows you to get a real value (a double-precision floating-point value).
+
+
+
Note
+
If you've created multiple systems, use fmod_system_select to select the FMOD system of which you want to get the user data and then call this function. After that, you can switch back using another call to fmod_system_select.
+
+
+
Syntax:
+
+fmod_system_get_user_data()
+
+
+
+
+
Returns:
+
+Real
+
+
+
+
+
