Next: , Previous: libldr, Up: C API


5.26 libmap

5.26.1 Overview

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

5.26.2 API

— Function: void lw6map_body_builtin_custom (lw6map_body_t * body, int w, int h, int d, int noise_percent, lw6map_rules_t * rules)

body: the body to initialize

w: the width

h: the height

d: the depth

noise_percent: the noise level to fill meta layers with

rules: the map rules

Sets up a default body structure.

Return value: none

— Function: void lw6map_body_clear (lw6map_body_t * body)

body: the structure to clear

Clears a body structure.

Return value: none.

— Function: void lw6map_body_fix_checksum (lw6map_body_t * body)

body: the structure to update

Updates (calculates) the checksum of a map body structure.

Return value: none.

— Function: int lw6map_body_check_and_fix_holes (lw6map_body_t * body, lw6map_rules_t * rules)

body: the structure to update

rules: the game rules

This (fundamental) function ensures that all playable areas in a map are connected. If isolated zones are found out, then they are marked as walls and not used any more.

Return value: none.

— Function: int lw6map_body_coord_from_texture (lw6map_level_t * level, int * body_x, int * body_y, int texture_x, int texture_y)

level: the level to work on

body_x: the body (logical) x coord

body_y: the body (logical) y coord

texture_x: the texture x coord

texture_y: the texture y coord

Gets body (logical) coords from texture position.

Return value: 1 on success, 0 on failure (out of bounds)

— Function: u_int8_t lw6map_body_get_with_texture_coord (lw6map_level_t * level, int texture_x, int texture_y, int z)

level: the level to work on

texture_x: the texture x coord

texture_y: the texture y coord

z: the z position (depth related)

Tells wether a given map position is free or not, but using texture coords.

Return value: 1 if position is playable, 0 if not (wall)

— Function: void lw6map_color_invert (lw6map_color_couple_t * color)

color: the color to invert

Inverts a color couple, that is, replace fg by bg and vice-versa.

Return value: none.

— Function: int lw6map_color_is_same (lw6map_color_couple_t * color1, lw6map_color_couple_t * color2)

color1: 1st color to compare

color2: 2nd color to compare

Compares two colors.

Return value: 1 if equal, 0 if not.

— Function: char * lw6map_team_color_index_to_key (int index)

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.

— Function: int lw6map_team_color_key_to_index (char * key)

key: key of the color, for instance "red"

The index of the color, between 0 & 9

Return value: an integer.

— Function: char * lw6map_team_color_index_to_label (int index)

index: index of the color between 0 & 9

Transforms a team color index into its readable string form, which can be used to display information to players.

Return value: a string, must *not* be freed.

— Function: void lw6map_cursor_texture_clear (lw6map_cursor_texture_t * cursor_texture)

cursor_texture: the cursor texture to clear

Clears a cursor texture (set it all transparent).

Return value: none

— Function: void lw6map_cursor_texture_builtin (lw6map_cursor_texture_t * cursor_texture)

cursor_texture: the cursor texture to clear

Sets a cursor texture to the builtin defauts, that is a circle that is black on the outside and gets white/transparent in the middle.

Return value: none

— Function: void lw6map_cursor_texture_layer_set (lw6map_cursor_texture_layer_t * cursor_texture_layer, int x, int y, lw6sys_color_8_t color)

cursor_texture_layer: the cursor texture_layer to change

x: x coord

y: y coord

color: the color

Sets a pixel in the cursor texture_layer.

Return value: none

— Function: lw6sys_color_8_t lw6map_cursor_texture_layer_get (lw6map_cursor_texture_layer_t * cursor_texture_layer, int x, int y)

cursor_texture_layer: the cursor texture_layer to query

x: x coord

y: y coord

Gets a pixel in the cursor texture_layer.

Return value: the color

— Function: lw6map_level_t * lw6map_dup (lw6map_level_t * source, lw6sys_progress_t * progress)

source: the map to copy

progress: to show advancement

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.

— Function: int lw6map_exp_get_highest_team_color_allowed (int exp)

exp: the player experience

Gets the highest color available for a given exp.

Return value: a color id

— Function: int lw6map_exp_get_highest_weapon_allowed (int exp)

exp: the player experience

Gets the highest weapon available for a given exp.

Return value: a weapon id

— Function: int lw6map_exp_is_team_color_allowed (lw6map_rules_t * rules, int team_color_id)

rules: set of rules to use

team_color_id: color id to test

Tests wether a team color is allowed for a given set of rules.

Return value: 1 if allowed, 0 if not.

— Function: int lw6map_exp_is_weapon_allowed (lw6map_rules_t * rules, int weapon_id)

rules: set of rules to use

weapon_id: weapon id to test

Tests wether a weapon is allowed for a given set of rules.

Return value: 1 if allowed, 0 if not.

— Function: int lw6map_exp_get_unlocked_team_color (int exp)

exp: exp to test

Get the unlocked team color for a given exp, if applyable.

Return value: -1 if nothing unlocked, else the team color

— Function: int lw6map_exp_get_unlocked_weapon (int exp)

exp: exp to test

Get the unlocked primary weapon for a given exp, if applyable.

Return value: -1 if nothing unlocked, else the weapon id

— Function: char * lw6map_to_hexa (lw6map_level_t * level)

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.

— Function: lw6map_level_t * lw6map_from_hexa (char * hexa)

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.

— Function: void lw6map_layer_builtin_custom (lw6map_layer_t * layer, int w, int h)

layer: the layer to init

w: width

h: height

Creates a default layer. This is mostly for testing purposes, the default layer is not empty, it contains a simplified map of the world.

Return value: none

— Function: void lw6map_layer_clear (lw6map_layer_t * layer)

layer: the layer to init

Clears a layer struct. This means freeing the pointer if it's non NULL and setting everything to 0.

Return value: none

— Function: lw6map_level_t * lw6map_new ()

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.

— Function: lw6map_level_t * lw6map_builtin_defaults ()

Creates a map, set to defaults. This is usefull mostly for testing. This builtin map has walls, paths, it's playable.

Return value: a newly allocated map.

— Function: lw6map_level_t * lw6map_builtin_custom (int w, int h, int d, int noise_percent)

w: the width of the map

h: the height of the map

d: the depth (number of layers) of the map

noise_percent: percentage of noise to use for metalayers

Creates a map, set to defaults. This is usefull mostly for testing. This one, unlike lw6map_builtin_defaults will let you give a width, height and a depth.

Return value: a newly allocated map.

— Function: void lw6map_free (lw6map_level_t * level)

Frees a map and releases all its internal ressources.

Return value: none.

— Function: int lw6map_memory_footprint (lw6map_level_t * level)

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

— Function: char * lw6map_repr (lw6map_level_t * level)

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.

— Function: int lw6map_is_same (lw6map_level_t * level_a, lw6map_level_t * level_b)

level_a: the first level to compare

level_b: the other level to compare

Compares two level structs, the idea is to compare the content, not only the pointers and level ids.

Return value: 1 if they're the same, 0 if not.

— Function: int lw6map_local_info_set_music_dir (lw6map_local_info_t * local_info, char * music_dir)

local_info: the structure to modify

music_dir: the new music_dir value

Sets the music_dir value, in a 'safe' manner, freeing any previous value and performing a string duplication.

Return value: 1 on success, 0 on failure.

— Function: void lw6map_local_info_clear (lw6map_local_info_t * local_info)

local_info: the structure to clear

Clears the local_info structure, before destroying a level for instance.

Return value: none

— Function: void lw6map_metadata_defaults (lw6map_metadata_t * metadata)

metadata: struct to set to defaults

Sets the metadata struct to defaults, this does not set fields to NULL/empty values, but rather fills it with data claiming, for instance, that this is a default map.

Return value: none.

— Function: void lw6map_metadata_clear (lw6map_metadata_t * metadata)

metadata: struct to clear

Clears a metadata, will expect it to be in a consistent state, that is either filled with proper values or completely zeroed.

Return value: none.

— Function: int lw6map_metadata_is_same (lw6map_metadata_t * metadata_a, lw6map_metadata_t * metadata_b)

metadata_a: first item to compare

metadata_b: second item to compare

Tells wether both metadata items contain the same values.

Return value: 1 if same, 0 if different.

— Function: void lw6map_meta_layer_set (lw6map_meta_layer_t * meta_layer, int x, int y, u_int8_t value)

meta_layer: the meta_layer structure

x: x coord

y: y coord

value: the value to set at this place

Simple setter for the meta_layer struct.

Return value: none

— Function: u_int8_t lw6map_meta_layer_get (lw6map_meta_layer_t * meta_layer, int x, int y)

meta_layer: the meta_layer structure

x: x coord

y: y coord

Simple getter for the meta_layer struct.

Return value: the value at this place

— Function: void lw6map_meta_layer_clear (lw6map_meta_layer_t * meta_layer)

meta_layer: the meta_layer to clear

Clears a meta_layer struct. This means freeing the pointer if it's non NULL and setting everything to 0.

Return value: none

— Function: int lw6map_meta_layer_builtin_custom (lw6map_meta_layer_t * meta_layer, int w, int h, int analog, int noise_percent, int seed)

meta_layer: the object to init

w: width

h: height

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

noise_percent: the quantity of noise to initialise the layer with

seed: a pseudo-random seed to feed the pseudo-random generator

Builds a custom metalyer, suitable for tests or demo, letting the choice of its size and the noise to fill it with. If noise is 100 then metalayer is "full". If noise is 0, then meta layer is empty.

Return value: 1 if OK, 0 on failure.

— Function: void lw6map_param_defaults (lw6map_param_t * param)

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

— Function: void lw6map_param_clear (lw6map_param_t * param)

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

— Function: void lw6map_param_copy (lw6map_param_t * dst, lw6map_param_t * src)

dst: the destination param struct

src: the source param struct

Copies parameters. Both structures must be zeroed or correctly initialized.

Return value: none

— Function: int lw6map_param_set (lw6map_param_t * param, char * key, char * value)

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, style and teams.

Return value: 1 if parameter successfully set, 0 on error.

— Function: char * lw6map_param_get (lw6map_param_t * param, char * key)

param: the param struct to query

key: the name of the parameter to get

Gets an entry from a param struct. All values returned as strings, do not use this in performance bottlenecks, this is just to export values to scripts, for instance.

Return value: dynamically allocated string, NULL on error, might return a string containing 0 on bad keys.

— Function: int lw6map_param_is_same (lw6map_param_t * param_a, lw6map_param_t * param_b)

param_a: one struct to compare

param_b: another struct to compare

Compares the contents of two param structs.

Return value: 1 if they contain the same thing, 0 if not

— Function: void lw6map_rules_defaults (lw6map_rules_t * rules)

rules: struct to set to defaults

Set rules to default values, as these are all integers, you can call this on any rules object.

Return value: none.

— Function: void lw6map_rules_copy (lw6map_rules_t * dst, lw6map_rules_t * src)

dst: destination (out param)

src: source (in param)

Copies the data from source to destination, simple wrapper on memcpy.

Return value: none.

— Function: void lw6map_rules_update_checksum (lw6map_rules_t * rules, u_int32_t * checksum)

rules: rules struct to check

checksum: checksum to update (in/out param)

Updates a checksum with the rules data.

Return value: none.

— Function: int32_t lw6map_rules_get_default (char * key)

key: key to query

Get the default value for a given string key. Of course you could access the member, but this function internally does the conversion between readable string and actual struct offset.

Return value: integer.

— Function: int32_t lw6map_rules_get_min (char * key)

key: key to query

Get the min value for a given string key. Of course you could access the member, but this function internally does the conversion between readable string and actual struct offset.

Return value: integer.

— Function: int32_t lw6map_rules_get_max (char * key)

key: key to query

Get the min value for a given string key. Of course you could access the member, but this function internally does the conversion between readable string and actual struct offset.

Return value: integer.

— Function: int32_t lw6map_rules_get_int (lw6map_rules_t * rules, char * key)

rules: struct to use

key: key to query

Get the value for a given string key, as an integer. Of course you could access the member, but this function internally does the conversion between readable string and actual struct offset.

Return value: integer.

— Function: int lw6map_rules_set_int (lw6map_rules_t * rules, char * key, int32_t value)

rules: struct to use

key: key to set

value: new integer value for key

Set the value for a given string key, as an integer. Of course you could access the member, but this function internally does the conversion between readable string and actual struct offset.

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

— Function: int lw6map_rules_get_bool (lw6map_rules_t * rules, char * key)

rules: struct to use

key: key to query

Get the value for a given string key, as a boolean. Of course you could access the member, but this function internally does the conversion between readable string and actual struct offset.

Return value: boolean.

— Function: int lw6map_rules_set_bool (lw6map_rules_t * rules, char * key, int value)

rules: struct to use

key: key to set

value: new boolean value for key

Set the value for a given string key, as a boolean. Of course you could access the member, but this function internally does the conversion between readable string and actual struct offset.

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

— Function: void lw6map_rules_clear (lw6map_rules_t * rules)

rules: struct to init

Set rules to 0, this is not defaults, this is 0 (probably unusable as a real-world setting).

Return value: none.

— Function: int lw6map_rules_is_same (lw6map_rules_t * rules_a, lw6map_rules_t * rules_b)

rules_a: first item to compare

rules_b: second item to compare

Compares two rules items. Will tell if they contain the same data.

Return value: 1 if same, 0 if different.

— Function: void lw6map_style_zero (lw6map_style_t * style)

style: struct to initialize

Sets a style struct to zero, simply puts zero everywhere without checking what was here before

Return value: none.

— Function: void lw6map_style_defaults (lw6map_style_t * style)

style: struct to modify

Sets a style struct to defaults values, expects the object to be in a consistent style, that's to say either containing real data or being zeroed.

Return value: none.

— Function: void lw6map_style_clear (lw6map_style_t * style)

style: struct to clear

Clears a style struct. This function won't work on an unitialized structure, structure must be zeroed by some CALLOC or something, else automatic freeing of pointers will fail.

Return value: none.

— Function: void lw6map_style_copy (lw6map_style_t * dst, lw6map_style_t * src)

dst: destination

src: source

Copies style data from source to destination. Like with clear, dst must be either initialized or totally zeroed, else function will fail (core dump)

Return value: none.

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

style: style struct to modify (out param)

key: key to use

value: value to use

Sets a style entry, takes string values and will identify the struct offset and convert the value to whatever C type is needed.

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

— Function: char * lw6map_style_get (lw6map_style_t * style, char * key)

style: style struct to query

key: key to use

Get a style entry, takes a string key and will identify the struct offset. The return value is converted to string, typically the cannonical representation suitable to write in an XML config file.

Return value: dynamically allocated string.

— Function: char * lw6map_style_get_default (char * key)

key: key to query

Get the default value for a style entry. This is quite a cost-expensive function given what it does, indeed it will convert anything to a string, and also perform key lookup to fetch the value.

Return value: dynamically allocated string.

— Function: int lw6map_color_set_is_same (lw6map_color_set_t * color_set_a, lw6map_color_set_t * color_set_b)

color_set_a: first item to compare

color_set_b: second item to compare

Compares two color sets, telling if they contain the same data.

Return value: 1 if same, 0 if different.

— Function: int lw6map_style_is_same (lw6map_style_t * style_a, lw6map_style_t * style_b)

style_a: first item to compare

style_b: second item to compare

Compares two style structures, telling if they contain the same data.

Return value: 1 if same, 0 if different.

— Function: void lw6map_teams_zero (lw6map_teams_t * teams)

teams: data to initialize

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

Return value: none.

— Function: void lw6map_teams_defaults (lw6map_teams_t * teams)

teams: data to initialize

Set the teams struct to its defaults.

Return value: none.

— Function: void lw6map_teams_clear (lw6map_teams_t * teams)

teams: data to initialize

Clears the teams struct, this is not the same as setting to defaults. This one supposes the struct has been properly initialized, at least zeroed before usage, it might contain pointers which should be freed.

Return value: none.

— Function: void lw6map_teams_copy (lw6map_teams_t * dst, lw6map_teams_t * src)

dst: destination

src: source

Copies the contents of the teams struct. It's a real duplicate, any string is reallocated.

Return value: none.

— Function: int lw6map_teams_set (lw6map_teams_t * teams, char * key, char * value)

teams: the teams to modify

key: the key to modify

value: the value to affect to the key, as a string

Sets one single parameter in a teams 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 * lw6map_teams_get (lw6map_teams_t * teams, char * key)

teams: the teams to modify

key: the key to modify

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

Return value: dynamically allocated string, NULL on error.

— Function: char * lw6map_teams_get_default (char * key)

key: the key we want informations about.

Gets the default value for a given teams key.

Return value: dynamically allocated string, NULL on error.

— Function: int lw6map_teams_is_same (lw6map_teams_t * teams_a, lw6map_teams_t * teams_b)

teams_a: one struct to compare

teams_b: another struct to compare

Compares the contents of two teams structs.

Return value: 1 if they contain the same thing, 0 if not

— Function: int lw6map_test (int mode)

mode: 0 for check only, 1 for full test

Runs the map module test suite.

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

— Function: int lw6map_texture_from_body (lw6map_texture_t * texture, lw6map_body_t * body, lw6map_color_couple_t * color)

texture: texture to load (out param)

body: body to pick data from

color: colors to use

Will create a default bicolor texture from the body data, this is in case we don't want to use the texture or there is none. Result is not beautifull but might be very comfortable to play.

Return value: 1 on success, 0 on failure.

— Function: void lw6map_texture_clear (lw6map_texture_t * texture)

texture: data to clear

Clears a texture object, expects it to be in a consitent state, either filled with real data of zeroed.

Return value: none.

— Function: int lw6map_texture_coord_from_body (lw6map_level_t * level, int * texture_x, int * texture_y, int body_x, int body_y)

level: map to work on

texture_x: texture x coordinate (out param)

texture_y: texture y coordinate (out param)

body_x: body x coordinate (in param)

body_y: body y coordinate (in param)

Translates from body coordinate space to texture coordinate space.

Return value: 1 on success, 0 if failure.

— Function: lw6sys_color_8_t lw6map_texture_get_with_body_coord (lw6map_level_t * level, int body_x, int body_y)

level: map to use

body_x: x coordinate in body space

body_y: y coordinate in body space

Get the color of a given point in the texture, using the body coordinate space.

Return value: RGBA 8-bit color.

— Function: int lw6map_texture_has_alpha (lw6map_texture_t * texture)

texture: texture object to test

Finds out if the texture is fully opaque or not. If it has an alpha layer (typically, PNG file) but this one is filled at 100% everywhere, then it will consider opaque. This is a slow function but the result is cached in the has_alpha member, so as the function is called at map loading, use the cached value instead.

Return value: 1 if has used alpha layer, 0 if opaque.

— Function: char * lw6map_weapon_index_to_key (int index)

index: index of the weapon between 0 & 19

Transforms a team weapon index into its readable string form, which can be used in config files for instance.

Return value: a string, must *not* be freed.

— Function: int lw6map_weapon_key_to_index (char * key)

key: key of the weapon, for instance "red"

The index of the weapon, between 0 & 19

Return value: an integer.

— Function: char * lw6map_weapon_index_to_label (int index)

index: index of the weapon between 0 & 19

Transforms a team weapon index into its readable string form, which can be used to display information to players.

Return value: a string, must *not* be freed.