From 159c35f706de14f3e3c6942934532011a1d77277 Mon Sep 17 00:00:00 2001
From: David Thompson <dthompson2@worcester.edu>
Date: Wed, 9 Jan 2019 20:26:28 -0500
Subject: audio: Add public audio API.

* chickadee/audio.scm: New file.
* Makefile.am (SOURCES): Add it.
* api.texi (Audio): Add docs.
---
 doc/api.texi | 458 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 456 insertions(+), 2 deletions(-)

(limited to 'doc')

diff --git a/doc/api.texi b/doc/api.texi
index f1726d9..18e0841 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -2787,8 +2787,462 @@ Return the data type of @var{attribute}.
 @node Audio
 @section Audio
 
-Most games need to play audio.  Background music to set the mood and
-many sound effects for when things happen.
+A game isn't complete without sound.  Most games play some cool
+background music to set the mood and have many sound effects to play
+when events happen.  The @code{(chickadee audio)} module provides a
+robust audio API backed by the OpenAL 3D audio system.
+
+@menu
+* Audio Files::                 Not audiophiles.
+* Sources::                     Audio emitters.
+* The Listener::                The player's ears.
+* The Environment::             Global sound model settings.
+@end menu
+
+The basics of playing audio are very simple.  Just load an audio file
+in the load hook (or anywhere else once the game loop is running) and
+play it!
+
+@example
+(use-modules (chickadee audio))
+
+(define audio #f)
+
+(define (load)
+  (set! audio (load-audio "neat-sound-effect.wav"))
+  (audio-play audio))
+
+(run-game #:load load)
+@end example
+
+For more advanced usage, check out the full API reference in the
+following sections.
+
+@node Audio Files
+@subsection Audio Files
+
+Sound data is represented by a special @code{<audio>} data type that
+stores not only the audio samples themselves, but metadata such as
+sample rate, number of channels, and how many bits are used for each
+sample.
+
+@deffn {Procedure} load-audio file-name [#:mode @code{static}]
+Load audio within @var{file-name}.  The following file formats are
+currently supported:
+
+@itemize
+@item WAV
+@item MP3
+@item Ogg Vorbis
+@end itemize
+
+Audio files can be loaded in two different ways, as indicated by
+@var{mode}:
+
+@itemize
+@item static:
+Load the entire audio file into memory.
+@item stream:
+Load chunks of the audio file as needed.
+@end itemize
+
+Generally speaking, sound effects don't take up much space and should
+be loaded statically, but music files are much larger and should use
+streaming.  Static loading is the default.
+@end deffn
+
+@deffn {Procedure} audio? @var{obj}
+Return @code{#t} if @var{obj} is an audio object.
+@end deffn
+
+@deffn {Procedure} streaming-audio? @var{audio}
+Return @code{#t} if @var{audio} uses stream loading.
+@end deffn
+
+@deffn {Procedure} static-audio?
+Return @code{#t} if @var{audio} uses static loading.
+@end deffn
+
+@deffn {Procedure} audio-mode audio
+Return the loading mode for @var{audio}, either @code{static} or
+@code{stream}.
+@end deffn
+
+@deffn {Procedure} audio-duration audio
+Return the duration of @var{audio} in seconds.
+@end deffn
+
+@deffn {Procedure} audio-bits-per-sample audio
+Return the number of bits per sample in @var{audio}.
+@end deffn
+
+@deffn {Procedure} audio-channels audio
+Return the number of channels in @var{audio}.
+@end deffn
+
+@deffn {Procedure} audio-sample-rate audio
+Return the sample rate of @var{audio}.
+@end deffn
+
+@deffn {Procedure} audio-play audio [#:pitch 1.0] [#:volume 1.0] @
+                   [#:min-volume 0.0] [#:max-volume 1.0] [#:max-distance] @
+                   [#:reference-distance 0.0] [#:rolloff-factor 1.0] @
+                   [#:cone-outer-volume 0.0] [#:cone-inner-angle 0.0] @
+                   [#:cone-outer-angle] @
+                   [#:position @code{(vec3 0.0 0.0 0.0)}] @
+                   [#:velocity @code{(vec3 0.0 0.0 0.0)}] @
+                   [#:direction @code{(vec3 0.0 0.0 0.0)}] @
+                   [#:relative? @code{#f}]
+
+Play @var{audio}.  There are many, many knobs to tweak that will
+affect the sound that comes out of the player's speakers.:
+
+@itemize
+@item @var{pitch}:
+Pitch multiplier.  The default value of 1.0 means no change in pitch.
+@item @var{volume}:
+Volume multiplier.  The default value of 1.0 means no change in volume.
+@item @var{min-volume}:
+Minimum volume.
+@item @var{max-volume}:
+Maximum volume.
+@item @var{max-distance}:
+Used with the inverse clamped distance model (the default model) to
+set the distance where there will no longer be any attenuation of the
+source.
+@item @var{reference-distance}:
+The distance where the volume for the audio would drop by half (before
+being influenced by the rolloff factor or maximum distance.)
+@item @var{rolloff-factor}:
+For slowing down or speeding up the rate of attenuation.  The default
+of 1.0 means no attenuation adjustment is made.
+@item @var{cone-outer-volume}:
+The volume when outside the oriented cone.
+@item @var{cone-inner-angle}:
+Inner angle of the sound cone, in radians.  The default value is 0.
+@item @var{cone-outer-angle}:
+Outer angle of the sound cone, in radians.  The default value is 2pi
+radians, or 360 degrees.
+@item @var{position}:
+The source of the sound emitter in 3D space.
+@item @var{velocity}:
+The velocity of the sound emitter in 3D space.
+@item @var{direction}:
+The direction of the sound emitter in 3D space.
+@item @var{relative?}:
+A flag that determines whether the position is in absolute coordinates
+or relative to the listener's location.  Absolute coordinates are used
+by default.
+@end itemize
+
+For games with basic sound needs (that is to say they don't need 3D
+sound modeling), the only things that really matter are @var{volume}
+and @var{pitch}.
+
+@end deffn
+
+@node Sources
+@subsection Sources
+
+While the @code{audio-play} procedure provides a quick and convenient
+way to play audio, it has some limitations.  What if the audio is a
+long piece of music that might need to be paused or stopped later?
+What if the audio should be looped?  What if the volume or pitch needs
+to be altered?  For manipulating audio in these ways, a ``source'' is
+required.  Sources can be thought of like a boombox: They sit
+somewhere in the room and play sound.  The pause or stop buttons can
+be pressed; it can be moved somewhere else; the volume knob can be
+adjusted; the CD can be changed.
+
+Sources are a great fit for handling background music, among other
+things.  For quick, one-off sound effects, @code{audio-play} is a
+better fit.
+
+@deffn {Procedure} make-source audio loop? [#:pitch 1.0] [#:volume 1.0] @
+                   [#:min-volume 0.0] [#:max-volume 1.0] [#:max-distance] @
+                   [#:reference-distance 0.0] [#:rolloff-factor 1.0] @
+                   [#:cone-outer-volume 0.0] [#:cone-inner-angle 0.0] @
+                   [#:cone-outer-angle] @
+                   [#:position @code{(vec3 0.0 0.0 0.0)}] @
+                   [#:velocity @code{(vec3 0.0 0.0 0.0)}] @
+                   [#:direction @code{(vec3 0.0 0.0 0.0)}] @
+                   [#:relative? @code{#f}]
+
+Return a new audio source.  @var{audio} is the audio data to use when
+playing.  @var{loop?} specifies whether or not to loop the audio
+during playback.
+
+Refer to @code{audio-play} (@pxref{Audio Files}) for information about
+the optional keyword arguments.
+@end deffn
+
+@deffn {Procedure} source? obj
+Return @code{#t} if @var{obj} is an audio source object.
+@end deffn
+
+@deffn {Procedure} streaming-source? source
+Return @code{#t} if @var{source} contains streaming audio.
+@end deffn
+
+@deffn {Procedure} static-source? source
+Return @code{#t} if @var{source} contains static audio.
+@end deffn
+
+@deffn {Procedure} source-playing? source
+Return @code{#t} if @var{source} is currently playing.
+@end deffn
+
+@deffn {Procedure} source-paused? source
+Return @code{#t} if @var{source} is currently paused.
+@end deffn
+
+@deffn {Procedure} source-stopped? source
+Return @code{#t} if @var{source} is currently stopped.
+@end deffn
+
+@deffn {Procedure} source-pitch source
+Return the pitch multiplier of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-volume source
+Return the volume multiplier of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-min-volume source
+Return the minimum volume of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-max-volume source
+Return the maximum volume of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-max-distance source
+Return the maximum distance of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-reference-distance source
+Return the reference distance of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-rolloff-factor source
+Return the rolloff factor of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-cone-outer-volume source
+Return the volume of @var{source} when outside the oriented cone.
+@end deffn
+
+@deffn {Procedure} source-cone-inner-angle source
+Return the inner angle of the sound cone of @var{source} in radians.
+@end deffn
+
+@deffn {Procedure} source-cone-outer-angle source
+Return the outer angle of the sound cone of @var{source} in radians.
+@end deffn
+
+@deffn {Procedure} source-position source
+Return the position of @var{source} as a 3D vector.
+@end deffn
+
+@deffn {Procedure} source-velocity source
+Return the velocity of @var{source} as a 3D vector.
+@end deffn
+
+@deffn {Procedure} source-direction source
+Return the direction of @var{source} as a 3D vector.
+@end deffn
+
+@deffn {Procedure} source-relative? source
+Return @code{#t} if the position of @var{source} is relative to the
+listener's position.
+@end deffn
+
+@deffn {Procedure} source-play source
+Begin/resume playback of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-pause source
+Pause playback of @var{source}.
+@end deffn
+
+@deffn {Procedure} source-toggle source
+Play @var{source} if it is currently paused or pause @var{source} if
+it is currently playing.
+@end deffn
+
+@deffn {Procedure} source-stop [source]
+Stop playing @var{source} or, if no source is specified, stop playing
+@emph{all} sources.
+@end deffn
+
+@deffn {Procedure} source-rewind source
+Rewind @var{source} to the beginning of the audio stream.
+@end deffn
+
+@deffn {Procedure} set-source-audio! source audio
+Set the playback stream for @var{source} to @var{audio}.
+@end deffn
+
+@deffn {Procedure} set-source-loop! source loop?
+Configure whether or not @var{source} should loop the audio stream.
+@end deffn
+
+@deffn {Procedure} set-source-pitch! source pitch
+Set the pitch multiplier of @var{source} to @var{pitch}
+@end deffn
+
+@deffn {Procedure} set-source-volume! source volume
+Set the volume of @var{source} to @var{volume}.  A value of 1.0 is
+100% volume.
+@end deffn
+
+@deffn {Procedure} set-source-min-volume! source volume
+Set the minimum volume of @var{source} to @var{volume}.
+@end deffn
+
+@deffn {Procedure} set-source-max-volume! source volume
+Set the maximum volume of @var{source} to @var{volume}.
+@end deffn
+
+@deffn {Procedure} set-source-max-distance! source distance
+Set the distance where there will no longer be any attenuation of
+@var{source} to @var{distance}.
+@end deffn
+
+@deffn {Procedure} set-source-reference-distance! source distance
+Set the reference distance of @var{source} to @var{distance}.
+@end deffn
+
+@deffn {Procedure} set-source-rolloff-factor! source factor
+Set the rolloff factor for @var{source} to @var{factor}.
+@end deffn
+
+@deffn {Procedure} set-source-cone-outer-volume! source volume
+Set the volume for @var{source} when outside the sound cone to @var{volume}.
+@end deffn
+
+@deffn {Procedure} set-source-cone-inner-angle! source angle
+Set the inner angle of the sound cone of @var{source} to @var{angle} radians.
+@end deffn
+
+@deffn {Procedure} set-source-cone-outer-angle! source angle
+Set the outer angle of the sound cone of @var{source} to @var{angle} radians.
+@end deffn
+
+@deffn {Procedure} set-source-position! source position
+Set the position of @var{source} to the 3D vector @var{position}.
+@end deffn
+
+@deffn {Procedure} set-source-velocity! source velocity
+Set the velocity of @var{source} to the 3D vector @var{velocity}.
+@end deffn
+
+@deffn {Procedure} set-source-direction! source direction
+Set the velocity of @var{source} to the 3D vector @var{direction}.
+@end deffn
+
+@deffn {Procedure} set-source-relative! source relative?
+If @var{relative?} is @code{#t}, the position of @var{source} is
+interpreted as relative to the listener's position.  Otherwise, the
+position of @var{source} is in absolute coordinates.
+@end deffn
+
+@node The Listener
+@subsection The Listener
+
+The listener is a collection of global state that represents the
+player within the 3D sound model.  For games that do not need 3D sound
+modeling, manipulating the listener's master volume is the only
+interesting thing to do here.
+
+@deffn {Procedure} listener-volume
+Return the current master volume of the listener.
+@end deffn
+
+@deffn {Procedure} listener-position
+Return the current position of the listener.
+@end deffn
+
+@deffn {Procedure} listener-velocity
+Return the current velocity of the listener.
+@end deffn
+
+@deffn {Procedure} listener-orientation
+Return the current orientation of the listener.
+@end deffn
+
+@deffn {Procedure} set-listener-volume! volume
+Set the listener's master volume to @var{volume}, a value in the range [0,
+1].
+@end deffn
+
+@deffn {Procedure} set-listener-position! position
+Set the listener's position to the 3D vector @var{position}.
+@end deffn
+
+@deffn {Procedure} set-listener-velocity! velocity
+Set the listener's velocity to the 3D vector @var{velocity}.
+@end deffn
+
+@deffn {Procedure} set-listener-orientation! at up
+Set the listener's orientation to the 3D vectors @var{at} and
+@var{up}.
+@end deffn
+
+@node The Environment
+@subsection The Environment
+
+The environment defines global parameters that govern how sound is
+processed within the 3D modeling space.
+
+@deffn {Procedure} doppler-factor
+Return the current doppler factor.
+@end deffn
+
+@deffn {Procedure} speed-of-sound
+Return the current speed of sound.
+@end deffn
+
+@deffn {Procedure} distance-model
+Return the current distance model.
+
+Possible return values are:
+
+@itemize
+@item @code{none}
+@item @code{inverse-distance}
+@item @code{inverse-distance-clamped} (the default)
+@item @code{linear-distance}
+@item @code{linear-distance-clamped}
+@item @code{exponent-distance}
+@item @code{exponent-distance-clamped}
+@end itemize
+
+@end deffn
+
+@deffn {Procedure} set-doppler-factor! doppler-factor
+Change the doppler factor to @var{doppler-factor}.
+@end deffn
+
+@deffn {Procedure} set-speed-of-sound! speed-of-sound
+Change the speed of sound to @var{speed-of-sound}.
+@end deffn
+
+@deffn {Procedure} set-distance-model! distance-model
+Change the distance model to @var{distance-model}.  Valid distance
+models are:
+
+@itemize
+@item @code{none}
+@item @code{inverse-distance}
+@item @code{inverse-distance-clamped}
+@item @code{linear-distance}
+@item @code{linear-distance-clamped}
+@item @code{exponent-distance}
+@item @code{exponent-distance-clamped}
+@end itemize
+
+@end deffn
 
 @node Scripting
 @section Scripting
-- 
cgit v1.2.3