The Battle for Wesnoth  1.19.12+dev
picture.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2025
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 "utils/optional_fwd.hpp"
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  * Generic locator abstracting the location of an image.
52  *
53  * Constructing locators is somewhat slow, while accessing images through
54  * locators is fast. The general idea is that callers should store locators
55  * and not strings to construct new ones. (The latter will still work, of
56  * course, even if it is slower.)
57  */
58 class locator
59 {
60 public:
61  enum type { NONE, FILE, SUB_FILE };
62 
63  locator() = default;
64  locator(locator&&) noexcept = default;
65  locator(const locator&) = default;
66 
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) = default;
72  locator& operator=(locator&&) = default;
73 
74  /** Returns a copy of this locator with the given IPF */
75  locator clone(const std::string& mods) const;
76 
77  bool operator==(const locator& a) const;
78  bool operator!=(const locator& a) const { return !operator==(a); }
79 
80  bool operator<(const locator& a) const;
81 
82  const std::string& get_filename() const { return filename_; }
83  bool is_data_uri() const { return is_data_uri_; }
84  const map_location& get_loc() const { return loc_ ; }
85  int get_center_x() const { return center_x_; }
86  int get_center_y() const { return center_y_; }
87  const std::string& get_modifications() const { return modifications_; }
88  type get_type() const { return type_; }
89 
90  /**
91  * Returns @a true if the locator does not correspond to an actual image.
92  */
93  bool is_void() const { return type_ == NONE; }
94 
95 private:
97  bool is_data_uri_ = false;
98  std::string filename_{};
99  std::string modifications_{};
101  int center_x_ = 0;
102  int center_y_ = 0;
103 
104 public:
105  friend std::size_t hash_value(const locator&);
106 };
107 
108 // write a readable representation of a locator, mostly for debugging
109 std::ostream& operator<<(std::ostream&, const locator&);
110 
111 /**
112  * Type used to store color information of central and adjacent hexes.
113  *
114  * The structure is one or several 4-char blocks: [L,R,G,B]
115  * The R, G, B values represent the color, and L the lightmap to use:
116  *
117  * -1: none
118  * 0: full hex
119  * 1-6: concave corners
120  * 7-12: convex half-corners 1
121  * 13-19: convex half-corners 2
122  */
124 {
125  light_adjust(int op, int r, int g, int b);
126 
127  int8_t l;
128  int8_t r;
129  int8_t g;
130  int8_t b;
131 
132 #ifdef __cpp_impl_three_way_comparison
133  auto operator<=>(const light_adjust&) const = default;
134 #else
135  // TODO C++20: default these (╯°□°)╯︵ ┻━┻
136  bool operator==(const light_adjust& o) const;
137  bool operator!=(const light_adjust& o) const { return !operator==(o); }
138 #endif
139 };
140 
141 /**
142  * Purges all image caches.
143  */
144 void flush_cache();
145 
146 /**
147  * Image cache manager.
148  *
149  * This class is responsible for setting up and flushing the image cache. No
150  * more than one instance of it should exist at a time.
151  */
152 struct manager
153 {
154  manager();
155  ~manager();
156 };
157 
158 /**
159  * Changes Time of Day color tint for all applicable image types.
160  *
161  * In particular this affects TOD_COLORED images, as well as
162  * images with lightmaps applied. Changing the previous values automatically
163  * invalidates all cached images of those types.
164  */
165 void set_color_adjustment(int r, int g, int b);
166 
167 /**
168  * Used to specify the rendering format of images.
169  */
170 enum TYPE
171 {
172  /** Unmodified original-size image. */
174  /** Standard hexagonal tile mask applied, removing portions that don't fit. */
176  /** Same as HEXED, but with Time of Day color tint applied. */
178  NUM_TYPES // Equal to the number of types specified above
179 };
180 
181 enum class scale_quality { nearest, linear };
182 
183 /**
184  * Returns an image surface suitable for software manipulation.
185  *
186  * The equivalent get_texture() function should generally be preferred.
187  *
188  * Surfaces will be cached for repeat access, unless skip_cache is set.
189  *
190  * @param i_locator Image path.
191  * @param type Rendering format.
192  * @param skip_cache Skip adding the result to the surface cache.
193  */
194 surface get_surface(const locator& i_locator, TYPE type = UNSCALED,
195  bool skip_cache = false);
196 
197 /**
198  * Returns an image texture suitable for hardware-accelerated rendering.
199  *
200  * Texture pointers are not unique, and will be cached and retained
201  * until no longer needed. Users of the returned texture do not have to
202  * worry about texture management.
203  *
204  * If caching is disabled via @a skip_cache, texture memory will be
205  * automatically freed once the returned object and all other linked
206  * textures (if any) are destroyed.
207  *
208  * @param i_locator Image path.
209  * @param type Rendering format.
210  * @param skip_cache Skip adding the result to the surface cache.
211  */
212 texture get_texture(const locator& i_locator, TYPE type = UNSCALED,
213  bool skip_cache = false);
214 
215 texture get_texture(const image::locator& i_locator, scale_quality quality,
216  TYPE type = UNSCALED, bool skip_cache = false);
217 
218 /**
219  * Caches and returns an image with a lightmap applied to it.
220  *
221  * Images will always be HEXED type.
222  *
223  * @param i_locator Image path.
224  * @param ls Light map to apply to the image.
225  */
226 surface get_lighted_image(const image::locator& i_locator, const std::vector<light_adjust>& ls);
227 texture get_lighted_texture(const image::locator& i_locator, const std::vector<light_adjust>& ls);
228 
229 /**
230  * Retrieves the standard hexagonal tile mask.
231  */
233 
234 /**
235  * Returns the width and height of an image.
236  *
237  * If the image is not yet in the surface cache, it will be loaded and cached
238  * unless skip_cache is explicitly set.
239  *
240  * @param i_locator Image path.
241  * @param skip_cache If true, do not cache the image if loaded.
242  */
243 point get_size(const locator& i_locator, bool skip_cache = false);
244 
245 /**
246  * Checks if an image fits into a single hex.
247  */
248 bool is_in_hex(const locator& i_locator);
249 
250 /**
251  * Checks if an image is empty after hex masking.
252  *
253  * This should be only used on terrain images, and it will automatically cache
254  * the hex-masked version if necessary.
255  */
256 bool is_empty_hex(const locator& i_locator);
257 
258 /**
259  * Returns @a true if the given image actually exists, without loading it.
260  */
261 bool exists(const locator& i_locator);
262 
263 /**
264  * Precache the existence of files in a binary path subdirectory (e.g. "terrain/").
265  */
266 void precache_file_existence(const std::string& subdir = "");
267 
268 bool precached_file_exists(const std::string& file);
269 
270 enum class save_result
271 {
272  success,
274  save_failed,
275  no_image
276 };
277 
278 save_result save_image(const locator& i_locator, const std::string& outfile);
279 save_result save_image(const surface& surf, const std::string& outfile);
280 
281 } // namespace image
map_location loc
Definition: move.cpp:172
double g
Definition: astarsearch.cpp:63
Generic locator abstracting the location of an image.
Definition: picture.hpp:59
locator(locator &&) noexcept=default
int get_center_x() const
Definition: picture.hpp:85
bool is_void() const
Returns true if the locator does not correspond to an actual image.
Definition: picture.hpp:93
map_location loc_
Definition: picture.hpp:100
std::string filename_
Definition: picture.hpp:98
const std::string & get_filename() const
Definition: picture.hpp:82
type get_type() const
Definition: picture.hpp:88
friend std::size_t hash_value(const locator &)
Hash function overload for boost::hash.
Definition: picture.cpp:67
bool is_data_uri() const
Definition: picture.hpp:83
const std::string & get_modifications() const
Definition: picture.hpp:87
int get_center_y() const
Definition: picture.hpp:86
bool is_data_uri_
Definition: picture.hpp:97
const map_location & get_loc() const
Definition: picture.hpp:84
locator::type type_
Definition: picture.hpp:96
locator()=default
bool operator<(const locator &a) const
Definition: picture.cpp:313
bool operator==(const locator &a) const
Definition: picture.cpp:299
locator clone(const std::string &mods) const
Returns a copy of this locator with the given IPF.
Definition: picture.cpp:228
std::string modifications_
Definition: picture.hpp:99
Wrapper class to encapsulate creation and management of an SDL_Texture.
Definition: texture.hpp:33
Functions to load and save images from/to disk.
bool is_empty_hex(const locator &i_locator)
Checks if an image is empty after hex masking.
Definition: picture.cpp:819
bool precached_file_exists(const std::string &file)
Definition: picture.cpp:896
save_result
Definition: picture.hpp:271
bool exists(const image::locator &i_locator)
Returns true if the given image actually exists, without loading it.
Definition: picture.cpp:840
void flush_cache()
Purges all image caches.
Definition: picture.cpp:210
surface get_surface(const image::locator &i_locator, TYPE type, bool skip_cache)
Returns an image surface suitable for software manipulation.
Definition: picture.cpp:679
surface get_hexmask()
Retrieves the standard hexagonal tile mask.
Definition: picture.cpp:793
std::ostream & operator<<(std::ostream &s, const locator &l)
Definition: picture.cpp:239
save_result save_image(const locator &i_locator, const std::string &filename)
Definition: picture.cpp:906
void precache_file_existence(const std::string &subdir)
Precache the existence of files in a binary path subdirectory (e.g.
Definition: picture.cpp:889
TYPE
Used to specify the rendering format of images.
Definition: picture.hpp:171
@ HEXED
Standard hexagonal tile mask applied, removing portions that don't fit.
Definition: picture.hpp:175
@ NUM_TYPES
Definition: picture.hpp:178
@ TOD_COLORED
Same as HEXED, but with Time of Day color tint applied.
Definition: picture.hpp:177
@ UNSCALED
Unmodified original-size image.
Definition: picture.hpp:173
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:942
point get_size(const locator &i_locator, bool skip_cache)
Returns the width and height of an image.
Definition: picture.cpp:799
texture get_lighted_texture(const image::locator &i_locator, const std::vector< light_adjust > &ls)
Definition: picture.cpp:770
void set_color_adjustment(int r, int g, int b)
Changes Time of Day color tint for all applicable image types.
Definition: picture.cpp:603
surface get_lighted_image(const image::locator &i_locator, const std::vector< light_adjust > &ls)
Caches and returns an image with a lightmap applied to it.
Definition: picture.cpp:747
bool is_in_hex(const locator &i_locator)
Checks if an image fits into a single hex.
Definition: picture.cpp:808
scale_quality
Definition: picture.hpp:181
surface surf
Image.
std::string filename
Filename.
Type used to store color information of central and adjacent hexes.
Definition: picture.hpp:124
bool operator==(const light_adjust &o) const
Definition: picture.cpp:502
bool operator!=(const light_adjust &o) const
Definition: picture.hpp:137
light_adjust(int op, int r, int g, int b)
Definition: picture.cpp:489
Image cache manager.
Definition: picture.hpp:153
Encapsulates the map of the game.
Definition: location.hpp:45
Holds a 2D point.
Definition: point.hpp:25
#define b