The Battle for Wesnoth  1.19.0+dev
picture.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2024
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 <optional>
22 
23 class surface;
24 class texture;
25 struct point;
26 
27 /**
28  * Functions to load and save images from/to disk.
29  *
30  * image::get_image() and other loading functions implement a pseudo-functional
31  * syntax to apply transformations to image files by including them as a suffix
32  * to the path (Image Path Functions). They also offer the option to choose
33  * between different rendering formats for a single image path according to the
34  * display intent -- unscaled, masked to hex, rescaled to zoom, etc.
35  *
36  * @code
37  * surface surf = image::get_image("units/elves-wood/shyde.png~TC(4,magenta)~FL()",
38  * image::UNSCALED);
39  * @endcode
40  *
41  * Internally, all loading functions utilize a cache to avoid reading
42  * individual images from disk more than once, or wasting valuable CPU time
43  * applying potentially expensive transforms every time (e.g. team colors on
44  * animated units). The cache can be manually invalidated using
45  * image::flush_cache(). Certain functions will invalidate parts of the cache
46  * as needed when relevant configuration parameters change in a way that would
47  * be expected to alter the output (e.g. Time of Day-tinted images).
48  */
49 namespace image {
50 
51 template<typename T>
52 class cache_type;
53 
54 /**
55  * Generic locator abstracting the location of an image.
56  *
57  * Constructing locators is somewhat slow, while accessing images through
58  * locators is fast. The general idea is that callers should store locators
59  * and not strings to construct new ones. (The latter will still work, of
60  * course, even if it is slower.)
61  */
62 class locator
63 {
64 public:
65  enum type { NONE, FILE, SUB_FILE };
66 
67  locator() = default;
68  locator(locator&&) noexcept = default;
69  locator(const locator&) = default;
70 
71  template<typename... Args>
72  locator(Args&&... args) : val_(std::forward<Args>(args)...)
73  {
74  }
75 
76  locator& operator=(const locator& a) = default;
77  locator& operator=(locator&&) = default;
78 
79  /** Returns a copy of this locator with the given IPF */
80  locator clone(const std::string& mods) const;
81 
82  bool operator==(const locator& a) const { return val_ == a.val_; }
83  bool operator!=(const locator& a) const { return !operator==(a); }
84 
85  const std::string& get_filename() const { return val_.filename; }
86  bool is_data_uri() const { return val_.is_data_uri; }
87  const map_location& get_loc() const { return val_.loc ; }
88  int get_center_x() const { return val_.center_x; }
89  int get_center_y() const { return val_.center_y; }
90  const std::string& get_modifications() const { return val_.modifications; }
91  type get_type() const { return val_.type; }
92 
93  /**
94  * Returns @a true if the locator does not correspond to an actual image.
95  */
96  bool is_void() const { return val_.type == NONE; }
97 
98  /**
99  * Tests whether the file the locator points at exists.
100  *
101  * is_void does not work before the image is loaded, and also a placeholder
102  * is returned instead in debug mode. Thus it's not possible to test for
103  * the existence of an actual file without this function.
104  *
105  * @note This does not test whether the image is valid or not.
106  *
107  * @return Whether or not the file exists.
108  */
109  bool file_exists() const;
110 
111  template<typename T>
112  bool in_cache(cache_type<T>& cache) const;
113 
114  template<typename T>
115  T& access_in_cache(cache_type<T>& cache) const;
116 
117  template<typename T>
118  const T& locate_in_cache(cache_type<T>& cache) const;
119 
120  template<typename T>
121  std::optional<T> copy_from_cache(cache_type<T>& cache) const;
122 
123  template<typename T>
124  void add_to_cache(cache_type<T>& cache, T data) const;
125 
126 private:
127  struct value
128  {
129  value() = default;
130 
131  value(const std::string& filename);
132  value(const std::string& filename, const std::string& modifications);
133  value(const std::string& filename, const map_location& loc, int center_x, int center_y, const std::string& modifications = "");
134 
135  bool operator==(const value& a) const;
136  bool operator<(const value& a) const;
137 
139  bool is_data_uri = false;
140  std::string filename{};
141  std::string modifications{};
143  int center_x = 0;
144  int center_y = 0;
145  };
146 
148 
149 public:
150  friend struct std::hash<value>;
151 
152  template<typename T>
153  friend class cache_type;
154 
155  std::size_t hash() const;
156 };
157 
158 // write a readable representation of a locator, mostly for debugging
159 std::ostream& operator<<(std::ostream&, const locator&);
160 
164 
165 /**
166  * Type used to store color information of central and adjacent hexes.
167  *
168  * The structure is one or several 4-char blocks: [L,R,G,B]
169  * The R, G, B values represent the color, and L the lightmap to use:
170  *
171  * -1: none
172  * 0: full hex
173  * 1-6: concave corners
174  * 7-12: convex half-corners 1
175  * 13-19: convex half-corners 2
176  */
177 typedef std::basic_string<signed char> light_string;
178 
179 /** Type used to pair light possibilities with the corresponding lit surface. */
180 typedef std::map<light_string, surface> lit_surface_variants;
181 typedef std::map<light_string, texture> lit_texture_variants;
182 
183 /** Lit variants for each locator. */
186 
187 /**
188  * Returns the light_string for one light operation.
189  *
190  * See light_string for more information.
191  */
192 light_string get_light_string(int op, int r, int g, int b);
193 
194 /**
195  * Purges all image caches.
196  */
197 void flush_cache();
198 
199 /**
200  * Image cache manager.
201  *
202  * This class is responsible for setting up and flushing the image cache. No
203  * more than one instance of it should exist at a time.
204  */
205 struct manager
206 {
207  manager();
208  ~manager();
209 };
210 
211 /**
212  * Changes Time of Day color tint for all applicable image types.
213  *
214  * In particular this affects TOD_COLORED images, as well as
215  * images with lightmaps applied. Changing the previous values automatically
216  * invalidates all cached images of those types.
217  */
218 void set_color_adjustment(int r, int g, int b);
219 
220 /**
221  * Used to specify the rendering format of images.
222  */
223 enum TYPE
224 {
225  /** Unmodified original-size image. */
227  /** Standard hexagonal tile mask applied, removing portions that don't fit. */
229  /** Same as HEXED, but with Time of Day color tint applied. */
231  NUM_TYPES // Equal to the number of types specified above
232 };
233 
234 enum class scale_quality { nearest, linear };
235 
236 /**
237  * Returns an image surface suitable for software manipulation.
238  *
239  * The equivalent get_texture() function should generally be preferred.
240  *
241  * Surfaces will be cached for repeat access, unless skip_cache is set.
242  *
243  * @param i_locator Image path.
244  * @param type Rendering format.
245  * @param skip_cache Skip adding the result to the surface cache.
246  */
247 surface get_surface(const locator& i_locator, TYPE type = UNSCALED,
248  bool skip_cache = false);
249 
250 /**
251  * Returns an image texture suitable for hardware-accelerated rendering.
252  *
253  * Texture pointers are not unique, and will be cached and retained
254  * until no longer needed. Users of the returned texture do not have to
255  * worry about texture management.
256  *
257  * If caching is disabled via @a skip_cache, texture memory will be
258  * automatically freed once the returned object and all other linked
259  * textures (if any) are destroyed.
260  *
261  * @param i_locator Image path.
262  * @param type Rendering format.
263  * @param skip_cache Skip adding the result to the surface cache.
264  */
265 texture get_texture(const locator& i_locator, TYPE type = UNSCALED,
266  bool skip_cache = false);
267 
268 texture get_texture(const image::locator& i_locator, scale_quality quality,
269  TYPE type = UNSCALED, bool skip_cache = false);
270 
271 /**
272  * Caches and returns an image with a lightmap applied to it.
273  *
274  * Images will always be HEXED type.
275  *
276  * @param i_locator Image path.
277  * @param ls Light map to apply to the image.
278  */
279 surface get_lighted_image(const image::locator& i_locator, const light_string& ls);
280 texture get_lighted_texture(const image::locator& i_locator, const light_string& ls);
281 
282 /**
283  * Retrieves the standard hexagonal tile mask.
284  */
286 
287 /**
288  * Returns the width and height of an image.
289  *
290  * If the image is not yet in the surface cache, it will be loaded and cached
291  * unless skip_cache is explicitly set.
292  *
293  * @param i_locator Image path.
294  * @param skip_cache If true, do not cache the image if loaded.
295  */
296 point get_size(const locator& i_locator, bool skip_cache = false);
297 
298 /**
299  * Checks if an image fits into a single hex.
300  */
301 bool is_in_hex(const locator& i_locator);
302 
303 /**
304  * Checks if an image is empty after hex masking.
305  *
306  * This should be only used on terrain images, and it will automatically cache
307  * the hex-masked version if necessary.
308  */
309 bool is_empty_hex(const locator& i_locator);
310 
311 /**
312  * Returns @a true if the given image actually exists, without loading it.
313  */
314 bool exists(const locator& i_locator);
315 
316 /**
317  * Precache the existence of files in a binary path subdirectory (e.g. "terrain/").
318  */
319 void precache_file_existence(const std::string& subdir = "");
320 
321 bool precached_file_exists(const std::string& file);
322 
323 enum class save_result
324 {
325  success,
327  save_failed,
328  no_image
329 };
330 
331 save_result save_image(const locator& i_locator, const std::string& outfile);
332 save_result save_image(const surface& surf, const std::string& outfile);
333 
334 }
double g
Definition: astarsearch.cpp:63
Generic locator abstracting the location of an image.
Definition: picture.hpp:63
locator(locator &&) noexcept=default
int get_center_x() const
Definition: picture.hpp:88
bool is_void() const
Returns true if the locator does not correspond to an actual image.
Definition: picture.hpp:96
T & access_in_cache(cache_type< T > &cache) const
Definition: picture.cpp:128
locator & operator=(const locator &a)=default
locator & operator=(locator &&)=default
bool file_exists() const
Tests whether the file the locator points at exists.
Definition: picture.cpp:564
const std::string & get_filename() const
Definition: picture.hpp:85
bool operator!=(const locator &a) const
Definition: picture.hpp:83
type get_type() const
Definition: picture.hpp:91
bool is_data_uri() const
Definition: picture.hpp:86
const T & locate_in_cache(cache_type< T > &cache) const
Definition: picture.cpp:122
const std::string & get_modifications() const
Definition: picture.hpp:90
int get_center_y() const
Definition: picture.hpp:89
std::optional< T > copy_from_cache(cache_type< T > &cache) const
Definition: picture.cpp:134
bool in_cache(cache_type< T > &cache) const
Definition: picture.cpp:116
const map_location & get_loc() const
Definition: picture.hpp:87
std::size_t hash() const
Definition: picture.cpp:110
locator()=default
bool operator==(const locator &a) const
Definition: picture.hpp:82
locator clone(const std::string &mods) const
Returns a copy of this locator with the given IPF.
Definition: picture.cpp:234
void add_to_cache(cache_type< T > &cache, T data) const
Definition: picture.cpp:141
Wrapper class to encapsulate creation and management of an SDL_Texture.
Definition: texture.hpp:33
Functions to load and save images from/to disk.
std::map< light_string, surface > lit_surface_variants
Type used to pair light possibilities with the corresponding lit surface.
Definition: picture.hpp:180
bool is_empty_hex(const locator &i_locator)
Checks if an image is empty after hex masking.
Definition: picture.cpp:835
bool precached_file_exists(const std::string &file)
Definition: picture.cpp:914
save_result
Definition: picture.hpp:324
bool exists(const image::locator &i_locator)
Returns true if the given image actually exists, without loading it.
Definition: picture.cpp:854
void flush_cache()
Purges all image caches.
Definition: picture.cpp:216
std::map< light_string, texture > lit_texture_variants
Definition: picture.hpp:181
cache_type< texture > texture_cache
Definition: picture.hpp:162
cache_type< lit_surface_variants > lit_surface_cache
Lit variants for each locator.
Definition: picture.hpp:184
cache_type< lit_texture_variants > lit_texture_cache
Definition: picture.hpp:185
surface get_surface(const image::locator &i_locator, TYPE type, bool skip_cache)
Returns an image surface suitable for software manipulation.
Definition: picture.cpp:673
surface get_hexmask()
Retrieves the standard hexagonal tile mask.
Definition: picture.cpp:808
std::ostream & operator<<(std::ostream &s, const locator &l)
Definition: picture.cpp:245
texture get_lighted_texture(const image::locator &i_locator, const light_string &ls)
Definition: picture.cpp:772
save_result save_image(const locator &i_locator, const std::string &filename)
Definition: picture.cpp:924
cache_type< surface > surface_cache
Definition: picture.hpp:161
std::basic_string< signed char > light_string
Type used to store color information of central and adjacent hexes.
Definition: picture.hpp:177
void precache_file_existence(const std::string &subdir)
Precache the existence of files in a binary path subdirectory (e.g.
Definition: picture.cpp:905
TYPE
Used to specify the rendering format of images.
Definition: picture.hpp:224
@ HEXED
Standard hexagonal tile mask applied, removing portions that don't fit.
Definition: picture.hpp:228
@ NUM_TYPES
Definition: picture.hpp:231
@ TOD_COLORED
Same as HEXED, but with Time of Day color tint applied.
Definition: picture.hpp:230
@ UNSCALED
Unmodified original-size image.
Definition: picture.hpp:226
texture get_texture(const image::locator &i_locator, TYPE type, bool skip_cache)
Returns an image texture suitable for hardware-accelerated rendering.
Definition: picture.cpp:960
point get_size(const locator &i_locator, bool skip_cache)
Returns the width and height of an image.
Definition: picture.cpp:814
surface get_lighted_image(const image::locator &i_locator, const light_string &ls)
Caches and returns an image with a lightmap applied to it.
Definition: picture.cpp:736
void set_color_adjustment(int r, int g, int b)
Changes Time of Day color tint for all applicable image types.
Definition: picture.cpp:596
light_string get_light_string(int op, int r, int g, int b)
Returns the light_string for one light operation.
Definition: picture.cpp:498
bool is_in_hex(const locator &i_locator)
Checks if an image fits into a single hex.
Definition: picture.cpp:824
scale_quality
Definition: picture.hpp:234
cache_type< bool > bool_cache
Definition: picture.hpp:163
std::string_view data
Definition: picture.cpp:194
std::string modifications
Definition: picture.hpp:141
map_location loc
Definition: picture.hpp:142
bool operator<(const value &a) const
Definition: picture.cpp:318
locator::type type
Definition: picture.hpp:138
std::string filename
Definition: picture.hpp:140
bool operator==(const value &a) const
Definition: picture.cpp:304
Image cache manager.
Definition: picture.hpp:206
Encapsulates the map of the game.
Definition: location.hpp:38
Holds a 2D point.
Definition: point.hpp:25
#define a
#define b