terrain_builder Class Reference

The class terrain_builder is constructed from a config object, and a gamemap object. More...

#include <builder.hpp>

Collaboration diagram for terrain_builder:

Collaboration graph
[legend]

List of all members.

Public Types

enum  ADJACENT_TERRAIN_TYPE { ADJACENT_BACKGROUND, ADJACENT_FOREGROUND }
 Used as a parameter for the get_terrain_at function. More...
typedef std::vector< animated
< image::locator > > 
imagelist
 A shorthand typedef for a list of animated image locators, the base data type returned by the get_terrain_at method.
typedef std::map< std::string,
rule_image_variant
rule_image_variantlist
 A map associating a rule_image_variant to a string representing the time of day.
typedef std::vector< rule_imagerule_imagelist
 A shorthand notation for a vector of rule_images.

Public Member Functions

 terrain_builder (const config &cfg, const config &level, const gamemap &map, const std::string &offmap_image)
 Constructor for the terrain_builder class.
const imagelistget_terrain_at (const gamemap::location &loc, const std::string &tod, ADJACENT_TERRAIN_TYPE const terrain_type)
 Returns a vector of strings representing the images to load & blit together to get the built content for this tile.
bool update_animation (const gamemap::location &loc)
 Updates the animation at a given tile.
void rebuild_terrain (const gamemap::location &loc)
 Performs a "quick-rebuild" of the terrain in a given location.
void rebuild_all ()
 Performs a complete rebuild of the list of terrain graphics attached to a map.

Private Types

typedef std::map
< gamemap::location,
terrain_constraint
constraint_set
 The list of constraints attached to a terrain_graphics WML rule.
typedef std::multimap< int,
building_rule
building_ruleset
 A set of building rules.
typedef std::multimap< int,
gamemap::location
anchormap
typedef std::map
< t_translation::t_terrain,
std::vector< gamemap::location > > 
terrain_by_type_map
 Shorthand typedef for a map associating a list of locations to a terrain type.

Private Member Functions

bool rule_valid (const building_rule &rule) const
 Tests for validity of a rule.
bool start_animation (building_rule &rule)
 Starts the animation on a rule.
terrain_constraint rotate (const terrain_constraint &constraint, int angle)
 "Rotates" a constraint from a rule.
void replace_token (std::string &s, const std::string &token, const std::string &replacement)
 Replaces, in a given string, a token with its value.
void replace_token (rule_image &image, const std::string &token, const std::string &replacement)
 Replaces, in a given rule_image, a token with its value.
void replace_token (rule_image_variant &variant, const std::string &token, const std::string &replacement)
 Replaces, in a given rule_variant_image, a token with its value.
void replace_token (rule_imagelist &, const std::string &token, const std::string &replacement)
 Replaces, in a given rule_imagelist, a token with its value.
void replace_token (building_rule &s, const std::string &token, const std::string &replacement)
 Replaces, in a given building_rule, a token with its value.
building_rule rotate_rule (const building_rule &rule, int angle, const std::vector< std::string > &angle_name)
 Rotates a template rule to a given angle, and returns the rotated rule.
void add_images_from_config (rule_imagelist &images, const config &cfg, bool global, int dx=0, int dy=0)
 Parses a "config" object, which should contains [image] children, and adds the corresponding parsed rule_images to a rule_imagelist.
void add_constraints (constraint_set &constraints, const gamemap::location &loc, const t_translation::t_match &type, const config &global_images)
 Creates a rule constraint object which matches a given list of terrains, and adds it to the list of constraints of a rule.
void add_constraints (constraint_set &constraints, const gamemap::location &loc, const config &cfg, const config &global_images)
 Creates a rule constraint object from a config object and adds it to the list of constraints of a rule.
void parse_mapstring (const std::string &mapstring, struct building_rule &br, anchormap &anchors, const config &global_images)
 Parses a map string (the map= element of a [terrain_graphics] rule, and adds constraints from this map to a building_rule.
void add_rule (building_ruleset &rules, building_rule &rule)
 Adds a rule to a ruleset.
void add_rotated_rules (building_ruleset &rules, building_rule &tpl, const std::string &rotations)
 Adds a set of rules to a ruleset, from a template rule which spans 6 rotations (or less if some of the rotated rules are invalid).
void parse_config (const config &cfg)
 Parses a configuration object containing [terrain_graphics] rules, and fills the building_rules_ member of the current class according to those.
void add_off_map_rule (const std::string &image)
 Adds a builder rule for the _off^_usr tile, this tile only has 1 image.
bool terrain_matches (t_translation::t_terrain tcode, const t_translation::t_list &terrains) const
 Checks whether a terrain code matches a given list of terrain codes.
bool terrain_matches (t_translation::t_terrain tcode, const t_translation::t_match &terrain) const
 Checks whether a terrain code matches a given list of terrain tcodes.
bool rule_matches (const building_rule &rule, const gamemap::location &loc, const int rule_index, const constraint_set::const_iterator type_checked) const
 Checks whether a rule matches a given location in the map.
void apply_rule (const building_rule &rule, const gamemap::location &loc)
 Applies a rule at a given location: applies the result of a matching rule at a given location: attachs the images corresponding to the rule, and sets the flags corresponding to the rule.
void build_terrains ()
 Calculates the list of terrains, and fills the tile_map_ member, from the gamemap and the building_rules_.

Private Attributes

const gamemapmap_
 A reference to the gamemap class used in the current level.
tilemap tile_map_
 The tile_map_ for the current level, which is filled by the build_terrains_ method to contain "tiles" representing images attached to each tile.
terrain_by_type_map terrain_by_type_
 A map representing all locations whose terrain is of a given type.
building_ruleset building_rules_

Classes

struct  building_rule
 The in-memory representation of a [terrain_graphics] WML rule. More...
struct  rule_image
 Each terrain_graphics rule is associated a set of images, which are applied on the terrain if the rule matches. More...
struct  rule_image_variant
 An image variant. More...
struct  terrain_constraint
 The in-memory representation of a [tile] WML rule inside of a [terrain_graphics] WML rule. More...
struct  tile
 Represents a tile of the game map, with all associated builder-specific parameters: flags, images attached to this tile, etc. More...
class  tilemap
 The map of "tile" structures corresponding to the level map. More...


Detailed Description

The class terrain_builder is constructed from a config object, and a gamemap object.

On construction, it parses the configuration and extracts the list of [terrain_graphics] rules. Each terrain_graphics rule attaches one or more images to a specific terrain pattern. It then applies the rules loaded from the configuration to the current map, and calculates the list of images that must be associated to each hex of the map.

The get_terrain_at method can then be used to obtain the list of images necessary to draw the terrain on a given tile.

Definition at line 42 of file builder.hpp.


Member Typedef Documentation

A shorthand typedef for a list of animated image locators, the base data type returned by the get_terrain_at method.

Definition at line 54 of file builder.hpp.

A map associating a rule_image_variant to a string representing the time of day.

Definition at line 162 of file builder.hpp.

A shorthand notation for a vector of rule_images.

Definition at line 198 of file builder.hpp.

The list of constraints attached to a terrain_graphics WML rule.

Definition at line 297 of file builder.hpp.

typedef std::multimap<int, building_rule> terrain_builder::building_ruleset [private]

A set of building rules.

In-memory representation of the whole set of [terrain_graphics] rules.

Definition at line 395 of file builder.hpp.

typedef std::multimap<int, gamemap::location> terrain_builder::anchormap [private]

Definition at line 587 of file builder.hpp.

Shorthand typedef for a map associating a list of locations to a terrain type.

Definition at line 713 of file builder.hpp.


Member Enumeration Documentation

Used as a parameter for the get_terrain_at function.

Enumerator:
ADJACENT_BACKGROUND  Represents terrains which are to be drawn behind unit sprites.
ADJACENT_FOREGROUND  Represents terrains which are to be drawn in front of them.

Definition at line 46 of file builder.hpp.


Constructor & Destructor Documentation

terrain_builder::terrain_builder ( const config cfg,
const config level,
const gamemap map,
const std::string &  offmap_image 
)

Constructor for the terrain_builder class.

Parameters:
cfg The main grame configuration object, where the [terrain_graphics] rule reside.
level A level (scenario)-specific configuration file, containing scenario-specific [terrain_graphics] rules.
map A properly-initialized gamemap object representing the current terrain map.
offmap_image The filename of the image which will be used as off map image (see add_off_map_rule()). This image automatically gets the 'terrain/' prefix and '.png' suffix

Definition at line 145 of file builder.cpp.

References add_off_map_rule(), build_terrains(), and parse_config().


Member Function Documentation

const terrain_builder::imagelist * terrain_builder::get_terrain_at ( const gamemap::location loc,
const std::string &  tod,
ADJACENT_TERRAIN_TYPE const   terrain_type 
)

Returns a vector of strings representing the images to load & blit together to get the built content for this tile.

Parameters:
loc The location relative the the terrain map, where we ask for the image list
tod The string representing the current time-of day. Will be used if some images specify several time-of-day- related variants.
terrain_type ADJACENT_BACKGROUND or ADJACENT_FOREGROUND, depending on wheter we ask for the terrain which is before, or after the unit sprite.
Returns:
Returns a pointer list of animated images corresponding to the parameters, or NULL if there is none.

Definition at line 163 of file builder.cpp.

References ADJACENT_BACKGROUND, ADJACENT_FOREGROUND, terrain_builder::tile::images_background, terrain_builder::tile::images_foreground, terrain_builder::tile::last_tod, terrain_builder::tilemap::on_map(), terrain_builder::tile::rebuild_cache(), and tile_map_.

Referenced by display::get_terrain_images().

bool terrain_builder::update_animation ( const gamemap::location loc  ) 

Updates the animation at a given tile.

Returns true if something has changed, and must be redrawn.

Parameters:
loc the location to update
Return values:
true,: this tile must be redrawn.

Definition at line 189 of file builder.cpp.

References terrain_builder::tilemap::on_map(), and tile_map_.

Referenced by game_display::invalidate_animations().

void terrain_builder::rebuild_terrain ( const gamemap::location loc  ) 

Performs a "quick-rebuild" of the terrain in a given location.

The "quick-rebuild" is no proper rebuild: it only clears the terrain cache for a given location, and replaces it with a single, default image for this terrain.

Parameters:
loc the location where to rebuild terrains
Todo:
TODO: rename this function

Definition at line 216 of file builder.cpp.

References animated< T, T_void_value >::add_frame(), gamemap::get_terrain(), gamemap::get_terrain_info(), terrain_builder::tile::images_background, terrain_builder::tile::images_foreground, map_, terrain_builder::tilemap::on_map(), animated< T, T_void_value >::start_animation(), and tile_map_.

Referenced by editor_display::rebuild_terrain().

void terrain_builder::rebuild_all (  ) 

Performs a complete rebuild of the list of terrain graphics attached to a map.

Should be called when a terrain is changed in the map.

Definition at line 242 of file builder.cpp.

References build_terrains(), terrain_builder::tilemap::reset(), terrain_by_type_, and tile_map_.

Referenced by display::rebuild_all().

bool terrain_builder::rule_valid ( const building_rule rule  )  const [private]

Tests for validity of a rule.

A rule is considered valid if all its images are present. This method is used, when building the ruleset, to only add rules which are valid to the ruleset.

Parameters:
rule The rule to test for validity
Returns:
true if the rule is valid, false if it is not.

Definition at line 249 of file builder.cpp.

References terrain_builder::building_rule::constraints, and image::exists().

Referenced by add_rule().

bool terrain_builder::start_animation ( building_rule rule  )  [private]

Starts the animation on a rule.

Parameters:
rule The rule on which ot start animations
Returns:
true

Definition at line 280 of file builder.cpp.

References terrain_builder::building_rule::constraints, utils::split(), and animated< T, T_void_value >::start_animation().

Referenced by add_rule().

terrain_builder::terrain_constraint terrain_builder::rotate ( const terrain_constraint constraint,
int  angle 
) [private]

"Rotates" a constraint from a rule.

Takes a template constraint from a template rule, and creates a constraint from this template, rotated to the given angle.

On a constraint, the relative position of each rule, and the "base" of each vertical images, are rotated according to the given angle.

Template terrain constraints are defined like normal terrain constraints, except that, flags, and image filenames, may contain template strings of the form

	 *  <code>@Rn</code>,
	 *
n being a number from 0 to 5. See the rotate_rule method for more info.

Parameters:
constraint A template constraint to rotate
angle An int, from 0 to 5, representing the rotation angle.

Definition at line 329 of file builder.cpp.

References terrain_builder::terrain_constraint::images, terrain_builder::terrain_constraint::loc, TILEWIDTH, gamemap::location::x, and gamemap::location::y.

Referenced by rotate_rule().

void terrain_builder::replace_token ( std::string &  s,
const std::string &  token,
const std::string &  replacement 
) [private]

Replaces, in a given string, a token with its value.

Parameters:
s The string in which to do the replacement
token The token to substitute
replacement The replacement string

Definition at line 412 of file builder.cpp.

References ERR_NG, and pos.

Referenced by replace_token(), and rotate_rule().

void terrain_builder::replace_token ( terrain_builder::rule_image image,
const std::string &  token,
const std::string &  replacement 
) [private]

Replaces, in a given rule_image, a token with its value.

The actual substitution is done in all variants of the given image.

Parameters:
image The rule_image in which to do the replacement
token The token to substitute
replacement The replacement string

Definition at line 425 of file builder.cpp.

References replace_token(), and terrain_builder::rule_image::variants.

void terrain_builder::replace_token ( rule_image_variant variant,
const std::string &  token,
const std::string &  replacement 
) [inline, private]

Replaces, in a given rule_variant_image, a token with its value.

The actual substitution is done in the "image_string" parameter of this rule_variant_image.

Parameters:
variant The rule_variant_image in which to do the replacement
token The token to substitute
replacement The replacement string

Definition at line 469 of file builder.hpp.

References terrain_builder::rule_image_variant::image_string, and replace_token().

void terrain_builder::replace_token ( terrain_builder::rule_imagelist list,
const std::string &  token,
const std::string &  replacement 
) [private]

Replaces, in a given rule_imagelist, a token with its value.

The actual substitution is done in all rule_images contained in the rule_imagelist.

Parameters:
& The rule_imagelist in which to do the replacement
token The token to substitute
replacement The replacement string

Definition at line 434 of file builder.cpp.

References replace_token().

void terrain_builder::replace_token ( terrain_builder::building_rule rule,
const std::string &  token,
const std::string &  replacement 
) [private]

Replaces, in a given building_rule, a token with its value.

The actual substitution is done in the rule_imagelists contained in all constraints of the building_rule, and in the flags (has_flag, set_flag and no_flag) contained in all constraints of the building_rule.

Parameters:
s The building_rule in which to do the replacement
token The token to substitute
replacement The replacement string

Definition at line 443 of file builder.cpp.

References terrain_builder::building_rule::constraints, and replace_token().

terrain_builder::building_rule terrain_builder::rotate_rule ( const building_rule rule,
int  angle,
const std::vector< std::string > &  angle_name 
) [private]

Rotates a template rule to a given angle, and returns the rotated rule.

Template rules are defined like normal rules, except that: * Flags and image filenames may contain template strings of the form

	 *  <code>@Rn</code>, n being a number from 0 to 5.
	 *
* The rule contains the rotations=r0,r1,r2,r3,r4,r5, with r0 to r5 being strings describing the 6 different positions, typically, n, ne, se, s, sw, and nw (but maybe anything else.)

A template rule will generate 6 rules, which are similar to the template, except that:

* The map of constraints ( [tile]s ) of this rule will be rotated by an angle, of 0 to 5 pi / 6

* On the rule which is rotated to 0rad, the template strings

	 *    @R0, @R1, @R2, @R3, @R4, @R5,
	 *
will be replaced by the corresponding r0, r1, r2, r3, r4, r5 variables given in the rotations= element.

* On the rule which is rotated to pi/3 rad, the template strings

	 *    @R0, @R1, @R2 etc.
	 *
will be replaced by the corresponding r1, r2, r3, r4, r5, r0 (note the shift in indices).

* On the rule rotated 2pi/3, those will be replaced by r2, r3, r4, r5, r0, r1 and so on.

Definition at line 466 of file builder.cpp.

References a, terrain_builder::building_rule::constraints, ERR_NG, terrain_builder::terrain_constraint::loc, terrain_builder::building_rule::location_constraints, terrain_builder::building_rule::precedence, terrain_builder::building_rule::probability, push_back(), replace_token(), and rotate().

Referenced by add_rotated_rules().

void terrain_builder::add_images_from_config ( rule_imagelist images,
const config cfg,
bool  global,
int  dx = 0,
int  dy = 0 
) [private]

Parses a "config" object, which should contains [image] children, and adds the corresponding parsed rule_images to a rule_imagelist.

Parameters:
images The rule_imagelist into which to add the parsed images.
cfg The WML configuration object to parse
global Whether those [image]s elements belong to a [terrain_graphics] element, or to a [tile] child. Set to true if those belong to a [terrain_graphics] element.
dx The X coordinate of the constraint those images apply to, relative to the start of the rule. Only meaningful if global is set to false.
dy The Y coordinate of the constraint those images apply to.

Definition at line 517 of file builder.cpp.

References config::get_children(), name, utils::split(), and TILEWIDTH.

Referenced by add_constraints().

void terrain_builder::add_constraints ( terrain_builder::constraint_set constraints,
const gamemap::location loc,
const t_translation::t_match type,
const config global_images 
) [private]

Creates a rule constraint object which matches a given list of terrains, and adds it to the list of constraints of a rule.

Parameters:
constraints The constraint set to which to add the constraint.
loc The location of the constraint
type The list of terrains this constraint will match
global_images A configuration object containing [image] tags describing rule-global images.

Definition at line 569 of file builder.cpp.

References add_images_from_config(), about::images, t_translation::t_match::terrain, TILEWIDTH, gamemap::location::x, and gamemap::location::y.

Referenced by add_constraints(), parse_config(), and parse_mapstring().

void terrain_builder::add_constraints ( terrain_builder::constraint_set constraints,
const gamemap::location loc,
const config cfg,
const config global_images 
) [private]

Creates a rule constraint object from a config object and adds it to the list of constraints of a rule.

Parameters:
constraints The constraint set to which to add the constraint.
loc The location of the constraint
cfg The config object describing this constraint. Usually, a [tile] child of a [terrain_graphics] rule.
global_images A configuration object containing [image] tags describing rule-global images.

Definition at line 588 of file builder.cpp.

References add_constraints(), add_images_from_config(), terrain_builder::terrain_constraint::has_flag, terrain_builder::terrain_constraint::images, terrain_builder::terrain_constraint::no_flag, terrain_builder::terrain_constraint::set_flag, utils::split(), and t_translation::WILDCARD.

void terrain_builder::parse_mapstring ( const std::string &  mapstring,
struct building_rule br,
anchormap anchors,
const config global_images 
) [private]

Parses a map string (the map= element of a [terrain_graphics] rule, and adds constraints from this map to a building_rule.

Parameters:
mapstring The map vector to parse
br The building rule into which to add the extracted constraints
anchors A map where to put "anchors" extracted from the map.
global_images A config object representing the images defined as direct children of the [terrain_graphics] rule.

Definition at line 611 of file builder.cpp.

References add_constraints(), t_translation::t_terrain::base, terrain_builder::building_rule::constraints, ERR_NG, map, t_translation::NONE_TERRAIN, t_translation::t_terrain::overlay, t_translation::read_builder_map(), t_translation::STAR, t_translation::TB_DOT, t_translation::TB_STAR, and t_translation::write_terrain_code().

Referenced by parse_config().

void terrain_builder::add_rule ( building_ruleset rules,
building_rule rule 
) [private]

Adds a rule to a ruleset.

Checks for validity before adding the rule.

Parameters:
rules The ruleset into which to add the rules.
rule The rule to add.

Definition at line 658 of file builder.cpp.

References terrain_builder::building_rule::precedence, rule_valid(), and start_animation().

Referenced by add_rotated_rules().

void terrain_builder::add_rotated_rules ( building_ruleset rules,
building_rule tpl,
const std::string &  rotations 
) [private]

Adds a set of rules to a ruleset, from a template rule which spans 6 rotations (or less if some of the rotated rules are invalid).

Parameters:
rules The ruleset into which to add the rules.
tpl The template rule
rotations A comma-separated string containing the 6 values for replacing rotation template strings
(@Rn) 

Definition at line 666 of file builder.cpp.

References add_rule(), rotate_rule(), and utils::split().

Referenced by parse_config().

void terrain_builder::parse_config ( const config cfg  )  [private]

void terrain_builder::add_off_map_rule ( const std::string &  image  )  [private]

Adds a builder rule for the _off^_usr tile, this tile only has 1 image.

Parameters:
image The filename of the image

Definition at line 804 of file builder.cpp.

References config::add_child(), cfg, config::child(), t_translation::OFF_MAP_USER, parse_config(), and t_translation::write_terrain_code().

Referenced by terrain_builder().

bool terrain_builder::terrain_matches ( t_translation::t_terrain  tcode,
const t_translation::t_list terrains 
) const [inline, private]

Checks whether a terrain code matches a given list of terrain codes.

Parameters:
tcode The terrain to check
terrains The terrain list agains which to check the terrain. May contain the metacharacters
  • '*' STAR, meaning "all terrains"
  • '!' NOT, meaning "all terrains except those present in the list."
Returns:
returns true if "tcode" matches the list or the list is empty, else false.

Definition at line 651 of file builder.hpp.

References t_translation::terrain_matches().

Referenced by build_terrains(), and rule_matches().

bool terrain_builder::terrain_matches ( t_translation::t_terrain  tcode,
const t_translation::t_match terrain 
) const [inline, private]

Checks whether a terrain code matches a given list of terrain tcodes.

Parameters:
tcode The terrain code to check
terrain The terrain match structure which to check the terrain. See previous definition for more details.
Returns:
returns true if "tcode" matches the list or the list is empty, else false.

Definition at line 664 of file builder.hpp.

References t_translation::t_match::is_empty, and t_translation::terrain_matches().

bool terrain_builder::rule_matches ( const building_rule rule,
const gamemap::location loc,
const int  rule_index,
const constraint_set::const_iterator  type_checked 
) const [private]

Checks whether a rule matches a given location in the map.

Parameters:
rule The rule to check.
loc The location in the map where we want to check whether the rule matches.
rule_index The index of the rule, relative to the start of the rule list. Rule indices are used for seeding the pseudo-random-number generator used for probability calculations.
type_checked The constraint which we already know that its terrain types matches.

Definition at line 831 of file builder.cpp.

References a, b, terrain_builder::building_rule::constraints, terrain_builder::tile::flags, gamemap::get_terrain(), terrain_builder::building_rule::location_constraints, map_, terrain_builder::tilemap::on_map(), terrain_builder::building_rule::probability, terrain_matches(), tile_map_, gamemap::location::valid(), gamemap::location::x, and gamemap::location::y.

Referenced by build_terrains().

void terrain_builder::apply_rule ( const building_rule rule,
const gamemap::location loc 
) [private]

Applies a rule at a given location: applies the result of a matching rule at a given location: attachs the images corresponding to the rule, and sets the flags corresponding to the rule.

Parameters:
rule The rule to apply
loc The location to which to apply the rule.

Definition at line 890 of file builder.cpp.

References BASE_Y_INTERVAL, terrain_builder::building_rule::constraints, terrain_builder::tile::flags, terrain_builder::tile::images, terrain_builder::tilemap::on_map(), and tile_map_.

Referenced by build_terrains().

void terrain_builder::build_terrains (  )  [private]

Calculates the list of terrains, and fills the tile_map_ member, from the gamemap and the building_rules_.

Definition at line 920 of file builder.cpp.

References apply_rule(), building_rules_, terrain_builder::building_rule::constraints, gamemap::get_terrain(), gamemap::h(), loc, log_scope, map_, r, rule_matches(), terrain_by_type_, terrain_matches(), and gamemap::w().

Referenced by rebuild_all(), and terrain_builder().


Member Data Documentation

const gamemap& terrain_builder::map_ [private]

A reference to the gamemap class used in the current level.

Definition at line 702 of file builder.hpp.

Referenced by build_terrains(), rebuild_terrain(), and rule_matches().

The tile_map_ for the current level, which is filled by the build_terrains_ method to contain "tiles" representing images attached to each tile.

Definition at line 708 of file builder.hpp.

Referenced by apply_rule(), get_terrain_at(), rebuild_all(), rebuild_terrain(), rule_matches(), and update_animation().

A map representing all locations whose terrain is of a given type.

Definition at line 718 of file builder.hpp.

Referenced by build_terrains(), and rebuild_all().

Definition at line 720 of file builder.hpp.

Referenced by build_terrains(), and parse_config().


The documentation for this class was generated from the following files:

Generated by doxygen 1.5.5 on 23 May 2008 for The Battle for Wesnoth
Gna! | Forum | Wiki | CIA | devdocs