libliquidwar6 - Liquid War 6
Description: Liquid War 6

Next: libbot, Up: C API

### 5.1 libliquidwar6

#### 5.1.1 Overview

View lcov test coverage results on http://www.ufoot.org/liquidwar/v6/doc/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: void lw6_set_ret (int ret)

> ret: return value to set, 1 for success, 0 for failure

> Sets the ret value for the script.

> Return value: none

— Function: int lw6_get_ret ()

> Get the ret value for the script.

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

— Function: int lw6_fix_env (int argc, const 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_bot ()

> Register the functions of the bot module, make them callable from Guile.

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

— 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_register_funcs_cfg ()

> Register the functions of the cfg module, make them callable from Guile.

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

— Function: int lw6_register_funcs_cli ()

> Register the functions of the cli module, make them callable from Guile.

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

— Function: int lw6_register_funcs_cns ()

> Register the functions of the cns module, make them callable from Guile.

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

— Function: int lw6_register_funcs_dsp ()

> Register the functions of the dsp module, make them callable from Guile.

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

— Function: int lw6_register_funcs_gen ()

> Register the functions of the gen module, make them callable from Guile.

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

— Function: int lw6_register_funcs_gfx ()

> Register the functions of the gfx module, make them callable from Guile.

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

— Function: int lw6_register_funcs_gui ()

> Register the functions of the gui module, make them callable from Guile.

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

— Function: int lw6_register_funcs_hlp ()

> Register the functions of the hlp module, make them callable from Guile.

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

— Function: int lw6_register_funcs_img ()

> Register the functions of the img module, make them callable from Guile.

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

— Function: int lw6_register_funcs_ker ()

> Register the functions of the ker module, make them callable from Guile.

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

— Function: int lw6_register_funcs_ldr ()

> Register the functions of the ldr module, make them callable from Guile.

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

— Function: int lw6_register_funcs_map ()

> Register the functions of the map module, make them callable from Guile.

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

— Function: int lw6_register_funcs_net ()

> Register the functions of the net module, make them callable from Guile.

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

— Function: int lw6_register_funcs_p2p ()

> Register the functions of the p2p module, make them callable from Guile.

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

— Function: int lw6_register_funcs_pil ()

> Register the functions of the pil module, make them callable from Guile.

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

— Function: int lw6_register_funcs_snd ()

> Register the functions of the snd module, make them callable from Guile.

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

— Function: int lw6_register_funcs_srv ()

> Register the functions of the srv module, make them callable from Guile.

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

— Function: int lw6_register_funcs_sys ()

> Register the functions of the sys module, make them callable from Guile.

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

— Function: int lw6_register_funcs_tsk ()

> Register the functions of the tsk module, make them callable from Guile.

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

— Function: int lw6_init_global (int argc, const 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 ()

> 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). Important note: this function can only be called once in a program, usually at the end. If called twice, and typically, if *any* Guile code is run after it, the risk is that Guile code does not find objects that it should, or said differently, Guile might try to manipulate stuff that has been deleted without its being warned about it. In practice, libGC way of doing thing is usually a good thing, since it will from time to time keep objects in memory that shouldn't, so there's no point in changing that, but as we are pedantic in LW6 about the fact that everything at program exit must be perfectly freed, the problem arises. So well, only call this once at the end, else problem will show up, the usual form is a segfault on the delete callback, as when Guile finally runs its GC, the object does not exist any more.

> Return value: none.

— Function: int lw6_main (int argc, const 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, const 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: 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: SCM lw6_make_scm_jpeg (lw6img_jpeg_t * c_jpeg)

> c_jpeg: the database object

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

> Return value: the SCM object

— Function: lw6img_jpeg_t * lw6_scm_to_jpeg (SCM jpeg)

> jpeg: the jpeg to convert (SCM object)

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

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

— Function: void lw6_free_jpeg_smob (lw6_jpeg_smob_t * jpeg_smob)

> jpeg_smob: the smob to free

> Frees a jpeg 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_register (int mode)

> mode: test mode (bitmask)

> Registers all tests for the lw6 module.

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

— Function: int lw6_test_run (int mode)

> mode: test mode (bitmask)

> 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.