Draws terrain sprites on the map. More...

#include <layer_terrain.h>

Inheritance diagram for freeciv::layer_terrain:

Collaboration diagram for freeciv::layer_terrain:

Classes
struct	matching_group

struct	terrain_info

Public Types
enum	sprite_type { CELL_WHOLE , CELL_CORNER , CELL_HEX_CORNER }
	Indicates how many sprites are used to draw a tile. More...

Public Member Functions
	layer_terrain (struct tileset *ts, int number)

virtual	~layer_terrain ()=default

bool	create_matching_group (const QString &name)
	Creates a matching group with the given name. More...

bool	add_tag (const QString &tag, const QString &sprite_name)
	Makes a terrain tag available for use by this layer. More...

bool	set_tag_sprite_type (const QString &tag, sprite_type type)
	Sets the type of sprite used to draw the specified tag. More...

bool	set_tag_offsets (const QString &tag, int offset_x, int offset_y)
	Sets the offsets used to draw the specified tag. More...

bool	set_tag_matching_group (const QString &tag, const QString &group_name)
	Sets the matching group for the specified tag. More...

bool	set_tag_matches_with (const QString &tag, const QString &group_name)
	Sets the specified tag to be matched against a group. More...

void	enable_blending (const QString &tag)
	Enable blending on this layer for the given terrain tag. More...

void	initialize_terrain (const terrain *terrain) override
	Sets up the structure to draw the specified terrain. More...

std::vector< drawn_sprite >	fill_sprite_array (const tile ptile, const tile_edge pedge, const tile_corner pcorner, const unit punit) const override
	Returns the list of sprites drawn by this layer somewhere on the map. More...

Public Member Functions inherited from freeciv::layer
	layer (struct tileset *ts, mapview_layer layer)
	Constructor. More...

virtual	~layer ()=default
	Destructor. More...

virtual void	load_sprites ()
	Loads all sprites that do not depend on the ruleset. More...

virtual void	initialize_player (const player *player)
	Initializes data specific to one player. More...

virtual void	free_player (int player_id)
	Frees data initialized by initialize_player. More...

virtual void	initialize_city_style (const citystyle &style, int index)
	Initializes data for a city style. More...

virtual void	initialize_extra (const extra_type *extra, const QString &tag, extrastyle_id style)
	Initializes extra-specific data. More...

virtual void	reset_ruleset ()
	Resets cached data that depends on the ruleset. More...

mapview_layer	type () const

Static Public Attributes
constexpr static auto	MAX_NUM_MATCH_WITH = 8

Private Types
enum	match_style { MATCH_NONE , MATCH_SAME , MATCH_PAIR , MATCH_FULL }

Private Member Functions
matching_group *	group (const QString &name)
	Retrieves the group structure of the provided name. More...

void	initialize_cell_whole_match_none (const terrain *terrain, terrain_info &info)
	Sets up terrain information for CELL_WHOLE and `MATCH_SAME`. More...

void	initialize_cell_whole_match_same (const terrain *terrain, terrain_info &info)
	Sets up terrain information for CELL_WHOLE and `MATCH_SAME`. More...

void	initialize_cell_corner_match_none (const terrain *terrain, terrain_info &info)
	Sets up terrain information for CELL_CORNER and `MATCH_NONE`. More...

void	initialize_cell_corner_match_same (const terrain *terrain, terrain_info &info)
	Sets up terrain information for CELL_CORNER and `MATCH_SAME`. More...

void	initialize_cell_corner_match_pair (const terrain *terrain, terrain_info &info)
	Sets up terrain information for CELL_CORNER and `MATCH_PAIR`. More...

void	initialize_cell_corner_match_full (const terrain *terrain, terrain_info &info)
	Sets up terrain information for CELL_CORNER and `MATCH_FULL`. More...

void	initialize_cell_hex_corner (const terrain *terrain, terrain_info &info)
	Sets up terrain information for CELL_HEX_CORNER. More...

void	initialize_blending (const terrain *terrain, terrain_info &info)
	Initializes blending sprites. More...

int	terrain_group (const terrain *pterrain) const
	Retrieves the group number for a given terrain. More...

void	fill_terrain_sprite_array (std::vector< drawn_sprite > &sprs, const tile ptile, const terrain pterrain, terrain **tterrain_near) const
	Helper function for fill_sprite_array. More...

void	fill_blending_sprite_array (std::vector< drawn_sprite > &sprs, const tile ptile, const terrain pterrain, terrain **tterrain_near) const
	Helper function for fill_sprite_array. More...

Private Attributes
int	m_number = 0

std::vector< std::unique_ptr< QPixmap > >	m_allocated
	List of those sprites in 'cells' that are allocated by some other means than load_sprite() and thus are not freed by unload_all_sprites(). More...

std::map< QChar, matching_group >	m_matching_groups

std::map< QString, terrain_info >	m_terrain_tag_info
	Before terrains are loaded, this contains the list of available terrain tags. More...

std::map< int, terrain_info >	m_terrain_info
	Every terrain drawn in this layer appears here. More...

Additional Inherited Members
Protected Member Functions inherited from freeciv::layer
struct tileset *	tileset () const

bool	do_draw_unit (const tile ptile, const unit punit) const
	Whether a unit should be drawn. More...

bool	solid_background (const tile ptile, const unit punit, const city *pcity) const
	Whether a solid background should be drawn on a tile instead of its terrain. More...

QPixmap *	load_sprite (const QStringList &possible_names, bool required=false, bool verbose=true) const
	Shortcut to load a sprite from the tileset. More...

Detailed Description

Draws terrain sprites on the map.

Terrain layers are a core feature of the map. They are used to draw sprites representing terrain. Up to three layers can be used. Within each layer, one can choose how each terrain will be drawn.

The configuration is based on tags that are used when constructing sprite identifiers. Tags represent sets of related sprites that, drawn in a specific way, construct the visual representation of a tile. The tag used to represent a terrain is taken from its graphic_str or graphic_alt properties.

Each tag has a set of properties that influence how sprites are drawn. The offsets at which the sprites are drawn is set using set_tag_offsets. The tiles can be drawn in two ways: either a single sprite is used for the whole tile (CELL_WHOLE), or one sprite is used to draw each corner of the tile (CELL_CORNER). This is set with set_tag_sprite_type. "Matching" with adjacent terrain types provides a powerful mechanism for sophisticated effects. For isometric tilesets, it is also possible to use a mask to blend adjacent tiles together with enable_blending.

Matching

The sprites used to draw a tile can depend on adjacent terrains, allowing the representation of continuous coasts, ridges and other edges.

To use tag matching, one first defines a number of terrain groups ("match type" in spec files). Groups are created with create_matching_group. Every tag must be in a group, set with set_tag_matching_group. The first letter of group names must be unique within a layer. Each tag can then be matched against any number of groups. There will be one sprite for each combination of groups next to the tile of interest.

The simplest matching is no matching, in which case the sprite used doesn't depend on adjacent terrain. This is available for both CELL_WHOLE and CELL_CORNER, although there is little use for the second. The sprite names for CELL_WHOLE are formed like t.l0.grassland1, where 0 is the layer number, grassland appears in the name of the tilespec section, and 1 is an index (when there are several sprites with indices 1, 2, 3, ..., one is picked at random). For CELL_CORNER, the names are like t.l0.grassland_cell_u, where u ("up") indicates the direction of the corner. It can be u ("up"), d ("down"), r ("right"), or l ("left").

When a tag is matched against one group, there are two possibilities:

The matched group is the same as the tag group. For CELL_WHOLE, this requires sprites with names like t.l0.grassland_n1e0s0w0, where the n1 indicates that the terrain in the north direction is in the same group as the tile that is being drawn, and the 0's indicate that other terrains are different. Sprites must be provided for all 16 combinations of 0's and 1's. Amplio2 forests and hills are drawn this way.

For CELL_CORNER, this requires 24 sprites with names like t.l0.grassland_cell_u010. t.l0.grassland_cell_u is like in the no match case, and 010 indicates which sides of the corner match the terrain being drawn. Amplio2 ice uses this method.
The matched group is different from the tag group (only supported for CELL_CORNER). There are again 24 sprites, this time with names like t.l0.grassland_cell_u_a_a_b. The first letter, in this example u, is the direction of the corner. The other three indicate which terrains are found on the three external sides of the corner. They are the first letter of the name of a matching group: the group being matched against if the adjacent terrain is of that group, and otherwise the group of the sprite being drawn. The coasts of Amplio2 lakes use this method.

When more than one group is used, which is only supported for CELL_CORNER, the sprites are named like t.l0.cellgroup_a_b_c_d. Each sprite represents the junction of four tiles with the group names first letters a, b, c, and d. Each sprite is split in four to provide four corner sprites. Amplio2 coasts are drawn this way.

Definition at line 27 of file layer_terrain.h.

Member Enumeration Documentation

◆ match_style

enum freeciv::layer_terrain::match_style

private

Enumerator
MATCH_NONE
MATCH_SAME
MATCH_PAIR
MATCH_FULL

Definition at line 42 of file layer_terrain.h.

◆ sprite_type

enum freeciv::layer_terrain::sprite_type

Indicates how many sprites are used to draw a tile.

Enumerator
CELL_WHOLE	One sprite for the entire tile.
CELL_CORNER	One sprite for each corner of the tile.
CELL_HEX_CORNER	One sprite for each hexagonal corner of the tile.

Definition at line 30 of file layer_terrain.h.

Constructor & Destructor Documentation

◆ layer_terrain()

freeciv::layer_terrain::layer_terrain	(	struct tileset *	ts,
		int	number
	)

explicit

Definition at line 109 of file layer_terrain.cpp.

◆ ~layer_terrain()

virtual freeciv::layer_terrain::~layer_terrain ( )

virtualdefault

Member Function Documentation

◆ add_tag()

bool freeciv::layer_terrain::add_tag	(	const QString &	tag,
		const QString &	sprite_name
	)

Makes a terrain tag available for use by this layer.

This function only makes the tag available. Its properties must be set using the set_tag_* functions.

Returns: True if the tag did not exist.

Definition at line 149 of file layer_terrain.cpp.

◆ create_matching_group()

bool freeciv::layer_terrain::create_matching_group ( const QString & name )

Creates a matching group with the given name.

Returns: Whether the operation succeeded.

Definition at line 118 of file layer_terrain.cpp.

◆ enable_blending()

void freeciv::layer_terrain::enable_blending ( const QString & tag )

Enable blending on this layer for the given terrain tag.

Definition at line 226 of file layer_terrain.cpp.

◆ fill_blending_sprite_array()

void freeciv::layer_terrain::fill_blending_sprite_array	(	std::vector< drawn_sprite > &	sprs,
		const tile *	ptile,
		const terrain *	pterrain,
		terrain **	tterrain_near
	)		const

private

Helper function for fill_sprite_array.

Fill in the sprite array for blended terrain.

This function assumes that m_blending contains a value for pterrain.

Definition at line 1015 of file layer_terrain.cpp.

Referenced by fill_sprite_array().

◆ fill_sprite_array()

std::vector< drawn_sprite > freeciv::layer_terrain::fill_sprite_array	(	const tile *	ptile,
		const tile_edge *	pedge,
		const tile_corner *	pcorner,
		const unit *	punit
	)		const

overridevirtual

Returns the list of sprites drawn by this layer somewhere on the map.

Only one of ptile, pedge, or pcorner should be non-null.

Reimplemented from freeciv::layer.

Definition at line 708 of file layer_terrain.cpp.

◆ fill_terrain_sprite_array()

void freeciv::layer_terrain::fill_terrain_sprite_array	(	std::vector< drawn_sprite > &	sprs,
		const tile *	ptile,
		const terrain *	pterrain,
		terrain **	tterrain_near
	)		const

private

Helper function for fill_sprite_array.

Definition at line 818 of file layer_terrain.cpp.

Referenced by fill_sprite_array().

◆ group()

layer_terrain::matching_group * freeciv::layer_terrain::group ( const QString & name )

private

Retrieves the group structure of the provided name.

Parameters

name	The name to look for.

Returns: The terrain group structure, or nullptr on failure.

Definition at line 756 of file layer_terrain.cpp.

Referenced by fill_terrain_sprite_array(), set_tag_matches_with(), set_tag_matching_group(), and terrain_group().

◆ initialize_blending()

void freeciv::layer_terrain::initialize_blending	(	const terrain *	terrain,
		terrain_info &	info
	)

private

Initializes blending sprites.

Definition at line 655 of file layer_terrain.cpp.

Referenced by initialize_terrain().

◆ initialize_cell_corner_match_full()

void freeciv::layer_terrain::initialize_cell_corner_match_full	(	const terrain *	terrain,
		terrain_info &	info
	)

private

Sets up terrain information for CELL_CORNER and MATCH_FULL.

Definition at line 459 of file layer_terrain.cpp.

Referenced by initialize_terrain().

◆ initialize_cell_corner_match_none()

void freeciv::layer_terrain::initialize_cell_corner_match_none	(	const terrain *	terrain,
		terrain_info &	info
	)

private

Sets up terrain information for CELL_CORNER and MATCH_NONE.

Definition at line 382 of file layer_terrain.cpp.

Referenced by initialize_terrain().

◆ initialize_cell_corner_match_pair()

void freeciv::layer_terrain::initialize_cell_corner_match_pair	(	const terrain *	terrain,
		terrain_info &	info
	)

private

Sets up terrain information for CELL_CORNER and MATCH_PAIR.

Definition at line 431 of file layer_terrain.cpp.

Referenced by initialize_terrain().

◆ initialize_cell_corner_match_same()

void freeciv::layer_terrain::initialize_cell_corner_match_same	(	const terrain *	terrain,
		terrain_info &	info
	)

private

Sets up terrain information for CELL_CORNER and MATCH_SAME.

Definition at line 404 of file layer_terrain.cpp.

Referenced by initialize_terrain().

◆ initialize_cell_hex_corner()

void freeciv::layer_terrain::initialize_cell_hex_corner	(	const terrain *	terrain,
		terrain_info &	info
	)

private

Sets up terrain information for CELL_HEX_CORNER.

Definition at line 540 of file layer_terrain.cpp.

Referenced by initialize_terrain().

◆ initialize_cell_whole_match_none()

void freeciv::layer_terrain::initialize_cell_whole_match_none	(	const terrain *	terrain,
		terrain_info &	info
	)

private

Sets up terrain information for CELL_WHOLE and MATCH_SAME.

Definition at line 334 of file layer_terrain.cpp.

Referenced by initialize_terrain().

◆ initialize_cell_whole_match_same()

void freeciv::layer_terrain::initialize_cell_whole_match_same	(	const terrain *	terrain,
		terrain_info &	info
	)

private

Sets up terrain information for CELL_WHOLE and MATCH_SAME.

Definition at line 364 of file layer_terrain.cpp.

Referenced by initialize_terrain().

◆ initialize_terrain()

void freeciv::layer_terrain::initialize_terrain ( const terrain * terrain )

overridevirtual

Sets up the structure to draw the specified terrain.

Reimplemented from freeciv::layer.

Definition at line 240 of file layer_terrain.cpp.

◆ set_tag_matches_with()

bool freeciv::layer_terrain::set_tag_matches_with	(	const QString &	tag,
		const QString &	group_name
	)

Sets the specified tag to be matched against a group.

The tag must have been created using add_tag.

Definition at line 212 of file layer_terrain.cpp.

◆ set_tag_matching_group()

bool freeciv::layer_terrain::set_tag_matching_group	(	const QString &	tag,
		const QString &	group_name
	)

Sets the matching group for the specified tag.

The tag must have been created using add_tag.

Definition at line 194 of file layer_terrain.cpp.

◆ set_tag_offsets()

bool freeciv::layer_terrain::set_tag_offsets	(	const QString &	tag,
		int	offset_x,
		int	offset_y
	)

Sets the offsets used to draw the specified tag.

The tag must have been created using add_tag.

Definition at line 181 of file layer_terrain.cpp.

◆ set_tag_sprite_type()

bool freeciv::layer_terrain::set_tag_sprite_type	(	const QString &	tag,
		sprite_type	type
	)

Sets the type of sprite used to draw the specified tag.

The tag must have been created using add_tag.

Definition at line 168 of file layer_terrain.cpp.

◆ terrain_group()

int freeciv::layer_terrain::terrain_group ( const terrain * pterrain ) const

private

Retrieves the group number for a given terrain.

Parameters

pterrain The terrain to look for. Can be null.

Returns: The terrain group number, or -1 if not drawn in this layer.

Definition at line 778 of file layer_terrain.cpp.

Member Data Documentation

◆ m_allocated

std::vector<std::unique_ptr<QPixmap> > freeciv::layer_terrain::m_allocated

private

List of those sprites in 'cells' that are allocated by some other means than load_sprite() and thus are not freed by unload_all_sprites().

Definition at line 119 of file layer_terrain.h.

Referenced by initialize_cell_corner_match_full(), and initialize_cell_hex_corner().

◆ m_matching_groups

std::map<QChar, matching_group> freeciv::layer_terrain::m_matching_groups

private

Definition at line 121 of file layer_terrain.h.

Referenced by create_matching_group(), and group().

◆ m_number

int freeciv::layer_terrain::m_number = 0

private

Definition at line 113 of file layer_terrain.h.

Referenced by create_matching_group(), fill_sprite_array(), initialize_blending(), initialize_cell_corner_match_full(), initialize_cell_corner_match_none(), initialize_cell_corner_match_pair(), initialize_cell_corner_match_same(), initialize_cell_hex_corner(), initialize_cell_whole_match_none(), initialize_cell_whole_match_same(), and initialize_terrain().

◆ m_terrain_info

std::map<int, terrain_info> freeciv::layer_terrain::m_terrain_info

private

Every terrain drawn in this layer appears here.

Definition at line 130 of file layer_terrain.h.

Referenced by fill_blending_sprite_array(), fill_terrain_sprite_array(), initialize_terrain(), and terrain_group().

◆ m_terrain_tag_info

std::map<QString, terrain_info> freeciv::layer_terrain::m_terrain_tag_info

private

Before terrains are loaded, this contains the list of available terrain tags.

Definition at line 127 of file layer_terrain.h.

Referenced by add_tag(), enable_blending(), initialize_terrain(), set_tag_matches_with(), set_tag_matching_group(), set_tag_offsets(), and set_tag_sprite_type().

◆ MAX_NUM_MATCH_WITH

constexpr static auto freeciv::layer_terrain::MAX_NUM_MATCH_WITH = 8

staticconstexpr

Definition at line 65 of file layer_terrain.h.

Classes

Public Types

Public Member Functions

Static Public Attributes

Private Types

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Matching

Member Enumeration Documentation

◆ match_style

◆ sprite_type

Constructor & Destructor Documentation

◆ layer_terrain()

◆ ~layer_terrain()

Member Function Documentation

◆ add_tag()

◆ create_matching_group()

◆ enable_blending()

◆ fill_blending_sprite_array()

◆ fill_sprite_array()

◆ fill_terrain_sprite_array()

◆ group()

◆ initialize_blending()

◆ initialize_cell_corner_match_full()

◆ initialize_cell_corner_match_none()

◆ initialize_cell_corner_match_pair()

◆ initialize_cell_corner_match_same()

◆ initialize_cell_hex_corner()

◆ initialize_cell_whole_match_none()

◆ initialize_cell_whole_match_same()

◆ initialize_terrain()

◆ set_tag_matches_with()

◆ set_tag_matching_group()

◆ set_tag_offsets()

◆ set_tag_sprite_type()

◆ terrain_group()

Member Data Documentation

◆ m_allocated

◆ m_matching_groups

◆ m_number

◆ m_terrain_info

◆ m_terrain_tag_info

◆ MAX_NUM_MATCH_WITH