((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/sdl-mixer" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.") (tags "egg" "sdl-mixer")) (section 2 "sdl-mixer " (toc) (section 3 "Introduction" (p "This egg provides a schemely wrapper around the libsdl-mixer library. The original library documentation can be found at " (link "http://www.libsdl.org/projects/SDL_mixer/docs/SDL_mixer.html" "the libsdl website") ".")) (section 3 "Author" (p (int-link "/users/christian-kellermann" "Christian Kellermann"))) (section 3 "Requirements" (p "sdl-mixer headers and libraries must be present. Versions prior to 0.6 also needed the SDL egg.")) (section 3 "API" (section 4 "Overview" (p "Opening and closing the audio device") (def (sig (procedure "(open-audio #!key sampling-rate sample-format channels chunk-size)" (id open-audio))) (p "Opens the audio device and initialises libsdl-mixer. Needs to be called at least once. It will close and reopen the device if it has been opened before.") (p "The defaults for the keyword arguments are:") (dl (dt "sampling-rate") (dd "44100") (dt "sample-format") (dd "AUDIO_S16SYS") (dt "channels") (dd "2") (dt "chunk-size") (dd "1024")) (p (i "Note:") " The sdl-init and mix-init procedures will be called only once.")) (def (sig (procedure "(close-audio)" (id close-audio))) (p "Closes the audio device and shuts down the mixer library. No procedure should access libsdl-mixer or sdl audio procedures after calling " (i "close-audio") "."))) (section 4 "Playing samples in channels" (def (sig (procedure "(load-sample filename) => sample" (id load-sample))) (p "Loads the sample from " (i "filename") ". Raises an exception if the sample cannot be loaded or the sample format is not supported by sdl-mixer. Returns a pointer representing the sample which can be used by " (i "play-sample") ".")) (def (sig (procedure "(play-sample sample #!key channel repeat fadein duration)" (id play-sample))) (p "Takes a " (i "sample") " pointer, which has been loaded with " (i "load-sample") " and plays it on " (i "channel") ". By default this is the next available channel. The sample will be repeated " (i "repeat") " times, which by default is " (i "#f") ", the sample will be played once only.") (p (i "fadein") " and " (i "duration") " control how long the sample is played and the time that is used to fade in the sample to the channel. Both values represent milliseconds.")) (def (sig (procedure "(pause-channel #!optional channel)" (id pause-channel)) (procedure "(resume-channel #!optional channel)" (id resume-channel))) (p "Will pause or resume all channels or the given " (i "channel") ".")) (def (sig (procedure "(halt-channel #!optional channel #!key fadeout)" (id halt-channel))) (p "Halts channel " (i "channel") " or all channels by default. If the " (i "fadeout") " parameter is set, this will be used to fade out the channel(s). " (i "fadeout") " is given in milliseconds.")) (def (sig (procedure "(channel-finished proc)" (id channel-finished))) (p "Sets a handler to be called when a channel has finished playing. The " (i "proc") " is expected to take an argument for the channel number that has finished.")) (def (sig (procedure "(channel-playing? channel)" (id channel-playing?)) (procedure "(channel-paused? channel)" (id channel-paused?))) (p "Predicates indicating whether " (i "channel") " is in playing or paused state."))) (section 4 "Playing music" (def (sig (procedure "(load-music filename) => music" (id load-music))) (p "Loads a file " (i "filename") " and returns a music object. A condition is raised if the format of the file is not supported by libsdl-mixer. It returns a pointer representing the music which can be used by " (i "play-music") ".")) (def (sig (procedure "(play-music music #!key repeat fadein volume)" (id play-music))) (p "Plays " (i "music") ", optionally repeating it " (i "repeat") " times (by default it is played once), using a fade in of " (i "fadein") " milliseconds with a volume value set to ''volume'.")) (def (sig (procedure "(halt-music #!key fadeout)" (id halt-music))) (p "Halts the currently played music, optionally with a fade out set to " (i "fadeout") " milliseconds.")) (def (sig (procedure "(pause-music)" (id pause-music)) (procedure "(resume-music)" (id resume-music)) (procedure "(rewind-music)" (id rewind-music))) (p "Pauses, resumes or rewinds the currently played music.")) (def (sig (procedure "(music-finished thunk)" (id music-finished))) (p "Calls " (i "thunk") " whenever the currently played music is finished.")) (def (sig (procedure "(music-type music)" (id music-type))) (p "Returns the type of " (i "music") ". The return value is a symbol, and can be: " (i "wav") ", " (i "mp3") ", " (i "mod") ", " (i "midi") ", " (i "ogg") " or " (i "user-specific") ".")) (def (sig (procedure "(music-volume #!optional new)" (id music-volume))) (p "Returns or sets the current volume level for music.")) (def (sig (procedure "(music-playing?)" (id music-playing?))) (p "Returns " (i "#t") " if music is playing.") (p (b "Note:") " A paused state is considered playing for libsdl-mixer..."))) (section 4 "Errors" (p "The procedures in this extension raise a composite condition with the properties:") (pre "((exn message msg)\n (sdl)\n (mixer))"))) (section 3 "Example" (highlight scheme "(use sdl-mixer)\n\n(open-audio)\n\n(channel-finished (lambda (c) (printf \"Channel ~a finished~%\" c)))\n\n(play-music (load-music \"background.mp3\"))\n(let ((s (load-sample \"noise.wav\")))\n     (play-sample s))\n(close-audio)")) (section 3 "License" (p "The wrapper is licensed as " (link "https://www.gnu.org/licenses/lgpl-3.0.txt" "LGPL") " as is the original libsdl-mixer.")) (section 3 "Version history" (dl (dt "0.1") (dd "dev release") (dt "0.2") (dd "bugfix to appease salmonella") (dt "0.3") (dd "callbacks added") (dt "0.4") (dd "defaults of open-audio, pause-channel, halt-channel,")) (pre " rewind-channel changed") (dl (dt "0.5") (dd "basically broken") (dt "0.6") (dd "bugfix release with working callbacks and without the need to install the SDL egg")))))