Firelight Technologies FMOD Studio API
System::setSpeakerPosition
This function allows the user to specify the position of their actual physical speaker to account for non standard setups.
It also allows the user to disable speakers from 3D consideration in a game.
The funtion is for describing the 'real world' speaker placement to provide a more natural panning solution for 3D sound.
Graphical configuration screens in an application could draw icons for speaker placement that the user could position at their will.
C++ Syntax
FMOD_RESULT System::setSpeakerPosition(
FMOD_SPEAKER speaker,
float x,
float y,
bool active
);
C Syntax
FMOD_RESULT FMOD_System_SetSpeakerPosition(
FMOD_SYSTEM *system,
FMOD_SPEAKER speaker,
float x,
float y,
FMOD_BOOL active
);
C# Syntax
RESULT System.setSpeakerPosition(
SPEAKER speaker,
float x,
float y,
bool active
);
JavaScript Syntax
System.setSpeakerPosition(
speaker,
x,
y,
active
);
Parameters
- speaker
- The selected speaker of interest to position.
- x
- The 2D X offset in relation to the listening position. For example -1.0 would mean the speaker is on the left, and +1.0 would mean the speaker is on the right. 0.0 is the speaker is in the middle.
- y
- The 2D Y offset in relation to the listening position. For example -1.0 would mean the speaker is behind the listener, and +1 would mean the speaker is in front of the listener.
- active
- Enables or disables speaker from 3D consideration. Useful for disabling center speaker for vocals for example, or the LFE. x and y can be anything in this case.
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
A typical stereo setup would look like this.
system->setSpeakerPosition(FMOD_SPEAKER_FRONT_LEFT, -1.0f, 0.0f, true);
system->setSpeakerPosition(FMOD_SPEAKER_FRONT_RIGHT, 1.0f, 0.0f, true);
A typical 7.1 setup would look like this.
system->setSpeakerPosition(FMOD_SPEAKER_FRONT_LEFT, sin(degtorad( -30)), cos(degtorad(-30)), true);
system->setSpeakerPosition(FMOD_SPEAKER_FRONT_RIGHT, sin(degtorad( 30)), cos(degtorad( 30)), true);
system->setSpeakerPosition(FMOD_SPEAKER_FRONT_CENTER, sin(degtorad( 0)), cos(degtorad( 0)), true);
system->setSpeakerPosition(FMOD_SPEAKER_LOW_FREQUENCY, sin(degtorad( 0)), cos(degtorad( 0)), true);
system->setSpeakerPosition(FMOD_SPEAKER_SURROUND_LEFT, sin(degtorad( -90)), cos(degtorad( -90)), true);
system->setSpeakerPosition(FMOD_SPEAKER_SURROUND_RIGHT, sin(degtorad( 90)), cos(degtorad( 90)), true);
system->setSpeakerPosition(FMOD_SPEAKER_BACK_LEFT, sin(degtorad(-150)), cos(degtorad(-150)), true);
system->setSpeakerPosition(FMOD_SPEAKER_BACK_RIGHT, sin(degtorad( 150)), cos(degtorad( 150)), true);
You could use this function to make sounds in front of your come out of different physical speakers. If you specified for example that FMOD_SPEAKER_BACK_RIGHT was in front of you at <0.0, 1.0> and you organized the other speakers accordingly the 3D audio would come out of the side right speaker when it was in front instead of the default which is only to the side.
This function is also useful if speakers are not 'perfectly symmetrical'. For example if the center speaker was closer to the front left than the front right, this function could be used to position that center speaker accordingly and FMOD would skew the panning appropriately to make it sound correct again.
The 2D coordinates used are only used to generate angle information. Size / distance does not matter in FMOD's implementation because it is not FMOD's job to attenuate or amplify the signal based on speaker distance. If it amplified the signal in the digital domain the audio could clip/become distorted. It is better to use the amplifier's analogue level capabilities to balance speaker volumes.
Calling System::setSoftwareFormat overrides these values, so this function must be called after this.
See Also
Version 1.10.03 Built on Feb 1, 2018