diff options
Diffstat (limited to 'docs/audio.org')
| -rw-r--r-- | docs/audio.org | 26 |
1 files changed, 13 insertions, 13 deletions
diff --git a/docs/audio.org b/docs/audio.org index 7d83e44..464e2c8 100644 --- a/docs/audio.org +++ b/docs/audio.org @@ -3,7 +3,7 @@ Downstroke's audio stack is a thin wrapper around SDL2's =SDL_mixer= library. It gives you two things: short /sound effects/ (one-shots triggered on input, collisions, pickups, etc.) and a single streaming /music/ track (a looping -background song). The friendly API lives in the =downstroke-sound= module and +background song). The friendly API lives in the =(downstroke sound)= module and is the only thing most games ever need to touch. Audio is deliberately kept outside the [[file:guide.org][=game= record]]. The sound module @@ -15,8 +15,8 @@ manage audio for you. * The minimum you need #+begin_src scheme -(import downstroke-engine - downstroke-sound) +(import (downstroke engine) + (downstroke sound)) (define *music-on?* #f) @@ -54,25 +54,25 @@ Four calls cover ~95% of real usage: Audio is split into two modules, and you pick the one that matches what you are doing: -- =downstroke-sound= — the friendly, high-level API. Symbolic sound names, an +- =(downstroke sound)= — the friendly, high-level API. Symbolic sound names, an internal registry, volume given as =0.0..1.0=, music that just loops. This is what the rest of this document documents, and what every demo uses. -- =downstroke-mixer= — raw FFI bindings to =SDL_mixer= +- =(downstroke mixer)= — raw FFI bindings to =SDL_mixer= (=Mix_OpenAudio=, =Mix_LoadWAV=, =Mix_PlayChannel=, =Mix_LoadMUS=, =Mix_PlayMusic=, =Mix_VolumeMusic=, …). No registry, no convenience, no type conversions. Values are raw C-level integers (volumes are =0..128=, channels are integers, loops is an integer count with =-1= for forever). -Reach for =downstroke-mixer= only when you need something the high-level +Reach for =(downstroke mixer)= only when you need something the high-level wrapper does not expose — for example, playing more than one concurrent music -track via channel groups, or fading effects. In practice, =downstroke-sound= -covers 99% of cases; you almost never =import downstroke-mixer= directly in +track via channel groups, or fading effects. In practice, =(downstroke sound)= +covers 99% of cases; you almost never =import (downstroke mixer)= directly in game code. *** Module-level state (be aware of this) -=downstroke-sound= keeps two global variables inside the module: +=(downstroke sound)= keeps two global variables inside the module: - =*sound-registry*= — an association list of =(symbol . Mix_Chunk*)= pairs populated by =load-sounds!=. @@ -87,7 +87,7 @@ This means: alist. - Calling =load-music!= replaces =*music*= without freeing the previous track — use =cleanup-audio!= if you need to swap tracks cleanly, or drop - into =downstroke-mixer= and call =mix-free-music!= yourself. + into =(downstroke mixer)= and call =mix-free-music!= yourself. - Two games in the same process would share this state. That is not a supported configuration; one =game-run!= per process is the expectation. @@ -175,7 +175,7 @@ and null chunks are silently ignored. SDL_mixer defaults to 8 simultaneous channels. If all channels are busy, the new sound is dropped. For most 2D games this is plenty; if you need -more, use =downstroke-mixer= directly and call =Mix_AllocateChannels=. +more, use =(downstroke mixer)= directly and call =Mix_AllocateChannels=. Volume on individual effects is not exposed by the high-level API — every chunk plays at the mixer's current chunk volume. If you need per-sound @@ -294,10 +294,10 @@ A full on/off toggle, as seen in the audio demo, looks like this: To change songs cleanly, halt the current one, free it, and load the new one. The high-level API does not free for you, so either call =cleanup-audio!= (which also closes the device — probably not what you want -mid-game) or drop to =downstroke-mixer=: +mid-game) or drop to =(downstroke mixer)=: #+begin_src scheme -(import downstroke-mixer) +(import (downstroke mixer)) (define (swap-music! path volume) (stop-music!) |