The Battle for Wesnoth  1.17.10+dev
video.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2022
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 "exceptions.hpp"
20 #include "sdl/point.hpp"
21 #include "sdl/rect.hpp"
22 #include "sdl/texture.hpp"
23 
24 #include <SDL2/SDL_render.h>
25 
26 #include <vector>
27 
28 class surface;
29 class texture;
30 
31 namespace video
32 {
33 
34 /******************/
35 /* Initialization */
36 /******************/
37 
38 /**
39  * For describing the type of faked display, if any.
40  *
41  * fake::window never tries to create a window, or draw anything.
42  * fake::draw does create an offscreen window, but does not draw to it.
43  */
44 enum class fake { none, window, draw };
45 
46 /**
47  * Initialize the video subsystem.
48  *
49  * This must be called before attempting to use any video functions.
50  */
51 void init(fake fake_type = fake::none);
52 
53 /**
54  * Deinitialize the video subsystem.
55  *
56  * This flushes all texture caches and disconnects the SDL video subsystem.
57  */
58 void deinit();
59 
60 /**
61  * Update buffers to match current resolution and pixel scale settings.
62  *
63  * If @p autoupdate is true and buffers are changed by this call,
64  * a full redraw is also triggered.
65  *
66  * If nothing has changed, it will not generate any new buffers or queue
67  * the redraw.
68  */
69 void update_buffers(bool autoupdate = true);
70 
71 
72 /**********************************/
73 /* Unit-test and headless support */
74 /**********************************/
75 
76 /** The game is running headless. There is no window or renderer. */
77 bool headless();
78 
79 /** The game is running unit tests. There is a window and offscreen
80  * render buffer, but performing actual rendering is unnecessary. */
81 bool testing();
82 
83 
84 /***********************/
85 /* Windowing functions */
86 /***********************/
87 
88 /** Whether we are currently in fullscreen mode */
89 bool is_fullscreen();
90 
91 /**
92  * Set the fullscreen state.
93  *
94  * If the setting matches the current fullscreen state, the window state
95  * will not be changed.
96  *
97  * If false and the window is fullscreen, the window will be restored to
98  * its last saved non-fullscreen configuration.
99  */
100 void set_fullscreen(bool);
101 
102 /**
103  * Toggle fullscreen mode.
104  *
105  * Equivalent to set_fullscreen(!is_fullscreen()).
106  */
107 void toggle_fullscreen();
108 
109 /**
110  * Set the window resolution.
111  *
112  * @todo this is no longer useful as fullscreen is always native resolution.
113  *
114  * @param resolution The new width and height.
115  *
116  * @returns Whether the resolution was successfully changed.
117  */
118 bool set_resolution(const point& resolution);
119 
120 /** The current window size in desktop coordinates. */
122 
123 /** Returns the list of available screen resolutions. */
124 std::vector<point> get_available_resolutions(bool include_current = false);
125 
126 /** The current video driver in use, or else "<not initialized>". */
127 std::string current_driver();
128 
129 /** A list of available video drivers. */
130 std::vector<std::string> enumerate_drivers();
131 
132 /**
133  * The refresh rate of the screen.
134  *
135  * If a refresh cannot be detected, this may return 0, or it may return a
136  * substitute value.
137  */
139 
140 /** True iff the window is not hidden. */
141 bool window_is_visible();
142 /** True iff the window has mouse or input focus */
143 bool window_has_focus();
144 /** True iff the window has mouse focus */
146 
147 /** Sets the title of the main window. */
148 void set_window_title(const std::string& title);
149 
150 /** Sets the icon of the main window. */
151 void set_window_icon(surface& icon);
152 
153 
154 /**********************/
155 /* Coordinate Systems */
156 /**********************/
157 
158 /**
159  * The game canvas area, in drawing coordinates.
160  *
161  * This is the "screen area", as seen by game systems, and as used for
162  * specifying where to draw things on-screen. It may differ, in high-dpi
163  * contexts, from input area, window area, and output area.
164  *
165  * Usually this is the only area game components should use or care about.
166  *
167  * The units it uses can be considered "pixels". Final output will be
168  * rendered in higher resolution automatically if and when appropriate.
169  */
170 rect game_canvas();
171 
172 /** The size of the game canvas, in drawing coordinates / game pixels. */
174 
175 /**
176  * The size of the current render target in drawing coordinates.
177  *
178  * This will be the same as game_canvas_size() unless the render target
179  * has been manually changed.
180  */
181 point draw_size();
182 
183 /**
184  * The current drawable area.
185  *
186  * Equivalent to {0, 0, draw_size().x, draw_size().y}.
187  */
188 rect draw_area();
189 
190 /**
191  * Returns the size of the final render target. This is irrelevant
192  * for most purposes. Use game_canvas_size() in stead.
193  */
195 
196 /** {0, 0, output_size().x, output_size().y} */
197 rect output_area();
198 
199 /**
200  * Returns the size of the window in display units / screen coordinates.
201  * This should match the value sent by window resize events, and also
202  * those used for setting resolution.
203  */
205 
206 /**
207  * Returns the input area of the window, in display coordinates.
208  *
209  * This can be slightly offset within the window, if the drawable area
210  * is not the same as the full window area. This will happen if output
211  * size is not a perfect multiple of the draw size.
212  *
213  * In general this will be almost, but not quite, equal to window_size().
214  *
215  * input_area() represents the portion of the window corresponding to
216  * game_canvas().
217  */
218 rect input_area();
219 
220 /**
221  * Get the current active pixel scale multiplier.
222  * This is equal to output_size() / game_canvas_size().
223  * Currently it is always integer, and the same in both dimensions.
224  *
225  * This may differ from preferences::pixel_scale() in some cases,
226  * For example if the window is too small to fit the desired scale.
227  *
228  * @returns The currently active pixel scale multiplier.
229  */
230 int get_pixel_scale();
231 
232 /**
233  * Convert coordinates in draw space to coordinates in render space.
234  */
235 rect to_output(const rect& draw_space_rect);
236 
237 
238 /******************/
239 /* Screen capture */
240 /******************/
241 // These functions are slow, and intended only for screenshots.
242 
243 /**
244  * Copy back a portion of the render target that is already drawn.
245  *
246  * This area is specified in draw coordinates, not render coordinates.
247  * Thus the size of the retrieved surface may not match the size of r.
248  *
249  * If not null, r will be automatically clipped to the drawing area.
250  *
251  * Note: This is a very slow function! Its use should be phased out
252  * for everything except maybe screenshots.
253  *
254  * @param r The portion of the render target to retrieve, in
255  * draw coordinates.
256  * If not null, this will be modified to reflect the
257  * portion of the draw area that has been returned.
258  */
259 surface read_pixels(SDL_Rect* r = nullptr);
260 
261 /**
262  * The same as read_pixels, but returns a low-resolution surface
263  * suitable for use with the old drawing system.
264  *
265  * This should be considered deprecated, and phased out ASAP.
266  */
267 surface read_pixels_low_res(SDL_Rect* r = nullptr);
268 
269 
270 /****************************/
271 /* Render target management */
272 /****************************/
273 
274 /**
275  * Set the render target, without any provided way of setting it back.
276  *
277  * End-users should not use this function directly. In stead use
278  * draw::set_render_target(), which returns a setter object which
279  * will automatically restore the render target upon leaving scope.
280  *
281  * @param t The new render target. This must be a texture created
282  * with SDL_TEXTUREACCESS_TARGET, or an empty texture to
283  * indicate the underlying window.
284  */
285 void force_render_target(const texture& t);
286 
287 /** Reset the render target to the main window / screen. */
288 void clear_render_target();
289 
290 /** Get the current render target.
291  *
292  * Will return an empty texture if the render target is the underlying
293  * window.
294  */
296 
297 
298 /*******************/
299 /* Exception types */
300 /*******************/
301 
302 /** An error specifically indicating video subsystem problems. */
303 struct error : public game::error
304 {
305  error() : game::error("unspecified video subsystem error") {}
306  error(const std::string& msg) : game::error(msg) {}
307 };
308 
309 /** Type that can be thrown as an exception to quit to desktop. */
311 {
312 public:
315  {
316  }
317 
318 private:
320 };
321 
322 /* This should only be used by draw.cpp for drawing, and texture.cpp for
323  * texture creation. Try not to use it for anything else. */
324 SDL_Renderer* get_renderer();
325 
326 /* This should not be used unless absolutely necessary. It's currently used
327  * for Windows tray notification and that's it. If it can be refactored out
328  * somehow then that would be best. */
329 SDL_Window* get_window();
330 
331 } // namespace video
void init(fake type)
Initialize the video subsystem.
Definition: video.cpp:87
std::vector< point > get_available_resolutions(const bool include_current)
Returns the list of available screen resolutions.
Definition: video.cpp:687
surface read_pixels(SDL_Rect *r)
Copy back a portion of the render target that is already drawn.
Definition: video.cpp:563
int get_pixel_scale()
Get the current active pixel scale multiplier.
Definition: video.cpp:471
SDL_Renderer * get_renderer()
Definition: video.cpp:629
std::string current_driver()
The current video driver in use, or else "<not initialized>".
Definition: video.cpp:643
An error specifically indicating video subsystem problems.
Definition: video.hpp:303
void set_window_title(const std::string &title)
Sets the title of the main window.
Definition: video.cpp:617
#define IMPLEMENT_LUA_JAILBREAK_EXCEPTION(type)
Helper macro for classes deriving from lua_jailbreak_exception.
rect output_area()
{0, 0, output_size().x, output_size().y}
Definition: video.cpp:450
bool is_fullscreen()
Whether we are currently in fullscreen mode.
Definition: video.cpp:747
bool window_has_focus()
True iff the window has mouse or input focus.
Definition: video.cpp:677
rect to_output(const rect &r)
Convert coordinates in draw space to coordinates in render space.
Definition: video.cpp:456
int current_refresh_rate()
The refresh rate of the screen.
Definition: video.cpp:476
void deinit()
Deinitialize the video subsystem.
Definition: video.cpp:113
void set_fullscreen(bool fullscreen)
Set the fullscreen state.
Definition: video.cpp:755
static void msg(const char *act, debug_info &i, const char *to="", const char *result="")
Definition: debugger.cpp:110
bool testing()
The game is running unit tests.
Definition: video.cpp:148
texture get_render_target()
Get the current render target.
Definition: video.cpp:518
std::vector< std::string > enumerate_drivers()
A list of available video drivers.
Definition: video.cpp:649
Wrapper class to encapsulate creation and management of an SDL_Texture.
Definition: texture.hpp:32
bool set_resolution(const point &resolution)
Set the window resolution.
Definition: video.cpp:784
void update_buffers(bool autoupdate)
Update buffers to match current resolution and pixel scale settings.
Definition: video.cpp:814
point current_resolution()
The current window size in desktop coordinates.
Definition: video.cpp:739
rect game_canvas()
The game canvas area, in drawing coordinates.
Definition: video.cpp:417
point output_size()
Returns the size of the final render target.
Definition: video.cpp:400
rect draw_area()
The current drawable area.
Definition: video.cpp:432
bool headless()
The game is running headless.
Definition: video.cpp:143
error(const std::string &msg)
Definition: video.hpp:306
void set_window_icon(surface &icon)
Sets the icon of the main window.
Definition: video.cpp:623
void force_render_target(const texture &t)
Set the render target, without any provided way of setting it back.
Definition: video.cpp:482
fake
For describing the type of faked display, if any.
Definition: video.hpp:44
point game_canvas_size()
The size of the game canvas, in drawing coordinates / game pixels.
Definition: video.cpp:422
An abstract description of a rectangle with integer coordinates.
Definition: rect.hpp:46
Holds a 2D point.
Definition: point.hpp:24
bool window_has_mouse_focus()
True iff the window has mouse focus.
Definition: video.cpp:682
Type that can be thrown as an exception to quit to desktop.
Definition: video.hpp:310
point draw_size()
The size of the current render target in drawing coordinates.
Definition: video.cpp:427
bool window_is_visible()
True iff the window is not hidden.
Definition: video.cpp:672
void toggle_fullscreen()
Toggle fullscreen mode.
Definition: video.cpp:779
surface read_pixels_low_res(SDL_Rect *r)
The same as read_pixels, but returns a low-resolution surface suitable for use with the old drawing s...
Definition: video.cpp:603
SDL_Window * get_window()
Definition: video.cpp:638
Contains the SDL_Rect helper code.
double t
Definition: astarsearch.cpp:65
Base class for all the errors encountered by the engine.
Definition: exceptions.hpp:28
point window_size()
Returns the size of the window in display units / screen coordinates.
Definition: video.cpp:409
rect input_area()
Returns the input area of the window, in display coordinates.
Definition: video.cpp:466
point resolution()
Definition: general.cpp:395
Definition: draw.hpp:42
Base class for exceptions that want to be thrown &#39;through&#39; lua.
void clear_render_target()
Reset the render target to the main window / screen.
Definition: video.cpp:513