Firelight Technologies FMOD Studio API

Sound::set3DCustomRolloff

Point a sound to use a custom rolloff curve. Must be used in conjunction with FMOD_3D_CUSTOMROLLOFF flag to be activated.

C++ Syntax

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

C Syntax

FMOD_RESULT FMOD_Sound_Set3DCustomRolloff(
  FMOD_SOUND *sound,
  FMOD_VECTOR *points,
  int numpoints
);

C# Syntax

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

JavaScript Syntax

Sound.set3DCustomRolloff(
  points,                          
  numpoints                        
);

Parameters

points

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

numpoints

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

Min and maxdistance are meaningless when FMOD_3D_CUSTOMROLLOFF is used and the values are ignored.

Here is an example of a custom array of points.

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

x represents the distance, y represents the volume. z is always 0.
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.

See Also

• FMOD_MODE
• FMOD_VECTOR
• Sound::get3DCustomRolloff
• Channel::set3DCustomRolloff
• Channel::get3DCustomRolloff

Version 1.10.03 Built on Feb 1, 2018