Blitz3D+ Command Reference

EmitSound ( sound,entity )

Parameters

sound - sound handle, loaded with Load3DSound

entity - entity handle

Description

Emits a sound from the position of an entity, and returns a sound channel.

The sound is played in 3D: its volume, stereo position and doppler shift are worked out from where the emitting entity is relative to the listener, and they keep updating as the entity and listener move while the sound plays - an engine noise emitted from a car circles the player as the car does.

Two things must be in place first: the sound must have been loaded with Load3DSound (a plain LoadSound sound won't position itself in 3D), and a listener must exist - calling EmitSound with no CreateListener is a runtime error.

The returned channel works with all the usual channel commands - ChannelVolume, ChannelPitch, StopChannel - for extra control on top of the 3D positioning. One entity can emit several sounds at once.

See also: Load3DSound, CreateListener, ChannelVolume, ChannelPitch.

Example

; EmitSound 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

    ; EmitSound plays the 3D sound from the drone entity, returning a
    ; sound channel. 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