Next: mod-csound, Previous: libsim, Up: C API

### 5.34 libsnd

#### 5.34.1 Overview

View lcov test coverage results on http://www.gnu.org/software/liquidwar6/coverage/src/lib/snd/index.html.

#### 5.34.2 API

— Function: int lw6snd_play_fx (lw6snd_backend_t * backend, int fx_id)

> backend: sound backend to use

> fx_id: sound fx id

> Plays a sound fx.

> Return value: 1 on success, 0 on error

— Function: int lw6snd_is_music_file (lw6snd_backend_t * backend, char * map_dir, char * music_path, char * music_file)

> backend: sound backend to use

> map_dir: map directory, to search additionnal files

> music_path: config entry containing multiple paths

> music_file: relative/local name of a music file

> Tells wether a file is a valid music file, typicallly based on file existence and extension. Not bullet proof, file might actually not be loadable, but chances are 99%.

> Return value: 1 if music file, 0 if not

— Function: int lw6snd_play_music_file (lw6snd_backend_t * backend, char * map_dir, char * music_path, char * music_file)

> backend: sound backend to use

> map_dir: map directory, to search additionnal files

> music_path: config entry containing multiple paths

> music_file: relative/local name of a music file

> Plays a music file.

> Return value: 1 if OK, 0 if not.

— Function: int lw6snd_play_music_random (lw6snd_backend_t * backend, char * music_path, char * music_filter, char * music_exclude)

> backend: sound backend to use

> music_path: config entry containing multiple paths

> music_filter: string filter, must be present

> music_exclude: string filter, must not be present

> Plays a random music file. The filter and exclude mecanisms are not complete regex filters, only a quick and dirty feature which should still help in some cases, such as sorting musics for the menus and for the rest.

> Return value: 1 if OK, 0 if not.

— Function: void lw6snd_stop_music (lw6snd_backend_t * backend)

> backend: sound backend to use

> Stops the music.

> Return value: none.

— Function: int lw6snd_init (lw6snd_backend_t * backend, float fx_volume, float water_volume, float music_volume)

> backend: the graphical backend to use

> fx_volume: sound fx volume

> water_volume: water sounds volume

> music_volume: music volume

> Sets up the sound backend for good, initializing a playback engine ready to play sounds and set to defaults. This call can typically fail if there's no device available, if the user doesn't have enough rights to access the hardware, and so on.

> Return value: 1 on success, 0 if not

— Function: void lw6snd_set_fx_volume (lw6snd_backend_t * backend, float volume)

> backend: sound backend to use

> volume: sound fx volume

> Changes sound fx volume.

> Return value: none.

— Function: void lw6snd_set_water_volume (lw6snd_backend_t * backend, float volume)

> backend: sound backend to use

> volume: water sounds volume

> Changes water sounds volume.

> Return value: none.

— Function: void lw6snd_set_music_volume (lw6snd_backend_t * backend, float volume)

> backend: sound backend to use

> volume: music volume

> Changes music volume.

> Return value: none.

— Function: void lw6snd_poll (lw6snd_backend_t * backend)

> backend: sound backend to use

> Polling function, must be called on a regular basis.

> Return value: none.

— Function: void lw6snd_quit (lw6snd_backend_t * backend)

> backend: the backend to quit

> Uninitializes the backend, that is, releases resources, stops playback.

> Return value: none.

— Function: char * lw6snd_repr (lw6snd_backend_t * backend)

> backend: the backend to represent

> Returns a readable version of the backend object.

> Return value: a newly allocated pointer.

— Function: lw6sys_assoc_t * lw6snd_get_backends (int argc, char * [] argv)

> argc: argc, as passed to `main`

> argv: argv, as passed to `main`

> List available snd backends. The hash contains pairs with id and name for each backend. The id is the technical key you can use to load the backend, the name is something more readable you can display in an interface. The backend objects themselves are not instanciated by this (in fact, they are, but released on the fly) you need to load and initialize them afterwards.

> Return value: hash containing id/name pairs.

— Function: lw6snd_backend_t * lw6snd_create_backend (int argc, char * [] argv, char * name)

> argc: argc, as passed to `main`

> argv: argv, as passed to `main`

> name: string containing snd key, typically got from `lw6snd_get_backends`

> Creates a snd backend, this is just about loading the dynamic library if needed, and/or check snd engine is available, and connect to it. It does not perform initialization.

> Return value: snd backend.

— Function: void lw6snd_destroy_backend (lw6snd_backend_t * backend)

> backend: snd backend to destroy

> Frees the ressources associated to a snd, which must have been properly uninitialized before.

> Return value: none.

— Function: int lw6snd_test (int mode)

> mode: 0 for check only, 1 for full test

> Runs the `snd` module test suite. If run in check mode (0), won't really perform the test, since it could fail because of hardware problems, context, permissions...

> Return value: 1 if test is successfull, 0 on error.