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


5.19 libgfx

5.19.1 Overview

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

5.19.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 (const 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, const lw6gui_look_t * look, const lw6map_level_t * level, const lw6ker_game_struct_t * game_struct, const lw6ker_game_state_t * game_state, lw6pil_local_cursors_t * local_cursors, lw6gui_menu_t * menu, float progress, float fps, float mps, const 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, const 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, const char * [] argv, const 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_register (int mode)

mode: test mode (bitmask)

Registers all tests for the libgfx module.

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

Function: int lw6gfx_test_run (int mode)

mode: test mode (bitmask)

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

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

Struct: lw6gfx_backend_s

The gfx backend is the first argument passed to any gfx 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 lw6gfx_backend_s: dl_handle

Type: lw6dyn_dl_handle_t *

Definition: lw6dyn_dl_handle_t* lw6gfx_backend_s::dl_handle

Handle on dynamic library (if it makes sense).

Member of lw6gfx_backend_s: gfx_context

Type: void *

Definition: void* lw6gfx_backend_s::gfx_context

Gfx specific data, what is behind this pointer really depends on the gfx engine.

Member of lw6gfx_backend_s: argc

Type: int

Definition: int lw6gfx_backend_s::argc

The argc value passed to main.

Member of lw6gfx_backend_s: argv

Type: const char **

Definition: const char** lw6gfx_backend_s::argv

The argv value passed to main.

Member of lw6gfx_backend_s: id

Type: u_int32_t

Definition: u_int32_t lw6gfx_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 lw6gfx_backend_s: init

Type: void *(*

Definition: void*(* lw6gfx_backend_s::init)(int argc, const char *argv[], lw6gui_video_mode_t *video_mode, lw6gui_resize_callback_func_t resize_callback)

Pointer on lw6gfx_init callback code.

Member of lw6gfx_backend_s: quit

Type: void(*

Definition: void(* lw6gfx_backend_s::quit)(void *gfx_context)

Pointer on lw6gfx_quit callback code.

Member of lw6gfx_backend_s: repr

Type: char *(*

Definition: char*(* lw6gfx_backend_s::repr)(void *gfx_context, u_int32_t id)

Pointer on lw6gfx_repr callback code.

Member of lw6gfx_backend_s: set_video_mode

Type: int(*

Definition: int(* lw6gfx_backend_s::set_video_mode)(void *gfx_context, lw6gui_video_mode_t *video_mode)

Pointer on lw6gfx_set_video_mode callback code.

Member of lw6gfx_backend_s: get_video_mode

Type: int(*

Definition: int(* lw6gfx_backend_s::get_video_mode)(void *gfx_context, lw6gui_video_mode_t *video_mode)

Pointer on lw6gfx_get_video_mode callback code.

Member of lw6gfx_backend_s: get_fullscreen_modes

Type: int(*

Definition: int(* lw6gfx_backend_s::get_fullscreen_modes)(void *gfx_context, lw6gui_fullscreen_modes_t *modes)

Pointer on lw6gfx_get_fullscreen_modes callback code.

Member of lw6gfx_backend_s: pump_events

Type: lw6gui_input_t *(*

Definition: lw6gui_input_t*(* lw6gfx_backend_s::pump_events)(void *gfx_context)

Pointer on lw6gfx_pump_events code.

Member of lw6gfx_backend_s: display

Type: int(*

Definition: int(* lw6gfx_backend_s::display)(void *gfx_context, int mask, const lw6gui_look_t *look, const lw6map_level_t *level, const lw6ker_game_struct_t *game_struct, const lw6ker_game_state_t *game_state, lw6pil_local_cursors_t *local_cursors, lw6gui_menu_t *menu, float progress, float fps, float mps, const char **log_list, int capture, int gfx_debug, int debug_team_id, int debug_layer_id)

Pointer on lw6gfx_display code.


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