Firelight Technologies FMOD Studio API

ChannelGroup::set3DCustomRolloff

Sets a custom rolloff curve to define how audio will attenuate over distance. Must be used in conjunction with FMOD_3D_CUSTOMROLLOFF flag to be activated.

C++ Syntax

FMOD_RESULT ChannelGroup::set3DCustomRolloff(
  FMOD_VECTOR *points,
  int numpoints
);

C Syntax

FMOD_RESULT FMOD_ChannelGroup_Set3DCustomRolloff(
  FMOD_CHANNELGROUP *channelgroup,
  FMOD_VECTOR *points,
  int numpoints
);

C# Syntax

RESULT ChannelGroup.set3DCustomRolloff(
  ref VECTOR points,
  int numpoints
);

JavaScript Syntax

ChannelGroup.set3DCustomRolloff(
  points,                          
  numpoints                        
);

Parameters

points

Array of FMOD_VECTOR structures where x = distance and y = volume from 0.0 to 1.0. z should be set to 0.

numpoints

Number of points in the array.

Return Values

If the function succeeds then the return value is FMOD_OK.
If the function fails then the return value will be one of the values defined in the FMOD_RESULT enumeration.

Remarks

Note! This function does not duplicate the memory for the points internally. The pointer you pass to FMOD must remain valid until there is no more use for it. Do not free the memory while in use, or use a local variable that goes out of scope while in use.

Points must be sorted by distance! Passing an unsorted list to FMOD will result in an error.

Set the points parameter to 0 or NULL to disable the points. If FMOD_3D_CUSTOMROLLOFF is set and the rolloff curve is 0, FMOD will revert to inverse curve rolloff.

Values set with ChannelControl::setMinMaxDistance are meaningless when FMOD_3D_CUSTOMROLLOFF is used, their values are ignored.

Here is an example of a custom array of points.

static FMOD_VECTOR curve[3] =
{
    { 0.0f,  1.0f, 0.0f },
    { 2.0f,  0.2f, 0.0f },
    { 20.0f, 0.0f, 0.0f }
};

Distances between points are linearly interpolated.

Note that after the highest distance specified, the volume in the last entry is used from that distance onwards.

To define the parameters per sound use Sound::set3DCustomRolloff.

See Also

• ChannelControl::get3DCustomRolloff
• ChannelControl::setMinMaxDistance
• Sound::set3DCustomRolloff
• FMOD_VECTOR
• FMOD_3D_CUSTOMROLLOFF

Version 1.10.03 Built on Feb 1, 2018