Next: libdyn, Previous: libdef, Up: C API

### 5.16 libdsp

#### 5.16.1 Overview

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

#### 5.16.2 API

— Function: lw6dsp_backend_t * lw6dsp_create_backend (int argc, char * [] argv, char * gfx_backend_name)

> argc: argc as passed to `main`

> argv: argv as passed to `main`

> gfx_backend_name: the id/name of the gfx backend to use

> Creates a dsp_backend object. The created object won't be displaying things until `lw6dsp_init` is called. No thread is created, but the graphics backend is loaded into memory. If video mode is not available, it will appear later, when trying to start displaying things, this function only allocates memory and checks code is available in case of a dynamically loaded gfx backend.

> Return value: a newly allocated object.

— Function: void lw6dsp_destroy_backend (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the dsp_backend object to free

> Frees all ressources used by a dsp_backend object. Note that you must call this on a inactive 'stopped' dsp_backend object.

> Return value: none.

— Function: char * lw6dsp_repr (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the object to represent

> Gives a short human-readable description of the object.

> Return value: a newly allocated string, must be freed.

— Function: int lw6dsp_init (lw6dsp_backend_t * dsp_backend, lw6dsp_param_t * param, lw6gui_resize_callback_func_t resize_callback)

> dsp_backend: the dsp_backend to start

> param: parameters to pass to the display funcs

> resize_callback: a function which will be called when there's a resize event

> Starts a dsp_backend object, that is, fire a separate thread and start rendering. This will set up a video mode, so it's very likely to fail if for some reason the video context isn't right, for instance if you try to set up graphical stuff but only have console access.

> Return value: 1 if success, 0 if error.

— Function: void lw6dsp_quit (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the dsp_backend to stop

> Stops a dsp_backend, that is, cancel rendering and unset the video mode, hardware shouldn't be used any more after this call.

> Return value: none.

— Function: int lw6dsp_update (lw6dsp_backend_t * dsp_backend, lw6dsp_param_t * param)

> dsp_backend: the dsp_backend to update

> param: parameters to pass to the dsp_backend funcs

> Passes a new set of parameters to the display function. This is in fact the only way to pass informations to the dsp_backend object once it's been started. This function will acquire a mutex, copy parameters, then give control back to the main thread while display keeps on going with new parameters in the background. It will get input informations. You really must call it often otherwise the screen won't get updated, or, at least, it will always display the same informations. It should be reasonnable to call this 10 or 20 times per second, the display itself can be faster, run at 60 or 100 fps to show smooth animation (eye candy).

> Return value: 1 if success, 0 if error.

— Function: int lw6dsp_get_nb_frames (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the dsp_backend to query

> Returns the number of frames displayed since the display was started.

> Return value: the number of frames displayed.

— Function: int lw6dsp_get_last_frame_rendering_time (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the dsp_backend to query

> Returns the rendering time of the last frame. Gives clues about performance.

> Return value: the number of milliseconds it took to draw screen

— Function: int lw6dsp_get_instant_fps (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the dsp_backend to query

> Returns the current frames per sec display rate. This is the instant value, it changes very often even if display seems smooth.

> Return value: the current instant display rate.

— Function: int lw6dsp_get_average_fps (lw6dsp_backend_t * dsp_backend)

> dsp_backend: the dsp_backend to query

> Returns the current frames per sec display rate. This is not absolutely accurate but fits for displaying info to the player, it's an average.

> Return value: the current averaged display rate.

— Function: int lw6dsp_get_video_mode (lw6dsp_backend_t * dsp_backend, lw6gui_video_mode_t * video_mode)

> dsp_backend: the dsp_backend to query

> video_mode: a structure which will contain the results

> Returns the current video mode, the one obtained by the driver. This function is also a way to know wether display is running correcly or not, by testing its return value.

> Return value: 1 if ok, 0 if failure (mode not set)

— Function: int lw6dsp_get_fullscreen_modes (lw6dsp_backend_t * dsp_backend, lw6gui_fullscreen_modes_t * fullscreen_modes)

> dsp_backend: the dsp_backend to query

> fullscreen_modes: a structure which will contain the results

> Returns the current available fullscreen modes. Note that this one will only work if display is started, unlike `lw6gfx_get_fullscreen_modes` which is used internally. The reason is that in this dsp module context, we need the thread to be launched, and the thread does start/stop display on its own.

> Return value: 1 if ok, 0 if failure (mode not set)

— Function: void lw6dsp_param_zero (lw6dsp_param_t * param)

> param: the structure to initialize

> Fills a display param struct with zeros, this is mandatory before any use. Think of it as a raw memset.

> Return value: none.

— Function: int lw6dsp_test (int mode)

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

> Runs the test suite for the dsp module. In check (0) mode, won't test much to avoid failure because of missing graphical environment.

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