The Battle for Wesnoth  1.19.0+dev
Classes | Typedefs | Enumerations | Functions
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  manager
 Image cache manager. More...
 

Typedefs

typedef cache_type< surfacesurface_cache
 
typedef cache_type< texturetexture_cache
 
typedef cache_type< bool > bool_cache
 
typedef std::basic_string< signed char > light_string
 Type used to store color information of central and adjacent hexes. More...
 
typedef std::map< light_string, surfacelit_surface_variants
 Type used to pair light possibilities with the corresponding lit surface. More...
 
typedef std::map< light_string, texturelit_texture_variants
 
typedef cache_type< lit_surface_variantslit_surface_cache
 Lit variants for each locator. More...
 
typedef cache_type< lit_texture_variantslit_texture_cache
 

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 signed char col_to_uchar (int i)
 
light_string get_light_string (int op, int r, int g, int b)
 Returns the light_string for one light operation. More...
 
static surface apply_light (surface surf, const light_string &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, const light_string &ls)
 Caches and returns an image with a lightmap applied to it. More...
 
texture get_lighted_texture (const image::locator &i_locator, const light_string &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...
 

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()",
@ UNSCALED
Unmodified original-size image.
Definition: picture.hpp:226

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

Typedef Documentation

◆ bool_cache

Definition at line 163 of file picture.hpp.

◆ light_string

typedef std::basic_string<signed char> image::light_string

Type used to store color information of central and adjacent hexes.

The structure is one or several 4-char blocks: [L,R,G,B] The R, G, B values represent the color, and L the lightmap to use:

-1: none 0: full hex 1-6: concave corners 7-12: convex half-corners 1 13-19: convex half-corners 2

Definition at line 177 of file picture.hpp.

◆ lit_surface_cache

Lit variants for each locator.

Definition at line 184 of file picture.hpp.

◆ lit_surface_variants

Type used to pair light possibilities with the corresponding lit surface.

Definition at line 180 of file picture.hpp.

◆ lit_texture_cache

Definition at line 185 of file picture.hpp.

◆ lit_texture_variants

Definition at line 181 of file picture.hpp.

◆ surface_cache

Definition at line 161 of file picture.hpp.

◆ texture_cache

Definition at line 162 of file picture.hpp.

Enumeration Type Documentation

◆ save_result

enum image::save_result
strong
Enumerator
success 
unsupported_format 
save_failed 
no_image 

Definition at line 323 of file picture.hpp.

◆ scale_quality

enum image::scale_quality
strong
Enumerator
nearest 
linear 

Definition at line 234 of file picture.hpp.

◆ 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 223 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 333 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,
const light_string ls 
)
static

◆ col_to_uchar()

static signed char image::col_to_uchar ( int  i)
static

Definition at line 493 of file picture.cpp.

References i.

Referenced by get_light_string().

◆ exists()

bool image::exists ( const image::locator i_locator)

◆ flush_cache()

void image::flush_cache ( )

◆ get_hexed()

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

◆ get_hexmask()

surface image::get_hexmask ( )

Retrieves the standard hexagonal tile mask.

Definition at line 808 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_light_string()

light_string image::get_light_string ( int  op,
int  r,
int  g,
int  b 
)

Returns the light_string for one light operation.

See light_string for more information.

Definition at line 498 of file picture.cpp.

References b, col_to_uchar(), and g.

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

◆ get_lighted_image()

surface image::get_lighted_image ( const image::locator i_locator,
const light_string ls 
)

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

Images will always be HEXED type.

Parameters
i_locatorImage path.
lsLight map to apply to the image.

Definition at line 736 of file picture.cpp.

References image::locator::access_in_cache(), image::locator::add_to_cache(), apply_light(), DBG_IMG, get_surface(), HEXED, image::locator::in_cache(), image::locator::is_void(), and image::locator::locate_in_cache().

Referenced by apply_light(), and get_lighted_texture().

◆ get_lighted_texture()

texture image::get_lighted_texture ( const image::locator i_locator,
const light_string ls 
)

◆ 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_locatorImage path.
skip_cacheIf true, do not cache the image if loaded.

Definition at line 814 of file picture.cpp.

References get_surface(), s, and UNSCALED.

Referenced by gui2::image::calculate_best_size(), display::draw_hex(), unit_frame::get_overlaped_hex(), intf_get_image_size(), unit_frame::redraw(), gui::scrollbar::scrollbar(), editor::mouse_action::set_terrain_mouse_overlay(), and gui2::window::update_render_textures().

◆ 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_locatorImage path.
typeRendering format.
skip_cacheSkip adding the result to the surface cache.

Definition at line 673 of file picture.cpp.

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

Referenced by get_hexed(), get_hexmask(), get_lighted_image(), get_size(), get_texture(), get_tod_colored(), help::image_width(), 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 
)

◆ 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_locatorImage path.
typeRendering format.
skip_cacheSkip adding the result to the surface cache.

Definition at line 960 of file picture.cpp.

References nearest.

Referenced by help::help_text_area::add_img_item(), gui2::image_shape::draw(), gui::scrollbar::draw_contents(), arrow::draw_hex(), 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_panel(), display::draw_report(), gui::menu::draw_row(), display::fade_tod_mask(), footsteps_images(), display::get_flag(), display::get_fog_shroud_images(), display::get_terrain_images(), gui::menu::style::item_size(), gui::menu::imgsel_style::load_image(), 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 648 of file picture.cpp.

References adjust_surface_color(), get_surface(), and HEXED.

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 835 of file picture.cpp.

References image::locator::add_to_cache(), get_hexmask(), get_surface(), HEXED, image::locator::in_cache(), image::locator::locate_in_cache(), and mask_surface().

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 824 of file picture.cpp.

References image::locator::add_to_cache(), image::locator::copy_from_cache(), 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

◆ load_image_data_uri()

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

Definition at line 462 of file picture.cpp.

References base64::decode(), ERR_IMG, and image::locator::get_filename().

Referenced by load_from_disk().

◆ load_image_file()

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

◆ load_image_sub_file()

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

◆ operator<<()

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

◆ 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 905 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

◆ precached_file_exists()

bool image::precached_file_exists ( const std::string &  file)

Definition at line 914 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 
)

◆ save_image() [1/2]

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

◆ save_image() [2/2]

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

◆ 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 596 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 655 of file picture.cpp.

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

Referenced by get_surface(), and get_texture().