Next: , Previous: libker, Up: C API


5.23 libldr

5.23.1 Overview

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

5.23.2 API

— Function: int lw6ldr_body_read (lw6map_body_t * body, char * dirname, lw6map_param_t * param, lw6ldr_hints_t * hints, int display_w, int display_h, float ratio, int bench_value, int magic_number, lw6sys_progress_t * progress)

body: the body to read, must point to allocated memory

dirname: the directory of the map

param: map parameters

hints: map hints

display_w: the display width

display_h: the display height

ratio: wished map ratio

bench_value: the bench value (depends on computer capacity)

magic_number: arbitrary constant

progress: structure to transmit loading progress

Reads the map body, that is, all the layers.

Return value: 1 if OK, 0 if failed.

— Function: void lw6ldr_auto_colors (lw6map_style_t * style, lw6ldr_hints_t * hints)

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.

— Function: int lw6ldr_cursor_texture_read (lw6map_cursor_texture_t * cursor_texture, char * dirname)

cursor_texture: the cursor texture (out param)

dirname: the directory we load the data form (map dir)

Reads the cursor texture information, if not available, will use defaults

Return value: 1 on success, 0 on failure.

— Function: void lw6ldr_free_entry (lw6ldr_entry_t * entry)

entry: the entry to free

Frees a map entry.

Return value: none.

— Function: lw6sys_list_t * lw6ldr_get_entries (char * map_path, char * relative_path)

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.

— Function: void lw6ldr_for_all_entries (char * map_path, char * relative_path, int recursive, lw6sys_list_callback_func_t callback_func, void * func_data)

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.

— Function: int lw6ldr_grease_apply (lw6map_layer_t * layer, lw6map_rules_t * rules, lw6ldr_hints_t * hints, lw6sys_progress_t * progress)

layer: the layer on which to apply the grease

rules: map rules

hints: map hints

progress: structure to transmit loading progress

Reads the map body, that is, all the layers.

Return value: 1 if OK, 0 if failed.

— Function: int lw6ldr_hints_read (lw6ldr_hints_t * hints, char * dirname)

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.

— Function: int lw6ldr_hints_set (lw6ldr_hints_t * hints, char * key, char * value)

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.

— Function: int lw6ldr_hints_update (lw6ldr_hints_t * hints, lw6sys_assoc_t * values)

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.

— Function: int lw6ldr_meta_layer_read (lw6map_meta_layer_t * meta_layer, char * filename, int target_w, int target_h, int analog)

meta_layer: the meta layer to read

filename: the file to open

target_w: the wanted width

target_h: the wanted height

analog: wether to use analog info (0-255) or boolean (0-1)

Reads a meta-layer from the disj, resampling is done according to the given parameters.

Return value: 1 on success, 0 on failure

— Function: int lw6ldr_meta_layer_read_if_exists (lw6map_meta_layer_t * meta_layer, char * dirname, char * file_only, int target_w, int target_h, int analog)

meta_layer: the meta layer to read

dirname: the map directory

file_only: the meta-layer file name only (without the path)

target_w: the wanted width

target_h: the wanted height

analog: wether to use analog info (0-255) or boolean (0-1)

Reads a meta-layer from the disj, resampling is done according to the given parameters. This function is different from lw6ldr_meta_layer_read for it will 1) concatenate dirname and file_only and 2) return OK (1) if file does not exist.

Return value: 1 on success, 0 on failure

— Function: int lw6ldr_param_read (lw6map_param_t * param, char * dirname)

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.

— Function: int lw6ldr_param_update (lw6map_param_t * param, lw6sys_assoc_t * values)

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.

— Function: void lw6ldr_print_example_rules_xml (FILE * f)

f: file to output content to

Print to a file a typical map rules.xml file.

Return value: none.

— Function: void lw6ldr_print_example_hints_xml (FILE * f)

f: file to output content to

Print to a file a typical map hints.xml file.

Return value: none.

— Function: void lw6ldr_print_example_style_xml (FILE * f)

f: file to output content to

Print to a file a typical map style.xml file.

Return value: none.

— Function: int lw6ldr_print_examples (char * user_dir)

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.

— Function: lw6map_level_t * lw6ldr_read (char * dirname, lw6sys_assoc_t * default_param, lw6sys_assoc_t * forced_param, int display_w, int display_h, int bench_value, int magic_number, lw6sys_progress_t * progress)

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)

bench_value: the bench value (depends on computer capacity)

magic_number: arbitrary constant

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 in forced_param replaces previous values. In practice, the default_param allows the user to set defaults which can still be overwritten by the map, while forced_param is a definitive 'ignore what is is defined in the map' way of doing things. See also lw6ldr_read_relative.

Return value: 1 if success, 0 if failed.

— Function: lw6map_level_t * lw6ldr_read_relative (char * map_path, char * relative_path, lw6sys_assoc_t * default_param, lw6sys_assoc_t * forced_param, int display_w, int display_h, int bench_value, int magic_number, lw6sys_progress_t * progress)

map_path: a collection of paths where to find maps

relative_path: something which will be appended to a map_path member

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)

bench_value: the bench value (depends on computer capacity)

magic_number: arbitrary constant

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 and forced_param work as in the function lw6ldr_read.

Return value: 1 if success, 0 if failure.

— Function: int lw6ldr_rules_read (lw6map_rules_t * rules, char * dirname)

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.

— Function: int lw6ldr_rules_update (lw6map_rules_t * rules, lw6sys_assoc_t * values)

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.

— Function: int lw6ldr_style_read (lw6map_style_t * style, char * dirname)

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.

— Function: int lw6ldr_style_set (lw6map_style_t * style, char * key, char * value)

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.

— Function: int lw6ldr_style_update (lw6map_style_t * style, lw6sys_assoc_t * values)

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.

— Function: int lw6ldr_test (int mode)

mode: 0 for check only, 1 for full test

Runs the ldr module test suite.

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

— Function: int lw6ldr_use_update (lw6ldr_use_t * use, lw6sys_assoc_t * values)

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.