CreateListener

CreateListener

Command Index · Blitz3D · 3D Sound

CreateListener:Int32 parent:Int32, rolloff_factor:Float32=1, doppler_scale:Float32=1, distance_scale:Float32=1

Parameter	Mode	Type	Default	Description
parent	In	Int32	required	The entity that carries the listener, typically the camera.
rolloff_factor	In	Float32	1	How fast sounds get quiet with distance: 0 means they do not, 1 is the normal rate and above that makes them fade faster. Defaults to 1.
doppler_scale	In	Float32	1	How strong the pitch change of moving sounds is: 0 turns it off, 1 is the real one and 2 shifts twice as far. Defaults to 1.
distance_scale	In	Float32	1	How many meters one unit of your world is, which sets the distances that volume falls off over and how fast things move for the doppler shift. Defaults to 1.

Returns: The entity handle of the listener, as in the original. It sits at the position of the parent and can be moved, turned, parented and freed like any other entity; EntityClass says "Listener".

Description

Creates the ear that 3D sounds are heard with. It is carried by another entity, usually the camera, so that sounds get quieter with distance and move between the left and right speaker as the listener moves and turns. Only one listener is used at a time. The listener has to exist before EmitSound is used.

Differences

• Volume falls off as 1 / (1 + rolloff * meters * 0.05), which is gentler than the curve of the original: the original (FMOD 3) is at full volume up to one meter and then falls off as meters ^ -rolloff, so at 20 meters with rolloff 1 it is at 5% where this runtime is at 50%. The environment variable BLITZLLVM_VOLUME_FALLOFF picks the curve: new (or unset) is the one above, legacy is the one of the original (checked by ear against Blitz3D 1.118; the original is noisier, since it opened FMOD at 44.1 kHz and 16 bits as common sound devices of Windows 98 wanted), and soloud is the one of SoLoud (the audio library of the SoLoud builds of Blitz3D), 1 / (1 + rolloff * (meters - 1)) from a meter on, which is the same as legacy for a rolloff of 1.
• The pitch follows the speeds along the line between the listener and the sound, with sound moving at 340 meters per second. Speeds are measured from how far the entities moved in their last step, so a sound that comes from an entity that was placed somewhere (and not moved) has no shift; nothing moves faster than 90% of the speed of sound as far as the shift is concerned. The shift follows a change of the speeds over about a tenth of a second, so a sound that passes the listener glides from the high pitch to the low one and does not jump.
• Samples of a source that drives past the listener at 60 meters per second, recorded with tools/render_doppler_samples.py: doppler_off.wav (doppler scale 0, steady 441 Hz), doppler_on.wav (scale 1, about 535 Hz while it comes closer, gliding down to 375 Hz as it passes and leaves) and doppler_far.wav (distance scale 0.25, so the speeds are a quarter and the shift is smaller).
• Samples of a source that moves away from 1 to 61 meters in two seconds (doppler off, rolloff 1), recorded with tools/render_falloff_samples.py: falloff_new.wav (fades to about 30%), falloff_soloud.wav and falloff_legacy.wav (both fade to under 2%).

Examples

Graphics3D 320, 240, 0, 2
SetBuffer BackBuffer()
camera = CreateCamera()
listener = CreateListener(camera)

source = CreateSphere()
PositionEntity source, 10, 0, 20
sound = Load3DSound("engine.wav")
LoopSound sound
EmitSound sound, source

While Not KeyHit(1)
	TurnEntity camera, 0, 0.5, 0
	RenderWorld
	Flip
Wend

Related Commands

EmitSound

Command Index · Blitz3D · 3D Sound