Next: mod-csound, Previous: libsim, Up: C API [Contents][Index]

### 5.40 libsnd

#### 5.40.1 Overview

View lcov test coverage results on http://www.ufoot.org/liquidwar/v6/doc/coverage/src/lib/snd/index.html.

#### 5.40.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 (const 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, const 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, const char * [] argv, const 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_register (int mode)

  mode: test mode (bitmask)

  Registers all tests for the libsnd module.

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

Function: int lw6snd_test_run (int mode)

  mode: test mode (bitmask)

  Runs the `snd` module test suite, testing most (if not all...) functions.

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

Struct: lw6snd_backend_s

  The snd backend is the first argument passed to any snd function, it contains reference to all the functions which can be used as well as a pointer on associated data. In OO, this would just be an object, with members and methods, using polymorphism through opaque pointers.

Member of lw6snd_backend_s: dl_handle

  Type: `lw6dyn_dl_handle_t *`

  Definition: `lw6dyn_dl_handle_t* lw6snd_backend_s::dl_handle`

  Handle on dynamic library (if it makes sense).

Member of lw6snd_backend_s: snd_context

  Type: `void *`

  Definition: `void* lw6snd_backend_s::snd_context`

  Snd specific data, what is behind this pointer really depends on the snd engine.

Member of lw6snd_backend_s: argc

  Type: `int`

  Definition: `int lw6snd_backend_s::argc`

  The argc value passed to main.

Member of lw6snd_backend_s: argv

  Type: `const char **`

  Definition: `const char** lw6snd_backend_s::argv`

  The argv value passed to main.

Member of lw6snd_backend_s: id

  Type: `u_int32_t`

  Definition: `u_int32_t lw6snd_backend_s::id`

  The id of the object, this is non-zero and unique within one run session, incremented at each object creation.

Member of lw6snd_backend_s: play_fx

  Type: `int(*`

  Definition: `int(* lw6snd_backend_s::play_fx)(void *snd_context, int fx_id)`

  Pointer on lw6snd_play_fx callback code.

Member of lw6snd_backend_s: is_music_file

  Type: `int(*`

  Definition: `int(* lw6snd_backend_s::is_music_file)(void *snd_context, char *music_file)`

  Pointer on lw6snd_is_music_file callback code.

Member of lw6snd_backend_s: play_music_file

  Type: `int(*`

  Definition: `int(* lw6snd_backend_s::play_music_file)(void *snd_context, char *music_file)`

  Pointer on lw6snd_play_music_file callback code.

Member of lw6snd_backend_s: play_music_random

  Type: `int(*`

  Definition: `int(* lw6snd_backend_s::play_music_random)(void *snd_context, char *music_path, char *music_filter, char *music_exclude)`

  Pointer on lw6snd_play_music_randomcallback code.

Member of lw6snd_backend_s: stop_music

  Type: `void(*`

  Definition: `void(* lw6snd_backend_s::stop_music)(void *snd_context)`

  Pointer on lw6snd_stop_music callback code.

Member of lw6snd_backend_s: init

  Type: `void *(*`

  Definition: `void*(* lw6snd_backend_s::init)(int argc, const char *argv[], float fx_volume, float water_volume, float music_volume)`

  Pointer on lw6snd_init callback code.

Member of lw6snd_backend_s: set_fx_volume

  Type: `void(*`

  Definition: `void(* lw6snd_backend_s::set_fx_volume)(void *snd_context, float volume)`

  Pointer on lw6snd_set_fx_volume callback code.

Member of lw6snd_backend_s: set_water_volume

  Type: `void(*`

  Definition: `void(* lw6snd_backend_s::set_water_volume)(void *snd_context, float volume)`

  Pointer on lw6snd_set_water_volume callback code.

Member of lw6snd_backend_s: set_music_volume

  Type: `void(*`

  Definition: `void(* lw6snd_backend_s::set_music_volume)(void *snd_context, float volume)`

  Pointer on lw6snd_set_music_volume callback code.

Member of lw6snd_backend_s: poll

  Type: `void(*`

  Definition: `void(* lw6snd_backend_s::poll)(void *snd_context)`

  Pointer on lw6snd_poll callback code.

Member of lw6snd_backend_s: quit

  Type: `void(*`

  Definition: `void(* lw6snd_backend_s::quit)(void *snd_context)`

  Pointer on lw6snd_quit callback code.

Member of lw6snd_backend_s: repr

  Type: `char *(*`

  Definition: `char*(* lw6snd_backend_s::repr)(void *snd_context, u_int32_t id)`

  Pointer on lw6snd_repr callback code.

Next: mod-csound, Previous: libsim, Up: C API [Contents][Index]