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