Next: libbot, Up: C API

### 5.1 libliquidwar6

#### 5.1.1 Overview

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

#### 5.1.2 API

— Function: void lw6_resize_callback (lw6gui_video_mode_t * video_mode)

> video_mode: the new video mode

> This callback is here because gfx needs to update the config when the screen is resized. But... we did not want to make gfx depend on cfg "directly". It's cleaner to pass parameters with Scheme, in the long run, it should make things easier. So this callback is the solution. Another side effect is that this way there's a tangible obvious trace of this updating of config status by the gfx module. Seeing it sticking out like a thumb isn't a bad thing.

> Return value: none

— Function: void lw6_release ()

> Functions which will call `quit`(), `free`(), `destroy`() on whatever smob object that has threads and/or requires hardware ressources. This is to be called before the Guile interpreter ends. This is because when it garbage collects objects at the end of the program, it has no idea of what order to use when freeing objects. So if an object which uses another one in a thread is freed after the other is freed, you get a (rather unexplainabled if not warned) segfault.

> Return value: none

— Function: void lw6_exit ()

> Sends a quit message and displays a newline.

> Return value: none

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

> argc: number of args as passed to main argv: array of strings as passed to main

> Fixes environment variables (path related) so that program can find its requirements. This must be called early in the program flow (else other calls might fail).

> Return value: 1 if success, 0 if failure

— Function: int lw6_register_funcs ()

> Register all the functions, make them callable from Guile. This is a very simple yet long and very usefull function, without it Guile has no knowledge of what LW6 is.

> Return value: 1 on success, 0 if failed.

— Function: extern void lw6_cns_handler (char * c_line)

> c_line: the line typed by the user

> This function will be called every time a message is typed on the console. It runs the given line in the current Guile environment.

> Return value: none

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

> argc: number of args as passed to main argv: array of strings as passed to main

> Initializes global values to their defaults.

> Return value: 1 on success, 0 if failed

— Function: void lw6_quit_global ()

> argc: number of args as passed to main argv: array of strings as passed to main

> Frees global values. Will also garbage collect objects in case Guile failed to do it perfectly (or we failed to tell Guile how to do it).

> Return value: none.

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

> argc: the argc parameter of the `main`() function, that is, the number of command-line args.

> argv: the argv parameter of the `main`() function, that is, an array containing pointers on command-line args.

> This function is directly called by `main`(). This means by linking against libliquidwar6 and calling it, you would have a program that is almost exactly the "official" upstream liquidwar6 binary, except you can tweak it and have all the power to call whatever other functions you like, embed it. In short, everything the binary does, you can do it in your own binarn, by linking against the library and calling this function.

> Return value: 1 if success, zero if failure. Note that this is the "standard" C / liquidwar6 way to proceed, but your `main`() function should return 0 if success, else an error code. Typical use is "return !lw6_main(argc, argv);".

— Function: int lw6_process_non_run_options (int argc, char * [] argv, int * run_game)

> argc: the number of command-line args, as passed to `main()`

> argv: an array of strings containing command-line args, as passed to `main()`

> run_game: a pointer to a boolean which will contain true (1) if the game must be launched, or false (0) if the option is such that game must be skipped. Example: –copyright, –help, ...

> Return value: non-zero if success, 0 if error. The error can be, for instance, the test suite returning "no, tests were not OK".

— Function: void lw6_print_help ()

> Displays a short help message.

> Return value: none

— Function: void lw6_print_version ()

> Displays the version of the game.

> Return value: none

— Function: void lw6_print_short_copyright ()

> Displays the copyright of the game (short version).

> Return value: none

— Function: void lw6_print_long_copyright ()

> Displays the copyright of the game (long version).

> Return value: none

— Function: void lw6_print_bench (float bench_result)

> Displays the program bench value.

> Return value: none

— Function: void lw6_print_pedigree ()

> Displays the program pedigree, think of this as version on steroids.

> Return value: none

— Function: void lw6_print_host ()

> Displays the host on which the program was compiled.

> Return value: none

— Function: void lw6_print_audit (int argc, char * [] argv)

> Displays various paths used by the game.

> Return value: none

— Function: void lw6_print_modules ()

> Displays the list of modules compiled with the game.

> Return value: none

— Function: void lw6_print_list_quick ()

> Displays the list of 'quick' options.

> Return value: none

— Function: void lw6_print_list_doc ()

> Displays the list of 'doc' options.

> Return value: none

— Function: void lw6_print_list_show ()

> Displays the list of 'show' options.

> Return value: none

— Function: void lw6_print_list_path ()

> Displays the list of 'path' options.

> Return value: none

— Function: void lw6_print_list_players ()

> Displays the list of 'players' options.

> Return value: none

— Function: void lw6_print_list_input ()

> Displays the list of 'input' options.

> Return value: none

— Function: void lw6_print_list_graphics ()

> Displays the list of 'graphics' options.

> Return value: none

— Function: void lw6_print_list_sound ()

> Displays the list of 'sound' options.

> Return value: none

— Function: void lw6_print_list_network ()

> Displays the list of 'network' options.

> Return value: none

— Function: void lw6_print_list_map ()

> Displays the list of 'map' options.

> Return value: none

— Function: void lw6_print_list_map_rules ()

> Displays the list of 'map rules' options.

> Return value: none

— Function: void lw6_print_list_map_hints ()

> Displays the list of 'map hints' options.

> Return value: none

— Function: void lw6_print_list_map_style ()

> Displays the list of 'amp style' options.

> Return value: none

— Function: void lw6_print_list_funcs ()

> Displays the list of 'funcs'.

> Return value: none

— Function: void lw6_print_list_hooks ()

> Displays the list of 'hooks'.

> Return value: none

— Function: void lw6_print_list_advanced ()

> Displays the list of 'advanced' options.

> Return value: none

— Function: void lw6_print_list_aliases ()

> Displays the list of options aliases.

> Return value: none

— Function: void lw6_print_list ()

> Displays the list of all known options.

> Return value: none

— Function: void lw6_print_about (char * keyword)

> Displays the about message for a keyword.

> Return value: none

— Function: void lw6_print_hello (int argc, char * [] argv)

> Displays 'hello' at the beginning of the program.

> Return value: none

— Function: void lw6_print_goodbye ()

> Displays 'goodbye', typically use at end of program to know it's over and everything went fine.

> Return value: none

— Function: SCM lw6_make_scm_dsp (lw6dsp_backend_t * c_dsp)

> c_dsp: the display object

> Creates an SCM 'dsp' object from C data.

> Return value: the SCM object

— Function: lw6dsp_backend_t * lw6_scm_to_dsp (SCM dsp)

> dsp: the dsp to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'dsp' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_dsp_smob (lw6_dsp_smob_t * dsp_smob)

> dsp_smob: the smob to free

> Frees a dsp smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_snd (lw6snd_backend_t * c_snd)

> c_snd: the sound object

> Creates an SCM 'snd' object from C data.

> Return value: the SCM object

— Function: lw6snd_backend_t * lw6_scm_to_snd (SCM snd)

> snd: the snd to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'snd' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_snd_smob (lw6_snd_smob_t * snd_smob)

> snd_smob: the smob to free

> Frees a snd smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_map (lw6map_level_t * c_map)

> c_map: the map object

> Creates an SCM 'map' object from C data.

> Return value: the SCM object

— Function: lw6map_level_t * lw6_scm_to_map (SCM map)

> map: the map to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'map' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_map_smob (lw6_map_smob_t * map_smob)

> map_smob: the smob to free

> Frees a map smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_menu (lw6gui_menu_t * c_menu)

> c_menu: the menu object

> Creates an SCM 'menu' object from C data.

> Return value: the SCM object

— Function: lw6gui_menu_t * lw6_scm_to_menu (SCM menu)

> menu: the menu to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'menu' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_menu_smob (lw6_menu_smob_t * menu_smob)

> menu_smob: the smob to free

> Frees a menu smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_game_struct (lw6ker_game_struct_t * c_game_struct, SCM map)

> c_game_struct: the game struct object

> map: the map (SCM object) referenced

> Creates an SCM 'game-struct' object from C data. Passing the map object enables the garbage collector not to free the map until the game struct is freed.

> Return value: the SCM object

— Function: lw6ker_game_struct_t * lw6_scm_to_game_struct (SCM game_struct)

> game_struct: the game_struct to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'game_struct' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_game_struct_smob (lw6_game_struct_smob_t * game_struct_smob)

> game_struct_smob: the smob to free

> Frees a game_struct smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_game_state (lw6ker_game_state_t * c_game_state, SCM game_struct)

> c_game_state: the game state object

> game_struct: the game struct (SCM object) referenced

> Creates an SCM 'game_state' object from C data. Passing game_struct enables the garbage collector not to free the game_struct until the game_state is freed.

> Return value: the SCM object

— Function: lw6ker_game_state_t * lw6_scm_to_game_state (SCM game_state)

> game_state: the game_state to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'game_state' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_game_state_smob (lw6_game_state_smob_t * game_state_smob)

> game_state_smob: the smob to free

> Frees a game_state smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_pilot (lw6pil_pilot_t * c_pilot)

> c_pilot: the pilot object

> Creates an SCM 'pilot' object from C data.

> Return value: the SCM object

— Function: lw6pil_pilot_t * lw6_scm_to_pilot (SCM pilot)

> pilot: the pilot to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'pilot' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_pilot_smob (lw6_pilot_smob_t * pilot_smob)

> pilot_smob: the smob to free

> Frees a pilot smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_bot (lw6bot_backend_t * c_bot, SCM game_state, SCM pilot)

> c_bot: the bot object

> game_state: the game state

> pilot: the pilot

> Creates an SCM 'bot' object from C data. Passing game_state and pilot enables the garbage collector not the free them until bot is freed.

> Return value: the SCM object

— Function: lw6bot_backend_t * lw6_scm_to_bot (SCM bot)

> bot: the bot to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'bot' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_bot_smob (lw6_bot_smob_t * bot_smob)

> bot_smob: the smob to free

> Frees a bot smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_look (lw6gui_look_t * c_look)

> c_look: the look object

> Creates an SCM 'look' object from C data.

> Return value: the SCM object

— Function: lw6gui_look_t * lw6_scm_to_look (SCM look)

> look: the look to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'look' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_look_smob (lw6_look_smob_t * look_smob)

> look_smob: the smob to free

> Frees a look smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_loader (lw6tsk_loader_t * c_loader)

> c_loader: the loader object

> Creates an SCM 'loader' object from C data.

> Return value: the SCM object

— Function: lw6tsk_loader_t * lw6_scm_to_loader (SCM loader)

> loader: the loader to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'loader' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_loader_smob (lw6_loader_smob_t * loader_smob)

> loader_smob: the smob to free

> Frees a loader smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_db (lw6p2p_db_t * c_db)

> c_db: the database object

> Creates an SCM 'db' object from C data.

> Return value: the SCM object

— Function: lw6p2p_db_t * lw6_scm_to_db (SCM db)

> db: the db to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'db' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_db_smob (lw6_db_smob_t * db_smob)

> db_smob: the smob to free

> Frees a db smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: SCM lw6_make_scm_node (lw6p2p_node_t * c_node, SCM db)

> c_node: the node object

> db: the db (SCM object) referenced

> Creates an SCM 'node' object from C data. Passing db enables the garbage collector not to free db until node is freed.

> Return value: the SCM object

— Function: lw6p2p_node_t * lw6_scm_to_node (SCM node)

> node: the node to convert (SCM object)

> Gets the internal C pointer corresponding to the scheme 'node' object.

> Return value: a pointer, *not* a copy, must not be freed

— Function: void lw6_free_node_smob (lw6_node_smob_t * node_smob)

> node_smob: the smob to free

> Frees a node smob, we need a special function to do that as structures like assoc hold pointers to these objects and therefore need a proper callback when being destroyed.

> Return value: none

— Function: int lw6_register_smobs ()

> Register all smobs to Guile.

> Return value: 1 on success, 0 if failed.

— Function: int lw6_test (int mode)

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

> Runs the liquidwar6 core module test suite, this will mostly test how Guile script integration works, loading a sample script and running it. It does not launch all the other sub modules tests.

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