Next: mod-gl, Previous: libdyn, Up: C API

### 5.18 libgfx

#### 5.18.1 Overview

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

#### 5.18.2 API

— Function: int lw6gfx_init (lw6gfx_backend_t * backend, lw6gui_video_mode_t * video_mode, lw6gui_resize_callback_func_t resize_callback)

> backend: the graphical backend to use

> video_mode: the video mode to use at start up

> resize_callback: a callback function which will be called at each resize event

> Sets up the graphical backend for good, initializing a video mode and allocating ressources. 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 lw6gfx_quit (lw6gfx_backend_t * backend)

> backend: the backend to quit

> Uninitializes the backend, that is, exits the graphical mode. All threads that use graphics must be closed when this is called.

> Return value: none.

— Function: char * lw6gfx_repr (lw6gfx_backend_t * backend)

> backend: the backend to represent

> Returns a readable version of the backend object.

> Return value: a newly allocated pointer.

— Function: int lw6gfx_set_video_mode (lw6gfx_backend_t * backend, lw6gui_video_mode_t * video_mode)

> backend: the backend to use

> video_mode: the new video mode

> This function changes the video mode. Note that the first time you set up the graphical environment you must call `lw6gfx_init` but to change the current mode, use this function. It should reload backend data automatically if needed (textures for instance). Note that before giving up and failing this function will try alternate video modes, and you're not garanteed to have the right mode after the call, even if it returns true. To check this, use `lw6gfx_get_video_mode`.

> Return value: 1 on success, 0 on failure;

— Function: int lw6gfx_get_video_mode (lw6gfx_backend_t * backend, lw6gui_video_mode_t * video_mode)

> backend: the backend to use

> video_mode: the current video mode (will be overwritten, out parameter)

> This function returns the current video mode.

> Return value: 1 on success, 0 on failure;

— Function: int lw6gfx_get_fullscreen_modes (lw6gfx_backend_t * backend, lw6gui_fullscreen_modes_t * fullscreen_modes)

> backend: the backend to use

> fullscreen_modes: the available fullscreen modes (will be overwritten, out parameter)

> This function returns the current video mode.

> Return value: 1 on success, 0 on failure;

— Function: lw6gui_input_t * lw6gfx_pump_events (lw6gfx_backend_t * backend)

> backend: the backend to use

> This function "pumps" events, that is gets pending events, puts them in queues, maintains internal states up to date. You really must call this very often or no input will be processed at all.

> Return value: a pointer on the internal input state, musn't be freed.

— Function: int lw6gfx_display (lw6gfx_backend_t * backend, int mask, lw6gui_look_t * look, lw6map_level_t * level, lw6ker_game_struct_t * game_struct, lw6ker_game_state_t * game_state, lw6pil_local_cursors_t * local_cursors, lw6gui_menu_t * menu, float progress, float fps, float mps, char ** log_list, int capture, int gfx_debug, int debug_team_id, int debug_layer_id)

> backend: the graphical backend to use

> mask: display flag, tells what to display

> look: the look, the skin, contains display options

> level: the level to display

> game_struct: the game_struct associated with the level

> game_state: the game_state associated with the level

> local_cursors: the cursor to center the focus on

> menu: the menu to display

> progress: the value of the progress indicator

> fps: the number of frames per second to display

> mps: the number of moves per second to display

> log_list: log messages to display

> capture: wether to enable capture mode or not

> gfx_debug: wether to enable gfx debugging tools

> debug_team_id: for debug display, team to display informations about

> debug_layer_id: for debug display, layer to display

> This is the major drawing function, the one that encapsulates all others. As the program uses a separate thread to display things, we just pass this function many parameters, and let it do its job alone. So many parameters might sometimes be useless. It also allows the graphics backend decide wether menus and hud and background should interact. Or not.

> Return value: 1 on success, 0 on failure.

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

> argc: argc, as passed to `main`

> argv: argv, as passed to `main`

> List available gfx 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: lw6gfx_backend_t * lw6gfx_create_backend (int argc, char * [] argv, char * name)

> argc: argc, as passed to `main`

> argv: argv, as passed to `main`

> name: string containing gfx key, typically got from `lw6gfx_get_backends`

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

> Return value: gfx backend.

— Function: void lw6gfx_destroy_backend (lw6gfx_backend_t * backend)

> backend: gfx backend to destroy

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

> Return value: none.

— Function: int lw6gfx_test (int mode)

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

> Runs the `gfx` module test suite. In check-only mode, this function won't test many things, for it requires a graphical mode to be available to perform the complete test.

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