Next: , Previous: , Up: C API   [Contents][Index]


5.16 libdsp

5.16.1 Overview

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

5.16.2 API

Function: lw6dsp_backend_t * lw6dsp_create_backend (lw6sys_context_t * sys_context, int argc, const char * [] argv, const char * gfx_backend_name)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6dsp_backend_t * dsp_backend)

sys_context: global system context

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 (lw6sys_context_t * sys_context, const lw6dsp_backend_t * dsp_backend)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6dsp_backend_t * dsp_backend, const lw6dsp_param_t * param, lw6gui_resize_callback_func_t resize_callback)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6dsp_backend_t * dsp_backend)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6dsp_backend_t * dsp_backend, const lw6dsp_param_t * param)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6dsp_backend_t * dsp_backend)

sys_context: global system context

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 (lw6sys_context_t * sys_context, 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 (lw6sys_context_t * sys_context, lw6dsp_backend_t * dsp_backend)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6dsp_backend_t * dsp_backend)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6dsp_backend_t * dsp_backend, lw6gui_video_mode_t * video_mode)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6dsp_backend_t * dsp_backend, lw6gui_fullscreen_modes_t * fullscreen_modes)

sys_context: global system context

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 (lw6sys_context_t * sys_context, lw6dsp_param_t * param)

sys_context: global system context

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_register (lw6sys_context_t * sys_context, int mode)

sys_context: global system context

mode: test mode (bitmask)

Registers all tests for the libdsp module.

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

Function: int lw6dsp_test_run (lw6sys_context_t * sys_context, int mode)

sys_context: global system context

mode: test mode (bitmask)

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

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

Struct: lw6dsp_backend_s

The dsp backend is the first argument passed to any dsp 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 lw6dsp_backend_s: id

Type: u_int32_t

Definition: u_int32_t lw6dsp_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 lw6dsp_backend_s: thread

Type: lw6sys_thread_handler_t *

Definition: lw6sys_thread_handler_t* lw6dsp_backend_s::thread

Thread running the display code. In fact running in a separate thread is the whole point of this display object.

Member of lw6dsp_backend_s: data

Type: void *

Definition: void* lw6dsp_backend_s::data

Data used by the display code. This is an opaque pointer, the internal structure will store details such as mutexes, parameters, information about the graphics backend, and so on.

Member of lw6dsp_backend_s: input

Type: lw6gui_input_t *

Definition: lw6gui_input_t* lw6dsp_backend_s::input

Input structure, will be updated by the display thread, so that it contains up-to-date information. This is actually the only way to get input from the user.

Struct: lw6dsp_misc_s

Miscellaneous parameters for display. One of the idea with this structure is that one must be able to compare two of them with a simple memcmp. Even the progress pointer can be compared this way, the rest is just plain data.

Member of lw6dsp_misc_s: mask

Type: int

Definition: int lw6dsp_misc_s::mask

Display mask, define what must be displayed.

Member of lw6dsp_misc_s: target_fps

Type: int

Definition: int lw6dsp_misc_s::target_fps

How many frames per second the engine needs to display.

Member of lw6dsp_misc_s: gfx_cpu_usage

Type: float

Definition: float lw6dsp_misc_s::gfx_cpu_usage

How much CPU need be used, the maximum is 1.0f, the idea behind this parameter is that if you set it to a low value, the display thread will yield timeslices letting other threads speed up. On a single-core CPU this can be usefull if the main calculation thread, the one that updates the game state, is falling behind.

Member of lw6dsp_misc_s: dirty_read

Type: int

Definition: int lw6dsp_misc_s::dirty_read

Dirty read mode.

Member of lw6dsp_misc_s: capture

Type: int

Definition: int lw6dsp_misc_s::capture

Wether we want to capture screen and dump it on disk.

Member of lw6dsp_misc_s: gfx_debug

Type: int

Definition: int lw6dsp_misc_s::gfx_debug

Wether to enable GFX debug mode.

Member of lw6dsp_misc_s: debug_team_id

Type: int

Definition: int lw6dsp_misc_s::debug_team_id

Parameter for debug mode, team ID to show info about.

Member of lw6dsp_misc_s: debug_layer_id

Type: int

Definition: int lw6dsp_misc_s::debug_layer_id

Parameter for debug mode, layer ID to show info about.

Member of lw6dsp_misc_s: repeat_settings

Type: lw6gui_repeat_settings_t

Definition: lw6gui_repeat_settings_t lw6dsp_misc_s::repeat_settings

Repeat settings, used by the input module.

Member of lw6dsp_misc_s: log_timeout

Type: int

Definition: int lw6dsp_misc_s::log_timeout

Delay after which messages disappear, in milliseconds.

Member of lw6dsp_misc_s: progress

Type: float *

Definition: volatile float* lw6dsp_misc_s::progress

Pointer on progress float, provides feedback to user.

Struct: lw6dsp_param_s

Parameters used by the display thread. Be carefull, those need be modify with adequate functions, else a (serious) race condition could occur.

Member of lw6dsp_param_s: misc

Type: lw6dsp_misc_t

Definition: lw6dsp_misc_t lw6dsp_param_s::misc

Miscellaneous parameters, things that didn’t fit elsewhere.

Member of lw6dsp_param_s: video_mode

Type: lw6gui_video_mode_t

Definition: lw6gui_video_mode_t lw6dsp_param_s::video_mode

Video mode. This is separated from the misc parameters for it requires special handling, indeed changing resolution might need calls to special functions to set up a new graphical context.

Member of lw6dsp_param_s: look

Type: lw6gui_look_t *

Definition: lw6gui_look_t* lw6dsp_param_s::look

Visual parameters.

Member of lw6dsp_param_s: menu

Type: lw6gui_menu_t *

Definition: lw6gui_menu_t* lw6dsp_param_s::menu

Menu object, the main interface to gather and transmit informations to the user, when not playing.

Member of lw6dsp_param_s: level

Type: lw6map_level_t *

Definition: lw6map_level_t* lw6dsp_param_s::level

The level, as loaded from disk.

Member of lw6dsp_param_s: game_struct

Type: lw6ker_game_struct_t *

Definition: lw6ker_game_struct_t* lw6dsp_param_s::game_struct

The game struct, that is the level post-processed to be usable by game algorithms.

Member of lw6dsp_param_s: game_state

Type: lw6ker_game_state_t *

Definition: lw6ker_game_state_t* lw6dsp_param_s::game_state

Changeable state of the game. Not that this pointer must really always be available, you can technically change its value but any value passed to it must be available and valid as long as the display is running, else you end up with a good old segfault.

Member of lw6dsp_param_s: pilot

Type: lw6pil_pilot_t *

Definition: lw6pil_pilot_t* lw6dsp_param_s::pilot

If in dirty-read mode, then game_state will be fetched from this object. It can be NULL if you don’t want to use the pilot.


Next: , Previous: , Up: C API   [Contents][Index]