The Battle for Wesnoth  1.19.14+dev
video.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 "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 
30 namespace video
31 {
32 
33 /******************/
34 /* Initialization */
35 /******************/
36 
37 /**
38  * For describing the type of faked display, if any.
39  *
40  * fake::no_window never tries to create a window, or draw anything.
41  * fake::no_draw does create an offscreen window, but does not draw to it.
42  * fake::hide_window creates a window as normal, but does not display it.
43  */
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 the game has set up a window to render into */
89 bool has_window();
90 
91 /** Whether we are currently in fullscreen mode */
92 bool is_fullscreen();
93 
94 /**
95  * Set the fullscreen state.
96  *
97  * If the setting matches the current fullscreen state, the window state
98  * will not be changed.
99  *
100  * If false and the window is fullscreen, the window will be restored to
101  * its last saved non-fullscreen configuration.
102  */
103 void set_fullscreen(bool);
104 
105 /**
106  * Toggle fullscreen mode.
107  *
108  * Equivalent to set_fullscreen(!is_fullscreen()).
109  */
110 void toggle_fullscreen();
111 
112 /**
113  * Set the window resolution.
114  *
115  * @todo this is no longer useful as fullscreen is always native resolution.
116  *
117  * @param resolution The new width and height.
118  *
119  * @returns Whether the resolution was successfully changed.
120  */
121 bool set_resolution(const point& resolution);
122 
123 /** The current window size in desktop coordinates. */
125 
126 /** Returns the list of available screen resolutions. */
127 std::vector<point> get_available_resolutions(bool include_current = false);
128 
129 /** The current video driver in use, or else "<not initialized>". */
130 std::string current_driver();
131 
132 /** A list of available video drivers. */
133 std::vector<std::string> enumerate_drivers();
134 
135 /**
136  * The refresh rate of the screen.
137  *
138  * In most cases, this will be the native refresh rate of the display, but
139  * could be lower if FPS has been artificially capped (i.e., through --max-fps).
140  *
141  * If a refresh cannot be detected, this may return 0, or it may return a
142  * substitute value.
143  */
145 
146 /** The native refresh rate of display, not taking any user preferences into account. */
147 int native_refresh_rate();
148 
149 /** True iff the window is not hidden. */
150 bool window_is_visible();
151 /** True iff the window has mouse or input focus */
152 bool window_has_focus();
153 /** True iff the window has mouse focus */
155 
156 /** Sets the title of the main window. */
157 void set_window_title(const std::string& title);
158 
159 /** Sets the icon of the main window. */
160 void set_window_icon(surface& icon);
161 
162 
163 /**********************/
164 /* Coordinate Systems */
165 /**********************/
166 
167 /**
168  * The game canvas area, in drawing coordinates.
169  *
170  * This is the "screen area", as seen by game systems, and as used for
171  * specifying where to draw things on-screen. It may differ, in high-dpi
172  * contexts, from input area, window area, and output area.
173  *
174  * Usually this is the only area game components should use or care about.
175  *
176  * The units it uses can be considered "pixels". Final output will be
177  * rendered in higher resolution automatically if and when appropriate.
178  */
179 rect game_canvas();
180 
181 /** The size of the game canvas, in drawing coordinates / game pixels. */
183 
184 /**
185  * The size of the current render target in drawing coordinates.
186  *
187  * This will be the same as game_canvas_size() unless the render target
188  * has been manually changed.
189  */
190 point draw_size();
191 
192 /**
193  * The current drawable area.
194  *
195  * Equivalent to {0, 0, draw_size().x, draw_size().y}.
196  */
197 rect draw_area();
198 
199 /**
200  * Returns the size of the final render target. This is irrelevant
201  * for most purposes. Use game_canvas_size() in stead.
202  */
204 
205 /** {0, 0, output_size().x, output_size().y} */
206 rect output_area();
207 
208 /**
209  * Returns the size of the window in display units / screen coordinates.
210  * This should match the value sent by window resize events, and also
211  * those used for setting resolution.
212  */
214 
215 /**
216  * Returns the input area of the window, in display coordinates.
217  *
218  * This can be slightly offset within the window, if the drawable area
219  * is not the same as the full window area. This will happen if output
220  * size is not a perfect multiple of the draw size.
221  *
222  * In general this will be almost, but not quite, equal to window_size().
223  *
224  * input_area() represents the portion of the window corresponding to
225  * game_canvas().
226  */
227 rect input_area();
228 
229 /**
230  * Get the current active pixel scale multiplier.
231  * This is equal to output_size() / game_canvas_size().
232  * Currently it is always integer, and the same in both dimensions.
233  *
234  * This may differ from prefs::get().pixel_scale() in some cases,
235  * For example if the window is too small to fit the desired scale.
236  *
237  * @returns The currently active pixel scale multiplier.
238  */
239 int get_pixel_scale();
240 
241 /**
242  * @returns Scale factor corresponding to maximum possible scale.
243  */
244 int get_max_pixel_scale();
245 
246 /**
247  * Convert coordinates in draw space to coordinates in render space.
248  */
249 rect to_output(const rect& draw_space_rect);
250 
251 
252 /******************/
253 /* Screen capture */
254 /******************/
255 // These functions are slow, and intended only for screenshots.
256 
257 /**
258  * Copy back a portion of the render target that is already drawn.
259  *
260  * This area is specified in draw coordinates, not render coordinates.
261  * Thus the size of the retrieved surface may not match the size of r.
262  *
263  * If not null, r will be automatically clipped to the drawing area.
264  *
265  * Note: This is a very slow function! Its use should be phased out
266  * for everything except maybe screenshots.
267  *
268  * @param r The portion of the render target to retrieve, in
269  * draw coordinates.
270  * If not null, this will be modified to reflect the
271  * portion of the draw area that has been returned.
272  */
273 surface read_pixels(rect* r = nullptr);
274 
275 /**
276  * The same as read_pixels, but returns a low-resolution surface
277  * suitable for use with the old drawing system.
278  *
279  * This should be considered deprecated, and phased out ASAP.
280  */
281 surface read_pixels_low_res(rect* r = nullptr);
282 
283 
284 /****************************/
285 /* Render target management */
286 /****************************/
287 
288 /**
289  * Set the render target, without any provided way of setting it back.
290  *
291  * End-users should not use this function directly. In stead use
292  * draw::set_render_target(), which returns a setter object which
293  * will automatically restore the render target upon leaving scope.
294  *
295  * @param t The new render target. This must be a texture created
296  * with SDL_TEXTUREACCESS_TARGET, or an empty texture to
297  * indicate the underlying window.
298  */
299 void force_render_target(const texture& t);
300 
301 /** Reset the render target to the main window / screen. */
302 void clear_render_target();
303 
304 /** Reset the render target to the primary render buffer. */
305 void reset_render_target();
306 
307 /** Get the current render target.
308  *
309  * Will return an empty texture if the render target is the underlying
310  * window.
311  */
313 
314 
315 /*******************/
316 /* Exception types */
317 /*******************/
318 
319 /** An error specifically indicating video subsystem problems. */
320 struct error : public game::error
321 {
322  error() : game::error("unspecified video subsystem error") {}
323  error(const std::string& msg) : game::error(msg) {}
324 };
325 
326 /** Type that can be thrown as an exception to quit to desktop. */
327 class quit final : public lua_jailbreak_exception
328 {
329 public:
332  {
333  this->store();
334  }
335 
336 private:
338 };
339 
340 
341 /***************/
342 /* Diagnostics */
343 /***************/
344 
345 /**
346  * Provides diagnostic information about the current renderer for the @a build_info API.
347  */
348 std::vector<std::pair<std::string, std::string>> renderer_report();
349 
350 /**
351  * Retrieves the current game screen DPI for the @a build_info API.
352  */
353 std::pair<float, float> get_dpi();
354 
355 
356 /**************************/
357 /* Implementation details */
358 /**************************/
359 
360 /* This should only be used by draw.cpp for drawing, and texture.cpp for
361  * texture creation. Try not to use it for anything else. */
362 SDL_Renderer* get_renderer();
363 
364 /* This should not be used unless absolutely necessary. It's currently used
365  * for Windows tray notification and that's it. If it can be refactored out
366  * somehow then that would be best. */
367 SDL_Window* get_window();
368 
369 } // namespace video
double t
Definition: astarsearch.cpp:63
Base class for exceptions that want to be thrown 'through' lua.
void store() const noexcept
Stores a copy the current exception to be rethrown.
Wrapper class to encapsulate creation and management of an SDL_Texture.
Definition: texture.hpp:33
Type that can be thrown as an exception to quit to desktop.
Definition: video.hpp:328
#define IMPLEMENT_LUA_JAILBREAK_EXCEPTION(type)
Helper macro for classes deriving from lua_jailbreak_exception.
bool window_has_mouse_focus()
True iff the window has mouse focus.
Definition: video.cpp:736
bool headless()
The game is running headless.
Definition: video.cpp:147
rect draw_area()
The current drawable area.
Definition: video.cpp:459
rect output_area()
{0, 0, output_size().x, output_size().y}
Definition: video.cpp:477
void set_window_title(const std::string &title)
Sets the title of the main window.
Definition: video.cpp:671
void clear_render_target()
Reset the render target to the main window / screen.
Definition: video.cpp:554
rect to_output(const rect &r)
Convert coordinates in draw space to coordinates in render space.
Definition: video.cpp:483
std::vector< std::pair< std::string, std::string > > renderer_report()
Provides diagnostic information about the current renderer for the build_info API.
Definition: video.cpp:900
void reset_render_target()
Reset the render target to the primary render buffer.
Definition: video.cpp:559
point output_size()
Returns the size of the final render target.
Definition: video.cpp:427
std::vector< point > get_available_resolutions(const bool include_current)
Returns the list of available screen resolutions.
Definition: video.cpp:741
void set_window_icon(surface &icon)
Sets the icon of the main window.
Definition: video.cpp:677
int get_max_pixel_scale()
Definition: video.cpp:503
bool window_is_visible()
True iff the window is not hidden.
Definition: video.cpp:726
void force_render_target(const texture &t)
Set the render target, without any provided way of setting it back.
Definition: video.cpp:523
point game_canvas_size()
The size of the game canvas, in drawing coordinates / game pixels.
Definition: video.cpp:449
SDL_Window * get_window()
Definition: video.cpp:692
bool window_has_focus()
True iff the window has mouse or input focus.
Definition: video.cpp:731
point window_size()
Returns the size of the window in display units / screen coordinates.
Definition: video.cpp:436
bool has_window()
Whether the game has set up a window to render into.
Definition: video.cpp:422
bool testing()
The game is running unit tests.
Definition: video.cpp:152
bool is_fullscreen()
Whether we are currently in fullscreen mode.
Definition: video.cpp:801
std::vector< std::string > enumerate_drivers()
A list of available video drivers.
Definition: video.cpp:703
rect game_canvas()
The game canvas area, in drawing coordinates.
Definition: video.cpp:444
std::pair< float, float > get_dpi()
Retrieves the current game screen DPI for the build_info API.
Definition: video.cpp:880
int get_pixel_scale()
Get the current active pixel scale multiplier.
Definition: video.cpp:498
point current_resolution()
The current window size in desktop coordinates.
Definition: video.cpp:793
int native_refresh_rate()
The native refresh rate of display, not taking any user preferences into account.
Definition: video.cpp:508
void init(fake type)
Initialize the video subsystem.
Definition: video.cpp:90
void set_fullscreen(bool fullscreen)
Set the fullscreen state.
Definition: video.cpp:809
void deinit()
Deinitialize the video subsystem.
Definition: video.cpp:119
bool set_resolution(const point &resolution)
Set the window resolution.
Definition: video.cpp:838
int current_refresh_rate()
The refresh rate of the screen.
Definition: video.cpp:513
surface read_pixels_low_res(rect *r)
The same as read_pixels, but returns a low-resolution surface suitable for use with the old drawing s...
Definition: video.cpp:657
std::string current_driver()
The current video driver in use, or else "<not initialized>".
Definition: video.cpp:697
surface read_pixels(rect *r)
Copy back a portion of the render target that is already drawn.
Definition: video.cpp:617
void toggle_fullscreen()
Toggle fullscreen mode.
Definition: video.cpp:833
SDL_Renderer * get_renderer()
Definition: video.cpp:683
void update_buffers(bool autoupdate)
Update buffers to match current resolution and pixel scale settings.
Definition: video.cpp:868
texture get_render_target()
Get the current render target.
Definition: video.cpp:564
fake
For describing the type of faked display, if any.
Definition: video.hpp:44
point draw_size()
The size of the current render target in drawing coordinates.
Definition: video.cpp:454
rect input_area()
Returns the input area of the window, in display coordinates.
Definition: video.cpp:493
static void msg(const char *act, debug_info &i, const char *to="", const char *result="")
Definition: debugger.cpp:109
Contains the SDL_Rect helper code.
Base class for all the errors encountered by the engine.
Definition: exceptions.hpp:29
Holds a 2D point.
Definition: point.hpp:25
An abstract description of a rectangle with integer coordinates.
Definition: rect.hpp:49
An error specifically indicating video subsystem problems.
Definition: video.hpp:321
error(const std::string &msg)
Definition: video.hpp:323