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

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

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