The Battle for Wesnoth  1.17.0-dev
picture.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2021
3  by David White <dave@whitevine.net>
4  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
5 
6  This program is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 2 of the License, or
9  (at your option) any later version.
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY.
12 
13  See the COPYING file for more details.
14 */
15 
16 #pragma once
17 
18 #include "map/location.hpp"
19 #include "terrain/translation.hpp"
20 
21 #include <unordered_map>
22 
23 class surface;
24 
25 /**
26  * Functions to load and save images from/to disk.
27  *
28  * image::get_image() and other loading functions implement a pseudo-functional
29  * syntax to apply transformations to image files by including them as a suffix
30  * to the path (Image Path Functions). They also offer the option to choose
31  * between different rendering formats for a single image path according to the
32  * display intent -- unscaled, masked to hex, rescaled to zoom, etc.
33  *
34  * @code
35  * surface surf = image::get_image("units/elves-wood/shyde.png~TC(4,magenta)~FL()",
36  * image::UNSCALED);
37  * @endcode
38  *
39  * Internally, all loading functions utilize a cache to avoid reading
40  * individual images from disk more than once, or wasting valuable CPU time
41  * applying potentially expensive transforms every time (e.g. team colors on
42  * animated units). The cache can be manually invalidated using
43  * image::flush_cache(). Certain functions will invalidate parts of the cache
44  * as needed when relevant configuration parameters change in a way that would
45  * be expected to alter the output (e.g. Time of Day-tinted images).
46  */
47 namespace image {
48 
49 template<typename T>
50 class cache_type;
51 
52 /**
53  * Generic locator abstracting the location of an image.
54  *
55  * Constructing locators is somewhat slow, while accessing images through
56  * locators is fast. The general idea is that callers should store locators
57  * and not strings to construct new ones. (The latter will still work, of
58  * course, even if it is slower.)
59  */
60 class locator
61 {
62 public:
63  enum type { NONE, FILE, SUB_FILE };
64 
65  locator();
66  locator(const locator& a, const std::string& mods = "");
67  locator(const char* filename);
68  locator(const std::string& filename);
69  locator(const std::string& filename, const std::string& modifications);
70  locator(const std::string& filename, const map_location& loc, int center_x, int center_y, const std::string& modifications = "");
71 
72  locator& operator=(const locator& a);
73 
74  bool operator==(const locator& a) const { return index_ == a.index_; }
75  bool operator!=(const locator& a) const { return index_ != a.index_; }
76  bool operator<(const locator& a) const { return index_ < a.index_; }
77 
78  const std::string& get_filename() const { return val_.filename_; }
79  bool is_data_uri() const { return val_.is_data_uri_; }
80  const map_location& get_loc() const { return val_.loc_ ; }
81  int get_center_x() const { return val_.center_x_; }
82  int get_center_y() const { return val_.center_y_; }
83  const std::string& get_modifications() const {return val_.modifications_;}
84  type get_type() const { return val_.type_; }
85  // const int get_index() const { return index_; };
86 
87  /**
88  * Returns @a true if the locator does not correspond to an actual image.
89  */
90  bool is_void() const { return val_.type_ == NONE; }
91 
92  /**
93  * Tests whether the file the locator points at exists.
94  *
95  * is_void does not work before the image is loaded, and also a placeholder
96  * is returned instead in debug mode. Thus it's not possible to test for
97  * the existence of an actual file without this function.
98  *
99  * @note This does not test whether the image is valid or not.
100  *
101  * @return Whether or not the file exists.
102  */
103  bool file_exists() const;
104 
105  template<typename T>
106  bool in_cache(cache_type<T>& cache) const;
107 
108  template<typename T>
109  T& access_in_cache(cache_type<T>& cache) const;
110 
111  template<typename T>
112  const T& locate_in_cache(cache_type<T>& cache) const;
113 
114  template<typename T>
115  void add_to_cache(cache_type<T>& cache, const T& data) const;
116 
117 private:
118  // Called by each constructor after actual construction to
119  // initialize the index_ field
120  void init_index();
121  void parse_arguments();
122 
123  struct value
124  {
125  value();
126  value(const char *filename);
127  value(const std::string& filename);
128  value(const std::string& filename, const std::string& modifications);
129  value(const std::string& filename, const map_location& loc, int center_x, int center_y, const std::string& modifications);
130 
131  bool operator==(const value& a) const;
132  bool operator<(const value& a) const;
133 
136  std::string filename_;
138  std::string modifications_;
141  };
142 
143 public:
144  typedef std::unordered_map<value, int> locator_finder_t;
145 
146 private:
147  friend struct std::hash<value>;
148 
149  int index_;
151 };
152 
153 surface load_from_disk(const locator& loc);
154 
157 
158 typedef std::map<t_translation::terrain_code, surface> mini_terrain_cache_map;
159 
160 extern mini_terrain_cache_map mini_terrain_cache;
161 extern mini_terrain_cache_map mini_fogged_terrain_cache;
162 extern mini_terrain_cache_map mini_highlighted_terrain_cache;
163 
164 /**
165  * Type used to store color information of central and adjacent hexes.
166  *
167  * The structure is one or several 4-char blocks: [L,R,G,B]
168  * The R, G, B values represent the color, and L the lightmap to use:
169  *
170  * -1: none
171  * 0: full hex
172  * 1-6: concave corners
173  * 7-12: convex half-corners 1
174  * 13-19: convex half-corners 2
175  */
176 typedef std::basic_string<signed char> light_string;
177 
178 /** Type used to pair light possibilities with the corresponding lit surface. */
179 typedef std::map<light_string, surface> lit_variants;
180 
181 /** Lit variants for each locator. */
183 
184 /**
185  * Returns the light_string for one light operation.
186  *
187  * See light_string for more information.
188  */
189 light_string get_light_string(int op, int r, int g, int b);
190 
191 /**
192  * Purges all image caches.
193  */
194 void flush_cache();
195 
196 /**
197  * Image cache manager.
198  *
199  * This class is responsible for setting up and flushing the image cache. No
200  * more than one instance of it should exist at a time.
201  */
202 struct manager
203 {
204  manager();
205  ~manager();
206 };
207 
208 /**
209  * Changes Time of Day color tint for all applicable image types.
210  *
211  * In particular this affects TOD_COLORED and BRIGHTENED images, as well as
212  * images with lightmaps applied. Changing the previous values automatically
213  * invalidates all cached images of those types. It also invalidates the
214  * internal cache used by reverse_image() (FIXME?).
215  */
216 void set_color_adjustment(int r, int g, int b);
217 
218 /**
219  * Sets the scaling factor for images.
220  *
221  * Changing the previous value automatically invalidates all cached scaled
222  * images.
223  */
224 void set_zoom(unsigned int zoom);
225 
226 /**
227  * Used to specify the rendering format of images.
228  */
229 enum TYPE
230 {
231  /** Unmodified original-size image. */
233  /** Image rescaled according to the zoom settings. */
235  /** Standard hexagonal tile mask applied, removing portions that don't fit. */
237  /** Image rescaled to fit into a hexagonal tile according to the zoom settings. */
239  /** Same as SCALED_TO_HEX, but with Time of Day color tint applied. */
241  /** Same as TOD_COLORED, but also brightened. */
243 };
244 
245 /**
246  * Caches and returns an image.
247  *
248  * @param i_locator Image path.
249  * @param type Rendering format.
250  */
251 surface get_image(const locator& i_locator, TYPE type = UNSCALED);
252 
253 /**
254  * Caches and returns an image with a lightmap applied to it.
255  *
256  * @param i_locator Image path.
257  * @param ls Light map to apply to the image.
258  * @param type This should be either HEXED or SCALED_TO_HEX.
259  */
260 surface get_lighted_image(const image::locator& i_locator, const light_string& ls, TYPE type);
261 
262 /**
263  * Retrieves the standard hexagonal tile mask.
264  */
266 
267 /**
268  * Checks if an image fits into a single hex.
269  */
270 bool is_in_hex(const locator& i_locator);
271 
272 /**
273  * Checks if an image is empty after hex masking.
274  *
275  * This should be only used on terrain images, and it will automatically cache
276  * the hex-masked version if necessary.
277  */
278 bool is_empty_hex(const locator& i_locator);
279 
280 /**
281  * Horizontally flips an image.
282  *
283  * The input MUST have originally been returned from an image namespace function.
284  * Returned images have the same semantics as those obtained from get_image().
285  */
286 surface reverse_image(const surface& surf);
287 
288 /**
289  * Returns @a true if the given image actually exists, without loading it.
290  */
291 bool exists(const locator& i_locator);
292 
293 /**
294  * Precache the existence of files in a binary path subdirectory (e.g. "terrain/").
295  */
296 void precache_file_existence(const std::string& subdir = "");
297 
298 bool precached_file_exists(const std::string& file);
299 
300 enum class save_result
301 {
302  success,
304  save_failed,
305  no_image
306 };
307 
308 save_result save_image(const locator& i_locator, const std::string& outfile);
309 save_result save_image(const surface& surf, const std::string& outfile);
310 
311 }
TYPE
Used to specify the rendering format of images.
Definition: picture.hpp:229
surface get_image(const image::locator &i_locator, TYPE type)
Caches and returns an image.
Definition: picture.cpp:816
const std::string & get_modifications() const
Definition: picture.hpp:83
int get_center_y() const
Definition: picture.hpp:82
void precache_file_existence(const std::string &subdir)
Precache the existence of files in a binary path subdirectory (e.g.
Definition: picture.cpp:1062
bool operator!=(const locator &a) const
Definition: picture.hpp:75
map_location loc_
Definition: picture.hpp:137
void add_to_cache(cache_type< T > &cache, const T &data) const
Definition: picture.cpp:145
std::string filename_
Definition: picture.hpp:136
void init_index()
Definition: picture.cpp:248
bool operator==(const locator &a) const
Definition: picture.hpp:74
bool precached_file_exists(const std::string &file)
Definition: picture.cpp:1071
save_result
Definition: picture.hpp:300
surface reverse_image(const surface &surf)
Horizontally flips an image.
Definition: picture.cpp:989
#define a
mini_terrain_cache_map mini_fogged_terrain_cache
Definition: picture.cpp:217
save_result save_image(const locator &i_locator, const std::string &filename)
Definition: picture.cpp:1081
T & access_in_cache(cache_type< T > &cache) const
Definition: picture.cpp:138
void parse_arguments()
Definition: picture.cpp:260
std::map< t_translation::terrain_code, surface > mini_terrain_cache_map
Definition: picture.hpp:158
type get_type() const
Definition: picture.hpp:84
Standard hexagonal tile mask applied, removing portions that don&#39;t fit.
Definition: picture.hpp:236
cache_type< lit_variants > lit_cache
Lit variants for each locator.
Definition: picture.hpp:182
Same as SCALED_TO_HEX, but with Time of Day color tint applied.
Definition: picture.hpp:240
cache_type< surface > image_cache
Definition: picture.hpp:155
void flush_cache()
Purges all image caches.
Definition: picture.cpp:222
#define b
bool exists(const image::locator &i_locator)
Returns true if the given image actually exists, without loading it.
Definition: picture.cpp:1011
const T & locate_in_cache(cache_type< T > &cache) const
Definition: picture.cpp:131
light_string get_light_string(int op, int r, int g, int b)
Returns the light_string for one light operation.
Definition: picture.cpp:593
std::string modifications_
Definition: picture.hpp:138
std::unordered_map< value, int > locator_finder_t
Definition: picture.hpp:144
void set_zoom(unsigned int amount)
Sets the scaling factor for images.
Definition: picture.cpp:705
std::map< light_string, surface > lit_variants
Type used to pair light possibilities with the corresponding lit surface.
Definition: picture.hpp:179
bool operator<(const locator &a) const
Definition: picture.hpp:76
Generic locator abstracting the location of an image.
Definition: picture.hpp:60
void set_color_adjustment(int r, int g, int b)
Changes Time of Day color tint for all applicable image types.
Definition: picture.cpp:691
Image rescaled according to the zoom settings.
Definition: picture.hpp:234
Encapsulates the map of the game.
Definition: location.hpp:38
surface load_from_disk(const locator &loc)
Definition: picture.cpp:666
cache_type< bool > bool_cache
Definition: picture.hpp:156
locator & operator=(const locator &a)
Definition: picture.cpp:341
double g
Definition: astarsearch.cpp:65
static tcache cache
Definition: minimap.cpp:124
surface get_hexmask()
Retrieves the standard hexagonal tile mask.
Definition: picture.cpp:941
std::basic_string< signed char > light_string
Type used to store color information of central and adjacent hexes.
Definition: picture.hpp:176
mini_terrain_cache_map mini_highlighted_terrain_cache
Definition: picture.cpp:218
int get_center_x() const
Definition: picture.hpp:81
Image cache manager.
Definition: picture.hpp:202
const std::string & get_filename() const
Definition: picture.hpp:78
bool is_in_hex(const locator &i_locator)
Checks if an image fits into a single hex.
Definition: picture.cpp:947
bool is_data_uri() const
Definition: picture.hpp:79
bool operator<(const value &a) const
Definition: picture.cpp:422
mini_terrain_cache_map mini_terrain_cache
Definition: picture.cpp:216
surface get_lighted_image(const image::locator &i_locator, const light_string &ls, TYPE type)
Caches and returns an image with a lightmap applied to it.
Definition: picture.cpp:889
const std::vector< std::string > & modifications(bool mp)
Definition: game.cpp:725
Image rescaled to fit into a hexagonal tile according to the zoom settings.
Definition: picture.hpp:238
const map_location & get_loc() const
Definition: picture.hpp:80
bool is_empty_hex(const locator &i_locator)
Checks if an image is empty after hex masking.
Definition: picture.cpp:970
Functions to load and save images from/to disk.
bool operator==(const value &a) const
Definition: picture.cpp:408
bool is_void() const
Returns true if the locator does not correspond to an actual image.
Definition: picture.hpp:90
bool in_cache(cache_type< T > &cache) const
Definition: picture.cpp:125
Unmodified original-size image.
Definition: picture.hpp:232
bool file_exists() const
Tests whether the file the locator points at exists.
Definition: picture.cpp:659
Same as TOD_COLORED, but also brightened.
Definition: picture.hpp:242