Next: libmap, Previous: libker, Up: C API

### 5.25 libldr

#### 5.25.1 Overview

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

#### 5.25.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: lw6ldr_entry_t * lw6ldr_dup_entry (lw6ldr_entry_t * entry)

> entry: the entry to dup

> Dup a map entry.

> Return value: newly allocated object.

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

> map_path: the map_path environment config variable, delimited path list

> relative_path: the relative path to use to find the map directory

> user_dir: the user 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, char * user_dir, 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

> user_dir: the user 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: lw6ldr_entry_t * lw6ldr_chain_entry (char * map_path, char * relative_path, char * user_dir)

> map_path: the map_path environment config variable, delimited path list

> relative_path: the relative path to use to find the map directory

> user_dir: the user directory

> Gets the next entry used in test programs.

> Return value: none.

— Function: int lw6ldr_exp_validate (lw6map_level_t * level, char * user_dir)

> level: the level to validate

> user_dir: user directory

> Validates a level, acknowledges you've won it. Upgrades exp.

> Return value: 1 on success, 0 on failure.

— 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: void lw6ldr_hints_defaults (lw6ldr_hints_t * hints)

> hints: data to initialize

> Set the hints struct to its defaults.

> Return value: none.

— Function: void lw6ldr_hints_zero (lw6ldr_hints_t * hints)

> hints: data to initialize

> Zeros the hints struct, this is not the same as setting to defaults.

> Return value: none.

— Function: void lw6ldr_hints_clear (lw6ldr_hints_t * hints)

> hints: data to initialize

> Clears the hints struct, this is not the same as setting to defaults.

> Return value: none.

— 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: char * lw6ldr_hints_get (lw6ldr_hints_t * hints, char * key)

> hints: the hints to modify

> key: the key to modify

> Gets one single parameter in a hints structure. Value is converted as a string.

> Return value: dynamically allocated string, NULL on error.

— Function: char * lw6ldr_hints_get_default (char * key)

> key: the key we want informations about.

> Gets the default value for a given hints key.

> Return value: dynamically allocated string, NULL on error.

— 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_metadata_read (lw6map_metadata_t * metadata, char * dirname)

> metadata: structure containting read data (out param)

> dirname: map dirname (absolute path)

> Reads the metadata, will first parse metadata.xml, and if not available read README and guess a title from map path. When function returns, all fields in structure are non-NULL.

> Return value: 1 on success, 0 on failure.

— 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: void lw6ldr_print_example_teams_xml (FILE * f)

> f: file to output content to

> Print to a file a typical map teams.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, char * user_dir, 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

> user_dir: the user directory

> 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, char * user_dir, 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

> user_dir: the user directory

> 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: void lw6ldr_resampler_init (lw6ldr_resampler_t * resampler, lw6map_param_t * param, lw6ldr_hints_t * hints, int source_w, int source_h, int display_w, int display_h, float target_ratio, int bench_value, int magic_number, int expected_depth, float gray_level)

> resampler: resampler object to init

> param: map parameters to use

> hints: loading hints

> source_w: width of source map

> source_h: height of source map

> display_w: width of source display

> display_h: height of source display

> target_ratio: ratio, that is width/height of the target

> bench_value: rough estimation of this computer power

> magic_number: arbitrary constant, needed to calibrate speed

> expected_depth: how thick the map could be (in practice, looks like d in whd)

> gray_level: used to estimate capacity, 1.0f is white and means many slots

> Initializes a resampler. There is wizardry based on the bench, magic number map size, gray level. This is bot bullet proof, but has been experience driven and is the result of many tries / failures and hopefully successes. Might need tuning as the algorithm evolves. This is the very function that chooses the actual logical map size.

> Return value: none.

— Function: void lw6ldr_resampler_force (lw6ldr_resampler_t * resampler, int source_w, int source_h, int target_w, int target_h)

> resampler: resampler to set

> source_w: source map width

> source_h: source map height

> target_w: target map width

> target_h: target map height

> Initializes a resampler with hardcoded values, does not calibrate according to context, simply set it to rescale the size you want.

> Return value: none.

— Function: void lw6ldr_resampler_source2target (lw6ldr_resampler_t * resampler, int * target_x, int * target_y, int source_x, int source_y)

> target_x: target x coordinate (out param)

> target_y: target y coordinate (out param)

> source_x: source x coordinate (in param)

> source_y: source y coordinate (in param)

> Transforms from source coordinate to target coordinates. Does rounding fine-tuning, it's not a simple integer division.

> Return value: none.

— Function: void lw6ldr_resampler_target2source (lw6ldr_resampler_t * resampler, int * source_x, int * source_y, int target_x, int target_y)

> source_x: source x coordinate (out param)

> source_y: source y coordinate (out param)

> target_x: target x coordinate (in param)

> target_y: target y coordinate (in param)

> Transforms from target coordinate to source coordinates. Yes, target to source. Target is our final logical map, source is what we loaded from disk, here we want to know, given a point in the target, where to fetch its data from source. Does rounding fine-tuning, it's not a simple integer division.

> Return value: none.

— 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_teams_read (lw6map_teams_t * teams, char * dirname)

> dirname: the directory of the map

> Read the teams (teams.xml) of a map. Pointer to teams 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_teams_update (lw6map_teams_t * teams, lw6sys_assoc_t * values)

> teams: the teams struct to fill with values (read/write parameter)

> values: an assoc containing strings with the new values

> Overrides teams with values. Pointer to teams 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 teams.

> 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_texture_read (lw6map_texture_t * texture, char * dirname, lw6map_param_t * param, lw6ldr_hints_t * hints, int use_texture, int display_w, int display_h, float * ratio, int * texture_exists, lw6sys_progress_t * progress)

> texture: structure to hold read data

> dirname: map dirname (absolute path)

> param: parameters to use

> hints: loading hints to use

> use_texture: wether to use texture.png

> display_w: display width

> display_h: display height

> ratio: target width/height factor (out param)

> texture_exists: true if texture.png is here (out param)

> progress: progress indicator (in/out param)

> Read the texture associated to a map. Pointer to texture must be valid, it's modified in-place. The function will automatically figure out if texture.png exists or if we must use foreground.png/background.png.

> Return value: 1 on success, 0 on failure.

— Function: void lw6ldr_use_defaults (lw6ldr_use_t * use)

> use: struct to initialize

> Sets the use structure to its defaults, this structure being used to now wether we should use texture, cursor textures, rules, hints, style, teams and music.

> Return value: none.

— Function: void lw6ldr_use_clear (lw6ldr_use_t * use)

> use: struct to clear

> Clears the use structure, set it to the use nothing mode.

> Return value: none.

— Function: int lw6ldr_use_set (lw6ldr_use_t * use, char * key, char * value)

> use: struct to modify

> key: key to change (as a string)

> value: value to set (as a string)

> Sets a key to the given value, OK all fields are integer, this is just a convenient function to be called in more general functions which are fed with those string pointers, typically coming from an XML file.

> Return value: 1 on success, 0 on failure (key not found).

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