Firelight Technologies FMOD Studio API

System::set3DSettings

Sets the global doppler scale, distance factor and log rolloff scale for all 3D sound in FMOD.

C++ Syntax

FMOD_RESULT System::set3DSettings(
  float dopplerscale,
  float distancefactor,
  float rolloffscale
);

C Syntax

FMOD_RESULT FMOD_System_Set3DSettings(
  FMOD_SYSTEM *system,
  float dopplerscale,
  float distancefactor,
  float rolloffscale
);

C# Syntax

RESULT System.set3DSettings(
  float dopplerscale,
  float distancefactor,
  float rolloffscale
);

JavaScript Syntax

System.set3DSettings(
  dopplerscale,                    
  distancefactor,                  
  rolloffscale                     
);

Parameters

dopplerscale

Scaling factor for doppler shift. Default = 1.0.

distancefactor

Relative distance factor to FMOD's units. Default = 1.0. (1.0 = 1 meter).

rolloffscale

Scaling factor for 3D sound rolloff or attenuation for FMOD_3D_INVERSEROLLOFF based sounds only (which is the default type). Default = 1.0.

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

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.

Note! This only affects doppler! If you keep your min/max distance, custom rolloff curves and positions in scale relative to each other the volume rolloff 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 distancefactor.

The rolloff scale sets the global attenuation rolloff factor for FMOD_3D_INVERSEROLLOFF based sounds only (which is the default). Volume for a sound set to FMOD_3D_INVERSEROLLOFF will scale at mindistance / distance. This gives an inverse attenuation of volume as the source gets further away (or closer). Setting this value makes the sound drop off faster or slower. The higher the value, the faster volume will attenuate, and conversely the lower the value, the slower it will attenuate. For example a rolloff factor of 1 will simulate the real world, where as a value of 2 will make sounds attenuate 2 times quicker.

Note! "rolloffscale" has no effect when using FMOD_3D_LINEARROLLOFF, FMOD_3D_LINEARSQUAREROLLOFF or FMOD_3D_CUSTOMROLLOFF.

See Also

• System::get3DSettings
• Sound::set3DMinMaxDistance
• Sound::get3DMinMaxDistance
• Channel::set3DAttributes
• Channel::get3DAttributes

Version 1.10.03 Built on Feb 1, 2018