Blitz3D+ Command Reference

Load3DSound ( filename$ )

Parameters

filename$ - filename of sound file to be loaded as a 3D sound

Description

Loads a sound for 3D use and returns its handle, for playing with EmitSound.

The difference from a plain LoadSound is what the engine prepares the sound for: a 3D sound can be positioned in space, so when emitted from an entity it pans between speakers, fades with distance and doppler-shifts with movement. Use Load3DSound for world sounds - footsteps, engines, gunfire, ambient machinery - and LoadSound for flat interface sounds and music.

Mono samples are the right source material for 3D sounds, since the 3D engine supplies the stereo placement itself.

Returns 0 if the file could not be loaded. A 3D sound can still be played flat with PlaySound, and the handle is freed with FreeSound like any other.

See also: EmitSound, CreateListener, LoadSound, PlaySound.

Example

; Load3DSound Example
; -------------------

Graphics3D 640,480,0,2
SetBuffer BackBuffer()

camera=CreateCamera()
PositionEntity camera,0,2,0

light=CreateLight()
RotateEntity light,45,45,0

; Textured ground plane
plane=CreatePlane()
ground_tex=LoadTexture("media/MossyGround.BMP")
ScaleTexture ground_tex,4,4
EntityTexture plane,ground_tex

; A siren drone circles the camera, beeping as it goes
drone=CreateSphere()
EntityColor drone,255,100,100
PositionEntity drone,8,2,0

; The listener rides on the camera - 3D sound is heard from its position
listener=CreateListener(camera)

; Load the beep as a 3D sound so it can be positioned in space
beep=Load3DSound("../2d_examples/media/beep.wav")

angle#=0
next_beep=MilliSecs()

While Not KeyDown(1)

    ; Fly the drone in a circle around the listener
    angle=angle+1
    PositionEntity drone,Cos(angle)*8,2,Sin(angle)*8

    ; Because the beep was loaded with Load3DSound, emitting it from the
    ; drone gives it a position in space. Emit a beep every 700 milliseconds
    If MilliSecs()>next_beep Then
        channel=EmitSound(beep,drone)
        next_beep=MilliSecs()+700
    EndIf

    ; Left / Right turn the camera - face the drone or turn away
    If KeyDown(203) Then TurnEntity camera,0,1,0
    If KeyDown(205) Then TurnEntity camera,0,-1,0

    RenderWorld

    Text 0,0,"Left / Right: turn camera   Esc: exit"
    Text 0,20,"Listen: the beep pans between speakers as the drone circles"

    Flip

Wend

End

Index