Skip to content

system

Jump to bottom
Francisco Dias edited this page Nov 22, 2024 · 5 revisions

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:

Note

fmod_system_set_output can be called before or after fmod_system_init on Android, GameCore, UWP, Windows and Mac. Other platforms can only call this before fmod_system_init.

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.

Note

This will internally call fmod_system_close, so calling fmod_system_close before this function is not necessary.


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_system_set_software_format

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.

Note

This function must be called before fmod_system_init, or after fmod_system_close.


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_system_get_software_format

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)
Argument Type Description
settings FmodSystemAdvancedSettings The advanced settings to use.



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.

Note

Users of the Studio API should call fmod_studio_system_set_num_listeners instead of this function.


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.

Note

Users of the Studio API should call fmod_studio_system_get_num_listeners instead of this function.


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:[email protected]: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.

Note

the 3D reverb system will not affect Studio events unless it is explicitly enabled by calling fmod_studio_event_instance_set_reverb_level on each event instance.


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.

Note

Users of the Studio API should call fmod_studio_system_set_listener_attributes instead of this function.


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.

Note

Users of the Studio API should call fmod_studio_system_get_listener_attributes instead of this function.


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)
Argument Type Description
record_driver_index Real The index of the recording device. A value in the range [0, fmod_system_get_record_num_drivers].



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)
Argument Type Description
device_index Real The index of the recording device. A value in the range [0, fmod_system_get_record_num_drivers].



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)
Argument Type Description
device_index Real The index of the recording device. A value in the range [0, fmod_system_get_record_num_drivers].



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)
Argument Type Description
device_index Real The index of the recording device. A value in the range [0, fmod_system_get_record_num_drivers].



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.

Note

FMOD System callbacks will be triggered as a Social Async Event but the async_load DS map won't contain any specific information.

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



YoYoGames 2024

FMOD Extension

Guides

FMOD Core Reference

FMOD Studio Reference

Extras

Clone this wiki locally