Blitz3D+ Command Reference

SetAudioWorld world

Parameters

world - the world whose listener drives 3D audio, or 0 for the default world

Description

Selects the world used for positional 3D audio.

Each world can contain its own listener (CreateListener), but only one world's listener is live at a time - the audio world's. EmitSound entities should belong to that world too, or their sounds have no listener to be heard from. When you switch the player from the menu world into the game world, remember to move the audio selection along with the visual one; the two are deliberately independent, so a background world can keep rendering to a canvas without stealing the soundscape.

SetAudioWorld changes nothing but the audio routing: it does not select, update, or render a world. Passing 0 selects the default world. A world loaded with LoadWorldAsync cannot be the audio world until WorldReady is True - earlier is a runtime error. If the audio world has no listener, positional audio falls back to a neutral listener at the origin; if the audio world is freed, the selection falls back to the default world.

Requires Extended mode.

See also: AudioWorld, SetWorld, CreateListener, EmitSound, FreeWorld.

Example

; SetAudioWorld Example
; ---------------------
; Requires Extended mode.

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

; The default world holds the game scene: a red spinning cube.
; Its camera carries this world's 3D audio listener
game_world=GetWorld()
game_camera=CreateCamera()
PositionEntity game_camera,0,1,-5
game_listener=CreateListener(game_camera)
game_light=CreateLight()
RotateEntity game_light,45,45,0
cube=CreateCube()
PositionEntity cube,0,1,0
EntityColor cube,255,80,80

; A separate world holds the preview scene, with its own listener
preview_world=CreateWorld()
SetWorld preview_world
preview_camera=CreateCamera()
PositionEntity preview_camera,0,1,-5
preview_listener=CreateListener(preview_camera)
preview_light=CreateLight()
RotateEntity preview_light,45,45,0
sphere=CreateSphere()
PositionEntity sphere,0,1,0
EntityColor sphere,80,140,255

SetWorld game_world
active_camera=game_camera

; Route positional 3D audio through the game world's listener
SetAudioWorld game_world

While Not KeyDown(1)

    ; Space moves the audio selection to the other world's listener.
    ; This is independent of the rendered world selection
    If KeyHit(57)
        If AudioWorld()=game_world Then SetAudioWorld preview_world Else SetAudioWorld game_world
    EndIf

    ; W switches the rendered world - note that AudioWorld does not change
    If KeyHit(17)
        If GetWorld()=game_world
            SetWorld preview_world
            active_camera=preview_camera
        Else
            SetWorld game_world
            active_camera=game_camera
        EndIf
    EndIf

    TurnEntity cube,0,1,0
    TurnEntity sphere,0,1,0

    ; Arrow keys move the selected world's camera
    If KeyDown(200) Then MoveEntity active_camera,0,0,0.1
    If KeyDown(208) Then MoveEntity active_camera,0,0,-0.1
    If KeyDown(203) Then TurnEntity active_camera,0,1,0
    If KeyDown(205) Then TurnEntity active_camera,0,-1,0

    RenderWorld

    Text 0,0,"Space: switch audio world   W: switch rendered world   Esc: exit"
    If AudioWorld()=game_world Then audio$="game world" Else audio$="preview world"
    Text 0,20,"SetAudioWorld selected "+AudioWorld()+" - the "+audio+"'s listener is live"
    Text 0,40,"GetWorld() = "+GetWorld()+" - unchanged by SetAudioWorld"

    Flip

Wend

SetAudioWorld 0
FreeWorld preview_world
End

Index