The Battle for Wesnoth  1.19.0-dev
canvas.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2007 - 2024
3  by Mark de Wever <koraq@xs4all.nl>
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 /**
17  * @file
18  * This file contains the canvas object which is the part where the widgets
19  * draw (temporally) images on.
20  */
21 
22 #pragma once
23 
24 #include "config.hpp"
25 #include "formula/callable.hpp"
26 #include "formula/function.hpp"
27 #include "sdl/texture.hpp"
28 #include "sdl/rect.hpp"
29 
30 struct point;
31 
32 namespace gui2
33 {
34 
35 /**
36  * A simple canvas which can be drawn upon.
37  *
38  * The class has a config which contains what to draw.
39  *
40  * The copy constructor does a shallow copy of the shapes to draw.
41  * a clone() will be implemented if really needed.
42  */
43 class canvas
44 {
45 public:
46  /**
47  * Abstract base class for all other shapes.
48  *
49  * The other shapes are declared and defined in canvas_private.hpp, since the
50  * implementation details are not interesting for users of the canvas.
51  */
52  class shape
53  {
54  public:
55  explicit shape(const config& cfg) : immutable_(cfg["immutable"].to_bool(false))
56  {
57  }
58 
59  virtual ~shape()
60  {
61  }
62 
63  /**
64  * Draws the canvas.
65  *
66  * @param variables The canvas can have formulas in it's
67  * definition, this parameter contains the values
68  * for these formulas.
69  */
70  virtual void draw(wfl::map_formula_callable& variables) = 0;
71 
72  bool immutable() const
73  {
74  return immutable_;
75  }
76 
77  private:
78  /**
79  * If this is true, this shape will not be removed from the canvas even if
80  * the canvas's content is reset.
81  */
82  bool immutable_;
83  };
84 
85  canvas();
86  canvas(const canvas&) = delete;
87  canvas& operator=(const canvas&) = delete;
88  canvas(canvas&& c) noexcept;
89 
90  /**
91  * Update the background blur texture, if relevant and necessary.
92  *
93  * This should be called sometime before draw().
94  * Updating it later is less important as it's quite expensive.
95  *
96  * @param screen_region The area of the screen underneath the canvas.
97  * @param force Regenerate the blur even if we already did it.
98  *
99  * @returns True if draw should continue, false otherwise.
100  */
101  bool update_blur(const rect& screen_region, const bool force = false);
102 
103  /** Clear the cached blur texture, forcing it to regenerate. */
104  void queue_reblur();
105 
106  /**
107  * Draw the canvas' shapes onto the screen.
108  *
109  * It makes sure the image on the canvas is up to date. Also executes the
110  * pre-blitting functions.
111  */
112  void draw();
113 
114  /**
115  * Sets the config.
116  *
117  * @param cfg The config object with the data to draw.
118  * @param force Whether to clear all shapes or not.
119  */
120  void set_cfg(const config& cfg, const bool force = false)
121  {
122  clear_shapes(force);
123  parse_cfg(cfg);
124  }
125 
126  /**
127  * Appends data to the config.
128  *
129  * @param cfg The config object with the data to draw.
130  */
131  void append_cfg(const config& cfg)
132  {
133  parse_cfg(cfg);
134  }
135 
136  /** Update WFL size variables. */
137  void update_size_variables();
138 
139  /***** ***** ***** setters / getters for members ***** ****** *****/
140 
141  unsigned get_width() const
142  {
143  return w_;
144  }
145 
146  unsigned get_height() const
147  {
148  return h_;
149  }
150 
151  void set_size(const point& size);
152 
153  void set_variable(const std::string& key, wfl::variant&& value)
154  {
155  variables_.add(key, std::move(value));
156  }
157 
158 private:
159  /** Vector with the shapes to draw. */
160  std::vector<std::unique_ptr<shape>> shapes_;
161 
162  /**
163  * The depth of the blur to use in the pre committing.
164  *
165  * @note at the moment there's one pre commit function, namely the
166  * blurring so use a variable here, might get more functions in the
167  * future. When that happens need to evaluate whether variables are the
168  * best thing to use.
169  */
170  unsigned blur_depth_;
171 
172  /** Blurred background texture. */
174 
175  /** The region of the screen we have blurred (if any). */
177 
178  /** Whether we have deferred rendering so we can capture for blur. */
179  bool deferred_;
180 
181  /** The full width of the canvas. */
182  unsigned w_;
183 
184  /** The full height of the canvas. */
185  unsigned h_;
186 
187  /** The variables of the canvas. */
189 
190  /** Action function definitions for the canvas. */
192 
193  /**
194  * Parses a config object.
195  *
196  * The config object is parsed and serialized by this function after which
197  * the config object is no longer required and thus not stored in the
198  * object.
199  *
200  * @param cfg The config object with the data to draw, see @ref GUICanvasWML
201  */
202  void parse_cfg(const config& cfg);
203 
204  void clear_shapes(const bool force);
205 };
206 
207 } // namespace gui2
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:159
Abstract base class for all other shapes.
Definition: canvas.hpp:53
shape(const config &cfg)
Definition: canvas.hpp:55
bool immutable_
If this is true, this shape will not be removed from the canvas even if the canvas's content is reset...
Definition: canvas.hpp:82
bool immutable() const
Definition: canvas.hpp:72
virtual void draw(wfl::map_formula_callable &variables)=0
Draws the canvas.
virtual ~shape()
Definition: canvas.hpp:59
A simple canvas which can be drawn upon.
Definition: canvas.hpp:44
texture blur_texture_
Blurred background texture.
Definition: canvas.hpp:173
bool deferred_
Whether we have deferred rendering so we can capture for blur.
Definition: canvas.hpp:179
wfl::action_function_symbol_table functions_
Action function definitions for the canvas.
Definition: canvas.hpp:191
void clear_shapes(const bool force)
Definition: canvas.cpp:662
void set_variable(const std::string &key, wfl::variant &&value)
Definition: canvas.hpp:153
unsigned blur_depth_
The depth of the blur to use in the pre committing.
Definition: canvas.hpp:170
wfl::map_formula_callable variables_
The variables of the canvas.
Definition: canvas.hpp:188
canvas(const canvas &)=delete
bool update_blur(const rect &screen_region, const bool force=false)
Update the background blur texture, if relevant and necessary.
Definition: canvas.cpp:516
rect blur_region_
The region of the screen we have blurred (if any).
Definition: canvas.hpp:176
void parse_cfg(const config &cfg)
Parses a config object.
Definition: canvas.cpp:604
void queue_reblur()
Clear the cached blur texture, forcing it to regenerate.
Definition: canvas.cpp:571
void append_cfg(const config &cfg)
Appends data to the config.
Definition: canvas.hpp:131
unsigned get_height() const
Definition: canvas.hpp:146
canvas & operator=(const canvas &)=delete
std::vector< std::unique_ptr< shape > > shapes_
Vector with the shapes to draw.
Definition: canvas.hpp:160
unsigned w_
The full width of the canvas.
Definition: canvas.hpp:182
void update_size_variables()
Update WFL size variables.
Definition: canvas.cpp:648
unsigned h_
The full height of the canvas.
Definition: canvas.hpp:185
void draw()
Draw the canvas' shapes onto the screen.
Definition: canvas.cpp:576
unsigned get_width() const
Definition: canvas.hpp:141
void set_size(const point &size)
Definition: canvas.cpp:655
void set_cfg(const config &cfg, const bool force=false)
Sets the config.
Definition: canvas.hpp:120
Wrapper class to encapsulate creation and management of an SDL_Texture.
Definition: texture.hpp:33
map_formula_callable & add(const std::string &key, const variant &value)
Definition: callable.hpp:253
Generic file dialog.
std::size_t size(const std::string &str)
Length in characters of a UTF-8 string.
Definition: unicode.cpp:85
Contains the SDL_Rect helper code.
Holds a 2D point.
Definition: point.hpp:25
An abstract description of a rectangle with integer coordinates.
Definition: rect.hpp:47
mock_char c