diff options
Diffstat (limited to 'doc/api.texi')
| -rw-r--r-- | doc/api.texi | 458 |
1 files changed, 456 insertions, 2 deletions
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 |