FMExAudioPlayer3D Class
This class is used to play and manipulate FMExAudio instances in a simulated 3D environment. 3D sound will work with any number of speakers attached, although stereo ouput is the recommended minimum. FMOD Ex will automatically utilize surround sound hardware for 3D audio on supported systems for an even more immersive experience. By design, each FMExAudioPlayer3D instance will only playback one sound at a time (it essentially only has one "voice"). Calling one of the Play methods simply stops any current playback and starts playing the new sound.
Important: You must assign a FMEx.Listener3D instance when using 3D audio, and call FMEx.Update for every frame of your simulation.
Note: Calling a Play method without specifying an audio sample and with no DefaultAudio defined will cause any current playback to stop. Playback will also stop if an FMExAudioPlayer3D goes out of scope.
Constructors
-
FMExAudioPlayer3D ( audio As FMExAudio = Nil, linearRolloff As Boolean = False )
The optional audio parameter will be assigned to the DefaultAudio property. Setting the optional linearRollOff to True will play sounds using linear 3D volume attenuation from Minimum3DDistance to Maximum3DDistance, rather than the default (more realistic, but more CPU-intensive) logarithmic attenuation.
Properties
-
DefaultAudio As FMExAudio
Play methods will play this sound if they are called without specifying another FMExAudio instance. If DefaultAudio is Nil (default) no sound will play unless specified in a Play method. -
Maximum3DDistance As Double = 10000.0
The default value of 10000.0 is the typical "best setting" for sounds that use the default logarithmic roll off. When using linear roll off, this is the distance from the sound where it becomes inaudible - the default value will usually need to be drastically reduced in this case. -
Minimum3DDistance As Double = 1.0
The distance from the sound origin where the volume begins attenuating. When a listener is within this distance the sound will play at full volume. Beyond this distance the sound attenuates according to its roll off type (defined in the Constructor), the Maximum3DDistance, and the FMEx.RolloffScale3D setting.
Methods
-
Play ( audio As FMExAudio = Nil )
Plays the passed audio, or the DefaultAudio if no audio is specified. The audio will stop when the end of the sound is reach. -
PlayLooping ( audio As FMExAudio = Nil, count As Integer = -1 )
Plays the passed audio, or the DefaultAudio if no audio is specified. The optional count parameter defines how many times to loop after the first playback. A count of 0 will play once, 1 will play twice, etc. The default count of -1 will loop indefinitely. -
PlayLoopingPalendrone ( audio As FMExAudio = Nil, count As Integer = -1 )
Same as PlayLooping, however the audio is played backwards when the end or loop point is encountered. -
Set3DPosition ( x As Double, y As Double, z As Double )
Sets the position of the sound in global 3D space. -
Set3DPositionAndVelocity ( px As Single, py As Single, pz As Single, vx As Single, vy As Single, vz As Single )
Sets both the position of the sound in global 3D space (px,py,pz), and its velocity (direction and speed) vector (vx,vy,vz). Velocity is required by FMOD Ex to calculate Doppler (pitch shifting) effects for moving sounds. -
Set3DVelocity ( x As Double, y As Double, z As Double )
Sets the velocity (direction and speed) vector of the sound. Velocity is required by FMOD Ex to calculate Doppler (pitch shifting) effects for moving sounds.