Previous: C to Guile API, Up: Reference
context: opaque pointer on a context
Overwrites any existing option with command line args
Return value: 1 if success, 0 if error
cfg_context: a context returned by
lw6cfg_init
Overwrites any existing vale in the config with environment variables prefixed by LW6_.
Return value: 1 if successfull, 0 if error.
key: the key of the value to format
value: the value to format
type: the type of the value to format
Formats, converts, a given value to its cannonical representation. Booleans will be converted to true/false, strings containing integers will be stripped from junk, and so on. This is a performance killer but will ensure everything is correct.
Return value: a newly allocated string, containing the same as the input, but reformatted the pedantic way.
key: the key of the value to format
value: the value to format
Formats, converts, a given value to its cannonical representation. Booleans will be converted to true/false, strings containing integers will be stripped from junk, and so on. This is a performance killer but will ensure everything is correct. This function will automatically guess the type of the value from its description in the help system.
Return value: a newly allocated string, containing the same as the input, but reformatted the pedantic way.
cfg_context: a context returned by
lw6cfg_init
filename: a file path, absolute or relative
Loads the given config file, and stores its values into the current context. Parameters which are both in the config file and given as command line parameters, will be taken from the command-line.
Return value: 1 if successfull, 0 if error.
cfg_context: a context returned by
lw6cfg_init
filename: a file path, absolute or relative
Save current options into the given config file. Before saving the file, all command line arguments will be read and will override current values. This means the saved file will contain values given as command line arguments.
Return value: 1 if successfull, 0 if error.
argc: number of command line arguments, as given to
main
argv: a list of command line arguments, as given to
main
Initializes a config context object. This object is hidden behind an opaque void * pointer to avoid direct access to its elements.
Return value: an opaque pointer, must be freed with
lw6cfg_quit
.
cfg_context: a context returned by
lw6cfg_init
Frees a config cfg_context object. You must call this once you're done with the context.
Return value: none.
argc: number of command line arguments, as given to
main
argv: a list of command line arguments, as given to
main
Overwrites the config file with defaults. Use this to get rid of old configurations.
argc: number of command-line args, as passed to
main
argv: arry of command-line args, as passed to
main
key: the key to query
Unified "value" getter, which gets informations from environment variables, command line, and config file. The rules is that the command-line argument always has the last word. It will override any other value. Follows environment variables, which will be used if no command-line argument is supplied. Note that these are "LW6_" prefixed and uppercased environment variables as opposed to lowercased and "dash-separated" keys. Finally, if there's no environment variable, nor any config-file corresponding entry, the value will be searched in the config file. If there's no information in the config file, NULL is returned.
Return value: a string with the value. Can be NULL. Must be freed.
argc: number of command-line args, as passed to
main
argv: arry of command-line args, as passed to
main
Gets the user dir, taking all parameters in account, that's to say the "LW6_USER_DIR" env value, the "–user-dir" command-line paramater and the LW6DEF_USER_DIR config file entry.
Return value: the directory path, might be NULL, must be freed.
argc: number of command-line args, as passed to
main
argv: arry of command-line args, as passed to
main
Gets the user dir, taking all parameters in account, that's to say the "LW6_LOG_FILE" env value, the "–log-file" command-line paramater and the LW6DEF_LOG_FILE config file entry.
Return value: the directory path, might be NULL, must be freed.
argc: number of command-line args, as passed to
main
argv: arry of command-line args, as passed to
main
Gets the user dir, taking all parameters in account, that's to say the "LW6_MAP_PATH" env value, the "–map-path" command-line paramater and the LW6DEF_MAP_PATH config file entry.
Return value: the directory path, might be NULL, must be freed.
Opens a .so file directly, using a valid (full) path name.
Return value: a handle to the module, once it's opened. You might still need to call a module specific
init
() function, but it's another story.
argc: the number of command-line arguments as passed to
main
top_level_lib: the top-level library concerned, this means is it "cli", "gfx", "snd" or "srv". This will tell the function to search for the .so file in the correct subdirectory. Think of this as a category.
Opens a .so file corresponding to the given backend, it is capable to search for system libraries installed after "make install" but if not found, it will also search in the current build directory, finding the .so files in hidden .libs subdirectories.
Return value: a handle to the module, once it's opened. You might still need to call a module specific
init
() function, but it's another story.
handle: the backend to close.
Closes an opened backend. Note that you must call any backend specific clear, destroy, deinit, exit, function before.
Return value: 1 if success, 0 on error.
handle: the backend concerned
func_name: the function name, as a NULL terminated string
Finds a C function in the given backend.
Return value: a pointer to the function, NULL if not found.
argc: the number of command line args, as passed to main
argv: the commind line args, as passed to main
top_level_lib: the library category to query (gfx, snd, cli, srv ...)
Returns an assoc which lists all the available modules. The key of the assoc entries in the module internal name such as 'gl' and the value associated is a NULL terminated string describing the module, for instance 'OpenGL'.
Return value: an assoc object containing key/label pairs.
argc: the number of command-line arguments as passed to
main
top_level_lib: the top-level library concerned, this means is it "cli", "gfx", "snd" or "srv". This will tell the function to search for the .so file in the correct subdirectory. Think of this as a category.
backend_name: the actual name of the backend, this is the name of the .so file, between "libmod_" and ".so". For instance, to find "libmod_gl.so", the right argument is "gl".
Get the full path to a .so file corresponding to the given backend, it is capable to search for system libraries installed after "make install" but if not found, it will also search in the current build directory, finding the .so files in hidden .libs subdirectories.
Return value: the full path of the .so file, needs to be freed.
Runs the
dyn
module test suite, testing most (if not all...) functions. Will try to load libraries and query them for standard LW6-expected functions.Return value: 1 if test is successfull, 0 on error.
title: the string to be displayed, what the user sees. Can be freed after the call is done, function will make a copy internally.
Constructs a new menu object. Note that you can always call other functions to modify it afterwards.
Return value: a pointer to the newly allocated object.
menu: a pointer to the menu.
Frees the menu, checking if things are OK before doing so.
Return value: none.
menu: a pointer to the menu.
Gets the memory occupied by the menu. Could be usefull to help a garbage collector taking decisions or reporting erros, for instance.
Return value: the number of bytes used.
menu: a pointer to the menu.
Constructs a readable description of the object. Usefull for debugging, or to introspect things using scripts, at run-time. Does not necessarly describe all the informations about the object, but helps knowing what it is.
Return value: a string describing the object, must be freed.
menu: a pointer to the menu.
title: the new title, you can free it after calling the function, an internal copy will be made.
Change the title of the menu. That is to say, its title. Use this function to change the title, don't try to access the struct directly. The idea is to have safe memory management.
Return value: none
menu: the menu we want to query
position: the order of the item we want
Gets the menu item at the given position. First item is 0, last is N-1. Returns a pointer on the real object, not a copy.
Return value: a pointer to a menu item, NULL if out of range.
menu: the menu we want to modify
position: the position of the item we want to select
now: the current time, as a timestamp.
Selects the item at the given position. Use this function to be sure that only one item is selected, and all other states are consistent. Timestamp is needed for the sake of eye-candy.
Return value: 1 if success, 0 if failure (out of range).
menu: the menu to scroll
Scrolls a menu up, used as a callback for mouse wheel up for instance. The idea is just to decrement the first displayed item index.
Return value: 1 if OK, 0 if failed (out of range).
menu: the menu to scroll
Scrolls a menu down, used as a callback for mouse wheel down for instance. The idea is just to increment the first displayed item index.
Return value: 1 if OK, 0 if failed (out of range).
menu: the menu to center
position: the position of the menuitem to be put in the center
max_displayed_items: the maximum number of items displayed
Centers the menu on a given menuitem. Typically used when pushing a menu with a menuitem selected 'anywhere' in the list.
Return value: none.
menu: the menu we want to modify
menuitem: the item to insert
position: the position the new item will occupy ("insert before" mode)
now: the current time, as a timestamp.
Inserts the given item in the menu. All items starting at the insert position will be "pushed" (that is, their position incremented by 1). Once the menuitem is inserted, the menu object will take care of memory management and automatically free it when needed.
Return value: 1 if success, 0 if failure (memory problem, out of range).
menu: the menu we want to modify
menuitem: the item to insert
now: the current time, as a timestamp.
Appends the given item to the menu. Once the menuitem is appended, the menu object will take care of memory management and automatically free it when needed.
Return value: 1 if success, 0 if failure (memory problem).
menu: the menu we want to modify
position: the item to insert
now: the current time, as a timestamp.
Removes an item from the menu. It will automatically be freed.
Return value: 1 if success, 0 if failure (out of range).
menu: the menu concerned
max_displayed_items: the maximum number of items to display at once
Updates the display range. The reason for having this is that the first item, that is, how far we scroll in a very long menu, depends on the previous position. Plus you have to handle limit cases (begin/end). Thus, this function, which will automatically pick-up a suitable position. Of course,
first_item_displayed
is not necessarly equal toselected_item
.Return value: none.
menu: the menu to work on
label: the label of the menuitem to append
value: the value of the menuitem to append
enabled: wether the inserted menuitem should be enabled
selected: wether the inserted menuitem should be selected
colored: wether the inserted menuitem should use value as its color
now: current time (timestamp)
Inserts a menu item at the given position. The idea is that the menu item object is automatically constructed on the fly, and an id is returned, which can be passed to '_using_id' menu-related functions. This is typically for using in scripts. The idea is that the script just keeps a copy of the id returned, and can this way operate directly on the menuitem without keeping a pointer, a smob or anything internally. From the C point of view, having a real C structure enables persistent data from one display to the other, and this is nice and conveninent. I acknowledge the prototype is scary.
Return value: 0 if error, or else an id which will later be used with '_using_id' functions.
menu: the menu to work on
label: the label of the menuitem to append
value: the value of the menuitem to append
enabled: wether the appended menuitem should be enabled
selected: wether the appended menuitem should be selected
colored: wether the appended menuitem should use value as its color
now: current time (timestamp)
Appends a menuitem using the same logic as
lw6gui_menu_insert_for_id_use
that is to say a parameter is returned which can later be used to directly operate on a given menuitem, without having its pointer, and even if its position changes.Return value: 0 if error, or else an id which will later be used with '_using_id' functions.
menu: the menu to work on
menuitem_id: the id of the menuitem to remove
now: current time (timestamp)
Deletes the menuitem with the given id. Very important: the id is not the position. Id are arbitrary numbers that stick to menuitems, but they are not directly linked with the position. This function is practical to use if, for some reason, you don't have the pointer on the menuitem.
Return value: 1 if success, 0 if failure (out of range).
menu: the menu to work on
menuitem_id: the id of the menuitem to synchronize
now: current time (timestamp)
Updates the menuitem with the given id. Very important: the id is not the position. Id are arbitrary numbers that stick to menuitems, but they are not directly linked with the position. This function is practical to use if, for some reason, you don't have the pointer on the menuitem. In practice, it's heavily used in the game to transmit informations from the scripts to the core C engine. Additionnaly, this function will automatically synchronize the
selected_item
field of the menu struct.Return value: 1 if success, 0 if failure (out of range).
label: the string to be displayed, what the user sees. Can be freed after the call is done, function will make a copy internally.
value: the value. No GUI function uses this, this is the "real" value associated to the item.
enabled: wether the menu item can be selected, used, and so on
selected: wether the menu item is the item selected among all menu items.
colored: wetherr the menu item must, when drawn, be colored according to its value.
Constructs a new menuitem object. Note that you can always call other functions to modify these values afterwards, this might change rendering since
lw6gui_menuitem_set_value
orlw6gui_menuitem_set_label
will, for instance, modify the "when was that item last modified" information.Return value: a pointer to the newly allocated object.
menuitem: a pointer to the menuitem.
Frees the menuitem, checking if things are OK before doing so.
Return value: none.
menuitem: a pointer to the menuitem.
Gets the memory occupied by the menuitem. Could be usefull to help a garbage collector taking decisions or reporting erros, for instance.
Return value: the number of bytes used.
menuitem: a pointer to the menuitem.
Constructs a readable description of the object. Usefull for debugging, or to introspect things using scripts, at run-time. Does not necessarly describe all the informations about the object, but helps knowing what it is.
Return value: a string describing the object, must be freed.
menuitem: a pointer to the menuitem.
label: the new label, you can free it after calling the function, an internal copy will be made.
now: the current time, as a timestamp.
Change the label of the menu item. That is to say, what the user sees. Use this function to change the menuitem value, don't try to access the struct directly. The idea is 1) to have safe memory management and 2) to keep the
last_change
member up to date. It can be later used for eye-candy effects.Return value: none
menuitem: a pointer to the menuitem.
now: the current time, as a timestamp.
Changes the value of a menuitem. This is the internal value, not what the user sees. Use this function to change the menuitem value, don't try to access the struct directly. The idea is to keep the
last_change
member up to date. It can be later used for eye-candy effects.Return value: none
menuitem: a pointer to the menuitem.
now: the current time, as a timestamp.
Switches the menuitem to selected state. Use this function, don't try to modify the struct members directly. The idea is to have the
last_select
parameter up to date. It can be later used for eye-candy effects.Return value: none
menuitem: a pointer to the menuitem.
now: the current time, as a timestamp.
Switches the menuitem to unselected state. Use this function, don't try to modify the struct members directly. The idea is to have the
last_unselect
parameter up to date. It can be later used for eye-candy effects.Return value: none
menuitem: the menuitem we want to identify
Returns a checksum which can be used to know, for instance, wether the menuitem has changed or not, and if we should redraw it.
Return value: a checksum.
closest: the closest resolution found
wished: the wished resolution
available: a list of available resolutions (list of lw6sys_whd_t *)
Finds the closest resolution available, this is just a small utility to cope with different screen shapes and avoid requesting 640x480 when it's just not available but there's a 640x400 instead.
Return value: 1 if the wished resolution exists in available list and was found, else 0 if the wished resolution doesn't exist and an approximative match was picked.
Run tests in the gui module.
Return value: 1 if successfull, 0 if failed.
keyword: the keyword we want to check out
Checks wether a given keyword is documented or not.
Return value: 1 if documented, 0 if not.
type: the type of the data associated to the keyword, will be written
keyword: the keyword we want help about
Returns the documentation string associated to a keyword. The keyword might be a command-line option, a Guile function, an XML file entry. Raises a warning if the keyword is undocumented, but never returns NULL, you can use the returned value without checking it. String is localized if a translation is available. It's safe to call this function with type being NULL.
Return value: a help string, never NULL, must not be freed. Additionnally, type will be updated.
keyword: the keyword we want the type of
Returns the type of a keyword. Calls lw6hlp_about internally.
Return value: the type, might be LW6HLP_TYPE_VOID.
keyword1: the 1st keyword
keyword2: the 2nd keyword
Checks wether a keyword matches another. Not only a string comparison, will also try and guess if the error is only about dash "-" replaced by underscode "_", for instance.
Return value: 1 if matches, 0 if different.
Returns a list of all available keywords.
Return value: a list containing all the keywords. Strings are not dynamically allocated, you can't modify them.
list: a pointer to a list of keywords f: the file to print the content to
Prints all the keywords from the list. One keyword per line.
Return value: none.
list: a pointer to a list of keywords f: the file to print the content to
Prints all the keywords from the list, with the associated keyword help, to the given file. Output is formatted to fit on the standard terminal/console.
Return value: none.
Initializes the help reference, this must be called before any call to lw6hlp_about or such help related functions.
Return value: 1 on success, 0 if failed
Un-initializes the help reference, this must be called at the end of the program.
Return value: 1 on success, 0 if failed
body: the body to read, must point to allocated memory
dirname: the directory of the map
param: map parameters
hints: map hints
ratio: wished map ratio
progress: structure to transmit loading progress
Reads the map body, that is, all the layers.
Return value: 1 if OK, 0 if failed.
style: the style structure to process.
hints: additionnal hints to know what to set automatically
Deduces all colors from background color, if needed. The function will check color_auto parameters and replace all other colors by base and alternate colors if needed. Note that the background color itself is not changed by this function. Background can only be guessed from texture.
Return value: none.
entry: the entry to free
Frees a map entry.
Return value: none.
map_path: the map_path environment config variable, delimited path list
relative_path: the relative path to use to find the map directory
Lists all maps in a given directory. Returns a list of lw6ldr_entry_t which can contain both directories with subdirs and actual maps. Maps are sorted before being returned, first directories, then maps, sorted in alphabetical order.
Return value: a list of dynamically allocated lw6ldr_entry_t.
map_path: the map_path environment config variable, delimited path list
relative_path: the relative path to use to find the map directory
recursive: if non-zero, map search will recurse in subdirs
callback_func: the function which will be called on each entry
func_data: an extra pointer to pass data to callback_func
Executes a given function on all maps in a given place, typically used in test programs.
Return value: none.
dirname: the directory of the map
Read the hints (hints.xml) of a map. Pointer to hints must be valid, and values already initialized, either zeroed or filled in with defaults or custom values.
Return value: 1 if success, 0 if failed.
hints: the hints to modify
key: the key to modify
value: the value to affect to the key, as a string
Sets one single parameter in a hints structure. Value must always be passed as a string, will be converted to the right type automatically when storing it in the structure.
Return value: 1 if success, 0 if failed. Note that while 0 really means there's a problem, some affectations can fail and return 1, needs to be worked on.
hints: the hints struct to fill with values (read/write parameter)
values: an assoc containing strings with the new values
Overrides hints with values. Pointer to hints must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. Not all parameters need be defined in values. It can even be NULL. The idea is just that if something is defined in values, it will override the existing hints.
Return value: 1 if success, 0 if failed.
param: the parameter struct to fill with values (read/write parameter)
dirname: the directory of the map
Read the parameters associated to a map. Pointer to param must be valid, and values already initialized, either zeroed or filled in with defaults or custom values.
Return value: 1 if success, 0 if failed.
param: the parameter struct to fill with values (read/write parameter)
values: an assoc containing strings with the new values
Overrides param with values. Pointer to param must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. Not all parameters need be defined in values. It can even be NULL. The idea is just that if something is defined in values, it will override the existing param.
Return value: 1 if success, 0 if failed.
f: file to output content to
Print to a file a typical map rules.xml file.
Return value: none.
f: file to output content to
Print to a file a typical map hints.xml file.
Return value: none.
f: file to output content to
Print to a file a typical map style.xml file.
Return value: none.
user_dir: the user directory or at least, a writable one
Writes all example XML files in 'user_dir/example/', will create the directory if needed.
Return value: 1 if success, 0 if failed.
dirname: the directory containing the map
default_param: default parameters, as strings
forced_param: forced parameters, as strings
display_w: the width of the display output (resolution)
display_h: the height of the display output (resolution)
progress: information used to handle the progress bar
Loads a map from dist. The default_param and forced_param can contain values corresponding to rules.xml and style.xml entries. Parameters are read in 4 steps. 1st, a default value is picked by the program. 2nd, any value in
default_param
replaces previous values. 3rd, any value in rules.xml or style.xml replaces previous values. 4th, any value inforced_param
replaces previous values. In practice, thedefault_param
allows the user to set defaults which can still be overwritten by the map, whileforced_param
is a definitive 'ignore what is is defined in the map' way of doing things. See alsolw6ldr_read_relative
.Return value: 1 if success, 0 if failed.
map_path: a collection of paths where to find maps
relative_path: something which will be appended to a
map_path
memberdefault_param: default parameters, as strings
forced_param: forced parameters, as strings
display_w: the width of the display output (resolution)
display_h: the height of the display output (resolution)
progress: information used to handle the progress bar
Reads a map from disk, using the map-path value, which is a collection of paths defined by the command-line, the environment variables, and the config file.
default_param
andforced_param
work as in the functionlw6ldr_read
.Return value: 1 if success, 0 if failure.
dirname: the directory of the map
Read the rules (rules.xml) of a map. Pointer to rules must be valid, and values already initialized, either zeroed or filled in with defaults or custom values.
Return value: 1 if success, 0 if failed.
rules: the rules struct to fill with values (read/write parameter)
values: an assoc containing strings with the new values
Overrides rules with values. Pointer to rules must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. Not all parameters need be defined in values. It can even be NULL. The idea is just that if something is defined in values, it will override the existing rules.
Return value: 1 if success, 0 if failed.
dirname: the directory of the map
Read the style (style.xml) of a map. Pointer to style must be valid, and values already initialized, either zeroed or filled in with defaults or custom values.
Return value: 1 if success, 0 if failed.
style: the style to modify
key: the key to modify
value: the value to affect to the key, as a string
Sets one single parameter in a style structure. Value must always be passed as a string, will be converted to the right type automatically when storing it in the structure.
Return value: 1 if success, 0 if failed. Note that while 0 really means there's a problem, some affectations can fail and return 1, needs to be worked on.
style: the style struct to fill with values (read/write parameter)
values: an assoc containing strings with the new values
Overrides style with values. Pointer to style must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. Not all parameters need be defined in values. It can even be NULL. The idea is just that if something is defined in values, it will override the existing style.
Return value: 1 if success, 0 if failed.
use: the use struct to fill with values (read/write parameter)
values: an assoc containing strings with the new values
Overrides use with values. Pointer to use must be valid, and values already initialized, either zeroed or filled in with defaults or custom values. Not all parameters need be defined in values. It can even be NULL. The idea is just that if something is defined in values, it will override the existing use.
Return value: 1 if success, 0 if failed.
color: the color to invert
Inverts a color couple, that is, replace fg by bg and vice-versa.
Return value: none.
color1: 1st color to compare
color2: 2nd color to compare
Compares two colors.
Return value: 1 if equal, 0 if not.
index: index of the color between 0 & 9
Transforms a team color index into its readable string form, which can be used in config files for instance.
Return value: a string, must *not* be freed.
key: key of the color, for instance "red"
The index of the color, between 0 & 9
Return value: an integer.
source: the map to copy
Performs a deep copy of the map, all elements are newly allocated and source can safely be destroyed after it's been duplicated.
Return value: a newly allocated map, may be NULL.
Converts a map to something that is later readable by
lw6map_from_hexa
to reproduce the exact same map. Just a serializer.Return value: a newly allocated pointer, NULL if conversion failed.
hexa: an hexadecimal ASCII string, created by
lw6map_to_hexa
Constructs a map from an hexadecimal string generated by
lw6map_to_hexa
. Just an un-serializer.Return value: a new map, might be NULL if string isn't correct.
Creates a new empty map. This object is perfectly unusable as is, since it has a 0x0 size, and many things set to "NULL". Still, it's used internally and is the canonical way to create the object, it ensures later calls that set up default parameters, for instance, will succeed.
Return value: a newly allocated pointer.
nb_layers: the number of layers of the map
w: the width of the map
h: the height of the map
Creates a map, set to defaults. This is usefull mostly for testing, it will just create a dull rectangle plain and uninteresting map, however it's a quick way to have a working object and test stuff on it.
Return value: a newly allocated map.
Frees a map and releases all its internal ressources.
Return value: none.
Reports how many bytes the map needs, in memory. Note that this is not contiguous memory, it involves a bunch of pointers, and possibly much more...
Returns a string describing the map. This is a very short description, use it for logs, and to debug stuff. By no means it's a complete exhaustive description. Still, the string returned should be unique.
Return value: a dynamically allocated string.
param: the param struct to modify
Sets a param structure to its default value, note that current structured must be zeroed or correctly initialized.
Return value: none
param: the param struct to modify
Resets a param structure to nothing. Note that current structured must be zeroed or correctly initialized. The idea is just to free member pointers before calling free.
Return value: none
dst: the destination param struct
src: the source param struct
Copies parameters. Both structures must be zeroed or correctly initialized.
Return value: none
param: the param struct to modify
key: the name of the parameter to modify
value: the value of the parameter to modify
Sets an entry in a param struct. All values must be submitted as strings, internally, the function will call atoi to convert to integers if needed, for instance. It will also dispatch automatically between rules and style.
Return value: 1 if parameter successfully set, 0 on error.
Reports the last network error. This is basically a debug function, designed mostly for Microsoft Winsock API, but can be safely called on any platform.
Return value: the last error code, has no universal meaning, depends on the platform you're working on.
sock: the socket descriptor
Receives a line terminated by LF ("\n", chr(10)) or CR/LF ("\r\n", chr(10)chr(13)) on a TCP socket, that is, stream oriented. If there's no complete line available, function returns immediately with NULL. Same if socket is closed, broken, whatever. Only if there's something consistent will the function return non-NULL.
Return value: a dynamically allocated string with the content received. The tailing (CR)/LF is stripped.
sock: the socket descriptor
line: the line to be sent, without the "\n" at the end
Sends a line terminated by LF ("\n", chr(10)) on a TCP socket, that is, stream oriented. The "\n" is automatically added, do not bother sending it.
Return value: non-zero if success
sock: the socket descriptor
incoming_ip: the IP address of the sender (returned)
incoming_port: the IP port of the sender (returned)
Receives a line terminated by LF ("\n", chr(10)) or CR/LF ("\r\n", chr(10)chr(13)) on a UDP socket, that is, datagram oriented. If there's no complete line available, function returns immediately with NULL. Same if socket is closed, broken, whatever. Only if there's something consistent will the function return non-NULL. By-value parameters allow the caller to know where the data come from.
Return value: a dynamically allocated string with the content received. The tailing (CR)/LF is stripped.
sock: the socket descriptor
line: the line to be sent, without the "\n" at the end
ip: the IP address of the target
port: the IP port of the target
Sends a line terminated by LF ("\n", chr(10)) on a UDP socket, that is, datagram oriented. The "\n" is automatically added, do not bother sending it.
Return value: the number of bytes sent, 0 if failure
Initializes the low-level network API, you must call this before calling any other network related function, for it allocates a dynamic context which is in turn used by every function.
Return value: non-zero if success
Frees memory, joins active threads, and releases everything set up by network code.
Return value: void
bench_result: pointer to float, will contain the bench result
Runs a standard, normalized bench on a default map. Results can be interpreted as an estimated speed/power of your computer.
Return value: 1 on success, 0 if failure
rules: the set of rules to use (defines polarity)
shape: the shape of the map (logical part)
x: the x coord to fix
y: the y coord to fix
z: the z coord to fix
Similar to
lw6map_coords_fix
but using floats, this function can be used to check cursor position boundaries. Any float pointer can be NULL.Return value: none.
game_state: the game state we're going to work on
sleep: sleep latency, in seconds, typically very low (0.002)
ticks: the current ticks (1000 ticks per sec, used to calibrate)
Initializes a 'pilot' object, this object is responsible for interpreting messages, transform them into low-level 'ker' module function calls, and handle all the thread-spooky stuff.
Return value: a working pilot object. May be NULL on memory failure.
pilot: the object to free.
Frees a 'pilot' object, note that this might involve joining some threads, so it can 'take some time'.
Return value: none.
pilot: the object to send commands to.
command_text: the text of the command, as received form network
verified: wether we're sure this message is valid.
Sends a command and handles it internally.
Return value: 1 if OK, 0 if not.
pilot: the object to commit.
Commits all commands sent and actually send them to the corresponding threads. This commit system allows better performance by sending, for instance, all the commands for a given round together.
Return value: none.
pilot: the object to perform the backup on
Makes a new backup in the pilot, that is, copy 'reference' to 'backup'.
Return value: 1 if OK, 0 if not.
target: the game_state structure which will get the informations.
pilot: the object to get informations from.
Gets the backup from the pilot object. This is the last snapshot taken by
make_backup
or, by default, the game_state the pilot was constructed with.Return value: 1 if OK, 0 if not.
target: the game_state structure which will get the informations.
pilot: the object to get informations from.
Gets the latest reference game_state, that is, a stable snapshot of the game, with no inconsistency, a game position that exists and that we can rely on. Note that getting this can take time since a global mutex is required, and computations must end before you get the data.
Return value: 1 if OK, 0 if not.
target: the game_state structure which will get the informations.
pilot: the object to get informations from.
Gets the informations from the pilot object, not being worried about game consistency, this one will just return the latest version available. It might even be in an inconsistent state, the position could reflect a position which will never exist. Still, the data returned will not correspond to a half-spread or half-moved game_state. The data has at least some basic consistency and getting this does require some mutex lock, however wait time should be fairly small (max. a round).
Return value: 1 if OK, 0 if not.
Returns a string describing the pilot. This is a very short description, use it for logs, and to debug stuff. By no means it's a complete exhaustive description. Still, the string returned should be unique.
Return value: a dynamically allocated string.
pilot: the object to calibrate
ticks: the current ticks setting (1000 ticks per second)
round: the round expected to be returned with this ticks value
Calibrates the pilot, that is, initializes it so that subsequent calls to
lw6pil_pilot_get_round
return consistent values.Return value: none.
pilot: the pilot to speed up
round_inc: the number of rounds
Re-calibrates the pilot so that it speeds up a bit. This will basically increase next_round by round_inc.
Return value: none.
pilot: the pilot to speed up
round_dec: the number of rounds
Re-calibrates the pilot so that it slows down a bit. This will basically decrease next_round by round_inc.
Return value: none.
pilot: the object to query
ticks: the current ticks setting (1000 ticks per second)
Returns the round one should use to generate new events/commands at a given time (given in ticks).
Return value: none.
pilot: the object to query
Returns the round of the last commit (reference game_state) for this object.
Return value: the commit round (reference object)
pilot: the object to query
Returns the round which is targetted in the reference game_state, this is 'how far computation will go in the reference game_state if no new commands are issued'. Note that there can always be some commands which are not yet processed, so you should not rely on this too heavily, however it gives a good idea of how things are going.
Return value: the target round (reference object)
pilot: the object to query
Returns the current round in the reference game_state. There's no lock on this call so don't rely on this too heavily, it just gives you an idea of wether the pilot is very late on its objectives or just on time.
Return value: the current round (reference object)
pilot: the object to query
Returns the max current round in the reference or draft game states. No lock on this call so don't rely on this too heavily, it just gives you an idea of computation state.
Return value: the current round (reference object)
Runs the
pil
module test suite.Return value: 1 if test is successfull, 0 on error.
keyword: the option to match, without the prefix "-" or "–"
argv_string: the argv value, for instance argv[1]
This is an utility function which allow the program to handle options in a uniform manner. Key comparison is insensitive, that is, –option and –OPTION are equivalent. Besides, -option and –OPTION are equivalent too. Liquid War 6 documentation mentions options in lowercase with a double dash (–option) by default, but it's a fact, the program supports variants. This is just for convenience, the philosophy behind this behavior is "be as permissive as possible when interpreting input, and as strict as possible when generating output". In fact, it's even said that Liquid War 6 will accept the argument without any prefix dash as being valid... This is to say running "liquidwar6 –option" is the same as running "liquidwar6 option". But, this is a secret 8-)
Return value: non zero if it matches, 0 if it doesn't.
argc: the number of arguments, as passed to
main
argv: an array of arguments, as passed to
main
keyword: the keyword to match
Parses all command-line arguments, searching for one precise "–key[=...]" entry.
Return value: 1 if key is present, 0 if not.
argc: the number of arguments, as passed to
main
argv: an array of arguments, as passed to
main
keyword: the keyword to match
Parses all command-line arguments, searching for one precise "–key=value" pair, and returns the value.
Return value: a pointer to the value. May be NULL. Must be freed.
argc: the number of arguments, as passed to
main
argv: an array of arguments, as passed to
main
keyword: the keyword to match
Parses all command-line arguments, searching for one precise "–key=value" pair, and returns the value. If a corresponding environment variable is available, but no command-line parameter was passed, the environment variable is intepreted. Such environment variables are uppercased, prefixed by "LW6_" and "_" replaces "-". The environment variable will be overriden if the command-line parameter is present.
Return value: a pointer to the value. May be NULL. Must be freed.
free_func: optional callback used to free memory when stored date is a pointer. Can be NULL when one stores non dynamically allocated data, such as an integer or a static array.
Creates an empty assoc. There's a difference between NULL and an empty assoc. The empty assoc would (in Scheme) be '() whereas NULL corresponds to undefined "is not a assoc and will generate errors if you ever call assoc functions on it". Such created assoc are not performant hash tables but slowish "strcmp me for each key" associative arrays, the key being a "char *" string and the value a "void *" pointer.
Return value: a pointer to the newly allocated associative array. Must be freed with
lw6sys_assoc_free
.
assoc: the assoc to be freed.
The function will cascade delete all elements, using (if not NULL...) the callback passed when first creating the assoc.
Return value: void
assoc: the assoc to test
key: the key to search
Not a very fast function, since on a "big" assoc, strcmp will be called internally until the key is found.
Return value: non-zero if there's an entry with the corresponding key.
assoc: the assoc to query
key: the key of which we want the value
Return value: a void pointer to the data contained in the assoc. Note that the pointer on the actual data is returned, that is, if it's static data, you must not try to free it... As long as memory management is concerned, destroying the assoc will actually free the data if needed.
assoc: the assoc to modify
key: the key we want to updated
value: the new value
Sets a value in an associative array. The key pointer need not be persistent, it can be freed after affectation. In fact a new string will be created internally. This is not true for the value, it's hard to find way to copy "any object". So if you want an associative array of strings, key can disappear after calling this function, but not value. The function passed as free_func when creating the assoc will be used to free stuff whenever needed (unset or free).
Return value: void
assoc: the assoc concerned
key: the key to unset
Clears an entry in an associative array. The callback passed when creating the assoc will be called if needed, to free the data automatically.
Return value: void
assoc: the assoc to work on
Returns a list containing all the keys of the assoc. The list must be free with lw6sys_list_free by the caller. This list copies all the keys of the assoc, so it is safe to use it once the assoc is deleted. However the keys will of course be of little interest in this case. But the program won't segfault.
Return value: the list of keys.
assoc: the assoc to work on
func: a callback to call on each entry
func_data: a pointer on some data which will be passed to the callback
Executes a function on all assoc items. The func_data parameter allows you to pass extra values to the function, such as a file handler or any variable which can not be inferred from list item values, and you of course do not want to make global...
Return value: void
assoc: the assoc to work on
func: a callback to call on each entry, may be NULL
func_data: a pointer on some data which will be passed to the callback
Executes a function on all assoc items, like
lw6sys_assoc_sort_and_map
but befor doing so, sorts all entries in alphabetical order.Return value: void
assoc: the assoc to duplicate, can be NULL
dup_func: the function which will be called to duplicate data
Duplicates an assoc. All keys will be copied so that if the first assoc is deleted, the duplicated one is fine. Additionnaly, dup_func will be called with all data fields. If dup_func is NULL, then data values will simply be copied. This is likely to be usefull when data is not dynamically allocated.
Returned value: a newly allocated assoc.
Will set up a default memory bazooka, a slow yet convenient tool to track down and hopefully kill memory leaks. Named bazooka after a night wasted to track down an unfoundable leak... BAZOOOOOOKA!!!
Return value: 1 if success, 0 if failed.
size: number of items (calls to malloc) to keep
Resizes, the memory bazooka. What's this? It's an inelegant yet efficient tool to track down memory leak. Memory bazooka will keep track of every call to malloc, keeping a trace of what has been malloced, where it has been called (from which file, which line), how much memory was allocated, it will even show you what's at the address in a 0-terminated string-friendly fashion. Of course this slows down the program, so in production, you might set this to 0, but for debugging, a million bazooka is worth the megabytes and CPU cycles it wastes.
Return value: 1 if success, 0 if failure.
The companion of
lw6sys_set_memory_bazooka_size
. This function will return how many calls to malloc can be traced. A return value of 0 indicates that feature is disabled.Return value: size of the bazooka array.
state: the state of the eraser
Sets the memory bazooka eraser state. Note that to really work, it requires the memory bazooka to be "big enough".
Return value: 1 if activated, 0 if not. Note that the main reason for it not to be activated is if the memory bazooka has zero size.
Provided you have always called the
LW6SYS_MALLOC
anLW6SYS_CALLOC
to allocate memory, this function will tell you how many timesmalloc
has been called.Return value: the number of calls to
lw6sys_malloc
orlw6sys_calloc
since program was started.
Provided you have always called the
LW6SYS_FREE
macro to free memory, this function will tell you how many timesfree
has been called.Return value: the number of calls to
lw6sys_free
since program was started.
Reports memory bazooka diagnostics on the console. Carefull, this one is not reentrant, call at the end of your program when all threads are joined.
Return value: 1 if no allocated stuff left, 0 if there are still malloc'ed stuff
Returns the name of the package. This is the
PACKAGE_TARNAME
constant defined by the GNU Autoconf ./configure script. While it's always possible to use the defined constant directly, using this function will return the value defined when compiling the binary, not the one you're using when compiling another program relying on Liquid War as a library.Return value: a non-NULL string "liquidwar6", must not be freed.
Returns the name of the package, in a user friendly form, which can include spaces, for instance. This is the
PACKAGE_NAME
constant defined by the GNU Autoconf ./configure script. While it's always possible to use the defined constant directly, using this function will return the value defined when compiling the binary, not the one you're using when compiling another program relying on Liquid War as a library.Return value: a non-NULL string "Liquid War 6", must not be freed.
Returns the description of the package. This is the
PACKAGE_STRING
constant defined by the GNU Autoconf ./configure script. It's the concatenation ofPACKAGE_NAME
andVERSION
. While it's always possible to use the defined constant directly, using this function will return the value defined when compiling the binary, not the one you're using when compiling another program relying on Liquid War as a library.Return value: a non-NULL string "Liquid War 6 <version>", must not be freed.
Returns the version of the program. This is the
VERSION
constant defined by the GNU Autoconf ./configure script. Same asPACKAGE_VERSION
. Note that while using a function to getPACKAGE_TARNAME
might seem useless, having both ways to get the version, that is, a function and a constant, is very usefull. Think, for instance, that a dynamically loaded shared library might need to check its own version against the version of the core program.Return value: a non-NULL string, which must not be freed.
Returns the the program codename. This is the little name of the version. It's been decided that all LW6 releases would take the name of a famous general, warrior, whatever. For instance, it could be "Napoleon".
Return value: a non-NULL string, traditionnally the name of a famous general, someone which has been involved in war. Must not be freed (I mean, the string, not the general).
Returns the program stamp. This is like a serial number. It's is not the same as the version. The version is meant to be set to something readable. This is just a cryptic thing, incremented at each ./configure or each developper's "I feel like it needs to be incremented". The idea is just to keep (one more...) track of which source code is build. Ideally, this would be plugged to the source revision control system but this has some drawbacks, including that it would require it to modify files before commiting them, which is not safe, and almost impossible if you sign archives. One more point: this is a string. It's true the return value is actually a string containing the representation of an integer, but because all other build parameters are strings, and because we don't know what the future reserves, it's a string.
Return value: a non-NULL string like "42", which must not be freed.
Returns an md5 checkum which is caculated from C (.c and .h) source files. This is complementary with the build stamp. By default the stamp will be enough to check what has been compiled, but one can always imagine a case where Bob compiles something a little different than Alice, with the same stamp, incremented by 1 from a common source tree. They apply their own patches, for instance. This md5sum double-checks that two binaries have been built from the same sources. Note that this is not the md5 checksum of the generated binary. Nor does it include any information about scheme scripts and data.
Return value: a non-NULL string, which must not be freed.
Returns a (very) short copyright information about the program.
Return value: a non-NULL string, single line whithout '\n' at the end. Must not be freed.
Returns the license for the program (GNU GPL v3 or later).
Return value: a non-NULL string, single line whithout '\n' at the end. Must not be freed.
Returns the arguments passed to the GNU Autoconf ./configure script when buildling the game. Very usefull to know how the binary was generated, that is, what kind of optimizations are peculiar settings it uses.
Return value: a non-NULL string, which, passed to ./configure again, would hopefully generate the same binary. Must not be freed.
Returns __VERSION__ GCC preprocessor value, that is, the human readable version of the compiler.
Return value: a non-NULL string, must not be freed.
Returns the arguments which would allow another program to use liquidwar6 as a library. Typically, pass this to gcc when compiling your sources. Basically contains "-I" switches which tell where the headers are.
Return value: a non-NULL string, which must not be freed.
Returns the arguments which would allow another program to link against liquidwar6. Pass this to gcc or libtool when compiling your program. Basically contains a "-L" option which says where the library is. Note that this will only allow you to link against the main libliquidwar6 library, but not the dynamically loaded modules.
Return value: a non-NULL string, which must not be freed.
Returns the value return by the standard shell
hostname
command on the machine where the game has been built. Usefull to track binaries and know where do they come from.Return value: a non-NULL string, must not be freed.
Returns the compilation date. While this information can easily be obtained with the C
__DATE__
macro, having this function is convenient for it returns a value which is the same for the whole program, and does not possibly change in every file.Return value: a non-NULL string, must not be freed.
Returns the compilation date. While this information can easily be obtained with the C
__TIME__
macro, having this function is convenient for it returns a value which is the same for the whole program, and does not possibly change in every file.Return value: a non-NULL string, must not be freed.
Returns the CPU this program is designed for. Convenient on i386 compatible CPUs to know which flavor (i386, i586...) the binary is made for.
Return value: a non-NULL string, must not be freed.
Returns the endianness of the computer.
Return value: 'little' (x86-like) or 'big' (ppc-like), as a string. Must not be freed.
Returns the system pointer size, in bytes.
Return value: 4 for 32-bit, 8 for 64-bit.
Returns the OS this program is designed for. Usefull for bug reports.
Return value: a non-NULL string, must not be freed.
Tells wether the program was compiled for Microsoft Windows, or not.
Return value: 1 if compiled on windows 32-bit, 0 if not
Returns the top source directory, when the game was built. This can seem useless and non relevant on the end-user's machine, but... it's a must-have for developpers and packagers. Without this, binaries would never find their associated data, especially when building outside the source tree. Or, testing the game would be impossible without installing it, given the fact that most of the code is in scripts that are stored in /usr/local by default, this would be painfull. So this function is here to help finding data within the source tree when the game is not installed yet. Note that the function is rather clever, since it will automatically try to remove useless '../' sequences at the beginning of a possibly relative path.
Return value: a non-NULL string, must not be freed.
Returns the
prefix
value as given to the GNU Autoconf ./configure script. Used to deduce the path to other directories and files.Return value: a non-NULL string, "/usr/local" by default. Must not be freed.
Returns the
datadir
value defined by the GNU Autoconf ./configure script. This is not the value which can be overriden by the Liquid War 6 specific. "–data-dir" option.datadir
is usually something like "/usr/local/share" while the actual Liquid War 6 defined data dir is a more profound path which includes the name of the package, its version, and so on.Return value: a non-NULL string, "/usr/local/share" by default. Must not be freed.
Returns the
libdir
value defined by the GNU Autoconf ./configure script. This is not the value which can be overriden by the Liquid War 6 specific. "–mod-dir" option.datadir
is usually something like "/usr/local/lib" while the actual Liquid War 6 defined module dir is a more profound path which includes the name of the package, its version, and so on.Return value: a non-NULL string, "/usr/local/lib" by default. Must not be freed.
Returns the
includedir
value defined by the GNU Autoconf ./configure script. As for other options, it's interesting to have this value, this enables the program to inform people who want to hack the game of the place headers are supposed to be installed.Return value: a non-NULL string, "/usr/local/include" by default. Must not be freed.
Returns the
localedir
value defined by the GNU Autoconf ./configure script. Used as an argument for gettext / libintl functions.Return value: a non-NULL string, "/usr/local/share/locale" by default. Must not be freed.
Returns the
docdir
value defined by the GNU Autoconf ./configure script. Used to write consistent XML file headers.Return value: a non-NULL string, "/usr/local/share/doc/liquidwar6" by default. Must not be freed.
Tells wether console is enabled or not.
Return value: "yes" or "no", must no be freed.
Tells wether the graphical mod-gl backend was compiled.
Return value: "yes" or "no", must no be freed.
Tells wether the audio mod-csound backend was compiled.
Return value: "yes" or "no", must no be freed.
Tells wether the audio mod-ogg backend was compiled.
Return value: "yes" or "no", must no be freed.
Tells wether the network mod-http backend was compiled.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled in optimize mode.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled in allinone mode.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled in fullstatic mode.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled with suitable informations for gprof.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled with suitable informations for gcov.
Return value: "yes" or "no", must no be freed.
Tells wether the game was compiled for later use with valgrind.
Return value: "yes" or "no", must no be freed.
Dumps in the log file the whole program pedigree, target, modules, that is, what are the values of all the build options. Usefull for bug reports.
Return value: none.
data: the data to process
len: the length, in bytes, of the data to process
Creates a checksum from a byte array. This could be mapped on any standard CRC-32 and/or MD5 algorithm, but licence issues for those are such a headache that for the sake of simplicity, it's wrapped here. In LW6 context, we do not really really fear any attack for these checksums are used internally to track bugs and check, for instance, that two game states are actually the same on two distant computers in a network game. Data encryption and security of network links is another debate. Additionnally, this function returns an integer, easier to handle in standard C than any malloc'ed stuff.
Return value: the checksum, as an integer.
value: the string to process
Creates a checksum from a string. This is a convenience function to save the programmer the hassle of calling strlen before any checksum calculation.
Return value: the checksum, as an integer.
value: the integer to process
Creates a checksum from an integer. This is a convenience function to save the programmer the hassle of passing a pointer to the integer with the size of it each time there's a checksum to do. Additionnally, with this one you can pass an int8 or an int16, and function will work just the same indenpendantly of endianness.
Return value: the checksum, as an integer.
value: the integer to process
Creates a checksum from an integer. This is a convenience function to save the programmer the hassle of passing a pointer to the integer with the size of it each time there's a checksum to do. This function handles 64-bit long long integers..
Return value: the checksum, as an integer.
whd: a pointer to the wh struct to be processed
Creates a checksum from the given structure. Convenience function to save the hassle of passing a pointer to and the size of the
lw6sys_wh_t
struct each time, knowing that there are very often checksums calculated on it. Also avoids endianess issues.Return value: the checksum, as an integer.
xyz: a pointer to the xy struct to be processed
Creates a checksum from the given structure. Convenience function to save the hassle of passing a pointer to and the size of the
lw6sys_xy_t
struct each time, knowing that there are very often checksums calculated on it. Also avoids endianess issues.Return value: the checksum, as an integer.
checksum: a pointer to the previous checksum
data: the data to process
len: the length, in bytes, of the data to process
Creates a checksum from the given data. The difference with
lw6sys_checksum
is that this one updates an existing checksum, thus enabling the programmer to call it sequentially and get a global checksum on different sources.Return value: none.
checksum: a pointer to the previous checksum
value: the string to process
Creates a checksum from the given string. The difference with
lw6sys_checksum_str
is that this one updates an existing checksum, thus enabling the programmer to call it sequentially and get a global checksum on different sources.Return value: none.
checksum: a pointer to the previous checksum
value: the integer to process
Creates a checksum from the given integer. The difference with
lw6sys_checksum_int32
is that this one updates an existing checksum, thus enabling the programmer to call it sequentially and get a global checksum on different sources.Return value: none.
checksum: a pointer to the previous checksum
value: the integer to process
Creates a checksum from the given integer. The difference with
lw6sys_checksum_int64
is that this one updates an existing checksum, thus enabling the programmer to call it sequentially and get a global checksum on different sources.Return value: none.
checksum: a pointer to the previous checksum
whd: a pointer to the wh struct to be processed
Creates a checksum from the given structure. The difference with
lw6sys_checksum_whd
is that this one updates an existing checksum, thus enabling the programmer to call it sequentially and get a global checksum on different sources.Return value: none.
checksum: a pointer to the previous checksum
xyz: a pointer to the xy struct to be processed
Creates a checksum from the given structure. The difference with
lw6sys_checksum_xyz
is that this one updates an existing checksum, thus enabling the programmer to call it sequentially and get a global checksum on different sources.Return value: none.
f: the value to convert, from 0.0f to 1.0f
Converts a floating point value between 0.0f and 1.0f to its 8-bit equivalent between 0 and 255. Usefull in color conversion.
Return value: an integer between 0 and 255.
i: the value to convert, from 0 to 255
Converts an 8-bit value between 0 and 255 to its floating-point equivalent between 0.0f and 1.0f. Usefull in color conversion.
Return value: a float between 0.0f and 1.0f.
color_f: the color to convert
Converts a color from floating point format to the integer "0 to 255" common format. All fields (RGBA) are converted.
Return value: the color in 8-bit format.
color_f: the converted color (pointer must point to writable memory)
color_8: the color to convert
Converts a color from the integer "0 to 255" common format to floating point format. All fields (RGBA) are converted.
Return value: none.
color_f: the color to convert
Converts a color from floating point format to a single integer, where all fields (RGBA) are serialized. This serialization is endianess independant. Could be used directly by low-level libraries such as SDL.
Return value: the color serialized in an integer.
color_8: the color to convert
Converts a color from common "0 to 255" structured format to a single integer, where all fields (RGBA) are serialized. This serialization is endianess independant. Could be used directly by low-level libraries such as SDL.
Return value: the color serialized in an integer.
color_f: the converted color (point must point to writable memory)
color_i: the color to convert
Converts a color from a serialized integer format to a floating point structure.
Return value: none.
color_i: the color to convert
Converts a color from a serialized integer format to a "0 to 255" based structure.
Return value: the converted color (structure).
ascii: the color to convert
Converts a color from a human readable string to a "0 to 255" based structure. The string must be of the form "#RRGGBBAA" or "#RGB", in a general manner any HTML-valid value should work.
Return value: the converted color (structure).
color_f: the converted color (pointer must point to writable memory)
ascii: the color to convert
Converts a color from a human readable string to a float based structure. The string must be of the form "#RRGGBBAA" or "#RGB", in a general manner any HTML-valid value should work.
Return value: none.
color_8: the color to convert
Converts a color from a "0 - 255" integer based structure to its readable form "#RRGGBBAA". If alpha is 255 (0xFF), that is, if it's opaque, then the "AA" part is ommitted.
Return value: a newly allocated string.
color_hsv: the target color, in HSV format
color_8: the source color, in RGB 256 format
Converts from HSV to RGB. Usefull for color manipulation, since most colors are stored in RGB but HSV is convenient for transformation. Alpha layer is kept as is.
Return value: none.
color_hsv: the source color, in HSV format
Converts from RGB to HSV. Usefull to make colors transformed in HSV format usable again by all display routines, which consume RGB. Alpha layer is kept as is.
Return value: the RGB color.
size: number of the color array (number of items)
colors: the colors to compute
Tries to find out the "average" color from an array of colors. The algorithm is far from perfect, but should output a color which reflects the colors passed in.
Return value: the (inexact) average color.
color1: first color
color2: second color
coeff: the ponderation coefficient
Tries to find a color between the two colors passed as an argument. The coefficient can be used, to set the relative weight of each color. Using 0 will return color1, 1 will return color2 and 0.5 will make an average between the two colors. Any value between 0 and 1 can be used.
Return value: the (inexact) ponderated color.
color1: first color
color2: second color
Calculates the distance between two colors. The unit is arbitrary, a big value means "colors are different", 0 means they are the same. A distance of 1 corresponds to colors which have barely anything in common, but the result can still be greater than 1. Alpha layer is not taken in account.
Return value: the distance.
color: the color to modify
Make a color "solid" that is make it not transparent at all.
Return value: none.
color: the color to modify
Make a color "solid" that is make it not transparent at all.
Return value: none.
str: string to convert
Just a plain wrapper on
atoi
, it's here for API consistency.Return value: an integer.
str: string to convert
Transform a string into a boolean value. Accepts "0"/"1" in input, but also y/n, yes/no, true/false, on/off.
Return value: an integer, 0 or 1.
str: string to convert
A wrapper on
atof
, makes sure the locale used is C (default) and won't change the decimal separator whatsoever. Usefull for serialization for instance.Return value: a float.
value: the integer to convert
Converts an integer to a string, the advantage of this function is it allocates memory, and does the dirty job.
Return value: a newly allocated pointer, must be freed, may be NULL.
value: the boolean to convert
Converts a boolean to a string, the advantage of this function is it allocates memory, and does the dirty job.
Return value: a newly allocated pointer, must be freed, may be NULL.
value: the float to convert
Converts a float to a string, the advantage of this function is it allocates memory, and does the dirty job.
Return value: a newly allocated pointer, must be freed, may be NULL.
mode: the debug mode, 1 if set, 0 if not.
Sets the debug mode.
user_dir: the user directory, where user can write data.
Clears the dump file. That is, resets it to a "0 byte" file.
Return value: none.
user_dir: the user directory, where user can write data.
content: the content to be written in the dump file.
Writes the dump file onto the disk. The dump is used for special error messages which do not really fit in the standard log, and require a special treatment. In pratice, it's used to log fatal script (Guile) errors.
Return value: 1 if success, 0 if failure.
Gets the ENV separator, that is, for instance, the character used to separate paths in environment variables. Typically, this would be ":" on GNU and ";" on Microsft platforms.
Return value: the ascii character code.
Gets the ENV separator, that is, for instance, the character used to separate paths in environment variables. Typically, this would be ":" on GNU and ";" on Microsft platforms.
Return value: a pointer to a single 0-terminated character string which contains the character. Must not be freed.
value1: the left part to be concatenated
value2: the right part to be concatenated
Concatenates two values and puts the ENV separator, as returned by
lw6sys_env_separator_char
between them.Return value: the concatenated string, must be freed.
keyword: the keyword to be searched in the environment variables.
Searches environment variables for the given keyword. The keyword will be fixed so that all dashes "-" characters are replaced by underscores "_" characters. Characters will be changed to uppercase. Any non alphanumeric character will be replaced by "_". Finally, an "LW6_" prefix will be added. That is to say, calling this function with "my-param" will search for the "LW6_MY_PARAM" environment variable.
Return value: 1 if the environment variable exists, 0 if not.
keyword: the keyword to be searched in the environment variables.
Searches environment variables for the given value. The keyword will be fixed so that all dashes "-" characters are replaced by underscores "_" characters. Characters will be changed to uppercase. Any non alphanumeric character will be replaced by "_". Finally, an "LW6_" prefix will be added. That is to say, calling this function with "my-param" will search for the "LW6_MY_PARAM" environment variable.
Return value: the value for the given keyword. May be NULL. Must be freed.
keyword: the environment variable to set
value: the value of the environment variable to set
Sets the environment variable to a given value. If value is NULL, variable is unset. Note that unlike lw6sys_getenv, this function does not transform the keyword into "LW6_..." before setting the value, so it's your responsability to call "lw6sys_keyword_as_env" if needed.
Return value: 1 if success, 0 if failed
value: the value, a list of item separated by... the separator
Splits the environment value into a list of strings containing each element. All strings are dynamically allocated, but they will be freed automatically when the list is freed.
Return value: a list of strings.
Gets the home directory of the user. Used internally to calculate the
user
-dir value. Note that Liquid War 6, by default, never stores files under '$HOME', instead it put things in '$HOME/.liquidwar6', that is 'user-dir'. If the environment variable 'HOME' is not set, will return '.'.Return value: a newly allocated pointer, must be freed.
Gets the name of the current user. Difference with the standard function
getlogin
is that this function will returned a dynamically allocated pointer, and provide a default value if it's undefined. Also, if will look at the content of the 'LOGNAME' environment variable if needed, and will even provide a default value.Return value: a newly allocated pointer, must be freed.
Gets the name of the current host. The name of the computer. Might not work perfectly, this function is just used to provide default values for player names and such things.
Return value: a newly allocated pointer, must be freed.
filename: absolute or relative filename
Clears a file, that is, make it a 0 byte file, empty, ready to be filled if needed. If this function is called successfully, program can reasonnably assume file will be writable during its execution.
Return value: 1 if success, 0 if failure.
filename: absolute or relative filename
Reads the content of a file, and returns it as a string. Note that content might or might not be ascii or binary, the function will however put a tailing 0 character at the end so that low-level standard C functions do not segfault when used with the returned value.
Return value: a newly allocated pointer, must be freed.
filename: absolute or relative filename
content: the content to be written.
Writes the content into the file. Content is assumed to be a string, function will segfault if it's not correctly 0 terminated as in C string convention. So this function will not allow you to write down arbitrary binary data, however LW6 uses mostly text files to store information, and opaque binary data usage is not recommended.
free_func: optional callback used to free memory when stored date is a pointer. Can be NULL when one stores non dynamically allocated data, such as an integer or a static array.
size: the estimated size of the hash table. Note that this is an estimation only. You could theorically fit 1000000 objects in a 3-sized hash. Problem -> this is inefficient, you'd better use an assoc or a bigger hash. If you store 3 elements in a 1000000-sized hash, you'll waste memory. It might be wise to use a prime number as the estimated size. 421 is prime ;)
Creates an empty hash. There's a difference between NULL and an empty hash.
Return value: a pointer to the newly allocated hash table. Must be freed with
lw6sys_hash_free
.
hash: the hash to be freed.
The function will cascade delete all elements, using (if not NULL...) the callback passed when first creating the hash.
Return value: void
hash: the hash to test
key: the key to search
Not a very fast function, since on a "big" hash, strcmp will be called internally until the key is found.
Return value: non-zero if there's an entry with the corresponding key.
hash: the hash to query
key: the key of which we want the value
Return value: a void pointer to the data contained in the hash. Note that the pointer on the actual data is returned, that is, if it's static data, you must not try to free it... As long as memory management is concerned, destroying the hash will actually free the data if needed.
hash: the hash to modify
key: the key we want to updated
value: the new value
Sets a value in a hash table. The key pointer need not be persistent, it can be freed after affectation. In fact a new string will be created internally. This is not true for the value, it's hard to find way to copy "any object". So if you want a hash table of strings, key can disappear after calling this function, but not value. The function passed as free_func when creating the hash will be used to free stuff whenever needed (unset or free).
Return value: void
hash: the hash concerned
key: the key to unset
Clears an entry in a hash table. The callback passed when creating the hash will be called if needed, to free the data automatically.
Return value: void
hash: the hash to work on
Returns a list containing all the keys of the hash. The list must be free with lw6sys_list_free by the caller. This list copies all the keys of the hash, so it is safe to use it once the hash is deleted. However the keys will of course be of little interest in this case. But the program won't segfault.
Return value: the list of keys.
hash: the hash to work on
func: a callback to call on each entry
func_data: a pointer on some data which will be passed to the callback
Executes a function on all hash items. The func_data parameter allows you to pass extra values to the function, such as a file handler or any variable which can not be inferred from list item values, and you of course do not want to make global...
Return value: void
hash: the hash to work on
func: a callback to call on each entry, may be NULL
func_data: a pointer on some data which will be passed to the callback
Executes a function on all hash items, like
lw6sys_hash_sort_and_map
but befor doing so, sorts all entries in alphabetical order.Return value: void
hash: the hash to duplicate, can be NULL
dup_func: the function which will be called to duplicate data
Duplicates an hash. All keys will be copied so that if the first hash is deleted, the duplicated one is fine. Additionnaly, dup_func will be called with all data fields. If dup_func is NULL, then data values will simply be copied. This is likely to be usefull when data is not dynamically allocated.
Returned value: a newly allocated hash.
hexa_string: an initialization string, can be NULL.
Creates an hexa serializer object. It can be initialized or not, if an initialization string is provided it must of course be valid hexadecimal ascii code, and all serialized content will simply be appended to it.
Return value: a newly allocated object.
hexa_serializer: an hexa serializer object
Frees an hexa serializer object.
Return value: none.
hexa_serializer: an hexa serializer object
Rewinds the serializer pointer, that is, make it point to start. Usefull before calling pop functions, when one wants to be sure to get the first object.
Return value: none.
hexa_serializer: an hexa serializer object
Tests wether we're at EOF. Usefull when one wants to know if there's still some data or if all objects have been correctly popped.
Return value: 1 if at end of file, 0 if not.
hexa_serializer: an hexa serializer object
Exports the current content of the serializer as a string. String can then safely be sent on the network, for instance. String is copied from internal value, so it's safe to use it after serializer has been freed or modified.
Return value: a newly allocated string, must be freed.
hexa_serializer: an hexa serializer object
value: value to push
Pushes a 64 bit integer in the serializer object.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to push
Pushes a 32 bit integer in the serializer object.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to push
Pushes a 16 bit integer in the serializer object.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to push
Pushes an 8 bit integer in the serializer object.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to push
Pushes a floating point value in the serializer object.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to push
Pushes a string in the serializer object. Note that the string is not directly copied in the serializer, instead all its characters are converted to their ASCII equivalent, then appended.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to push
Pushes a lw6sys_xyz_t structure in the serializer object. Calling this avoids calling push for 2 integers separately.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to push
Pushes a lw6sys_whd_t structure in the serializer object. Calling this avoids calling push for 2 integers separately.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to push
Pushes a color structure in the serializer object.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to pop (returned value)
Pops a 64 bit integer from the serializer object.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to pop (returned value)
Pops a 32 bit integer from the serializer object.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to pop (returned value)
Pops a 16 bit integer from the serializer object.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to pop (returned value)
Pops an 8 bit integer from the serializer object.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to pop (returned value)
Pops a floating point value from the serializer object.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to pop (returned value)
Pops a string from the serializer object. The returned value is a newly allocated pointer, which must be freed, you don't need to provide a buffer, just a valid pointer on a NULL pointer.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to pop (returned value)
Pops a lw6sys_xyz_t structure from the serializer object. Avoids calling two integer pops.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to pop (returned value)
Pops a lw6sys_whd_t structure from the serializer object. Avoids calling two integer pops.
Return value: 1 if success, 0 if failure
hexa_serializer: an hexa serializer object
value: value to pop (returned value)
Pops a color from the serializer object.
Return value: 1 if success, 0 if failure
Initializes the history system. Not initializing won't cause any segfault, but data will be inconsistent.
Return value: none.
msg: the message to register.
Registers a message in the history log, that is, adds it.
Return value: none.
timeout: the message age limit.
Get all the messages that are younger than timeout (in seconds).
Return value: a pointer on string pointers. May be NULL. Last pointer is NULL too, that's how you know the array is over.
history: the data to free
Frees a pointer returned by
lw6sys_history_get
.Return value: none.
string: the string to convert
Used to force strings into UTF-8 mode, this is basically to match the TTF font settings used when displaying stuff on OpenGL. Indeed, in this case, the standard _ gettext function won't work, we need to force UTF-8 mode. If the locale is UTF-8, then function does nothing, but at least it's transparent usage won't hurt.
Returned value: a newly allocated string, always in UTF-8 no matter what the locale is.
Long 16-bit ID generator, calls the random function internally. As usual, those are not perfect random numbers, however the function implementation emphasizes more on 'real randomness' rather than relying on performance. Generating twice the same number should be fairly rare.
Long 32-bit ID generator, calls the random function internally. As usual, those are not perfect random numbers, however the function implementation emphasizes more on 'real randomness' rather than relying on performance. Generating twice the same number should be fairly rare.
Long 64-bit ID generator, calls the random function internally. As usual, those are not perfect random numbers, however the function implementation emphasizes more on 'real randomness' rather than relying on performance. Generating twice the same number should be fairly rare.
id_16: the id to check
Checks wether the given id is a valid 16-bit id.
Return value: 1 if OK, 0 if not a valid id.
id_32: the id to check
Checks wether the given id is a valid 32-bit id.
Return value: 1 if OK, 0 if not a valid id.
id_64: the id to check
Checks wether the given id is a valid 64-bit id.
Return value: 1 if OK, 0 if not a valid id.
id: the id to check
Checks wether the given id is a valid id (16, 32 or 64-bit).
Return value: 1 if OK, 0 if not a valid id.
id: the id to convert
Transform an id into its string representation. Error checking is done, if the id is invalid, returned value is NULL. All ids (16, 32 and 64-bit) are handled.
Return value: a newly allocated string, might be NULL.
id: the id to convert
Transform an id into a long integer. Error checking is done, if the id is invalid, returned value is 0. All ids (16, 32 and 64-bit) are handled.
Return value: the id as a long integer, 0 if incorrect source id.
keyword: the keyword to transform
Transforms a keyword into a "key", that is, removes all heading dashes, switches to lowercase, and other stuff. This is used internally to match options and config file parameters, for instance.
Return value: a newly allocated pointer, must be freed.
keyword: the keyword to transform
Transforms a keyword into a command-line parameter to be matched. Does the same as
lw6sys_keyword_as_key
, and adds a "–" prefix.Return value: a newly allocated pointer, must be freed.
keyword: the keyword to transform
Transforms a keyword into the corresponding environment variable name. It will uppercase the name, replace "-" by "_", and add a "LW6_" prefix. "my-param" will become "LW6_MY_PARAM".
Return value: a newly allocated pointer, must be freed.
keyword: the keyword to transform
Transforms a keyword into the corresponding config file entry. In practice, just the same as
lw6sys_keyword_as_key
.Return value: a newly allocated pointer, must be freed.
free_func: a callback which will be called on data when freeing the list
Creates an empty list. There's a difference between NULL and an empty list. The empty list would (in Scheme) be '() whereas NULL corresponds to undefined "is not a list and will generate errors if you ever call list functions on it".
Return value: a pointer to the created object, may be NULL.
list: the list to delete.
Delete a list, this will cascade delete all the following items in the list.
Return value: none.
list: the current position in the list
It's safer to call this rather than dig right into the internals of the list.
Return value: a new position in the list, may be NULL.
list: the list we want informations about
Checks wether the list is empty or not. Note that being empty and being NULL is not the same. An empty list is a valid pointer on a list where there's no item, a NULL pointer is not a list at all. Do *NOT* call this function on NULL.
Return value: 1 if empty, 0 if there is at list one item.
list: the list we want informations about
Calculates the length of the list. This is a performance killer for lists are inadapted to this. But it can still be usefull.
Return value: the number of elements, 0 is none (empty list).
list: the list where elements will be taken
func: the function which will be executed
func_data: additionnal data to be passed to
func
Executes a function on all list items. The
func_data
parameter allows you to pass extra values to the function, such as a file handler or any variable which can not be inferred from list item values, and you of course do not want to make global... Not as convenient as a real "for each" construct as can be found in any modern langage, but does the job. No return value, if you really want one, pass a structure infunc_data
and modify something in it on success, failure, whatever.Return value: none.
list: a pointer to the list (pointer on pointer, read/write value)
data: the data to be pushed
Pushes data on the list. The
free_func
function is copied from the previous element. The pointer on the list is changed "in place" (in/out). Note that if there's amalloc
problem it might end-up being NULL... This should be rare but it *can* happen. You cannot push something else than a pointer, pushing an int is a very bad idea. Push a pointer on the integer, and ensure it's always there, ormalloc
it and passlw6sys_free_callback
when creating the list. If you think you can cast an integer into a pointer, think 64-bit machines...Return value: none.
list: a pointer to the list (pointer on pointer, read/write value)
Pops data from the list, the returned value is what was passed to list_push. The pointer on the list is changed "in place" (in/out). When data is popped, that needs some freeing (i.e. free_func was not NULL when creating the list) then it's the responsibility of the caller to free it when popping it. One popped it's not freed, but it's out of the list scope. Of course the lw6sys_list_t is freed, but not the data. If you happen to store non-NULL data in your list, you can call this function without bothering calling
lw6sys_list_is_empty
and assume that when you get NULL, there's no data left. At this stage, the list won't exist anymore BTW, you won't even need to free it. The idea is: popping a list which has no elements left (empty list) destroys the list and returns NULL.Return value: a pointer on the popped data, whatever you pushed.
list: a pointer to the list (pointer on pointer, read/write value)
data: the data to be pushed
Pushes data on the list. The
free_func
function is copied from the previous element. The pointer on the list is changed "in place" (in/out). Note that if there's amalloc
problem it might end-up being NULL... This should be rare but it *can* happen. You cannot push something else than a pointer, pushing an int is a very bad idea. Push a pointer on the integer, and ensure it's always there, ormalloc
it and passlw6sys_free_callback
when creating the list. If you think you can cast an integer into a pointer, think 64-bit machines...Return value: none.
list: a pointer to the list (pointer on pointer, read/write value)
Pops data from the list, the returned value is what was passed to list_push. The pointer on the list is changed "in place" (in/out). When data is popped, that needs some freeing (i.e. free_func was not NULL when creating the list) then it's the responsibility of the caller to free it when popping it. One popped it's not freed, but it's out of the list scope. Of course the lw6sys_list_t is freed, but not the data. If you happen to store non-NULL data in your list, you can call this function without bothering calling
lw6sys_list_is_empty
and assume that when you get NULL, there's no data left. At this stage, the list won't exist anymore BTW, you won't even need to free it. The idea is: popping a list which has no elements left (empty list) destroys the list and returns NULL.Return value: a pointer on the popped data, whatever you pushed.
list: the list to duplicate, can be NULL
dup_func: the function which will be called to duplicate data
Duplicates a list. All data will be copied so that if the first list is deleted, the duplicated one is fine. Addtionnally, dup_func will be called to filter all data, and possibly allocated new pointers if needed, for instance. If dup_func is NULL, then data values will simply be copied. This is likely to be usefull when data is not dynamically allocated.
Returned value: a newly allocated list.
filename: the name of the log file.
Sets up the log file. Until you call this function, messages all logged to the default log file, as returned by the
lw6sys_get_default_log_file
function.Return value: void
filename: the name of the log file.
Clears the log file, this function would typically be called at the beginning of the program. If filename is NULL, then the default log file is cleared.
Return value: void
level_id: the log level to use. Possible values are, by order, LW6SYS_LOG_ERROR_ID (0), LW6SYS_LOG_WARNING_ID (1), LW6SYS_LOG_NOTICE_ID (2), LW6SYS_LOG_INFO_ID (3) and LW6SYS_LOG_DEBUG_ID (4).
file: the name of the source file where the function is called, one can use __FILE__
line: the line in the source file where the function is called, one can use __LINE__
fmt: a printf-like format string ...: printf-like arguments, corresponding to
fmt
.This function is usually called with the first three arguments packed into a single macro. A typical use is "lw6sys_log(LW6SYS_LOG_WARNING,"sys","problem s d","foo",1)". The
LW6SYS_LOG_WARNING
macro expands and fills the first 3 args, so there's no need to type __FILE__ and __LINE__ again and again. Note that this function will reset errno. The idea is to call it whenever there's something to do with errno (if you deal with errno, it's a good habit to log it) then errno is cleared so that it won't interfere with next log messages.
fmt: a printf-like format string ...: printf-like arguments, corresponding to
fmt
.This function is a special log function which will dump informations on the console only, without opening any log file whatsoever. The idea is that it's a "never fail" function. Additionnally, it will never return but quit the program. This can be used as an ultimate emergency function, use it when the program won't run for sure, and displaying an immediate error message is the only issue.
level: the log level, integer between 0 & 4. 4 is very verbose (debug), 0 displays errors only.
size: number of bytes to allocate.
file: name of the file calling the function, use
__FILE__
line: line in the file calling the function, use
__LINE__
This is a wrapper over the standard
malloc
function. Additionnally it will keep track of the call with an internal program-wide counter, thus enabling memory leak checks. You should not use this function directly but use the macroLW6SYS_MALLOC
which has the same syntax, without the last two parameters, which are automatically provided by macro expansion.Return value: the newly allocated pointer. Data is not initialized.
size: number of bytes to allocate.
file: name of the file calling the function, use
__FILE__
line: line in the file calling the function, use
__LINE__
This is a wrapper over the standard
calloc
function. Additionnally it will keep track of the call with an internal program-wide counter, thus enabling memory leak checks. You should not use this function directly but use the macroLW6SYS_CALLOC
which has the same syntax, without the last two parameters, which are automatically provided by macro expansion.Return value: the newly allocated pointer. Data is filled with zeros.
ptr: the pointer to reallocate.
size: number of bytes to allocate.
file: name of the file calling the function, use
__FILE__
line: line in the file calling the function, use
__LINE__
This is a wrapper over the standard
realloc
function. You should not use this function directly but use the macroLW6SYS_REALLOC
which has the same syntax, without the last two parameters, which are automatically provided by macro expansion.Return value: the newly allocated pointer.
ptr: the pointer to free.
file: name of the file calling the function, use
__FILE__
line: line in the file calling the function, use
__LINE__
This is a wrapper over the standard
free
function. Additionnally it will keep track of the call with an internal program-wide counter, thus enabling memory leak checks. You should not use this function directly but use the macroLW6SYS_FREE
which has the same syntax, without the last two parameters, which are automatically provided by macro expansion.Return value: none.
ptr: the pointer to free.
This is a callback to be used when the
lw6sys_free
does not fit. A good example is a list, which, to free its elements, requires you to provide a callback that only takes 1 arg, the pointer to free. Problem,lw6sys_free
takes 3 args. And theLW6SYS_FREE
macro is not usable in such a context. And you can't use standardfree
either for it would mess up themalloc
/free
automatical count which is so convenient to track memory leaks. So this callback is here, it's only drawback is that in case of an error, the error will not be reported with the real file and line parameters. It's still better than nothing.Return value: none.
Gives a raw approximation of available memory, in megabytes. Value is to be taken with distance, but it can give good hints when system is running short of ressources.
Return value: number of megabytes (physical memory) available.
Checks the endianess of the machine. PPC is big endian, for instance.
Return value: 1 if system is big endian, 0 if little endian.
Checks the endianess of the machine. x86 is little endian, for instance.
Return value: 1 if system is little endian, 0 if big endian.
Checks of common types and usefull structures, this is a debugging function which helps finding compiler strange behaviors and programmer's bad intuitions.
Return value: 1 if everything is OK, 0 if error.
Creates a mutex object.
Return value: newly allocated pointer.
mutex: the mutex to destroy.
Destroys a mutex object.
Return value: none.
mutex: the mutex to use
Locks the mutex. Note that this should never fail unless there's a serious initialization problem, instead, function will wait forever until mutex is released.
Return value: 1 if success, 0 if failure.
mutex: the mutex to use
Tries to locks the mutex. That is, tells wether mutex can be locked immediately or not. Note that this does not mean there's 100% chance next call to lock will terminated immediately, since lock can still be acquired by another thread.
Return value: 1 if mutex unlocked, 0 if locked or error.
mutex: the mutex to use
Unlocks a mutex.
Return value: 1 if sucess, 0 if error.
Returns how many mutexes have been locked since program start. Usefull for sanity checking when debugging.
Return value: number of calls to lock
Returns how many mutexes have been unlocked since program start. Usefull for sanity checking when debugging.
Return value: number of calls to unlock
Checks wether unlock has been called as many times as lock. Usefull for sanity checking when debugging.
Return value: 1 if OK, 0 if inconsistency.
Function which returns always true, that is, something different than 0.
Function which returns always false, that is, 0. This can seem totally useless but it does have some utility. It's used for instance to "fool" the compiler and force it to compile and link functions in binaries, so that, afterwards, dynamically loaded .so files can find in the main binary some functions which would otherwise be stripped during the final link.
Returns the default user directory. Note that this value is not static, it can depend, for instance, of the environment variable
HOME
.Return value: a newly allocated string.
Returns the default config file. Note that this value is not static, it can depend, for instance, of the environment variable
HOME
.Return value: a newly allocated string.
Returns the default log file. Note that this value is not static, it can depend, for instance, of the environment variable
HOME
.Return value: a newly allocated string.
Returns the default prefix, could be /usr/local for instance.
Return value: a newly allocated string.
Returns the default module directory (dynamically loaded libraries).
Return value: a newly allocated string.
Returns the default data directory.
Return value: a newly allocated string.
Returns the default map directory.
Return value: a newly allocated string.
Returns the default map path, which can be composed of several directories.
Return value: a newly allocated string.
Returns the default script file.
Return value: a newly allocated string.
Logs all default values to log file. Usefull for debugging, to know where the program is searching for its informations.
Returns the current working directory (absolute path).
Return value: a newly allocated string.
argc: argc, number of arguments, as given to
main
argv: argv, pointer to arguments, as given to
main
Returns the binary directory, that is, the directory the binary is stored in. This is calculated dynamically, by interpreting command-line arguments.
Return value: a newly allocated string.
argc: argc, number of arguments, as given to
main
argv: argv, pointer to arguments, as given to
main
Returns the user dir, taking in account command-line and environment variables. However config file content has no impact on the result.
Return value: a newly allocated string.
argc: argc, number of arguments, as given to
main
argv: argv, pointer to arguments, as given to
main
Returns the config file, taking in account command-line and environment variables. However config file content has no impact on the result.
Return value: a newly allocated string.
argc: argc, number of arguments, as given to
main
argv: argv, pointer to arguments, as given to
main
Returns the log file, taking in account command-line and environment variables. However config file content has no impact on the result.
Return value: a newly allocated string.
argc: argc, number of arguments, as given to
main
argv: argv, pointer to arguments, as given to
main
Returns the prefix, taking in account command-line and environment variables. However config file content has no impact on the result.
Return value: a newly allocated string.
argc: argc, number of arguments, as given to
main
argv: argv, pointer to arguments, as given to
main
Returns the mod dir (modules, shared .so), taking in account command-line and environment variables. However config file content has no impact on the result.
Return value: a newly allocated string.
argc: argc, number of arguments, as given to
main
argv: argv, pointer to arguments, as given to
main
Returns the data dir, taking in account command-line and environment variables. However config file content has no impact on the result.
Return value: a newly allocated string.
argc: argc, number of arguments, as given to
main
argv: argv, pointer to arguments, as given to
main
Returns the map dir, taking in account command-line and environment variables. However config file content has no impact on the result.
Return value: a newly allocated string.
argc: argc, number of arguments, as given to
main
argv: argv, pointer to arguments, as given to
main
Returns the map path, taking in account command-line and environment variables. However config file content has no impact on the result. Map path can contain several directories.
Return value: a newly allocated string.
argc: argc, number of arguments, as given to
main
argv: argv, pointer to arguments, as given to
main
Returns the script file, taking in account command-line and environment variables. However config file content has no impact on the result.
Return value: a newly allocated string.
argc: argc, number of arguments, as given to
main
argv: argv, pointer to arguments, as given to
main
Logs all the main options values which are not config-file dependant but depend on built-in defaults, command-line arguments and environment variables. Usefull to debug and know where the program is searching for things.
filename: the file to test
Tests the existence of a file on the filesystem. File is considered to exists if it's at least readable.
Return value: 1 if OK, 0 if file doesn't exist or can't be read.
dirname: the directory to test
Tests the existence of a directory on the filesystem.
Return value: 1 if OK, 0 if directory doesn't exist.
dirname: the directory to create
Creates a directory, performing sanity checks such as verifying the directory really exists after being created.
Return value: 1 if OK, 0 if error.
dirname: the directory to create
Creates a directory like
lw6sys_create_dir
but this function is silent in the sense that it won't log any error. Usefull to create the log directory itself, for instance, and avoid infinite loops on error.Return value: 1 if OK, 0 if error.
path: a path
Adds a slash, or in a general manner, a directory separator, at the end of a path, if needed. So /foo/bar will become /foo/bar/ but /bar/foo/ will remain /bar/foo/.
Return value: a newly allocated string, must be freed.
path: a path
Strips the slash, or in a general manner, the directory separator, at the end of a path, if needed. So /foo/bar/ will become /foo/bar but /bar/foo will remain /bar/foo.
Return value: a newly allocated string, must be freed.
path1: left part of the path
path2: right part of the path
Concatenates 2 parts of a path. Function will try to avoid stupid "double-slash" when concatenating /foo/ with /bar/ and conversely insert a directory separator when concatenating /foo with bar/.
Return value: a newly allocated string, must be freed.
path: a path
Splits a path into all its parts. For instance /boo/bar/foo2/bar2 returns a 4 elements list. This is more than a plain split, for heading and tailing slashes will be ignored, and various path separators will be interpreted (depends on platform).
Return value: a list containing 0-terminated strings.
path: a path
Checks wether a path is relative or absolute.
Return value: 1 if relative, 0 if absolute.
path: a path
Checks wether a path is "." or not. Will also trap "" and "./".
Return value: 1 if relative, 0 if absolute.
path: a path
Returns the parent path. That will return /foo when given /foo/bar in input.
Return value: a newly allocated string, must be freed.
path: a path
Given the ../foo/bar path, will return foo/bar. Usefull to get rid of heading ../ when a path is known to start with it.
Return value: a newly allocated string, must be freed.
path: a path
Given the ../foo/bar path, will return foo/bar. Usefull to get rid of heading ../ when a path is known to start with it. This is different from
lw6sys_path_unparent
just because the result is not dynamically allocated and copied from source.Return value: a pointer which points somewhere within the string passed as an argument.
f: file to output content to
Prints a standard Liquid War compliant XML header in the given file.
Return value: none.
f: file to output content to
Prints a standard Liquid War 6 compliant XML footer in the given file.
Return value: none.
progress: the progress struct to initialize
value: the value to point to
Sets a progress struct to default values, that is, ranging from 0.0f to 1.0f.
Return value: none.
progress: the progress struct to update
min: the min value
max: the max value
value: the current value
Updates a progress struct. This is typically the function used by a callback to show the progress of a process. Note that this is note an initializer. Rather, the progress struct was initialized before, and this call is done in a loop with min being 0, max being the last value in the loop, and value the current index in the loop. NULL pointers correctly handled internally, so call this with any parameters, it's safe.
Return value: none.
progress1: the first part of the splitted progress progress2: the second part of the splitted progress progress_src: the progress to split
Utility function to split a progress struct, that is, if a progress was ranging from a to b, make 2 progress structs, ranging from a to c and from c to b, c being between a and b.
Return value: none
progress1: the first part of the splitted progress progress2: the second part of the splitted progress progress3: the third part of the splitted progress progress_src: the progress to split
Utility function to split a progress struct, this one will split it into 3 equal parts.
Return value: none
progress1: the first part of the splitted progress progress2: the second part of the splitted progress progress3: the third part of the splitted progress progress4: the fourth part of the splitted progress progress_src: the progress to split
Utility function to split a progress struct, this one will split it into 4 equal parts.
Return value: none
progress: the progress to update
Sets the progress to its min value, NULL values correctly handled.
Return value: none
progress: the progress to update
Sets the progress to the average between min and max, NULL values correctly handled.
Return value: none
progress: the progress to update
Sets the progress to its max value, NULL values correctly handled.
Return value: none
range: the high limit for random generated numbers. If you want random numbers between 0 and 5, set this to 6.
Wrapper over standard random function. This one is thread safe. This idea is not to provide cryptographic-proof random numbers, rather generate sequences which are random enough to generate unique server ids and such things. The function is initialized on its first call, and results depend on timestamp, host name, user name, and memory available.
min: the min value, as a float
max: the max value, as a float
Returns a random float number between min & max. Can be equal to min or max.
Function used to avoid initializing SDL several times in a program. AFAIK Allegro has a
was_init
function, but SDL doesn't. With this function - which every LW6 sub-module should use - one can know globally, for the whole program, wether SDL has been initialized or not.
Call this whenever you are done with SDL and exit it, so that the
lw6sys_sdl_register
function works correctly.Return value: 1 if SDL needs to be unregistered, that is, if it has already been initialized, else 0.
data: pointer to the data, must contain at least 8 bytes of writable space
value: the integer to serialize
Serializes a 64-bit integer in a byte buffer. Result is not dependant on machine endianess. Typically used for checksums or high-level serializations.
data: pointer to the data, must contain at least 8 bytes
Recovers a 64-bit integer from a byte buffer created, for instance, with
lw6sys_serialize_int64
.
data: pointer to the data, must contain at least 4 bytes of writable space
value: the integer to serialize
Serializes a 32-bit integer in a byte buffer. Result is not dependant on machine endianess. Typically used for checksums or high-level serializations.
data: pointer to the data, must contain at least 4 bytes
Recovers a 32-bit integer from a byte buffer created, for instance, with
lw6sys_serialize_int32
.
data: pointer to the data, must contain at least 2 bytes of writable space
value: the integer to serialize
Serializes a 16-bit integer in a byte buffer. Result is not dependant on machine endianess. Typically used for checksums or high-level serializations.
data: pointer to the data, must contain at least 2 bytes
Recovers a 16-bit integer from a byte buffer created, for instance, with
lw6sys_serialize_int16
.
shape: the dimensions to control
min_wh: the min value for w and h
max_wh: the max value for w and h
max_d: the max value for d
Will check wether the given shape respects some basic constraints, being not to small and not too big.
Return value: 1 if OK, 0 if not.
shape: the boundary box
pos: the position
Checks wether position is within the given boundary box.
Return value: 1 if OK, 0 if not.
list_a: pointer to a list of int item
list_b: pointer to a list of int item
A typicall sort callback function, can be passed to
lw6sys_sort
to sort a list of integers.Return value: -1 if
list_a
<list_b
, 0 iflist_a
==list_b
, 1 iflist_a
>list_b
list_a: pointer to a list of int item
list_b: pointer to a list of int item
A typicall sort callback function, can be passed to
lw6sys_sort
to sort a list of integers. This one will sort in reverse mode.Return value: 1 if
list_a
<list_b
, 0 iflist_a
==list_b
, -1 iflist_a
>list_b
list_a: pointer to a list of float item
list_b: pointer to a list of float item
A typicall sort callback function, can be passed to
lw6sys_sort
to sort a list of floating point numbers.Return value: -1 if
list_a
<list_b
, 0 iflist_a
==list_b
, 1 iflist_a
>list_b
list_a: pointer to a list of float item
list_b: pointer to a list of float item
A typicall sort callback function, can be passed to
lw6sys_sort
to sort a list of floating point numbers. This one will sort in reverse mode.Return value: 1 if
list_a
<list_b
, 0 iflist_a
==list_b
, -1 iflist_a
>list_b
list_a: pointer to a list of string item
list_b: pointer to a list of string item
A typicall sort callback function, can be passed to
lw6sys_sort
to sort a list of 0-terminated strings.Return value: -1 if
list_a
<list_b
, 0 iflist_a
==list_b
, 1 iflist_a
>list_b
list_a: pointer to a list of string item
list_b: pointer to a list of string item
A typicall sort callback function, can be passed to
lw6sys_sort
to sort a list of 0-terminated strings. This one will sort in reverse mode.Return value: 1 if
list_a
<list_b
, 0 iflist_a
==list_b
, -1 iflist_a
>list_b
list: the list to sort, might be modified by the function
sort_func: the callback function used to sort
A general sorting function. Internally, will use the glibc
qsort
function, but this one is adapted to the LW6 specific data structures, more exactly, thelw6sys_list
structure. Several default sort callbacks are defined, but one is free to use any callback, provided it has the right prototype.
src: the string to copy
Duplicate a string, creating a new pointer on it, which must be freed afterwards. The main difference with
strdup
is that here we use the LW6SYS_MALLOC macro to track down possible memory leaks.Return value: a newly allocated pointer, must be freed.
str1: the left part to be concatenated
str2: the right part to be concatenated
Concatenate 2 strings, and put the result in a newly allocated string. Unlike
strcat
which uses the same pointer.Return value: a newly allocated pointer, must be freed.
fmt: a format string, like the one you would pass to
printf
...: optional arguments, like the ones you would pass toprintf
An sprintf like function, except it allocates a new string automatically, with "enough space". This is not a highly optimized function, it will allocate plenty of memory, possibly several times, and thus consume time and resources. But it has the great advantage of freeing the programmer of the dirty work of guessing "how log will the sprintf'ed string be?" before even generating it. So it's a time saver for the programmer. Additionnally, helps avoiding memory leaks and buffer overflows.
Return value: a new allocated string, must be freed.
str: the string to test
Tests wether a string is blank, that is, if it's composed of space, tabs, or carriage returns only.
Return value: 1 if blank, 0 if not.
str_ptr: a pointer to a string pointer (read/write parameter).
Skips blanks at the beginning of a string. The passed parameter is modifed in place. Usefull for parsing.
Return value: 1 if blanks were found, else 0.
str: a pointer to the string, which will be modified in-place.
Used to clean up some strings, for instance if they come from the network, we don't necessarly want system chars to be displayed on the console. Basically it removes all characters with an ASCII code inferior to 32, that is, all system characters. This way, there won't be any tab, linefeed, or any of such characters left.
Return value: none.
str: a pointer to the string we want to modify
prefix: a prefix to put before each line
Reformats a string, that is, insert newline characters in the right places to that it fits in a given number of columns. A prefix is appended at the beginning of each line. Will not handle strings which already contain newline characters perfectly.
Return value: a newly allocated string, must be freed.
Returns the value of EOL, that is, the "end of line" sequence. Will simply return "\n" on UNIX and "\r\n" on Microsoft platforms. Note that while this is convenient to write config and example files, for instance, it's a bad idea to use this to generate network messages, because this kind of message needs to be platform independant. Thus any network protocol oriented string would use chr(10) and char(13) directly.
Return value: the EOL string, must not be freed.
str: a string
c: the delimiter to split with
Splits a string, for instance 'foo,bar' splited with 'o' will return 'f', ” and ',bar'.
Return value: a list containing 0-terminated strings.
str: a string
c: the delimiter to split with
Splits a string, ignoring empty '0-length' members. For instance 'foo,bar' splited with 'o' will return 'f' and ',bar'.
Return value: a list containing 0-terminated strings.
Runs the
sys
module test suite, testing most (if not all...) functions. Note that some tests perform file system operations and might therefore fail on a read-only filesystem, or if user permissions are not sufficient.Return value: 1 if test is successfull, 0 on error.
callback_func: the main callback, the function that will run the thread
callback_join: function which will be called when joining, at the end
callback_data: data which will be passed to the callback
flag: a user flag which will be associated to the thread
Creates a thread. All threads must be joined. This is because we really do not want the game to leak, and detached threads are typically the kind of thing that leaves stuff in the heap. Note that callback_func is just something which will be called when joining it can be NULL. The idea is to put in it free & delete functions, which you can't call before joining when you want the main thread to get the results of the callback_func.
Return value: an opaque pointer on the thread. Can be NULL if failed.
thread_handler: thread to work on
Tells wether the callback is done, that is to say, wether the results are available, and we can join.
Return value: 1 if done, else 0.
thread_handler: thread to query
Returns the id of the thread, this is an internal value, unique for each process, which can help identifying the thread.
Return value: the id, should be >0.
thread_handler: thread to query
Returns the data associated to the thread, that is, the pointer which was passed to the callback function.
Return value: a pointer.
thread_handler: thread to query
Returns the flag associated to the thread, that is, the integer which was given when creating the thread. This can be used in any way you want to decide what to do when a thread is over, for instance.
Return value: a pointer.
thread_handler: thread to end
Joins the thread, that's to say wait until the thread is over, and destroys the ressources associated to it. Note that if the thread is looping forever, this function will just wait forever. This is the only way to end a thread.
Return value: none.
Utility function used to check how many threads where created and joined.
Return value: how many threads were created.
Utility function used to check how many threads where created and joined.
Return value: how many threads were joined.
Utility function used to check how many threads where created and joined. This one will compare the results of
lw6sys_get_thread_create_count
andlw6sys_get_thread_join_count
.Return value: 1 if both are equals, 0 if not (error...).
Returns a 64-bit timestamp, for general purpose, but no precise timing. Precision is only of 1 second, see the
gfx
module for more accurate timing, for animations for instance.Return value: the timestamp.
Returns the uptime, in seconds, since program startup. Based on timestamp.
Return value: the uptime, in seconds.
seconds: the number of seconds to wait, fractions allowed
Will sleep for the given amount of seconds. Provides accurate timing and has "about-millisecond" precision, since it uses
select
internally. Might however be interrupted in some cases, so consider function can always return quicker than specified. A common usage of this function is polling loops, where you don't care if 2 polls are very close, but simply want to avoid polling continuously, therefore consumming 100% of the CPU for nothing.
sleep: how many seconds to wait between every poll
Creates a new loader. This object is used to do some reputed slow calculus in the background, in a separated thread. Typical example is map loading. This is a high-level objects which encapsulates threads and other wizardry.
Return value: a pointer to the loader, NULL if failed.
loader: the loader to free.
Deletes a loader. Will automatically stop the child thread, free data, and so on.
Return value: none.