Skip to content

channel_control

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

Channel Control

FMOD Object: ChannelControl


This module holds functionality related to the shared APIs between Channel and ChannelGroup.

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_channel_control_is_playing

FMOD Function: ChannelControl::isPlaying


This function retrieves the playing state.

Note

A channel is considered playing after fmod_system_play_sound or fmod_system_play_dsp, even if it is paused.

Note

A channelgroup is considered playing if it has any playing channels.


Syntax:

fmod_channel_control_is_playing(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a channelcontrol.



Returns:

Boolean



Back To Top

fmod_channel_control_stop

FMOD Function: ChannelControl::stop


This function stops the channel (or all channels in nested channelgroups) from playing.

This will free up internal resources for reuse by the virtual voice system.

Note

Channels are stopped automatically when their playback position reaches the length of the sound being played. This is not the case however if the channel is playing a DSP or the sound is looping, in which case the channel will continue playing until stop is called. Once stopped, the channel handle will become invalid and can be discarded and any API calls made with it will return FMOD_RESULT.ERR_INVALID_HANDLE.


Syntax:

fmod_channel_control_stop(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a channelcontrol.



Returns:

N/A



Back To Top

fmod_channel_control_set_paused

FMOD Function: ChannelControl::setPaused


This function sets the paused state.

Pause halts playback which effectively freezes fmod_channel_get_position and fmod_channel_control_get_dsp_clock values.

Note

An individual pause state is kept for each object, pausing a parent channelgroup will effectively pause this object however when queried the individual pause state is returned.


Syntax:

fmod_channel_control_set_paused(channel_control_ref, paused)
Argument Type Description
channel_control_ref Real A reference to a channelcontrol.
paused Boolean Paused state. A value of true indicates playback halted. A value of false indicates playback active.



Returns:

N/A



Back To Top

fmod_channel_control_get_paused

FMOD Function: ChannelControl::getPaused


This function retrieves the paused state.

Note

An individual pause state is kept for each object, pausing a parent channelgroup will effectively pause this object however when queried the individual pause state is returned.


Syntax:

fmod_channel_control_get_paused(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Boolean



Back To Top

fmod_channel_control_set_mode

FMOD Function: ChannelControl::setMode


This function sets the playback mode that controls how this object behaves.

The supported modes are:

  • FMOD_MODE.LOOP_OFF
  • FMOD_MODE.LOOP_NORMAL
  • FMOD_MODE.LOOP_BIDI
  • FMOD_MODE.2D
  • FMOD_MODE.3D
  • FMOD_MODE.3D_HEADRELATIVE
  • FMOD_MODE.3D_WORLDRELATIVE
  • FMOD_MODE.3D_INVERSEROLLOFF
  • FMOD_MODE.3D_LINEARROLLOFF
  • FMOD_MODE.3D_LINEARSQUAREROLLOFF
  • FMOD_MODE.3D_INVERSETAPEREDROLLOFF
  • FMOD_MODE.3D_CUSTOMROLLOFF
  • FMOD_MODE.3D_IGNOREGEOMETRY
  • FMOD_MODE.VIRTUAL_PLAYFROMSTART

When changing the loop mode, sounds created with fmod_system_create_stream or FMOD_MODE.CREATESTREAM may have already been pre-buffered and executed their loop logic ahead of time before this call was even made. This is dependent on the size of the sound versus the size of the stream decode buffer (see FmodSystemCreateSoundExInfo). If this happens, you may need to reflush the stream buffer by calling fmod_channel_set_position. Note this will usually only happen if you have sounds or loop points that are smaller than the stream decode buffer size.

When changing the loop mode of sounds created with fmod_system_create_sound or FMOD_MODE.CREATESAMPLE, if the sound was set up as FMOD_MODE.LOOP_OFF, then set to FMOD_MODE.LOOP_NORMAL with this function, the sound may click when playing the end of the sound. This is because the sound needs to be prepared for looping using fmod_sound_set_mode, by modifying the content of the PCM data (i.e. data past the end of the actual sample data) to allow the interpolators to read ahead without clicking. If you use fmod_channel_control_set_mode it will not do this (because different Channels may have different loop modes for the same sound) and may click if you try to set it to looping on an unprepared sound. If you want to change the loop mode at runtime it may be better to load the sound as looping first (or use fmod_sound_set_mode), to let it prepare the data as if it was looping so that it does not click whenever fmod_channel_control_set_mode is used to turn looping on.

If FMOD_MODE.3D_IGNOREGEOMETRY or FMOD_MODE.VIRTUAL_PLAYFROMSTART is not specified, the flag will be cleared if it was specified previously.


Syntax:

fmod_channel_control_set_mode(channel_control_ref, mode)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
mode FMOD_MODE The playback mode. More than one mode can be set at once by combining them with the OR operator. The default is FMOD_MODE.DEFAULT.



Returns:

N/A



Back To Top

fmod_channel_control_get_mode

FMOD Function: ChannelControl::getMode


This function retrieves the playback mode bits that control how this object behaves.

You can test the playback mode bitfield against a specific FMOD_MODE with the AND operator.


Syntax:

fmod_channel_control_get_mode(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Real



Back To Top

fmod_channel_control_set_pitch

FMOD Function: ChannelControl::setPitch


This function sets the relative pitch / playback rate.

It scales the playback frequency of a Channel or if issued on a ChannelGroup it scales the frequencies of all Channels contained in the ChannelGroup.

Note

An individual pitch value is kept for each object, changing the pitch of a parent ChannelGroup will effectively alter the pitch of this object however when queried the individual pitch value is returned.


Syntax:

fmod_channel_control_set_pitch(channel_control_ref, pitch)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
pitch Real The pitch value where 0.5 represents half pitch (one octave down), 1.0 represents unmodified pitch and 2.0 represents double pitch (one octave up).



Returns:

N/A



Back To Top

fmod_channel_control_get_pitch

FMOD Function: ChannelControl::getPitch


This function retrieves the relative pitch / playback rate.

The pitch is a value where 0.5 represents half pitch (one octave down), 1 represents unmodified pitch and 2 represents double pitch (one octave up).

Note

An individual pitch value is kept for each object, a parent ChannelGroup pitch will effectively scale the pitch of this object however when queried the individual pitch value is returned.


Syntax:

fmod_channel_control_get_pitch(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Real



Back To Top

fmod_channel_control_get_audibility

FMOD Function: ChannelControl::getAudibility


This function retrieves an estimation of the output volume.

The estimated volume is calculated based on 3D spatialization, occlusion, API volume levels and DSPs used.

While this does not represent the actual waveform, Channels playing FSB files will take into consideration the overall peak level of the file (if available).

This value is used to determine which Channels should be audible and which Channels to virtualize when resources are limited.

See the FMOD Virtual Voice System white paper for more details about how audibility is calculated.


Syntax:

fmod_channel_control_get_audibility(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Real



Back To Top

fmod_channel_control_set_volume

FMOD Function: ChannelControl::setVolume


This function sets the volume level.

Note

To define the volume per Sound use fmod_sound_set_defaults.

Note

Setting volume at a level higher than 1 can lead to distortion/clipping.


Syntax:

fmod_channel_control_set_volume(channel_control_ref, volume)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
volume Real The (linear) volume level. 0 = silent, 1 = full. A negative level inverts the signal. Values larger than 1 amplify the signal. Default is 1.



Returns:

N/A



Back To Top

fmod_channel_control_get_volume

FMOD Function: ChannelControl::getVolume


This function retrieves the (linear) volume level.


Syntax:

fmod_channel_control_get_volume(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Real



Back To Top

fmod_channel_control_set_volume_ramp

FMOD Function: ChannelControl::setVolumeRamp


This function sets whether volume changes are ramped or instantaneous.

Volume changes when not paused will be ramped to the target value to avoid a pop sound, this function allows that setting to be overridden and volume changes to be applied immediately.


Syntax:

fmod_channel_control_set_volume_ramp(channel_control_ref, ramp)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
ramp Boolean The ramp state. A value of true means volume change is ramped. A value of false means volume change is instantaneous. Default is true.



Returns:

N/A



Back To Top

fmod_channel_control_get_volume_ramp

FMOD Function: ChannelControl::getVolumeRamp


This function retrieves whether volume changes are ramped or instantaneous.

It returns the ramp state. A value of true means volume change is ramped. A value of false means volume change is instantaneous.


Syntax:

fmod_channel_control_get_volume_ramp(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Real



Back To Top

fmod_channel_control_set_mute

FMOD Function: ChannelControl::setMute


This function sets the mute state.

Mute is an additional control for volume, the effect of which is equivalent to setting the volume to zero.

Note

An individual mute state is kept for each object, muting a parent ChannelGroup will effectively mute this object however when queried the individual mute state is returned. fmod_channel_control_get_audibility can be used to calculate overall audibility for a Channel or ChannelGroup.


Syntax:

fmod_channel_control_set_mute(channel_control_ref, mute)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
mute Boolean The mute state to set. A value of true means silent. A value of false means audible.



Returns:

N/A



Back To Top

fmod_channel_control_get_mute

FMOD Function: ChannelControl::getMute


This function retrieves the mute state.

The mute state is a value where true indicates silent and false indicates audible.

Note

An individual mute state is kept for each object, muting a parent ChannelGroup will effectively mute this object however when queried the individual mute state is returned. fmod_channel_control_get_audibility can be used to calculate overall audibility for a Channel or ChannelGroup.


Syntax:

fmod_channel_control_get_mute(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Boolean



Back To Top

fmod_channel_control_set_3d_attributes

FMOD Function: ChannelControl::set3DAttributes


This function sets the 3D position and velocity used to apply panning, attenuation and doppler.

Note

The FMOD_MODE.AS_3D flag must be set on this object otherwise FMOD_RESULT.ERR_NEEDS3D is returned.

Note

Vectors must be provided in the correct handedness.

Note

For a stereo 3D sound, you can set the spread of the left/right parts in speaker space by using fmod_channel_control_set_3d_spread.


Syntax:

fmod_channel_control_set_3d_attributes(control_ref, pos, vel)
Argument Type Description
control_ref Real A reference to a channel control.
pos FmodVector The position in 3D space used for panning and attenuation. The values are expressed in FMOD Distance Units.
vel FmodVector The velocity in 3D space used for doppler. The values are expressed in FMOD Distance Units per second.



Returns:

N/A



Back To Top

fmod_channel_control_get_3d_attributes

FMOD Function: ChannelControl::get3DAttributes


This function retrieves the 3D position and velocity used to apply panning, attenuation and doppler.


Syntax:

fmod_channel_control_get_3d_attributes(control_ref)
Argument Type Description
control_ref Real A reference to a channel control.



Returns:

FmodControl3DAttributes



Back To Top

fmod_channel_control_set_3d_cone_orientation

FMOD Function: ChannelControl::set3DConeOrientation


This function sets the orientation of a 3D cone shape, used for simulated occlusion.

Note

The FMOD_MODE.AS_3D flag must be set on this object otherwise FMOD_RESULT.ERR_NEEDS3D is returned.

Note

This function has no effect unless fmod_channel_control_set_3d_cone_settings has been used to change the cone inside/outside angles from the default.

Note

Vectors must be provided in the correct handedness.


Syntax:

fmod_channel_control_set_3d_cone_orientation(control_ref, orientation)
Argument Type Description
control_ref Real A reference to a channel control.
orientation FmodVector The normalized orientation vector, which represents the direction of the sound cone. Default is [0, 0, 1].



Returns:

N/A



Back To Top

fmod_channel_control_get_3d_cone_orientation

FMOD Function: ChannelControl::get3DConeOrientation


This function retrieves the orientation of a 3D cone shape, used for simulated occlusion.

The orientation is returned as a normalized orientation vector, which represents the direction of the sound cone.


Syntax:

fmod_channel_control_get_3d_cone_orientation(control_ref)
Argument Type Description
control_ref Real A reference to a channel control.



Returns:

FmodVector



Back To Top

fmod_channel_control_set_3d_cone_settings

FMOD Function: ChannelControl::set3DConeSettings


This function sets the angles and attenuation levels of a 3D cone shape, for simulated occlusion which is based on direction.

When fmod_channel_control_set_3d_cone_orientation is used and a 3D 'cone' is set up, attenuation will automatically occur for a sound based on the relative angle of the direction the cone is facing, vs the angle between the sound and the listener.

  • If the relative angle is within the inside_cone_angle, the sound will not have any attenuation applied.
  • If the relative angle is between the inside_cone_angle and outside_cone_angle, linear volume attenuation (between 1 and outsidevolume) is applied between the two angles until it reaches the outside_cone_angle.
  • If the relative angle is outside of the outside_cone_angle the volume does not attenuate any further.

Note

The FMOD_MODE.AS_3D flag must be set on this object otherwise fmod_last_result will return FMOD_RESULT.ERR_NEEDS3D.


Syntax:

fmod_channel_control_set_3d_cone_settings(channel_control_ref, inside_cone_angle, outside_cone_angle, outside_volume)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
inside_cone_angle Real The inside cone angle. This is the angle spread within which the sound is unattenuated, expressed in degrees. The default value is 360.
outside_cone_angle Real The outside cone angle. This is the angle spread outside of which the sound is attenuated to its outside_volume, expressed in degrees. The default value is 360.
outside_volume Real The cone outside volume. A (linear) value in the range [0, 1]. Default is 1.



Returns:

N/A



Back To Top

fmod_channel_control_get_3d_cone_settings

FMOD Function: ChannelControl::get3DConeSettings


This function retrieves the angles and attenuation levels of a 3D cone shape, for simulated occlusion which is based on direction.

When fmod_channel_control_set_3d_cone_orientation is used and a 3D 'cone' is set up, attenuation will automatically occur for a sound based on the relative angle of the direction the cone is facing, vs the angle between the sound and the listener.

  • If the relative angle is within the inside_cone_angle, the sound will not have any attenuation applied.
  • If the relative angle is between the inside_cone_angle and outside_cone_angle, linear volume attenuation (between 1 and outsidevolume) is applied between the two angles until it reaches the outside_cone_angle.
  • If the relative angle is outside of the outside_cone_angle the volume does not attenuate any further.

Syntax:

fmod_channel_control_get_3d_cone_settings(control_ref)
Argument Type Description
control_ref Real A reference to a channel control.



Returns:

Fmod3DConeSettings



Back To Top

fmod_channel_control_set_3d_custom_rolloff

FMOD Function: ChannelControl::set3DCustomRolloff


This function sets a custom roll-off shape for 3D distance attenuation.

Note

This function must be used in conjunction with FMOD_MODE._AS_3D_CUSTOMROLLOFF flag to be activated.

If FMOD_MODE._AS_3D_CUSTOMROLLOFF is set and the roll-off shape is not set, FMOD will revert to FMOD_MODE.AS_3D_INVERSETAPEREDROLLOFF roll-off mode.

When a custom roll-off is specified a Channel or ChannelGroup's 3D 'minimum' and 'maximum' distances are ignored.

The distance in-between point values is linearly interpolated until the final point where the last value is held.

If the points are not sorted by distance, an error will result.

// Defining a custom array of points
curve =
{
    { x:  0, y: 1, z: 0 },
    { x:  2, y: 2, z: 0 },
    { x: 20, y: 0, z: 0 }
};

Syntax:

fmod_channel_control_set_3d_custom_rolloff(control_ref, points)
Argument Type Description
control_ref Real A reference to a channel control.
points Array of FmodVector An array of vectors sorted by distance, where x = distance and y = volume from 0 to 1. z should be set to 0. Pass an empty array to disable custom rolloff.



Returns:

N/A



Back To Top

fmod_channel_control_get_3d_custom_rolloff

FMOD Function: ChannelControl::get3DCustomRolloff


This function retrieves the current custom roll-off shape for 3D distance attenuation.


Syntax:

fmod_channel_control_get_3d_custom_rolloff(control_ref)
Argument Type Description
control_ref Real A reference to a channel control.



Returns:

Array of FmodVector



Back To Top

fmod_channel_control_set_3d_distance_filter

FMOD Function: ChannelControl::set3DDistanceFilter


This function sets an override value for the 3D distance filter.

If distance filtering is enabled, by default the FMOD 3D engine will automatically attenuate frequencies using a lowpass and a highpass filter, based on 3D distance. This function allows the distance filter effect to be set manually, or to be set back to 'automatic' mode.


Syntax:

fmod_channel_control_set_3d_distance_filter(channel_control_ref, custom, custom_level, center_freq)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
custom Boolean Whether to override automatic distance filtering and use custom_level instead. Default is false.
custom_level Real The attenuation factor where 1 represents no attenuation and 0 represents complete attenuation. The default value is 1.
center_freq Real The center frequency, in Hertz, of the band-pass filter used to simulate distance attenuation, 0 for default. This must be a value in the range [10, 22050].



Returns:

N/A



Back To Top

fmod_channel_control_get_3d_distance_filter

FMOD Function: ChannelControl::get3DDistanceFilter


This function retrieves the override values for the 3D distance filter.


Syntax:

fmod_channel_control_get_3d_distance_filter(control_ref)
Argument Type Description
control_ref Real A reference to a channel control.



Returns:

FmodControl3DDistanceFilter



Back To Top

fmod_channel_control_set_3d_doppler_level

FMOD Function: ChannelControl::set3DDopplerLevel


This function sets the amount by which doppler is scaled.

The doppler effect will be disabled if fmod_system_set_3d_num_listeners is given a value greater than 1.

Note

The FMOD_MODE.AS_3D flag must be set on this object otherwise FMOD_RESULT.ERR_NEEDS3D is returned.


Syntax:

fmod_channel_control_set_3d_doppler_level(channel_control_ref, level)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
level Real Doppler scale where 0 represents no doppler, 1 represents natural doppler and 5 represents exaggerated doppler. The default value is 1.



Returns:

N/A



Back To Top

fmod_channel_control_get_3d_doppler_level

FMOD Function: ChannelControl::get3DDopplerLevel


This function retrieves the amount by which doppler is scaled.

The value returned is the doppler level, on a scale where 0 represents no doppler, 1 represents natural doppler and 5 represents exaggerated doppler.


Syntax:

fmod_channel_control_get_3d_doppler_level(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Real



Back To Top

fmod_channel_control_set_3d_level

FMOD Function: ChannelControl::set3DLevel


This function sets the blend between 3D panning and 2D panning.


Syntax:

fmod_channel_control_set_3d_level(channel_control_ref, level)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
level Real The 3D pan level where 0 represents panning/attenuating solely with 2D panning functions and 1 represents solely 3D.



Returns:

N/A



Back To Top

fmod_channel_control_get_3d_level

FMOD Function: ChannelControl::get3DLevel


This function retrieves the blend between 3D panning and 2D panning.

The value returned is the (linear) 3D pan level where 0 represents panning/attenuating solely with 2D panning functions and 1 represents solely 3D.

Note

The FMOD_MODE.AS_3D flag must be set on this object otherwise FMOD_RESULT.ERR_NEEDS3D is returned.

The 2D functions include:

The 3D functions include:


Syntax:

fmod_channel_control_get_3d_level(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Real



Back To Top

fmod_channel_control_set_3d_min_max_distance

FMOD Function: ChannelControl::set3DMinMaxDistance


This function sets the minimum and maximum distances used to calculate the 3D roll-off attenuation.

When the listener is within the minimum distance of the sound source the 3D volume will be at its maximum. As the listener moves from the minimum distance to the maximum distance the sound will attenuate following the roll-off curve set. When outside the maximum distance the sound will no longer attenuate.

Attenuation in 3D space is controlled by the roll-off mode, which can be one of FMOD_MODE.AS_3D_INVERSEROLLOFF, FMOD_MODE.AS_3D_LINEARROLLOFF, FMOD_MODE.AS_3D_LINEARSQUAREROLLOFF, FMOD_MODE.AS_3D_INVERSETAPEREDROLLOFF, FMOD_MODE.AS_3D_CUSTOMROLLOFF.

Minimum distance is useful to give the impression that the sound is loud or soft in 3D space. A sound with a small 3D minimum distance in a typical (non custom) roll-off mode will make the sound appear small, and the sound will attenuate quickly. A sound with a large minimum distance will make the sound appear larger.

The FMOD_MODE.AS_3D flag must be set on this object otherwise fmod_last_result will return FMOD_RESULT.ERR_NEEDS3D.

To define the min and max distance per Sound instead of Channel or ChannelGroup use fmod_sound_set_3d_min_max_distance.

If FMOD_MODE.AS_3D_CUSTOMROLLOFF has been set on this object these values are stored, but ignored in 3D processing.


Syntax:

fmod_channel_control_set_3d_min_max_distance(channel_control_ref, min, max)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
min Real The distance from the source where attenuation begins. A value in the range [0, max]. Default is 1.
max Real The distance from the source where attenuation ends. A value in the range [min, infinity]. Default is 10000.



Returns:

N/A



Back To Top

fmod_channel_control_get_3d_min_max_distance

FMOD Function: ChannelControl::get3DMinMaxDistance


This function retrieves the minimum and maximum distances used to calculate the 3D roll-off attenuation.


Syntax:

fmod_channel_control_get_3d_min_max_distance(control_ref)
Argument Type Description
control_ref Real A reference to a channel control.



Returns:

FmodControl3DMinMaxDistance



Back To Top

fmod_channel_control_set_3d_occlusion

FMOD Function: ChannelControl::set3DOcclusion


This function sets the 3D attenuation factors for the direct and reverb paths.

There is a reverb path/send when fmod_channel_control_set_reverb_properties has been used, reverb_occlusion controls its attenuation.

If the System has been initialized with FMOD_INIT.CHANNEL_DISTANCEFILTER or FMOD_INIT.CHANNEL_LOWPASS the direct_occlusion is applied as frequency filtering rather than volume attenuation.


Syntax:

fmod_channel_control_set_3d_occlusion(channel_control_ref, direct_occlusion, reverb_occlusion)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
direct_occlusion Real The occlusion factor for the direct path where 0 represents no occlusion and 1 represents full occlusion. Default is 0.
reverb_occlusion Real Occlusion factor for the reverb path where 0 represents no occlusion and 1 represents full occlusion. Default is 0.



Returns:

N/A



Back To Top

fmod_channel_control_get_3d_occlusion

FMOD Function: ChannelControl::get3DOcclusion


This function retrieves the 3D attenuation factors for the direct and reverb paths.


Syntax:

fmod_channel_control_get_3d_occlusion(control_ref)
Argument Type Description
control_ref Real A reference to a channel control.



Returns:

FmodControl3DOcclusion



Back To Top

fmod_channel_control_set_3d_spread

FMOD Function: ChannelControl::set3DSpread


This function sets the spread of a 3D sound in speaker space.

When the spread angle is 0 (default) a multi-channel signal will collapse to mono and be spatialized to a single point based on fmod_channel_control_set_3d_attributes calculations. As the angle is increased, each channel within a multi-channel signal will be rotated away from that point. For 2, 4, 6, 8, and 12 channel signals, the spread is arranged from leftmost speaker to rightmost speaker intelligently, for example in 5.1 the leftmost speaker is rear left, followed by front left, center, front right then finally rear right as the rightmost speaker (LFE is not spread). For other channel counts the individual channels are spread evenly in the order of the signal. As the signal is spread the power will be preserved.

For a stereo signal given different spread angles:

  • 0: Sound is collapsed to mono and spatialized to a single point.
  • 90: Left channel is rotated 45 degrees to the left compared with angle=0 and the right channel 45 degrees to the right.
  • 180: Left channel is rotated 90 degrees to the left compared with angle=0 and the right channel 90 degrees to the right.
  • 360: Left channel is rotated 180 degrees to the left and the right channel 180 degrees to the right. This means the sound is collapsed to mono and spatialized to a single point in the opposite direction compared with (angle=0).

Syntax:

fmod_channel_control_set_3d_spread(channel_control_ref, angle)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
angle Real The angle (in degrees) over which the sound is spread. The default value is 0.



Returns:

N/A



Back To Top

fmod_channel_control_get_3d_spread

FMOD Function: ChannelControl::get3DSpread


This function retrieves the spread of a 3D sound in speaker space.

It returns the angle (in degrees) over which the sound is spread.


Syntax:

fmod_channel_control_get_3d_spread(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Real



Back To Top

fmod_channel_control_set_pan

FMOD Function: ChannelControl::setPan


This function sets the left/right pan level.

This is a convenience function to avoid passing a matrix, it will overwrite values set via fmod_channel_control_set_mix_levels_input, fmod_channel_control_set_mix_levels_output and fmod_system_set_software_format.

Mono inputs are panned from left to right using constant power panning (non linear fade). Stereo and greater inputs will isolate the front left and right input channels and fade them up and down based on the pan value (silencing other channels). The output channel count will always match the System speaker mode set via fmod_system_set_software_format.

Note

If the System is initialized with FMOD_SPEAKERMODE.RAW calling this function will produce silence.


Syntax:

fmod_channel_control_set_pan(channel_control_ref, pan)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
pan Real The pan level where -1 represents full left, 0 represents center and 1 represents full right. Default is 0.



Returns:

N/A



Back To Top

fmod_channel_control_set_mix_levels_input

FMOD Function: ChannelControl::setMixLevelsInput


This function sets the incoming volume level for each channel of a multi-channel signal.

This is a convenience function to avoid passing a matrix, it will overwrite values set via fmod_channel_control_set_pan, fmod_channel_control_set_mix_levels_output and fmod_channel_control_set_mix_matrix.

Note

This is currently only supported for Channel, not ChannelGroup.


Syntax:

fmod_channel_control_set_mix_levels_input(control_ref, levels)
Argument Type Description
control_ref Real A reference to a channel control.
levels Array of Real An array of volume levels for each incoming channel. Volume level. 0 = silent, 1 = full. A negative level inverts the signal. Values larger than 1 amplify the signal.



Returns:

N/A



Back To Top

fmod_channel_control_set_mix_levels_output

FMOD Function: ChannelControl::setMixLevelsOutput


This function sets the outgoing volume levels for each speaker.

Specify the level for a given output speaker, if the channel count of the input and output do not match, channels will be up/down mixed as appropriate to approximate the given speaker values. For example stereo input with 5.1 output will use the center parameter to distribute signal to the center speaker from front left and front right channels.

This is a convenience function to avoid passing a matrix, it will overwrite values set via fmod_channel_control_set_pan, fmod_channel_control_set_mix_levels_input and fmod_channel_control_set_mix_matrix.

The output channel count will always match the System speaker mode set via fmod_system_set_software_format.

Note

If the System is initialized with FMOD_SPEAKERMODE.RAW calling this function will produce silence.


Syntax:

fmod_channel_control_set_mix_levels_output(channel_control_ref, front_left, front_right, center, lfe, surround_left, surround_right, back_left, back_right)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
front_left Real The volume level for FMOD_SPEAKER.FRONT_LEFT. Volume level. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal.
front_right Real The volume level for FMOD_SPEAKER.FRONT_RIGHT. Volume level. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal.
center Real The volume level for FMOD_SPEAKER.FRONT_CENTER. Volume level. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal.
lfe Real The volume level for FMOD_SPEAKER.LOW_FREQUENCY. Volume level. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal.
surround_left Real The volume level for FMOD_SPEAKER.SURROUND_LEFT. Volume level. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal.
surround_right Real The volume level for FMOD_SPEAKER.SURROUND_RIGHT. Volume level. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal.
back_left Real The volume level for FMOD_SPEAKER.BACK_LEFT. Volume level. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal.
back_right Real The volume level for FMOD_SPEAKER.BACK_RIGHT. Volume level. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal.



Returns:

N/A



Back To Top

fmod_channel_control_set_mix_matrix

FMOD Function: ChannelControl::setMixMatrix


This function sets a 2 dimensional pan matrix that maps the signal from input channels (columns) to output speakers (rows).

This will overwrite values set via fmod_channel_control_set_pan, fmod_channel_control_set_mix_levels_input and fmod_channel_control_set_mix_levels_output.

If no matrix is passed in via matrix a default upmix, downmix, or unit matrix will take its place. A unit matrix allows a signal to pass through unchanged.

Example 5.1 unit matrix:

1 0 0 0 0 0
0 1 0 0 0 0
0 0 1 0 0 0
0 0 0 1 0 0
0 0 0 0 1 0
0 0 0 0 0 1

Note

Matrix element values can be below 0 to invert a signal and above 1 to amplify the signal. Note that increasing the signal level too far may cause audible distortion.


Syntax:

fmod_channel_control_set_mix_matrix(control_ref, matrix, out_channels, in_channels, in_channel_hop)
Argument Type Description
control_ref Real A reference to a channel control.
matrix Array of Real A two-dimensional array of volume levels in row-major order. Each row represents an output speaker, each column represents an input channel.
out_channels Real The number of output channels (rows) in matrix.
in_channels Real The number of input channels (columns) in matrix.
in_channel_hop Real The width (total number of columns) in the source matrix. A matrix element is referenced as 'outchannel * inchannel_hop + inchannel'. The default value is in_channels.



Returns:

N/A



Back To Top

fmod_channel_control_get_mix_matrix

FMOD Function: ChannelControl::getMixMatrix


This function retrieves a 2 dimensional pan matrix that maps the signal from input channels (columns) to output speakers (rows).

Note

Matrix element values can be below 0 to invert a signal and above 1 to amplify the signal. Note that increasing the signal level too far may cause audible distortion.


Syntax:

fmod_channel_control_get_mix_matrix(control_ref)
Argument Type Description
control_ref Real A reference to a channel control.



Returns:

FmodControlMixMatrix



Back To Top

fmod_channel_control_set_reverb_properties

FMOD Function: ChannelControl::setReverbProperties


This function sets the wet / send level for a particular reverb instance.

Channels are automatically connected to all existing reverb instances due to the default wet level of 1. ChannelGroups however will not send to any reverb by default requiring an explicit call to this function.

ChannelGroup reverb is optimal for the case where you want to send 1 mixed signal to the reverb, rather than a lot of individual Channel reverb sends. It is advisable to do this to reduce CPU if you have many Channels inside a ChannelGroup.

When setting a wet level for a ChannelGroup, any Channels under that ChannelGroup will still have their existing sends to the reverb. To avoid this doubling up you should explicitly set the Channel wet levels to 0.


Syntax:

fmod_channel_control_set_reverb_properties(channel_control_ref, reverb_instance, wet)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
reverb_instance Real A reverb instance index.
wet Real The send level for the signal to the reverb. 0 = none, 1 = full. A negative level inverts the signal. Default is 1 for Channel, 0 for ChannelGroup.



Returns:

N/A



Back To Top

fmod_channel_control_get_reverb_properties

FMOD Function: ChannelControl::getReverbProperties


This function retrieves the wet / send level for a particular reverb instance.

It returns the send level for the signal to the reverb. 0 = none, 1 = full.


Syntax:

fmod_channel_control_get_reverb_properties(channel_control_ref, reverb_instance)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
reverb_instance Real A reverb instance index.



Returns:

Real



Back To Top

fmod_channel_control_set_low_pass_gain

FMOD Function: ChannelControl::setLowPassGain


This function sets the gain of the dry signal when built-in lowpass / distance filtering is applied.

Note

This requires the built-in lowpass to be created with FMOD_INIT.CHANNEL_LOWPASS or FMOD_INIT.CHANNEL_DISTANCEFILTER.

Note

This is currently only supported for Channel, not ChannelGroup.


Syntax:

fmod_channel_control_set_low_pass_gain(channel_control_ref, gain)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
gain Real The gain level where 0 represents silent (full filtering) and 1 represents full volume (no filtering). Default is 1.



Returns:

N/A



Back To Top

fmod_channel_control_get_low_pass_gain

FMOD Function: ChannelControl::getLowPassGain


This function retrieves the gain of the dry signal when built-in lowpass / distance filtering is applied.

The function returns the gain level where 0 represents silent (full filtering) and 1 represents full volume (no filtering).

Note

This requires the built-in lowpass to be created with FMOD_INIT.CHANNEL_LOWPASS or FMOD_INIT.CHANNEL_DISTANCEFILTER.

Note

Currently only supported for Channel, not ChannelGroup.


Syntax:

fmod_channel_control_get_low_pass_gain(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Real



Back To Top

fmod_channel_control_add_dsp

FMOD Function: ChannelControl::addDSP


This function adds a DSP unit to the specified index in the DSP chain.

If dsp_ref is already added to an existing object it will be removed and then added to this object.

For detailed information on FMOD's DSP network, read the DSP Architecture and Usage white paper.


Syntax:

fmod_channel_control_add_dsp(channel_control_ref, dsp_chain_offset, dsp_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
dsp_chain_offset Real The offset into the DSP chain, see FMOD_CHANNELCONTROL_DSP_INDEX for special named offsets for 'head' and 'tail' and 'fader' units.
dsp_ref Real The DSP unit to be added.



Returns:

N/A



Back To Top

fmod_channel_control_remove_dsp

FMOD Function: ChannelControl::removeDSP


This function removes the specified DSP unit from the DSP chain.


Syntax:

fmod_channel_control_remove_dsp(channel_control_ref, dsp_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
dsp_ref Real The DSP unit to be removed.



Returns:

N/A



Back To Top

fmod_channel_control_get_num_dsps

FMOD Function: ChannelControl::getNumDSPs


This function retrieves the number of DSP units in the DSP chain.

See DSP chain.


Syntax:

fmod_channel_control_get_num_dsps(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Real



Back To Top

fmod_channel_control_get_dsp

FMOD Function: ChannelControl::getDSP


This function retrieves the DSP unit at the specified index in the DSP chain.

It returns the DSP unit at the specified index.

See DSP chain.


Syntax:

fmod_channel_control_get_dsp(channel_control_ref, index)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
index Real The offset into the DSP chain, see FMOD_CHANNELCONTROL_DSP_INDEX for special named offsets for 'head' and 'tail' and 'fader' units.



Returns:

Real



Back To Top

fmod_channel_control_set_dsp_index

FMOD Function: ChannelControl::setDSPIndex


This function sets the index in the DSP chain of the specified DSP.

See DSP chain.


Syntax:

fmod_channel_control_set_dsp_index(channel_control_ref, dsp_ref, chain_index)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
dsp_ref Real A reference to a DSP unit that exists in the DSP chain.
chain_index Real The offset into the DSP chain to move the DSP to, see FMOD_CHANNELCONTROL_DSP_INDEX for special named offsets.



Returns:

Real



Back To Top

fmod_channel_control_get_dsp_index

FMOD Function: ChannelControl::getDSPIndex


This function retrieves the index of a DSP inside the Channel or ChannelGroup's DSP chain.

See DSP chain.


Syntax:

fmod_channel_control_get_dsp_index(channel_control_ref, dsp_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
dsp_ref Real A DSP unit that exists in the DSP chain.



Returns:

Real



Back To Top

fmod_channel_control_get_dsp_clock

FMOD Function: ChannelControl::getDSPClock


This function retrieves the DSP clock values at this point in time.

To perform sample accurate scheduling in conjunction with fmod_channel_control_set_delay and fmod_channel_control_add_fade_point query the parent_clock value.


Syntax:

fmod_channel_control_get_dsp_clock(control_ref)
Argument Type Description
control_ref Real A reference to a channel control.



Returns:

FmodControlDSPClock



Back To Top

fmod_channel_control_set_delay

FMOD Function: ChannelControl::setDelay


This function sets a sample accurate start (and/or stop) time relative to the parent ChannelGroup DSP clock.


Syntax:

fmod_channel_control_set_delay(control_ref, dsp_clock_start, dsp_clock_end, stop_channels)
Argument Type Description
control_ref Real A reference to a channel control.
dsp_clock_start Real The DSP clock of the parent ChannelGroup to audibly start playing sound at. Default is 0.
dsp_clock_end Real DSP clock of the parent ChannelGroup to audibly stop playing sound at. Default is 0.
stop_channels Boolean True: When dspclock_end is reached, behaves like fmod_channel_control_stop has been called.
False: When dspclock_end is reached, behaves like fmod_channel_control_set_paused has been called, a subsequent dspclock_start allows it to resume.



Returns:

N/A



Back To Top

fmod_channel_control_get_delay

FMOD Function: ChannelControl::getDelay


This function retrieves a sample accurate start (and/or stop) time relative to the parent ChannelGroup DSP clock.


Syntax:

fmod_channel_control_get_delay(control_ref)
Argument Type Description
control_ref Real A reference to a channel control.



Returns:

FmodControlDelay



Back To Top

fmod_channel_control_add_fade_point

FMOD Function: ChannelControl::addFadePoint


This function adds a sample accurate fade point at a time relative to the parent ChannelGroup DSP clock.

Fade points are scaled against other volume settings and in-between each fade point the volume will be linearly ramped.

To perform sample accurate fading use fmod_channel_control_get_dsp_clock to query the parent clock value. If a parent ChannelGroup changes its pitch, the fade points will still be correct as the parent clock rate is adjusted by that pitch.


Syntax:

fmod_channel_control_add_fade_point(control_ref, dsp_clock, volume)
Argument Type Description
control_ref Real A reference to a channel control.
dsp_clock Real The DSP clock of the parent ChannelGroup to set the fade point volume. Expressed in samples.
volume Real The (linear) volume level at the given dsp_clock. Values above 1.0 amplify the signal.



Returns:

N/A


Example:

// Example. Ramp from full volume to half volume over the next 4096 samples
var _dsp_clock = FMOD_ChannelControl_GetDSPClock(target);
var _clock_val = _dsp_clock.parent_clock;
FMOD_ChannelControl_AddFadePoint(target, _clock_val, 1);
FMOD_ChannelControl_AddFadePoint(target, _clock_val + 4096, 0.5);

The above code shows how to perform sample accurate fading. It ramps from full volume to half volume over the next 4096 samples.



Back To Top

fmod_channel_control_set_fade_point_ramp

FMOD Function: ChannelControl::setFadePointRamp


This function adds a volume ramp at the specified time in the future using fade points.

This is a convenience function that creates a scheduled 64 sample fade point ramp from the current volume level to volume arriving at dsp_clock time.

Can be use in conjunction with fmod_channel_control_set_delay.

All fade points after dsp_clock will be removed.


Syntax:

fmod_channel_control_set_fade_point_ramp(control_ref, dsp_clock, volume)
Argument Type Description
control_ref Real A reference to a channel control.
dsp_clock Real The time (in samples) at which the ramp will end, as measured by the DSP clock of the parent ChannelGroup.
volume Real The volume level at the given dsp_clock. 0 = silent, 1 = full.



Returns:

N/A



Back To Top

fmod_channel_control_remove_fade_points

FMOD Function: ChannelControl::removeFadePoints


This function removes all fade points between the two specified clock values (inclusive).


Syntax:

fmod_channel_control_remove_fade_points(control_ref, dsp_clock_start, dsp_clock_end)
Argument Type Description
control_ref Real A reference to a channel control.
dsp_clock_start Real The DSP clock of the parent ChannelGroup at which to begin removing fade points. Expressed in samples.
dsp_clock_end Real The DSP clock of the parent ChannelGroup at which to stop removing fade points. Expressed in samples.



Returns:

N/A



Back To Top

fmod_channel_control_get_fade_points

FMOD Function: ChannelControl::getFadePoints


This function retrieves information about all stored fade points.


Syntax:

fmod_channel_control_get_fade_points(control_ref)
Argument Type Description
control_ref Real A reference to a channel control.



Returns:

FmodControlFadePoints



Back To Top

fmod_channel_control_set_callback

FMOD Function: ChannelControl::setCallback


This function enables the callback for ChannelControl level notifications.

Note

the Social Async Event's async_load will either hold a channel_ref or a channel_group_ref.

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_channel_control_set_callback(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

N/A


Triggers:

Social Async Event

When kind is one of FMOD_CHANNELCONTROL_CALLBACK_TYPE.END, FMOD_CHANNELCONTROL_CALLBACK_TYPE.VIRTUALVOICE or FMOD_CHANNELCONTROL_CALLBACK_TYPE.SYNCPOINT:

Key Type Description
type String The string "fmod_channel_control_set_callback"
kind FMOD_CHANNELCONTROL_CALLBACK_TYPE The kind of callback.
channel_ref Real A reference to the channel.
channel_group_ref Real A reference to a channel group.
point_index Real If kind is FMOD_CHANNELCONTROL_CALLBACK_TYPE.VIRTUALVOICE, this is a value where 0 represents 'virtual to real' and 1 represents 'real to virtual'. If kind is FMOD_CHANNELCONTROL_CALLBACK_TYPE.SYNCPOINT, this is a value representing the index of the sync point for use with fmod_sound_get_sync_point.

When kind is FMOD_CHANNELCONTROL_CALLBACK_TYPE.OCCLUSION:

Key Type Description
type String The string "fmod_channel_control_set_callback"
kind FMOD_CHANNELCONTROL_CALLBACK_TYPE The kind of callback.
channel_ref Real A reference to the channel.
channel_group_ref Real A reference to a channel group.
direct_occlusion Real A value that represents the calculated direct occlusion value.
reverb_occlusion Real A value that represents the calculated reverb occlusion value.


Back To Top

fmod_channel_control_get_system_object

FMOD Function: ChannelControl::getSystemObject


This function retrieves the System that created this object.


Syntax:

fmod_channel_control_get_system_object(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Real



Back To Top

fmod_channel_control_set_user_data

FMOD Function: ChannelControl::setUserData


This function sets a floating-point user value associated with this object.

Note

While FMOD supports arbitrary User Data, this function only allows you to set a real value (a double-precision floating-point value).


Syntax:

fmod_channel_control_set_user_data(channel_control_ref, data)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.
data Real The value to store on this object.



Returns:

N/A



Back To Top

fmod_channel_control_get_user_data

FMOD Function: ChannelControl::getUserData


This function retrieves the user value associated with this object, as set with fmod_channel_control_set_user_data.

Note

While FMOD allows arbitrary User Data, this function only allows you to get a real value (a double-precision floating-point value).


Syntax:

fmod_channel_control_get_user_data(channel_control_ref)
Argument Type Description
channel_control_ref Real A reference to a ChannelControl.



Returns:

Real



YoYoGames 2024

FMOD Extension

Guides

FMOD Core Reference

FMOD Studio Reference

Extras

Clone this wiki locally