image Namespace Reference

Functions to load and save images from/to disk. More...

Classes
class	pixel_callable
class	modification_queue
	A modified priority queue used to order image modifications. More...
class	modification
	Base abstract class for an image-path modification. More...
class	rc_modification
	Recolor (RC/TC/PAL) modification. More...
class	fl_modification
	Mirror (FL) modification. More...
class	rotate_modification
	Rotate (ROTATE) modification. More...
class	gs_modification
	Grayscale (GS) modification. More...
class	crop_transparency_modification
	Crop transparent padding (CROP_TRANSPARENCY) modification. More...
class	bw_modification
	Black and white (BW) modification. More...
struct	sepia_modification
	Give to the image a sepia tint (SEPIA) More...
class	negative_modification
	Make an image negative (NEG) More...
class	plot_alpha_modification
	Plot Alpha (Alpha) modification. More...
class	wipe_alpha_modification
	Wipe Alpha (Wipe_Alpha) modification. More...
class	adjust_alpha_modification
	Adjust Alpha (ADJUST_ALPHA) modification. More...
class	adjust_channels_modification
	Adjust Channels (CHAN) modification. More...
class	crop_modification
	Crop (CROP) modification. More...
class	blit_modification
	Scale (BLIT) modification. More...
class	mask_modification
	Mask (MASK) modification. More...
class	light_modification
	LIGHT (L) modification. More...
class	scale_modification
	Scaling (SCALE[_INTO], SCALE[_INTO]_SHARP) modifications. More...
class	xbrz_modification
	xBRZ scale (xBRZ) modification More...
class	o_modification
	Opacity (O) modification. More...
class	cs_modification
	Color-shift (CS, R, G, B) modification. More...
class	blend_modification
	Color blending (BLEND) modification. More...
class	bl_modification
	Gaussian-like blur (BL) modification. More...
struct	background_modification
	Fill background with a color (BG). More...
class	swap_modification
	Channel swap (SWAP). More...
class	cache_type
class	locator
	Generic locator abstracting the location of an image. More...
struct	light_adjust
	Type used to store color information of central and adjacent hexes. More...
struct	manager
	Image cache manager. More...

Enumerations
enum	TYPE { UNSCALED , HEXED , TOD_COLORED , NUM_TYPES }
	Used to specify the rendering format of images. More...
enum class	scale_quality { nearest , linear }
enum class	save_result { success , unsupported_format , save_failed , no_image }

Functions
std::function< rect(rect)>	prep_minimap_for_rendering (const gamemap &map, const team *vw=nullptr, const unit_map *units=nullptr, const std::map< map_location, unsigned int > *reach_map=nullptr, bool ignore_terrain_disabled=false)
	Prepares the minimap texture and returns a function which will render it to the current rendering target when invoked. More...
void	flush_cache ()
	Purges all image caches. More...
std::ostream &	operator<< (std::ostream &s, const locator &l)
static void	add_localized_overlay (const std::string &ovr_file, surface &orig_surf)
static surface	load_image_file (const image::locator &loc)
static surface	load_image_sub_file (const image::locator &loc)
static surface	load_image_data_uri (const image::locator &loc)
static surface	apply_light (surface surf, utils::span< const light_adjust > ls)
static surface	load_from_disk (const locator &loc)
void	set_color_adjustment (int r, int g, int b)
	Changes Time of Day color tint for all applicable image types. More...
static surface	get_hexed (const locator &i_locator, bool skip_cache=false)
static surface	get_tod_colored (const locator &i_locator, bool skip_cache=false)
static TYPE	simplify_type (const image::locator &i_locator, TYPE type)
	translate type to a simpler one when possible More...
surface	get_surface (const locator &i_locator, TYPE type=UNSCALED, bool skip_cache=false)
	Returns an image surface suitable for software manipulation. More...
surface	get_lighted_image (const image::locator &i_locator, utils::span< const light_adjust > ls)
	Caches and returns an image with a lightmap applied to it. More...
texture	get_lighted_texture (const image::locator &i_locator, utils::span< const light_adjust > ls)
surface	get_hexmask ()
	Retrieves the standard hexagonal tile mask. More...
point	get_size (const locator &i_locator, bool skip_cache=false)
	Returns the width and height of an image. More...
bool	is_in_hex (const locator &i_locator)
	Checks if an image fits into a single hex. More...
bool	is_empty_hex (const locator &i_locator)
	Checks if an image is empty after hex masking. More...
bool	exists (const locator &i_locator)
	Returns true if the given image actually exists, without loading it. More...
static void	precache_file_existence_internal (const std::string &dir, const std::string &subdir)
void	precache_file_existence (const std::string &subdir="")
	Precache the existence of files in a binary path subdirectory (e.g. More...
bool	precached_file_exists (const std::string &file)
save_result	save_image (const locator &i_locator, const std::string &filename)
save_result	save_image (const surface &surf, const std::string &filename)
texture	get_texture (const locator &i_locator, TYPE type=UNSCALED, bool skip_cache=false)
	Returns an image texture suitable for hardware-accelerated rendering. More...
texture	get_texture (const image::locator &i_locator, scale_quality quality, TYPE type, bool skip_cache)
	Returns a texture for the corresponding image. More...
void	build_spritesheet_from (const std::string &entry_point)

Detailed Description

Functions to load and save images from/to disk.

image::get_image() and other loading functions implement a pseudo-functional syntax to apply transformations to image files by including them as a suffix to the path (Image Path Functions). They also offer the option to choose between different rendering formats for a single image path according to the display intent – unscaled, masked to hex, rescaled to zoom, etc.

surface surf = image::get_image("units/elves-wood/shyde.png~TC(4,magenta)~FL()",
                                image::UNSCALED);

Internally, all loading functions utilize a cache to avoid reading individual images from disk more than once, or wasting valuable CPU time applying potentially expensive transforms every time (e.g. team colors on animated units). The cache can be manually invalidated using image::flush_cache(). Certain functions will invalidate parts of the cache as needed when relevant configuration parameters change in a way that would be expected to alter the output (e.g. Time of Day-tinted images).

Enumeration Type Documentation

save_result

enum image::save_result

strong

Enumerator
success
unsupported_format
save_failed
no_image

Definition at line 263 of file picture.hpp.

scale_quality

enum image::scale_quality

strong

Enumerator
nearest
linear

Definition at line 174 of file picture.hpp.

TYPE

enum image::TYPE

Used to specify the rendering format of images.

Enumerator
UNSCALED	Unmodified original-size image.
HEXED	Standard hexagonal tile mask applied, removing portions that don't fit.
TOD_COLORED	Same as HEXED, but with Time of Day color tint applied.
NUM_TYPES

Definition at line 163 of file picture.hpp.

Function Documentation

add_localized_overlay()

static void image::add_localized_overlay ( const std::string &  ovr_file, surface &  orig_surf  )

static

Definition at line 318 of file picture.cpp.

References filesystem::make_read_RWops(), and sdl_blit().

Referenced by load_image_file().

apply_light()

static surface image::apply_light ( surface  surf, utils::span< const light_adjust >  ls  )

static

Definition at line 505 of file picture.cpp.

References adjust_surface_color(), b, surface::clone(), g, get_lighted_image(), light_surface(), p, sdl_blit(), boost::span< T, E >::size(), and surf.

Referenced by get_lighted_image().

build_spritesheet_from()

void image::build_spritesheet_from

(

const std::string &

entry_point

)

Definition at line 230 of file spritesheet_generator.cpp.

References e, filesystem::get_binary_file_location(), game_config::path, and PLAIN_LOG.

Referenced by process_command_args().

exists()

bool image::exists

(

const image::locator &

i_locator

)

Returns true if the given image actually exists, without loading it.

Definition at line 832 of file picture.cpp.

References filesystem::get_binary_file_location(), image::locator::get_filename(), image::locator::is_data_uri(), image::locator::is_void(), and success.

Referenced by adjust_profile(), attack_info(), wesnothd::server::authenticate(), persist_file_context::clear_var(), filesystem::create_directory_if_missing(), filesystem::create_directory_if_missing_recursive(), addon_info::display_icon(), gui2::dialogs::game_load::display_savegame_internal(), filesystem::file_exists(), display::fill_images_list(), filesystem::find_other_version_saves_dirs(), filesystem::get_exe_path(), display::get_fog_shroud_images(), filesystem::get_game_manual_file(), game_display::get_reachmap_images(), image_exists(), intf_get_image_size(), gui2::unit_preview_pane::print_attack_details(), gui2::dialogs::addon_manager::publish_addon(), editor::mouse_action::set_terrain_mouse_overlay(), arrow::update_symbols(), and tmp_file::~tmp_file().

flush_cache()

void image::flush_cache

(

)

Purges all image caches.

Definition at line 200 of file picture.cpp.

Referenced by game_launcher::change_language(), video::deinit(), events::console_handler::do_refresh(), game_config_manager::load_game_config_for_game(), editor::editor_controller::refresh_image_cache(), game_config_manager::reload_changed_game_config(), and image::manager::~manager().

get_hexed()

static surface image::get_hexed ( const locator &  i_locator, bool  skip_cache = false  )

static

Definition at line 602 of file picture.cpp.

References surface::clone(), cut_surface(), DBG_IMG, dst, image::locator::get_filename(), get_hexmask(), get_surface(), mask_surface(), sdl_blit(), and UNSCALED.

Referenced by get_surface().

get_hexmask()

surface image::get_hexmask

(

)

Retrieves the standard hexagonal tile mask.

Definition at line 785 of file picture.cpp.

References get_surface(), game_config::images::terrain_mask, and UNSCALED.

Referenced by get_hexed(), is_empty_hex(), is_in_hex(), and load_image_sub_file().

get_lighted_image()

surface image::get_lighted_image	(	const image::locator &	i_locator,
		utils::span< const light_adjust >	ls
	)

Caches and returns an image with a lightmap applied to it.

Images will always be HEXED type.

Parameters

i_locator	Image path.
ls	Light map to apply to the image.

Definition at line 733 of file picture.cpp.

References apply_light(), DBG_IMG, get_surface(), HEXED, and image::locator::is_void().

Referenced by apply_light(), and get_lighted_texture().

get_lighted_texture()

texture image::get_lighted_texture	(	const image::locator &	i_locator,
		utils::span< const light_adjust >	ls
	)

Definition at line 759 of file picture.cpp.

References DBG_IMG, get_lighted_image(), and image::locator::is_void().

Referenced by display::draw_overlays_at(), and display::get_terrain_images().

get_size()

point image::get_size	(	const locator &	i_locator,
		bool	skip_cache = false
	)

Returns the width and height of an image.

If the image is not yet in the surface cache, it will be loaded and cached unless skip_cache is explicitly set.

Parameters

i_locator	Image path.
skip_cache	If true, do not cache the image if loaded.

Definition at line 791 of file picture.cpp.

References get_surface(), s, and UNSCALED.

Referenced by gui2::image::calculate_best_size(), unit_frame::get_overlaped_hex(), intf_get_image_size(), unit_frame::redraw(), unit_drawer::redraw_unit(), gui::scrollbar::scrollbar(), editor::mouse_action::set_terrain_mouse_overlay(), and gui2::dialogs::editor_edit_unit::update_image().

get_surface()

surface image::get_surface	(	const locator &	i_locator,
		TYPE	type = UNSCALED,
		bool	skip_cache = false
	)

Returns an image surface suitable for software manipulation.

The equivalent get_texture() function should generally be preferred.

Surfaces will be cached for repeat access, unless skip_cache is set.

Parameters

i_locator	Image path.
type	Rendering format.
skip_cache	Skip adding the result to the surface cache.

Definition at line 665 of file picture.cpp.

References DBG_IMG, get_hexed(), get_tod_colored(), HEXED, image::locator::is_void(), load_from_disk(), NUM_TYPES, simplify_type(), TOD_COLORED, UNSCALED, and WRN_IMG.

Referenced by font::add_attribute_image_shape(), get_hexed(), get_hexmask(), get_lighted_image(), get_size(), get_texture(), get_tod_colored(), game_launcher::init_video(), is_empty_hex(), is_in_hex(), load_image_file(), load_image_sub_file(), and save_image().

get_texture() [1/2]

texture image::get_texture	(	const image::locator &	i_locator,
		scale_quality	quality,
		TYPE	type,
		bool	skip_cache
	)

Returns a texture for the corresponding image.

Definition at line 940 of file picture.cpp.

References DBG_IMG, image::locator::get_modifications(), get_surface(), HEXED, image::locator::is_void(), linear, simplify_type(), and TOD_COLORED.

get_texture() [2/2]

texture image::get_texture	(	const locator &	i_locator,
		TYPE	type = UNSCALED,
		bool	skip_cache = false
	)

Returns an image texture suitable for hardware-accelerated rendering.

Texture pointers are not unique, and will be cached and retained until no longer needed. Users of the returned texture do not have to worry about texture management.

If caching is disabled via skip_cache, texture memory will be automatically freed once the returned object and all other linked textures (if any) are destroyed.

Parameters

i_locator	Image path.
type	Rendering format.
skip_cache	Skip adding the result to the surface cache.

Definition at line 934 of file picture.cpp.

References nearest.

Referenced by gui2::image_shape::draw(), gui::scrollbar::draw_contents(), unit_drawer::draw_ellipses(), wb::attack::draw_hex(), wb::suppose_dead::draw_hex(), display::draw_hex(), editor::editor_display::draw_hex(), game_display::draw_hex(), display::draw_label(), game_display::draw_movement_info(), display::draw_overlays_at(), display::draw_panel(), display::draw_report(), display::fade_tod_mask(), display::get_flag(), display::get_fog_shroud_images(), game_display::get_reachmap_images(), display::get_terrain_images(), gui::button::load_images(), prep_minimap_for_rendering(), unit_drawer::redraw_unit(), display::render_map_outside_area(), editor::mouse_action_item::set_item_mouse_overlay(), editor::mouse_action_paste::set_mouse_overlay(), editor::mouse_action_starting_position::set_mouse_overlay(), editor::mouse_action_map_label::set_mouse_overlay(), editor::mouse_action_select::set_mouse_overlay(), editor::mouse_action_village::set_mouse_overlay(), editor::mouse_action::set_terrain_mouse_overlay(), editor::mouse_action_unit::set_unit_mouse_overlay(), editor::item_palette::setup_item(), editor::terrain_palette::setup_item(), editor::unit_palette::setup_item(), gui::tristate_button::tristate_button(), and halo::halo_impl::effect::update().

get_tod_colored()

static surface image::get_tod_colored ( const locator &  i_locator, bool  skip_cache = false  )

static

Definition at line 639 of file picture.cpp.

References adjust_surface_color(), surface::clone(), get_surface(), HEXED, and markup::img().

Referenced by get_surface().

is_empty_hex()

bool image::is_empty_hex

(

const locator &

i_locator

)

Checks if an image is empty after hex masking.

This should be only used on terrain images, and it will automatically cache the hex-masked version if necessary.

Definition at line 811 of file picture.cpp.

References surface::clone(), get_hexmask(), get_surface(), HEXED, mask_surface(), and surf.

Referenced by terrain_builder::tile::rebuild_cache().

is_in_hex()

bool image::is_in_hex

(

const locator &

i_locator

)

Checks if an image fits into a single hex.

Definition at line 800 of file picture.cpp.

References get_hexmask(), get_surface(), in_mask_surface(), and UNSCALED.

Referenced by unit_frame::get_overlaped_hex().

load_from_disk()

static surface image::load_from_disk ( const locator &  loc )

static

Definition at line 564 of file picture.cpp.

References image::locator::FILE, load_image_data_uri(), load_image_file(), load_image_sub_file(), loc, and image::locator::SUB_FILE.

Referenced by get_surface().

load_image_data_uri()

static surface image::load_image_data_uri ( const image::locator &  loc )

static

Definition at line 447 of file picture.cpp.

References base64::decode(), ERR_IMG, loc, and surf.

Referenced by load_from_disk().

load_image_file()

static surface image::load_image_file ( const image::locator &  loc )

static

Definition at line 331 of file picture.cpp.

References add_localized_overlay(), game_config::images::blank, game_config::debug, ERR_IMG, filesystem::get_binary_file_location(), filesystem::get_localized_path(), get_surface(), loc, filesystem::make_read_RWops(), game_config::images::missing, UNSCALED, and WRN_IMG.

Referenced by load_from_disk().

load_image_sub_file()

static surface image::load_image_sub_file ( const image::locator &  loc )

static

Definition at line 383 of file picture.cpp.

References surface::clone(), cut_surface(), image::modification::decode(), e, image::modification_queue::empty(), ERR_CFG, get_hexmask(), get_surface(), loc, mask_surface(), utils::parenthetical_split(), image::modification_queue::pop(), surf, game_config::tile_size, image::modification_queue::top(), UNSCALED, map_location::valid(), map_location::x, and map_location::y.

Referenced by load_from_disk().

operator<<()

std::ostream & image::operator<<	(	std::ostream &	s,
		const locator &	l
	)

Definition at line 229 of file picture.cpp.

References image::locator::get_filename(), image::locator::get_modifications(), and s.

precache_file_existence()

void image::precache_file_existence

(

const std::string &

subdir = ""

)

Precache the existence of files in a binary path subdirectory (e.g.

"terrain/").

Definition at line 881 of file picture.cpp.

References filesystem::get_binary_paths(), p, and precache_file_existence_internal().

Referenced by terrain_builder::terrain_builder().

precache_file_existence_internal()

static void image::precache_file_existence_internal ( const std::string &  dir, const std::string &  subdir  )

static

Definition at line 854 of file picture.cpp.

References d, filesystem::DONT_REORDER, f, filesystem::FILE_NAME_ONLY, filesystem::get_files_in_dir(), filesystem::is_directory(), and filesystem::NO_FILTER.

Referenced by precache_file_existence().

precached_file_exists()

bool image::precached_file_exists

(

const std::string &

file

)

Definition at line 888 of file picture.cpp.

References b.

Referenced by image_exists().

prep_minimap_for_rendering()

std::function< rect(rect)> image::prep_minimap_for_rendering	(	const gamemap &	map,
		const team *	vw,
		const unit_map *	units,
		const std::map< map_location, unsigned int > *	reach_map,
		bool	ignore_terrain_disabled
	)

Prepares the minimap texture and returns a function which will render it to the current rendering target when invoked.

Definition at line 40 of file minimap.cpp.

References allied, draw::blit(), draw::clear(), game_config::color_info(), display::context(), DBG_DP, dst, enemy, draw::fill(), team::fogged(), gamemap_base::for_each_loc(), resources::gameboard, prefs::get(), team::get_minimap_color(), orb_status_helper::get_orb_color(), texture::get_raw_size(), display::get_singleton(), get_texture(), gamemap_base::h(), terrain_type::id(), display::is_blindfolded(), team::is_enemy(), is_odd(), loc, terrain_type::minimap_image(), terrain_type::minimap_image_overlay(), team::owns_village(), color_range::rep(), s, xbrz::scale(), set_texture_scale_quality(), team::shrouded(), team::side(), gamemap::tdata(), game_config::team_rgb_range, display_context::unit_orb_status(), display_context::village_owner(), gamemap::villages(), t_translation::VOID_TERRAIN, gamemap_base::w(), map_location::x, and map_location::y.

Referenced by gui2::minimap::impl_draw_background(), and display::recalculate_minimap().

save_image() [1/2]

save_result image::save_image	(	const locator &	i_locator,
		const std::string &	filename
	)

Definition at line 898 of file picture.cpp.

References filename, and get_surface().

Referenced by editor::editor_controller::do_screenshot(), game_launcher::play_render_image_mode(), and gui2::dialogs::screenshot_notification::save_screenshot().

save_image() [2/2]

save_result image::save_image	(	const surface &	surf,
		const std::string &	filename
	)

Definition at line 903 of file picture.cpp.

References lg::err(), filename, LOG_IMG, filesystem::make_write_RWops(), no_image, save_failed, success, surf, and unsupported_format.

set_color_adjustment()

void image::set_color_adjustment	(	int	r,
		int	g,
		int	b
	)

Changes Time of Day color tint for all applicable image types.

In particular this affects TOD_COLORED images, as well as images with lightmaps applied. Changing the previous values automatically invalidates all cached images of those types.

Definition at line 589 of file picture.cpp.

References b, g, and TOD_COLORED.

Referenced by display::update_tod().

simplify_type()

static TYPE image::simplify_type ( const image::locator &  i_locator, TYPE  type  )

static

translate type to a simpler one when possible

Definition at line 647 of file picture.cpp.

References image::locator::get_loc(), HEXED, TOD_COLORED, UNSCALED, and map_location::valid().

Referenced by get_surface(), and get_texture().