make a protocol for audio.engine sources/listeners. fix multiple clip play/pause/stop words, and fix when a clip gets disposed during update-audio

extra/audio/engine/engine.factor

@@ -16,6 +16,8 @@ TUPLE: audio-orientation
     { forward initial: { 0.0 0.0 -1.0 } }
     { up initial: { 0.0 1.0 0.0 } } ;
 
+C: <audio-orientation> audio-orientation
+
 : orientation>float-array ( orientation -- float-array )
     [ forward>> first3 ]
     [ up>> first3 ] bi 6 float-array{ } nsequence ; inline
@@ -26,6 +28,28 @@ TUPLE: audio-listener
     { velocity initial: { 0.0 0.0 0.0 } }
     { orientation initial: T{ audio-orientation } } ;
 
+GENERIC: audio-position ( source/listener -- position )
+GENERIC: audio-gain ( source/listener -- gain )
+GENERIC: audio-velocity ( source/listener -- velocity )
+GENERIC: audio-relative? ( source -- relative? )
+GENERIC: audio-orientation ( listener -- orientation )
+
+M: object audio-position drop { 0.0 0.0 0.0 } ; inline
+M: object audio-gain drop 1.0 ; inline
+M: object audio-velocity drop { 0.0 0.0 0.0 } ; inline
+M: object audio-relative? drop f ; inline
+M: object audio-orientation drop T{ audio-orientation } ; inline
+
+M: audio-source audio-position position>> ; inline
+M: audio-source audio-gain gain>> ; inline
+M: audio-source audio-velocity velocity>> ; inline
+M: audio-source audio-relative? relative?>> ; inline
+
+M: audio-listener audio-position position>> ; inline
+M: audio-listener audio-gain gain>> ; inline
+M: audio-listener audio-velocity velocity>> ; inline
+M: audio-listener audio-orientation orientation>> ; inline
+
 TUPLE: audio-engine < disposable
     { voice-count integer }
     { buffer-size integer }
@@ -33,7 +57,7 @@ TUPLE: audio-engine < disposable
     { al-device c-ptr }
     { al-context c-ptr }
     al-sources
-    { listener audio-listener }
+    listener
     { next-source integer }
     clips
     update-alarm ;
@@ -41,7 +65,7 @@ TUPLE: audio-engine < disposable
 TUPLE: audio-clip < disposable
     { audio-engine audio-engine }
     { audio audio }
-    { source audio-source }
+    source
     { loop? boolean }
     { al-source integer }
     { al-buffers uint-array }
@@ -152,18 +176,18 @@ ERROR: audio-context-not-available device-name ;
 
 : update-listener ( audio-engine -- )
     listener>> {
-        [ AL_POSITION swap position>> first3 alListener3f ]
-        [ AL_GAIN swap gain>> alListenerf ]
-        [ AL_VELOCITY swap velocity>> first3 alListener3f ]
-        [ AL_ORIENTATION swap orientation>> orientation>float-array alListenerfv ]
+        [ AL_POSITION swap audio-position first3 alListener3f ]
+        [ AL_GAIN swap audio-gain alListenerf ]
+        [ AL_VELOCITY swap audio-velocity first3 alListener3f ]
+        [ AL_ORIENTATION swap audio-orientation orientation>float-array alListenerfv ]
     } cleave ;
 
 : update-source ( audio-clip -- )
     [ al-source>> ] [ source>> ] bi {
-        [ AL_POSITION swap position>> first3 alSource3f ]
-        [ AL_GAIN swap gain>> alSourcef ]
-        [ AL_VELOCITY swap velocity>> first3 alSource3f ]
-        [ AL_SOURCE_RELATIVE swap relative?>> c:>c-bool alSourcei ]
+        [ AL_POSITION swap audio-position first3 alSource3f ]
+        [ AL_GAIN swap audio-gain alSourcef ]
+        [ AL_VELOCITY swap audio-velocity first3 alSource3f ]
+        [ AL_SOURCE_RELATIVE swap audio-relative? c:>c-bool alSourcei ]
     } 2cleave ;
 
 :: update-audio-clip ( audio-clip -- )
@@ -179,8 +203,8 @@ ERROR: audio-context-not-available device-name ;
         ] times
     ] if ;
 
-: clip-sources ( clips -- length sources )
-    [ length ] [ [ source>> ] uint-array{ } map-as ] bi ;
+: clip-al-sources ( clips -- length sources )
+    [ length ] [ [ al-source>> ] uint-array{ } map-as ] bi ;
 
 PRIVATE>
 
@@ -263,7 +287,7 @@ M: audio-clip dispose*
 
 : play-clips ( audio-clips -- )
     [ [ update-source ] each ]
-    [ clip-sources alSourcePlayv ] bi ;
+    [ clip-al-sources alSourcePlayv ] bi ;
 
 : <audio-clip> ( audio-engine audio source loop? -- audio-clip/f )
     (audio-clip) dup play-clip ;
@@ -272,19 +296,19 @@ M: audio-clip dispose*
     al-source>> alSourcePause ;
 
 : pause-clips ( audio-clip -- )
-    clip-sources alSourcePausev ;
+    clip-al-sources alSourcePausev ;
 
 : stop-clip ( audio-clip -- )
     dispose ;
 
 : stop-clips ( audio-clip -- )
-    [ clip-sources alSourceStopv ]
+    [ clip-al-sources alSourceStopv ]
     [ [ dispose ] each ] bi ;
 
 : update-audio ( audio-engine -- )
     {
         [ make-engine-current ]
         [ update-listener ]
-        [ clips>> [ update-audio-clip ] each ]
+        [ clips>> clone [ update-audio-clip ] each ]
     } cleave ;
 

extra/game/worlds/worlds-docs.factor

@@ -26,7 +26,7 @@ $nl
 
 HELP: begin-game-world
 { $values { "world" game-world } }
-{ $description "This generic word is called by the " { $link begin-world } " method for " { $link game-world } " subclasses immediately before the game world starts the game loop." } ;
+{ $description "This generic word is called by the " { $link begin-world } " method for " { $link game-world } " subclasses immediately before the game world starts the game loop. If the game world has an " { $link audio-engine } ", it will be initialized and started before " { $snippet "begin-game-world" } " is called." } ;
 
 HELP: end-game-world
 { $values { "world" game-world } }