|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
|
|
|
4
|
|
|
5 This software is provided 'as-is', without any express or implied
|
|
|
6 warranty. In no event will the authors be held liable for any damages
|
|
|
7 arising from the use of this software.
|
|
|
8
|
|
|
9 Permission is granted to anyone to use this software for any purpose,
|
|
|
10 including commercial applications, and to alter it and redistribute it
|
|
|
11 freely, subject to the following restrictions:
|
|
|
12
|
|
|
13 1. The origin of this software must not be misrepresented; you must not
|
|
|
14 claim that you wrote the original software. If you use this software
|
|
|
15 in a product, an acknowledgment in the product documentation would be
|
|
|
16 appreciated but is not required.
|
|
|
17 2. Altered source versions must be plainly marked as such, and must not be
|
|
|
18 misrepresented as being the original software.
|
|
|
19 3. This notice may not be removed or altered from any source distribution.
|
|
|
20 */
|
|
|
21
|
|
|
22 /**
|
|
|
23 * # CategoryVideo
|
|
|
24 *
|
|
|
25 * SDL's video subsystem is largely interested in abstracting window
|
|
|
26 * management from the underlying operating system. You can create windows,
|
|
|
27 * manage them in various ways, set them fullscreen, and get events when
|
|
|
28 * interesting things happen with them, such as the mouse or keyboard
|
|
|
29 * interacting with a window.
|
|
|
30 *
|
|
|
31 * The video subsystem is also interested in abstracting away some
|
|
|
32 * platform-specific differences in OpenGL: context creation, swapping
|
|
|
33 * buffers, etc. This may be crucial to your app, but also you are not
|
|
|
34 * required to use OpenGL at all. In fact, SDL can provide rendering to those
|
|
|
35 * windows as well, either with an easy-to-use
|
|
|
36 * [2D API](https://wiki.libsdl.org/SDL3/CategoryRender)
|
|
|
37 * or with a more-powerful
|
|
|
38 * [GPU API](https://wiki.libsdl.org/SDL3/CategoryGPU)
|
|
|
39 * . Of course, it can simply get out of your way and give you the window
|
|
|
40 * handles you need to use Vulkan, Direct3D, Metal, or whatever else you like
|
|
|
41 * directly, too.
|
|
|
42 *
|
|
|
43 * The video subsystem covers a lot of functionality, out of necessity, so it
|
|
|
44 * is worth perusing the list of functions just to see what's available, but
|
|
|
45 * most apps can get by with simply creating a window and listening for
|
|
|
46 * events, so start with SDL_CreateWindow() and SDL_PollEvent().
|
|
|
47 */
|
|
|
48
|
|
|
49 #ifndef SDL_video_h_
|
|
|
50 #define SDL_video_h_
|
|
|
51
|
|
|
52 #include <SDL3/SDL_stdinc.h>
|
|
|
53 #include <SDL3/SDL_error.h>
|
|
|
54 #include <SDL3/SDL_pixels.h>
|
|
|
55 #include <SDL3/SDL_properties.h>
|
|
|
56 #include <SDL3/SDL_rect.h>
|
|
|
57 #include <SDL3/SDL_surface.h>
|
|
|
58
|
|
|
59 #include <SDL3/SDL_begin_code.h>
|
|
|
60 /* Set up for C function definitions, even when using C++ */
|
|
|
61 #ifdef __cplusplus
|
|
|
62 extern "C" {
|
|
|
63 #endif
|
|
|
64
|
|
|
65 /**
|
|
|
66 * This is a unique ID for a display for the time it is connected to the
|
|
|
67 * system, and is never reused for the lifetime of the application.
|
|
|
68 *
|
|
|
69 * If the display is disconnected and reconnected, it will get a new ID.
|
|
|
70 *
|
|
|
71 * The value 0 is an invalid ID.
|
|
|
72 *
|
|
|
73 * \since This datatype is available since SDL 3.2.0.
|
|
|
74 */
|
|
|
75 typedef Uint32 SDL_DisplayID;
|
|
|
76
|
|
|
77 /**
|
|
|
78 * This is a unique ID for a window.
|
|
|
79 *
|
|
|
80 * The value 0 is an invalid ID.
|
|
|
81 *
|
|
|
82 * \since This datatype is available since SDL 3.2.0.
|
|
|
83 */
|
|
|
84 typedef Uint32 SDL_WindowID;
|
|
|
85
|
|
|
86 /* Global video properties... */
|
|
|
87
|
|
|
88 /**
|
|
|
89 * The pointer to the global `wl_display` object used by the Wayland video
|
|
|
90 * backend.
|
|
|
91 *
|
|
|
92 * Can be set before the video subsystem is initialized to import an external
|
|
|
93 * `wl_display` object from an application or toolkit for use in SDL, or read
|
|
|
94 * after initialization to export the `wl_display` used by the Wayland video
|
|
|
95 * backend. Setting this property after the video subsystem has been
|
|
|
96 * initialized has no effect, and reading it when the video subsystem is
|
|
|
97 * uninitialized will either return the user provided value, if one was set
|
|
|
98 * prior to initialization, or NULL. See docs/README-wayland.md for more
|
|
|
99 * information.
|
|
|
100 *
|
|
|
101 * \since This macro is available since SDL 3.2.0.
|
|
|
102 */
|
|
|
103 #define SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER "SDL.video.wayland.wl_display"
|
|
|
104
|
|
|
105 /**
|
|
|
106 * System theme.
|
|
|
107 *
|
|
|
108 * \since This enum is available since SDL 3.2.0.
|
|
|
109 */
|
|
|
110 typedef enum SDL_SystemTheme
|
|
|
111 {
|
|
|
112 SDL_SYSTEM_THEME_UNKNOWN, /**< Unknown system theme */
|
|
|
113 SDL_SYSTEM_THEME_LIGHT, /**< Light colored system theme */
|
|
|
114 SDL_SYSTEM_THEME_DARK /**< Dark colored system theme */
|
|
|
115 } SDL_SystemTheme;
|
|
|
116
|
|
|
117 /**
|
|
|
118 * Internal display mode data.
|
|
|
119 *
|
|
|
120 * This lives as a field in SDL_DisplayMode, as opaque data.
|
|
|
121 *
|
|
|
122 * \since This struct is available since SDL 3.2.0.
|
|
|
123 *
|
|
|
124 * \sa SDL_DisplayMode
|
|
|
125 */
|
|
|
126 typedef struct SDL_DisplayModeData SDL_DisplayModeData;
|
|
|
127
|
|
|
128 /**
|
|
|
129 * The structure that defines a display mode.
|
|
|
130 *
|
|
|
131 * \since This struct is available since SDL 3.2.0.
|
|
|
132 *
|
|
|
133 * \sa SDL_GetFullscreenDisplayModes
|
|
|
134 * \sa SDL_GetDesktopDisplayMode
|
|
|
135 * \sa SDL_GetCurrentDisplayMode
|
|
|
136 * \sa SDL_SetWindowFullscreenMode
|
|
|
137 * \sa SDL_GetWindowFullscreenMode
|
|
|
138 */
|
|
|
139 typedef struct SDL_DisplayMode
|
|
|
140 {
|
|
|
141 SDL_DisplayID displayID; /**< the display this mode is associated with */
|
|
|
142 SDL_PixelFormat format; /**< pixel format */
|
|
|
143 int w; /**< width */
|
|
|
144 int h; /**< height */
|
|
|
145 float pixel_density; /**< scale converting size to pixels (e.g. a 1920x1080 mode with 2.0 scale would have 3840x2160 pixels) */
|
|
|
146 float refresh_rate; /**< refresh rate (or 0.0f for unspecified) */
|
|
|
147 int refresh_rate_numerator; /**< precise refresh rate numerator (or 0 for unspecified) */
|
|
|
148 int refresh_rate_denominator; /**< precise refresh rate denominator */
|
|
|
149
|
|
|
150 SDL_DisplayModeData *internal; /**< Private */
|
|
|
151
|
|
|
152 } SDL_DisplayMode;
|
|
|
153
|
|
|
154 /**
|
|
|
155 * Display orientation values; the way a display is rotated.
|
|
|
156 *
|
|
|
157 * \since This enum is available since SDL 3.2.0.
|
|
|
158 */
|
|
|
159 typedef enum SDL_DisplayOrientation
|
|
|
160 {
|
|
|
161 SDL_ORIENTATION_UNKNOWN, /**< The display orientation can't be determined */
|
|
|
162 SDL_ORIENTATION_LANDSCAPE, /**< The display is in landscape mode, with the right side up, relative to portrait mode */
|
|
|
163 SDL_ORIENTATION_LANDSCAPE_FLIPPED, /**< The display is in landscape mode, with the left side up, relative to portrait mode */
|
|
|
164 SDL_ORIENTATION_PORTRAIT, /**< The display is in portrait mode */
|
|
|
165 SDL_ORIENTATION_PORTRAIT_FLIPPED /**< The display is in portrait mode, upside down */
|
|
|
166 } SDL_DisplayOrientation;
|
|
|
167
|
|
|
168 /**
|
|
|
169 * The struct used as an opaque handle to a window.
|
|
|
170 *
|
|
|
171 * \since This struct is available since SDL 3.2.0.
|
|
|
172 *
|
|
|
173 * \sa SDL_CreateWindow
|
|
|
174 */
|
|
|
175 typedef struct SDL_Window SDL_Window;
|
|
|
176
|
|
|
177 /**
|
|
|
178 * The flags on a window.
|
|
|
179 *
|
|
|
180 * These cover a lot of true/false, or on/off, window state. Some of it is
|
|
|
181 * immutable after being set through SDL_CreateWindow(), some of it can be
|
|
|
182 * changed on existing windows by the app, and some of it might be altered by
|
|
|
183 * the user or system outside of the app's control.
|
|
|
184 *
|
|
|
185 * When creating windows with `SDL_WINDOW_RESIZABLE`, SDL will constrain
|
|
|
186 * resizable windows to the dimensions recommended by the compositor to fit it
|
|
|
187 * within the usable desktop space, although some compositors will do this
|
|
|
188 * automatically without intervention as well. Use `SDL_SetWindowResizable`
|
|
|
189 * after creation instead if you wish to create a window with a specific size.
|
|
|
190 *
|
|
|
191 * \since This datatype is available since SDL 3.2.0.
|
|
|
192 *
|
|
|
193 * \sa SDL_GetWindowFlags
|
|
|
194 */
|
|
|
195 typedef Uint64 SDL_WindowFlags;
|
|
|
196
|
|
|
197 #define SDL_WINDOW_FULLSCREEN SDL_UINT64_C(0x0000000000000001) /**< window is in fullscreen mode */
|
|
|
198 #define SDL_WINDOW_OPENGL SDL_UINT64_C(0x0000000000000002) /**< window usable with OpenGL context */
|
|
|
199 #define SDL_WINDOW_OCCLUDED SDL_UINT64_C(0x0000000000000004) /**< window is occluded */
|
|
|
200 #define SDL_WINDOW_HIDDEN SDL_UINT64_C(0x0000000000000008) /**< window is neither mapped onto the desktop nor shown in the taskbar/dock/window list; SDL_ShowWindow() is required for it to become visible */
|
|
|
201 #define SDL_WINDOW_BORDERLESS SDL_UINT64_C(0x0000000000000010) /**< no window decoration */
|
|
|
202 #define SDL_WINDOW_RESIZABLE SDL_UINT64_C(0x0000000000000020) /**< window can be resized */
|
|
|
203 #define SDL_WINDOW_MINIMIZED SDL_UINT64_C(0x0000000000000040) /**< window is minimized */
|
|
|
204 #define SDL_WINDOW_MAXIMIZED SDL_UINT64_C(0x0000000000000080) /**< window is maximized */
|
|
|
205 #define SDL_WINDOW_MOUSE_GRABBED SDL_UINT64_C(0x0000000000000100) /**< window has grabbed mouse input */
|
|
|
206 #define SDL_WINDOW_INPUT_FOCUS SDL_UINT64_C(0x0000000000000200) /**< window has input focus */
|
|
|
207 #define SDL_WINDOW_MOUSE_FOCUS SDL_UINT64_C(0x0000000000000400) /**< window has mouse focus */
|
|
|
208 #define SDL_WINDOW_EXTERNAL SDL_UINT64_C(0x0000000000000800) /**< window not created by SDL */
|
|
|
209 #define SDL_WINDOW_MODAL SDL_UINT64_C(0x0000000000001000) /**< window is modal */
|
|
|
210 #define SDL_WINDOW_HIGH_PIXEL_DENSITY SDL_UINT64_C(0x0000000000002000) /**< window uses high pixel density back buffer if possible */
|
|
|
211 #define SDL_WINDOW_MOUSE_CAPTURE SDL_UINT64_C(0x0000000000004000) /**< window has mouse captured (unrelated to MOUSE_GRABBED) */
|
|
|
212 #define SDL_WINDOW_MOUSE_RELATIVE_MODE SDL_UINT64_C(0x0000000000008000) /**< window has relative mode enabled */
|
|
|
213 #define SDL_WINDOW_ALWAYS_ON_TOP SDL_UINT64_C(0x0000000000010000) /**< window should always be above others */
|
|
|
214 #define SDL_WINDOW_UTILITY SDL_UINT64_C(0x0000000000020000) /**< window should be treated as a utility window, not showing in the task bar and window list */
|
|
|
215 #define SDL_WINDOW_TOOLTIP SDL_UINT64_C(0x0000000000040000) /**< window should be treated as a tooltip and does not get mouse or keyboard focus, requires a parent window */
|
|
|
216 #define SDL_WINDOW_POPUP_MENU SDL_UINT64_C(0x0000000000080000) /**< window should be treated as a popup menu, requires a parent window */
|
|
|
217 #define SDL_WINDOW_KEYBOARD_GRABBED SDL_UINT64_C(0x0000000000100000) /**< window has grabbed keyboard input */
|
|
|
218 #define SDL_WINDOW_FILL_DOCUMENT SDL_UINT64_C(0x0000000000200000) /**< window is in fill-document mode (Emscripten only), since SDL 3.4.0 */
|
|
|
219 #define SDL_WINDOW_VULKAN SDL_UINT64_C(0x0000000010000000) /**< window usable for Vulkan surface */
|
|
|
220 #define SDL_WINDOW_METAL SDL_UINT64_C(0x0000000020000000) /**< window usable for Metal view */
|
|
|
221 #define SDL_WINDOW_TRANSPARENT SDL_UINT64_C(0x0000000040000000) /**< window with transparent buffer */
|
|
|
222 #define SDL_WINDOW_NOT_FOCUSABLE SDL_UINT64_C(0x0000000080000000) /**< window should not be focusable */
|
|
|
223
|
|
|
224
|
|
|
225 /**
|
|
|
226 * A magic value used with SDL_WINDOWPOS_UNDEFINED.
|
|
|
227 *
|
|
|
228 * Generally this macro isn't used directly, but rather through
|
|
|
229 * SDL_WINDOWPOS_UNDEFINED or SDL_WINDOWPOS_UNDEFINED_DISPLAY.
|
|
|
230 *
|
|
|
231 * \since This macro is available since SDL 3.2.0.
|
|
|
232 *
|
|
|
233 * \sa SDL_SetWindowPosition
|
|
|
234 */
|
|
|
235 #define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u
|
|
|
236
|
|
|
237 /**
|
|
|
238 * Used to indicate that you don't care what the window position is.
|
|
|
239 *
|
|
|
240 * If you _really_ don't care, SDL_WINDOWPOS_UNDEFINED is the same, but always
|
|
|
241 * uses the primary display instead of specifying one.
|
|
|
242 *
|
|
|
243 * \param X the SDL_DisplayID of the display to use.
|
|
|
244 *
|
|
|
245 * \since This macro is available since SDL 3.2.0.
|
|
|
246 *
|
|
|
247 * \sa SDL_SetWindowPosition
|
|
|
248 */
|
|
|
249 #define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X))
|
|
|
250
|
|
|
251 /**
|
|
|
252 * Used to indicate that you don't care what the window position/display is.
|
|
|
253 *
|
|
|
254 * This always uses the primary display.
|
|
|
255 *
|
|
|
256 * \since This macro is available since SDL 3.2.0.
|
|
|
257 *
|
|
|
258 * \sa SDL_SetWindowPosition
|
|
|
259 */
|
|
|
260 #define SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0)
|
|
|
261
|
|
|
262 /**
|
|
|
263 * A macro to test if the window position is marked as "undefined."
|
|
|
264 *
|
|
|
265 * \param X the window position value.
|
|
|
266 *
|
|
|
267 * \since This macro is available since SDL 3.2.0.
|
|
|
268 *
|
|
|
269 * \sa SDL_SetWindowPosition
|
|
|
270 */
|
|
|
271 #define SDL_WINDOWPOS_ISUNDEFINED(X) (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK)
|
|
|
272
|
|
|
273 /**
|
|
|
274 * A magic value used with SDL_WINDOWPOS_CENTERED.
|
|
|
275 *
|
|
|
276 * Generally this macro isn't used directly, but rather through
|
|
|
277 * SDL_WINDOWPOS_CENTERED or SDL_WINDOWPOS_CENTERED_DISPLAY.
|
|
|
278 *
|
|
|
279 * \since This macro is available since SDL 3.2.0.
|
|
|
280 *
|
|
|
281 * \sa SDL_SetWindowPosition
|
|
|
282 */
|
|
|
283 #define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u
|
|
|
284
|
|
|
285 /**
|
|
|
286 * Used to indicate that the window position should be centered.
|
|
|
287 *
|
|
|
288 * SDL_WINDOWPOS_CENTERED is the same, but always uses the primary display
|
|
|
289 * instead of specifying one.
|
|
|
290 *
|
|
|
291 * \param X the SDL_DisplayID of the display to use.
|
|
|
292 *
|
|
|
293 * \since This macro is available since SDL 3.2.0.
|
|
|
294 *
|
|
|
295 * \sa SDL_SetWindowPosition
|
|
|
296 */
|
|
|
297 #define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X))
|
|
|
298
|
|
|
299 /**
|
|
|
300 * Used to indicate that the window position should be centered.
|
|
|
301 *
|
|
|
302 * This always uses the primary display.
|
|
|
303 *
|
|
|
304 * \since This macro is available since SDL 3.2.0.
|
|
|
305 *
|
|
|
306 * \sa SDL_SetWindowPosition
|
|
|
307 */
|
|
|
308 #define SDL_WINDOWPOS_CENTERED SDL_WINDOWPOS_CENTERED_DISPLAY(0)
|
|
|
309
|
|
|
310 /**
|
|
|
311 * A macro to test if the window position is marked as "centered."
|
|
|
312 *
|
|
|
313 * \param X the window position value.
|
|
|
314 *
|
|
|
315 * \since This macro is available since SDL 3.2.0.
|
|
|
316 *
|
|
|
317 * \sa SDL_GetWindowPosition
|
|
|
318 */
|
|
|
319 #define SDL_WINDOWPOS_ISCENTERED(X) \
|
|
|
320 (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK)
|
|
|
321
|
|
|
322
|
|
|
323 /**
|
|
|
324 * Window flash operation.
|
|
|
325 *
|
|
|
326 * \since This enum is available since SDL 3.2.0.
|
|
|
327 */
|
|
|
328 typedef enum SDL_FlashOperation
|
|
|
329 {
|
|
|
330 SDL_FLASH_CANCEL, /**< Cancel any window flash state */
|
|
|
331 SDL_FLASH_BRIEFLY, /**< Flash the window briefly to get attention */
|
|
|
332 SDL_FLASH_UNTIL_FOCUSED /**< Flash the window until it gets focus */
|
|
|
333 } SDL_FlashOperation;
|
|
|
334
|
|
|
335 /**
|
|
|
336 * Window progress state
|
|
|
337 *
|
|
|
338 * \since This enum is available since SDL 3.2.8.
|
|
|
339 */
|
|
|
340 typedef enum SDL_ProgressState
|
|
|
341 {
|
|
|
342 SDL_PROGRESS_STATE_INVALID = -1, /**< An invalid progress state indicating an error; check SDL_GetError() */
|
|
|
343 SDL_PROGRESS_STATE_NONE, /**< No progress bar is shown */
|
|
|
344 SDL_PROGRESS_STATE_INDETERMINATE, /**< The progress bar is shown in a indeterminate state */
|
|
|
345 SDL_PROGRESS_STATE_NORMAL, /**< The progress bar is shown in a normal state */
|
|
|
346 SDL_PROGRESS_STATE_PAUSED, /**< The progress bar is shown in a paused state */
|
|
|
347 SDL_PROGRESS_STATE_ERROR /**< The progress bar is shown in a state indicating the application had an error */
|
|
|
348 } SDL_ProgressState;
|
|
|
349
|
|
|
350 /**
|
|
|
351 * An opaque handle to an OpenGL context.
|
|
|
352 *
|
|
|
353 * \since This datatype is available since SDL 3.2.0.
|
|
|
354 *
|
|
|
355 * \sa SDL_GL_CreateContext
|
|
|
356 * \sa SDL_GL_SetAttribute
|
|
|
357 * \sa SDL_GL_MakeCurrent
|
|
|
358 * \sa SDL_GL_DestroyContext
|
|
|
359 */
|
|
|
360 typedef struct SDL_GLContextState *SDL_GLContext;
|
|
|
361
|
|
|
362 /**
|
|
|
363 * Opaque type for an EGL display.
|
|
|
364 *
|
|
|
365 * \since This datatype is available since SDL 3.2.0.
|
|
|
366 */
|
|
|
367 typedef void *SDL_EGLDisplay;
|
|
|
368
|
|
|
369 /**
|
|
|
370 * Opaque type for an EGL config.
|
|
|
371 *
|
|
|
372 * \since This datatype is available since SDL 3.2.0.
|
|
|
373 */
|
|
|
374 typedef void *SDL_EGLConfig;
|
|
|
375
|
|
|
376 /**
|
|
|
377 * Opaque type for an EGL surface.
|
|
|
378 *
|
|
|
379 * \since This datatype is available since SDL 3.2.0.
|
|
|
380 */
|
|
|
381 typedef void *SDL_EGLSurface;
|
|
|
382
|
|
|
383 /**
|
|
|
384 * An EGL attribute, used when creating an EGL context.
|
|
|
385 *
|
|
|
386 * \since This datatype is available since SDL 3.2.0.
|
|
|
387 */
|
|
|
388 typedef intptr_t SDL_EGLAttrib;
|
|
|
389
|
|
|
390 /**
|
|
|
391 * An EGL integer attribute, used when creating an EGL surface.
|
|
|
392 *
|
|
|
393 * \since This datatype is available since SDL 3.2.0.
|
|
|
394 */
|
|
|
395 typedef int SDL_EGLint;
|
|
|
396
|
|
|
397 /**
|
|
|
398 * EGL platform attribute initialization callback.
|
|
|
399 *
|
|
|
400 * This is called when SDL is attempting to create an EGL context, to let the
|
|
|
401 * app add extra attributes to its eglGetPlatformDisplay() call.
|
|
|
402 *
|
|
|
403 * The callback should return a pointer to an EGL attribute array terminated
|
|
|
404 * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow
|
|
|
405 * process will fail gracefully.
|
|
|
406 *
|
|
|
407 * The returned pointer should be allocated with SDL_malloc() and will be
|
|
|
408 * passed to SDL_free().
|
|
|
409 *
|
|
|
410 * The arrays returned by each callback will be appended to the existing
|
|
|
411 * attribute arrays defined by SDL.
|
|
|
412 *
|
|
|
413 * \param userdata an app-controlled pointer that is passed to the callback.
|
|
|
414 * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`.
|
|
|
415 *
|
|
|
416 * \since This datatype is available since SDL 3.2.0.
|
|
|
417 *
|
|
|
418 * \sa SDL_EGL_SetAttributeCallbacks
|
|
|
419 */
|
|
|
420 typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void *userdata);
|
|
|
421
|
|
|
422 /**
|
|
|
423 * EGL surface/context attribute initialization callback types.
|
|
|
424 *
|
|
|
425 * This is called when SDL is attempting to create an EGL surface, to let the
|
|
|
426 * app add extra attributes to its eglCreateWindowSurface() or
|
|
|
427 * eglCreateContext calls.
|
|
|
428 *
|
|
|
429 * For convenience, the EGLDisplay and EGLConfig to use are provided to the
|
|
|
430 * callback.
|
|
|
431 *
|
|
|
432 * The callback should return a pointer to an EGL attribute array terminated
|
|
|
433 * with `EGL_NONE`. If this function returns NULL, the SDL_CreateWindow
|
|
|
434 * process will fail gracefully.
|
|
|
435 *
|
|
|
436 * The returned pointer should be allocated with SDL_malloc() and will be
|
|
|
437 * passed to SDL_free().
|
|
|
438 *
|
|
|
439 * The arrays returned by each callback will be appended to the existing
|
|
|
440 * attribute arrays defined by SDL.
|
|
|
441 *
|
|
|
442 * \param userdata an app-controlled pointer that is passed to the callback.
|
|
|
443 * \param display the EGL display to be used.
|
|
|
444 * \param config the EGL config to be used.
|
|
|
445 * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`.
|
|
|
446 *
|
|
|
447 * \since This datatype is available since SDL 3.2.0.
|
|
|
448 *
|
|
|
449 * \sa SDL_EGL_SetAttributeCallbacks
|
|
|
450 */
|
|
|
451 typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void *userdata, SDL_EGLDisplay display, SDL_EGLConfig config);
|
|
|
452
|
|
|
453 /**
|
|
|
454 * An enumeration of OpenGL configuration attributes.
|
|
|
455 *
|
|
|
456 * While you can set most OpenGL attributes normally, the attributes listed
|
|
|
457 * above must be known before SDL creates the window that will be used with
|
|
|
458 * the OpenGL context. These attributes are set and read with
|
|
|
459 * SDL_GL_SetAttribute() and SDL_GL_GetAttribute().
|
|
|
460 *
|
|
|
461 * In some cases, these attributes are minimum requests; the GL does not
|
|
|
462 * promise to give you exactly what you asked for. It's possible to ask for a
|
|
|
463 * 16-bit depth buffer and get a 24-bit one instead, for example, or to ask
|
|
|
464 * for no stencil buffer and still have one available. Context creation should
|
|
|
465 * fail if the GL can't provide your requested attributes at a minimum, but
|
|
|
466 * you should check to see exactly what you got.
|
|
|
467 *
|
|
|
468 * \since This enum is available since SDL 3.2.0.
|
|
|
469 */
|
|
|
470 typedef enum SDL_GLAttr
|
|
|
471 {
|
|
|
472 SDL_GL_RED_SIZE, /**< the minimum number of bits for the red channel of the color buffer; defaults to 8. */
|
|
|
473 SDL_GL_GREEN_SIZE, /**< the minimum number of bits for the green channel of the color buffer; defaults to 8. */
|
|
|
474 SDL_GL_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the color buffer; defaults to 8. */
|
|
|
475 SDL_GL_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the color buffer; defaults to 8. */
|
|
|
476 SDL_GL_BUFFER_SIZE, /**< the minimum number of bits for frame buffer size; defaults to 0. */
|
|
|
477 SDL_GL_DOUBLEBUFFER, /**< whether the output is single or double buffered; defaults to double buffering on. */
|
|
|
478 SDL_GL_DEPTH_SIZE, /**< the minimum number of bits in the depth buffer; defaults to 16. */
|
|
|
479 SDL_GL_STENCIL_SIZE, /**< the minimum number of bits in the stencil buffer; defaults to 0. */
|
|
|
480 SDL_GL_ACCUM_RED_SIZE, /**< the minimum number of bits for the red channel of the accumulation buffer; defaults to 0. */
|
|
|
481 SDL_GL_ACCUM_GREEN_SIZE, /**< the minimum number of bits for the green channel of the accumulation buffer; defaults to 0. */
|
|
|
482 SDL_GL_ACCUM_BLUE_SIZE, /**< the minimum number of bits for the blue channel of the accumulation buffer; defaults to 0. */
|
|
|
483 SDL_GL_ACCUM_ALPHA_SIZE, /**< the minimum number of bits for the alpha channel of the accumulation buffer; defaults to 0. */
|
|
|
484 SDL_GL_STEREO, /**< whether the output is stereo 3D; defaults to off. */
|
|
|
485 SDL_GL_MULTISAMPLEBUFFERS, /**< the number of buffers used for multisample anti-aliasing; defaults to 0. */
|
|
|
486 SDL_GL_MULTISAMPLESAMPLES, /**< the number of samples used around the current pixel used for multisample anti-aliasing. */
|
|
|
487 SDL_GL_ACCELERATED_VISUAL, /**< set to 1 to require hardware acceleration, set to 0 to force software rendering; defaults to allow either. */
|
|
|
488 SDL_GL_RETAINED_BACKING, /**< not used (deprecated). */
|
|
|
489 SDL_GL_CONTEXT_MAJOR_VERSION, /**< OpenGL context major version. */
|
|
|
490 SDL_GL_CONTEXT_MINOR_VERSION, /**< OpenGL context minor version. */
|
|
|
491 SDL_GL_CONTEXT_FLAGS, /**< some combination of 0 or more of elements of the SDL_GLContextFlag enumeration; defaults to 0. */
|
|
|
492 SDL_GL_CONTEXT_PROFILE_MASK, /**< type of GL context (Core, Compatibility, ES). See SDL_GLProfile; default value depends on platform. */
|
|
|
493 SDL_GL_SHARE_WITH_CURRENT_CONTEXT, /**< OpenGL context sharing; defaults to 0. */
|
|
|
494 SDL_GL_FRAMEBUFFER_SRGB_CAPABLE, /**< requests sRGB-capable visual if 1. Defaults to -1 ("don't care"). This is a request; GL drivers might not comply! */
|
|
|
495 SDL_GL_CONTEXT_RELEASE_BEHAVIOR, /**< sets context the release behavior. See SDL_GLContextReleaseFlag; defaults to FLUSH. */
|
|
|
496 SDL_GL_CONTEXT_RESET_NOTIFICATION, /**< set context reset notification. See SDL_GLContextResetNotification; defaults to NO_NOTIFICATION. */
|
|
|
497 SDL_GL_CONTEXT_NO_ERROR,
|
|
|
498 SDL_GL_FLOATBUFFERS,
|
|
|
499 SDL_GL_EGL_PLATFORM
|
|
|
500 } SDL_GLAttr;
|
|
|
501
|
|
|
502 /**
|
|
|
503 * Possible values to be set for the SDL_GL_CONTEXT_PROFILE_MASK attribute.
|
|
|
504 *
|
|
|
505 * \since This datatype is available since SDL 3.2.0.
|
|
|
506 */
|
|
|
507 typedef Uint32 SDL_GLProfile;
|
|
|
508
|
|
|
509 #define SDL_GL_CONTEXT_PROFILE_CORE 0x0001 /**< OpenGL Core Profile context */
|
|
|
510 #define SDL_GL_CONTEXT_PROFILE_COMPATIBILITY 0x0002 /**< OpenGL Compatibility Profile context */
|
|
|
511 #define SDL_GL_CONTEXT_PROFILE_ES 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */
|
|
|
512
|
|
|
513
|
|
|
514 /**
|
|
|
515 * Possible flags to be set for the SDL_GL_CONTEXT_FLAGS attribute.
|
|
|
516 *
|
|
|
517 * \since This datatype is available since SDL 3.2.0.
|
|
|
518 */
|
|
|
519 typedef Uint32 SDL_GLContextFlag;
|
|
|
520
|
|
|
521 #define SDL_GL_CONTEXT_DEBUG_FLAG 0x0001
|
|
|
522 #define SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG 0x0002
|
|
|
523 #define SDL_GL_CONTEXT_ROBUST_ACCESS_FLAG 0x0004
|
|
|
524 #define SDL_GL_CONTEXT_RESET_ISOLATION_FLAG 0x0008
|
|
|
525
|
|
|
526
|
|
|
527 /**
|
|
|
528 * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR
|
|
|
529 * attribute.
|
|
|
530 *
|
|
|
531 * \since This datatype is available since SDL 3.2.0.
|
|
|
532 */
|
|
|
533 typedef Uint32 SDL_GLContextReleaseFlag;
|
|
|
534
|
|
|
535 #define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE 0x0000
|
|
|
536 #define SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH 0x0001
|
|
|
537
|
|
|
538
|
|
|
539 /**
|
|
|
540 * Possible values to be set SDL_GL_CONTEXT_RESET_NOTIFICATION attribute.
|
|
|
541 *
|
|
|
542 * \since This datatype is available since SDL 3.2.0.
|
|
|
543 */
|
|
|
544 typedef Uint32 SDL_GLContextResetNotification;
|
|
|
545
|
|
|
546 #define SDL_GL_CONTEXT_RESET_NO_NOTIFICATION 0x0000
|
|
|
547 #define SDL_GL_CONTEXT_RESET_LOSE_CONTEXT 0x0001
|
|
|
548
|
|
|
549
|
|
|
550 /* Function prototypes */
|
|
|
551
|
|
|
552 /**
|
|
|
553 * Get the number of video drivers compiled into SDL.
|
|
|
554 *
|
|
|
555 * \returns the number of built in video drivers.
|
|
|
556 *
|
|
|
557 * \threadsafety This function should only be called on the main thread.
|
|
|
558 *
|
|
|
559 * \since This function is available since SDL 3.2.0.
|
|
|
560 *
|
|
|
561 * \sa SDL_GetVideoDriver
|
|
|
562 */
|
|
|
563 extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
|
|
|
564
|
|
|
565 /**
|
|
|
566 * Get the name of a built in video driver.
|
|
|
567 *
|
|
|
568 * The video drivers are presented in the order in which they are normally
|
|
|
569 * checked during initialization.
|
|
|
570 *
|
|
|
571 * The names of drivers are all simple, low-ASCII identifiers, like "cocoa",
|
|
|
572 * "x11" or "windows". These never have Unicode characters, and are not meant
|
|
|
573 * to be proper names.
|
|
|
574 *
|
|
|
575 * \param index the index of a video driver.
|
|
|
576 * \returns the name of the video driver with the given **index**, or NULL if
|
|
|
577 * index is out of bounds.
|
|
|
578 *
|
|
|
579 * \threadsafety This function should only be called on the main thread.
|
|
|
580 *
|
|
|
581 * \since This function is available since SDL 3.2.0.
|
|
|
582 *
|
|
|
583 * \sa SDL_GetNumVideoDrivers
|
|
|
584 */
|
|
|
585 extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index);
|
|
|
586
|
|
|
587 /**
|
|
|
588 * Get the name of the currently initialized video driver.
|
|
|
589 *
|
|
|
590 * The names of drivers are all simple, low-ASCII identifiers, like "cocoa",
|
|
|
591 * "x11" or "windows". These never have Unicode characters, and are not meant
|
|
|
592 * to be proper names.
|
|
|
593 *
|
|
|
594 * \returns the name of the current video driver or NULL if no driver has been
|
|
|
595 * initialized.
|
|
|
596 *
|
|
|
597 * \threadsafety This function should only be called on the main thread.
|
|
|
598 *
|
|
|
599 * \since This function is available since SDL 3.2.0.
|
|
|
600 *
|
|
|
601 * \sa SDL_GetNumVideoDrivers
|
|
|
602 * \sa SDL_GetVideoDriver
|
|
|
603 */
|
|
|
604 extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentVideoDriver(void);
|
|
|
605
|
|
|
606 /**
|
|
|
607 * Get the current system theme.
|
|
|
608 *
|
|
|
609 * \returns the current system theme, light, dark, or unknown.
|
|
|
610 *
|
|
|
611 * \threadsafety This function should only be called on the main thread.
|
|
|
612 *
|
|
|
613 * \since This function is available since SDL 3.2.0.
|
|
|
614 */
|
|
|
615 extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void);
|
|
|
616
|
|
|
617 /**
|
|
|
618 * Get a list of currently connected displays.
|
|
|
619 *
|
|
|
620 * \param count a pointer filled in with the number of displays returned, may
|
|
|
621 * be NULL.
|
|
|
622 * \returns a 0 terminated array of display instance IDs or NULL on failure;
|
|
|
623 * call SDL_GetError() for more information. This should be freed
|
|
|
624 * with SDL_free() when it is no longer needed.
|
|
|
625 *
|
|
|
626 * \threadsafety This function should only be called on the main thread.
|
|
|
627 *
|
|
|
628 * \since This function is available since SDL 3.2.0.
|
|
|
629 */
|
|
|
630 extern SDL_DECLSPEC SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count);
|
|
|
631
|
|
|
632 /**
|
|
|
633 * Return the primary display.
|
|
|
634 *
|
|
|
635 * \returns the instance ID of the primary display on success or 0 on failure;
|
|
|
636 * call SDL_GetError() for more information.
|
|
|
637 *
|
|
|
638 * \threadsafety This function should only be called on the main thread.
|
|
|
639 *
|
|
|
640 * \since This function is available since SDL 3.2.0.
|
|
|
641 *
|
|
|
642 * \sa SDL_GetDisplays
|
|
|
643 */
|
|
|
644 extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetPrimaryDisplay(void);
|
|
|
645
|
|
|
646 /**
|
|
|
647 * Get the properties associated with a display.
|
|
|
648 *
|
|
|
649 * The following read-only properties are provided by SDL:
|
|
|
650 *
|
|
|
651 * - `SDL_PROP_DISPLAY_HDR_ENABLED_BOOLEAN`: true if the display has HDR
|
|
|
652 * headroom above the SDR white point. This is for informational and
|
|
|
653 * diagnostic purposes only, as not all platforms provide this information
|
|
|
654 * at the display level.
|
|
|
655 *
|
|
|
656 * On KMS/DRM:
|
|
|
657 *
|
|
|
658 * - `SDL_PROP_DISPLAY_KMSDRM_PANEL_ORIENTATION_NUMBER`: the "panel
|
|
|
659 * orientation" property for the display in degrees of clockwise rotation.
|
|
|
660 * Note that this is provided only as a hint, and the application is
|
|
|
661 * responsible for any coordinate transformations needed to conform to the
|
|
|
662 * requested display orientation.
|
|
|
663 *
|
|
|
664 * On Wayland:
|
|
|
665 *
|
|
|
666 * - `SDL_PROP_DISPLAY_WAYLAND_WL_OUTPUT_POINTER`: the wl_output associated
|
|
|
667 * with the display
|
|
|
668 *
|
|
|
669 * On Windows:
|
|
|
670 *
|
|
|
671 * - `SDL_PROP_DISPLAY_WINDOWS_HMONITOR_POINTER`: the monitor handle
|
|
|
672 * (HMONITOR) associated with the display
|
|
|
673 *
|
|
|
674 * \param displayID the instance ID of the display to query.
|
|
|
675 * \returns a valid property ID on success or 0 on failure; call
|
|
|
676 * SDL_GetError() for more information.
|
|
|
677 *
|
|
|
678 * \threadsafety This function should only be called on the main thread.
|
|
|
679 *
|
|
|
680 * \since This function is available since SDL 3.2.0.
|
|
|
681 */
|
|
|
682 extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_DisplayID displayID);
|
|
|
683
|
|
|
684 #define SDL_PROP_DISPLAY_HDR_ENABLED_BOOLEAN "SDL.display.HDR_enabled"
|
|
|
685 #define SDL_PROP_DISPLAY_KMSDRM_PANEL_ORIENTATION_NUMBER "SDL.display.KMSDRM.panel_orientation"
|
|
|
686 #define SDL_PROP_DISPLAY_WAYLAND_WL_OUTPUT_POINTER "SDL.display.wayland.wl_output"
|
|
|
687 #define SDL_PROP_DISPLAY_WINDOWS_HMONITOR_POINTER "SDL.display.windows.hmonitor"
|
|
|
688
|
|
|
689 /**
|
|
|
690 * Get the name of a display in UTF-8 encoding.
|
|
|
691 *
|
|
|
692 * \param displayID the instance ID of the display to query.
|
|
|
693 * \returns the name of a display or NULL on failure; call SDL_GetError() for
|
|
|
694 * more information.
|
|
|
695 *
|
|
|
696 * \threadsafety This function should only be called on the main thread.
|
|
|
697 *
|
|
|
698 * \since This function is available since SDL 3.2.0.
|
|
|
699 *
|
|
|
700 * \sa SDL_GetDisplays
|
|
|
701 */
|
|
|
702 extern SDL_DECLSPEC const char * SDLCALL SDL_GetDisplayName(SDL_DisplayID displayID);
|
|
|
703
|
|
|
704 /**
|
|
|
705 * Get the desktop area represented by a display.
|
|
|
706 *
|
|
|
707 * The primary display is often located at (0,0), but may be placed at a
|
|
|
708 * different location depending on monitor layout.
|
|
|
709 *
|
|
|
710 * \param displayID the instance ID of the display to query.
|
|
|
711 * \param rect the SDL_Rect structure filled in with the display bounds.
|
|
|
712 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
713 * information.
|
|
|
714 *
|
|
|
715 * \threadsafety This function should only be called on the main thread.
|
|
|
716 *
|
|
|
717 * \since This function is available since SDL 3.2.0.
|
|
|
718 *
|
|
|
719 * \sa SDL_GetDisplayUsableBounds
|
|
|
720 * \sa SDL_GetDisplays
|
|
|
721 */
|
|
|
722 extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayBounds(SDL_DisplayID displayID, SDL_Rect *rect);
|
|
|
723
|
|
|
724 /**
|
|
|
725 * Get the usable desktop area represented by a display, in screen
|
|
|
726 * coordinates.
|
|
|
727 *
|
|
|
728 * This is the same area as SDL_GetDisplayBounds() reports, but with portions
|
|
|
729 * reserved by the system removed. For example, on Apple's macOS, this
|
|
|
730 * subtracts the area occupied by the menu bar and dock.
|
|
|
731 *
|
|
|
732 * Setting a window to be fullscreen generally bypasses these unusable areas,
|
|
|
733 * so these are good guidelines for the maximum space available to a
|
|
|
734 * non-fullscreen window.
|
|
|
735 *
|
|
|
736 * \param displayID the instance ID of the display to query.
|
|
|
737 * \param rect the SDL_Rect structure filled in with the display bounds.
|
|
|
738 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
739 * information.
|
|
|
740 *
|
|
|
741 * \threadsafety This function should only be called on the main thread.
|
|
|
742 *
|
|
|
743 * \since This function is available since SDL 3.2.0.
|
|
|
744 *
|
|
|
745 * \sa SDL_GetDisplayBounds
|
|
|
746 * \sa SDL_GetDisplays
|
|
|
747 */
|
|
|
748 extern SDL_DECLSPEC bool SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID displayID, SDL_Rect *rect);
|
|
|
749
|
|
|
750 /**
|
|
|
751 * Get the orientation of a display when it is unrotated.
|
|
|
752 *
|
|
|
753 * \param displayID the instance ID of the display to query.
|
|
|
754 * \returns the SDL_DisplayOrientation enum value of the display, or
|
|
|
755 * `SDL_ORIENTATION_UNKNOWN` if it isn't available.
|
|
|
756 *
|
|
|
757 * \threadsafety This function should only be called on the main thread.
|
|
|
758 *
|
|
|
759 * \since This function is available since SDL 3.2.0.
|
|
|
760 *
|
|
|
761 * \sa SDL_GetDisplays
|
|
|
762 */
|
|
|
763 extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetNaturalDisplayOrientation(SDL_DisplayID displayID);
|
|
|
764
|
|
|
765 /**
|
|
|
766 * Get the orientation of a display.
|
|
|
767 *
|
|
|
768 * \param displayID the instance ID of the display to query.
|
|
|
769 * \returns the SDL_DisplayOrientation enum value of the display, or
|
|
|
770 * `SDL_ORIENTATION_UNKNOWN` if it isn't available.
|
|
|
771 *
|
|
|
772 * \threadsafety This function should only be called on the main thread.
|
|
|
773 *
|
|
|
774 * \since This function is available since SDL 3.2.0.
|
|
|
775 *
|
|
|
776 * \sa SDL_GetDisplays
|
|
|
777 */
|
|
|
778 extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientation(SDL_DisplayID displayID);
|
|
|
779
|
|
|
780 /**
|
|
|
781 * Get the content scale of a display.
|
|
|
782 *
|
|
|
783 * The content scale is the expected scale for content based on the DPI
|
|
|
784 * settings of the display. For example, a 4K display might have a 2.0 (200%)
|
|
|
785 * display scale, which means that the user expects UI elements to be twice as
|
|
|
786 * big on this display, to aid in readability.
|
|
|
787 *
|
|
|
788 * After window creation, SDL_GetWindowDisplayScale() should be used to query
|
|
|
789 * the content scale factor for individual windows instead of querying the
|
|
|
790 * display for a window and calling this function, as the per-window content
|
|
|
791 * scale factor may differ from the base value of the display it is on,
|
|
|
792 * particularly on high-DPI and/or multi-monitor desktop configurations.
|
|
|
793 *
|
|
|
794 * \param displayID the instance ID of the display to query.
|
|
|
795 * \returns the content scale of the display, or 0.0f on failure; call
|
|
|
796 * SDL_GetError() for more information.
|
|
|
797 *
|
|
|
798 * \threadsafety This function should only be called on the main thread.
|
|
|
799 *
|
|
|
800 * \since This function is available since SDL 3.2.0.
|
|
|
801 *
|
|
|
802 * \sa SDL_GetWindowDisplayScale
|
|
|
803 * \sa SDL_GetDisplays
|
|
|
804 */
|
|
|
805 extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displayID);
|
|
|
806
|
|
|
807 /**
|
|
|
808 * Get a list of fullscreen display modes available on a display.
|
|
|
809 *
|
|
|
810 * The display modes are sorted in this priority:
|
|
|
811 *
|
|
|
812 * - w -> largest to smallest
|
|
|
813 * - h -> largest to smallest
|
|
|
814 * - bits per pixel -> more colors to fewer colors
|
|
|
815 * - packed pixel layout -> largest to smallest
|
|
|
816 * - refresh rate -> highest to lowest
|
|
|
817 * - pixel density -> lowest to highest
|
|
|
818 *
|
|
|
819 * \param displayID the instance ID of the display to query.
|
|
|
820 * \param count a pointer filled in with the number of display modes returned,
|
|
|
821 * may be NULL.
|
|
|
822 * \returns a NULL terminated array of display mode pointers or NULL on
|
|
|
823 * failure; call SDL_GetError() for more information. This is a
|
|
|
824 * single allocation that should be freed with SDL_free() when it is
|
|
|
825 * no longer needed.
|
|
|
826 *
|
|
|
827 * \threadsafety This function should only be called on the main thread.
|
|
|
828 *
|
|
|
829 * \since This function is available since SDL 3.2.0.
|
|
|
830 *
|
|
|
831 * \sa SDL_GetDisplays
|
|
|
832 */
|
|
|
833 extern SDL_DECLSPEC SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayModes(SDL_DisplayID displayID, int *count);
|
|
|
834
|
|
|
835 /**
|
|
|
836 * Get the closest match to the requested display mode.
|
|
|
837 *
|
|
|
838 * The available display modes are scanned and `closest` is filled in with the
|
|
|
839 * closest mode matching the requested mode and returned. The mode format and
|
|
|
840 * refresh rate default to the desktop mode if they are set to 0. The modes
|
|
|
841 * are scanned with size being first priority, format being second priority,
|
|
|
842 * and finally checking the refresh rate. If all the available modes are too
|
|
|
843 * small, then false is returned.
|
|
|
844 *
|
|
|
845 * \param displayID the instance ID of the display to query.
|
|
|
846 * \param w the width in pixels of the desired display mode.
|
|
|
847 * \param h the height in pixels of the desired display mode.
|
|
|
848 * \param refresh_rate the refresh rate of the desired display mode, or 0.0f
|
|
|
849 * for the desktop refresh rate.
|
|
|
850 * \param include_high_density_modes boolean to include high density modes in
|
|
|
851 * the search.
|
|
|
852 * \param closest a pointer filled in with the closest display mode equal to
|
|
|
853 * or larger than the desired mode.
|
|
|
854 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
855 * information.
|
|
|
856 *
|
|
|
857 * \threadsafety This function should only be called on the main thread.
|
|
|
858 *
|
|
|
859 * \since This function is available since SDL 3.2.0.
|
|
|
860 *
|
|
|
861 * \sa SDL_GetDisplays
|
|
|
862 * \sa SDL_GetFullscreenDisplayModes
|
|
|
863 */
|
|
|
864 extern SDL_DECLSPEC bool SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, bool include_high_density_modes, SDL_DisplayMode *closest);
|
|
|
865
|
|
|
866 /**
|
|
|
867 * Get information about the desktop's display mode.
|
|
|
868 *
|
|
|
869 * There's a difference between this function and SDL_GetCurrentDisplayMode()
|
|
|
870 * when SDL runs fullscreen and has changed the resolution. In that case this
|
|
|
871 * function will return the previous native display mode, and not the current
|
|
|
872 * display mode.
|
|
|
873 *
|
|
|
874 * \param displayID the instance ID of the display to query.
|
|
|
875 * \returns a pointer to the desktop display mode or NULL on failure; call
|
|
|
876 * SDL_GetError() for more information.
|
|
|
877 *
|
|
|
878 * \threadsafety This function should only be called on the main thread.
|
|
|
879 *
|
|
|
880 * \since This function is available since SDL 3.2.0.
|
|
|
881 *
|
|
|
882 * \sa SDL_GetCurrentDisplayMode
|
|
|
883 * \sa SDL_GetDisplays
|
|
|
884 */
|
|
|
885 extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetDesktopDisplayMode(SDL_DisplayID displayID);
|
|
|
886
|
|
|
887 /**
|
|
|
888 * Get information about the current display mode.
|
|
|
889 *
|
|
|
890 * There's a difference between this function and SDL_GetDesktopDisplayMode()
|
|
|
891 * when SDL runs fullscreen and has changed the resolution. In that case this
|
|
|
892 * function will return the current display mode, and not the previous native
|
|
|
893 * display mode.
|
|
|
894 *
|
|
|
895 * \param displayID the instance ID of the display to query.
|
|
|
896 * \returns a pointer to the desktop display mode or NULL on failure; call
|
|
|
897 * SDL_GetError() for more information.
|
|
|
898 *
|
|
|
899 * \threadsafety This function should only be called on the main thread.
|
|
|
900 *
|
|
|
901 * \since This function is available since SDL 3.2.0.
|
|
|
902 *
|
|
|
903 * \sa SDL_GetDesktopDisplayMode
|
|
|
904 * \sa SDL_GetDisplays
|
|
|
905 */
|
|
|
906 extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetCurrentDisplayMode(SDL_DisplayID displayID);
|
|
|
907
|
|
|
908 /**
|
|
|
909 * Get the display containing a point.
|
|
|
910 *
|
|
|
911 * \param point the point to query.
|
|
|
912 * \returns the instance ID of the display containing the point or 0 on
|
|
|
913 * failure; call SDL_GetError() for more information.
|
|
|
914 *
|
|
|
915 * \threadsafety This function should only be called on the main thread.
|
|
|
916 *
|
|
|
917 * \since This function is available since SDL 3.2.0.
|
|
|
918 *
|
|
|
919 * \sa SDL_GetDisplayBounds
|
|
|
920 * \sa SDL_GetDisplays
|
|
|
921 */
|
|
|
922 extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForPoint(const SDL_Point *point);
|
|
|
923
|
|
|
924 /**
|
|
|
925 * Get the display primarily containing a rect.
|
|
|
926 *
|
|
|
927 * \param rect the rect to query.
|
|
|
928 * \returns the instance ID of the display entirely containing the rect or
|
|
|
929 * closest to the center of the rect on success or 0 on failure; call
|
|
|
930 * SDL_GetError() for more information.
|
|
|
931 *
|
|
|
932 * \threadsafety This function should only be called on the main thread.
|
|
|
933 *
|
|
|
934 * \since This function is available since SDL 3.2.0.
|
|
|
935 *
|
|
|
936 * \sa SDL_GetDisplayBounds
|
|
|
937 * \sa SDL_GetDisplays
|
|
|
938 */
|
|
|
939 extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForRect(const SDL_Rect *rect);
|
|
|
940
|
|
|
941 /**
|
|
|
942 * Get the display associated with a window.
|
|
|
943 *
|
|
|
944 * \param window the window to query.
|
|
|
945 * \returns the instance ID of the display containing the center of the window
|
|
|
946 * on success or 0 on failure; call SDL_GetError() for more
|
|
|
947 * information.
|
|
|
948 *
|
|
|
949 * \threadsafety This function should only be called on the main thread.
|
|
|
950 *
|
|
|
951 * \since This function is available since SDL 3.2.0.
|
|
|
952 *
|
|
|
953 * \sa SDL_GetDisplayBounds
|
|
|
954 * \sa SDL_GetDisplays
|
|
|
955 */
|
|
|
956 extern SDL_DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *window);
|
|
|
957
|
|
|
958 /**
|
|
|
959 * Get the pixel density of a window.
|
|
|
960 *
|
|
|
961 * This is a ratio of pixel size to window size. For example, if the window is
|
|
|
962 * 1920x1080 and it has a high density back buffer of 3840x2160 pixels, it
|
|
|
963 * would have a pixel density of 2.0.
|
|
|
964 *
|
|
|
965 * \param window the window to query.
|
|
|
966 * \returns the pixel density or 0.0f on failure; call SDL_GetError() for more
|
|
|
967 * information.
|
|
|
968 *
|
|
|
969 * \threadsafety This function should only be called on the main thread.
|
|
|
970 *
|
|
|
971 * \since This function is available since SDL 3.2.0.
|
|
|
972 *
|
|
|
973 * \sa SDL_GetWindowDisplayScale
|
|
|
974 */
|
|
|
975 extern SDL_DECLSPEC float SDLCALL SDL_GetWindowPixelDensity(SDL_Window *window);
|
|
|
976
|
|
|
977 /**
|
|
|
978 * Get the content display scale relative to a window's pixel size.
|
|
|
979 *
|
|
|
980 * This is a combination of the window pixel density and the display content
|
|
|
981 * scale, and is the expected scale for displaying content in this window. For
|
|
|
982 * example, if a 3840x2160 window had a display scale of 2.0, the user expects
|
|
|
983 * the content to take twice as many pixels and be the same physical size as
|
|
|
984 * if it were being displayed in a 1920x1080 window with a display scale of
|
|
|
985 * 1.0.
|
|
|
986 *
|
|
|
987 * Conceptually this value corresponds to the scale display setting, and is
|
|
|
988 * updated when that setting is changed, or the window moves to a display with
|
|
|
989 * a different scale setting.
|
|
|
990 *
|
|
|
991 * \param window the window to query.
|
|
|
992 * \returns the display scale, or 0.0f on failure; call SDL_GetError() for
|
|
|
993 * more information.
|
|
|
994 *
|
|
|
995 * \threadsafety This function should only be called on the main thread.
|
|
|
996 *
|
|
|
997 * \since This function is available since SDL 3.2.0.
|
|
|
998 */
|
|
|
999 extern SDL_DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window);
|
|
|
1000
|
|
|
1001 /**
|
|
|
1002 * Set the display mode to use when a window is visible and fullscreen.
|
|
|
1003 *
|
|
|
1004 * This only affects the display mode used when the window is fullscreen. To
|
|
|
1005 * change the window size when the window is not fullscreen, use
|
|
|
1006 * SDL_SetWindowSize().
|
|
|
1007 *
|
|
|
1008 * If the window is currently in the fullscreen state, this request is
|
|
|
1009 * asynchronous on some windowing systems and the new mode dimensions may not
|
|
|
1010 * be applied immediately upon the return of this function. If an immediate
|
|
|
1011 * change is required, call SDL_SyncWindow() to block until the changes have
|
|
|
1012 * taken effect.
|
|
|
1013 *
|
|
|
1014 * When the new mode takes effect, an SDL_EVENT_WINDOW_RESIZED and/or an
|
|
|
1015 * SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event will be emitted with the new mode
|
|
|
1016 * dimensions.
|
|
|
1017 *
|
|
|
1018 * \param window the window to affect.
|
|
|
1019 * \param mode a pointer to the display mode to use, which can be NULL for
|
|
|
1020 * borderless fullscreen desktop mode, or one of the fullscreen
|
|
|
1021 * modes returned by SDL_GetFullscreenDisplayModes() to set an
|
|
|
1022 * exclusive fullscreen mode.
|
|
|
1023 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1024 * information.
|
|
|
1025 *
|
|
|
1026 * \threadsafety This function should only be called on the main thread.
|
|
|
1027 *
|
|
|
1028 * \since This function is available since SDL 3.2.0.
|
|
|
1029 *
|
|
|
1030 * \sa SDL_GetWindowFullscreenMode
|
|
|
1031 * \sa SDL_SetWindowFullscreen
|
|
|
1032 * \sa SDL_SyncWindow
|
|
|
1033 */
|
|
|
1034 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode);
|
|
|
1035
|
|
|
1036 /**
|
|
|
1037 * Query the display mode to use when a window is visible at fullscreen.
|
|
|
1038 *
|
|
|
1039 * \param window the window to query.
|
|
|
1040 * \returns a pointer to the exclusive fullscreen mode to use or NULL for
|
|
|
1041 * borderless fullscreen desktop mode.
|
|
|
1042 *
|
|
|
1043 * \threadsafety This function should only be called on the main thread.
|
|
|
1044 *
|
|
|
1045 * \since This function is available since SDL 3.2.0.
|
|
|
1046 *
|
|
|
1047 * \sa SDL_SetWindowFullscreenMode
|
|
|
1048 * \sa SDL_SetWindowFullscreen
|
|
|
1049 */
|
|
|
1050 extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode(SDL_Window *window);
|
|
|
1051
|
|
|
1052 /**
|
|
|
1053 * Get the raw ICC profile data for the screen the window is currently on.
|
|
|
1054 *
|
|
|
1055 * \param window the window to query.
|
|
|
1056 * \param size the size of the ICC profile.
|
|
|
1057 * \returns the raw ICC profile data on success or NULL on failure; call
|
|
|
1058 * SDL_GetError() for more information. This should be freed with
|
|
|
1059 * SDL_free() when it is no longer needed.
|
|
|
1060 *
|
|
|
1061 * \threadsafety This function should only be called on the main thread.
|
|
|
1062 *
|
|
|
1063 * \since This function is available since SDL 3.2.0.
|
|
|
1064 */
|
|
|
1065 extern SDL_DECLSPEC void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, size_t *size);
|
|
|
1066
|
|
|
1067 /**
|
|
|
1068 * Get the pixel format associated with the window.
|
|
|
1069 *
|
|
|
1070 * \param window the window to query.
|
|
|
1071 * \returns the pixel format of the window on success or
|
|
|
1072 * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more
|
|
|
1073 * information.
|
|
|
1074 *
|
|
|
1075 * \threadsafety This function should only be called on the main thread.
|
|
|
1076 *
|
|
|
1077 * \since This function is available since SDL 3.2.0.
|
|
|
1078 */
|
|
|
1079 extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window);
|
|
|
1080
|
|
|
1081 /**
|
|
|
1082 * Get a list of valid windows.
|
|
|
1083 *
|
|
|
1084 * \param count a pointer filled in with the number of windows returned, may
|
|
|
1085 * be NULL.
|
|
|
1086 * \returns a NULL terminated array of SDL_Window pointers or NULL on failure;
|
|
|
1087 * call SDL_GetError() for more information. This is a single
|
|
|
1088 * allocation that should be freed with SDL_free() when it is no
|
|
|
1089 * longer needed.
|
|
|
1090 *
|
|
|
1091 * \threadsafety This function should only be called on the main thread.
|
|
|
1092 *
|
|
|
1093 * \since This function is available since SDL 3.2.0.
|
|
|
1094 */
|
|
|
1095 extern SDL_DECLSPEC SDL_Window ** SDLCALL SDL_GetWindows(int *count);
|
|
|
1096
|
|
|
1097 /**
|
|
|
1098 * Create a window with the specified dimensions and flags.
|
|
|
1099 *
|
|
|
1100 * The window size is a request and may be different than expected based on
|
|
|
1101 * the desktop layout and window manager policies. Your application should be
|
|
|
1102 * prepared to handle a window of any size.
|
|
|
1103 *
|
|
|
1104 * `flags` may be any of the following OR'd together:
|
|
|
1105 *
|
|
|
1106 * - `SDL_WINDOW_FULLSCREEN`: fullscreen window at desktop resolution
|
|
|
1107 * - `SDL_WINDOW_OPENGL`: window usable with an OpenGL context
|
|
|
1108 * - `SDL_WINDOW_HIDDEN`: window is not visible
|
|
|
1109 * - `SDL_WINDOW_BORDERLESS`: no window decoration
|
|
|
1110 * - `SDL_WINDOW_RESIZABLE`: window can be resized
|
|
|
1111 * - `SDL_WINDOW_MINIMIZED`: window is minimized
|
|
|
1112 * - `SDL_WINDOW_MAXIMIZED`: window is maximized
|
|
|
1113 * - `SDL_WINDOW_MOUSE_GRABBED`: window has grabbed mouse focus
|
|
|
1114 * - `SDL_WINDOW_INPUT_FOCUS`: window has input focus
|
|
|
1115 * - `SDL_WINDOW_MOUSE_FOCUS`: window has mouse focus
|
|
|
1116 * - `SDL_WINDOW_EXTERNAL`: window not created by SDL
|
|
|
1117 * - `SDL_WINDOW_MODAL`: window is modal
|
|
|
1118 * - `SDL_WINDOW_HIGH_PIXEL_DENSITY`: window uses high pixel density back
|
|
|
1119 * buffer if possible
|
|
|
1120 * - `SDL_WINDOW_MOUSE_CAPTURE`: window has mouse captured (unrelated to
|
|
|
1121 * MOUSE_GRABBED)
|
|
|
1122 * - `SDL_WINDOW_ALWAYS_ON_TOP`: window should always be above others
|
|
|
1123 * - `SDL_WINDOW_UTILITY`: window should be treated as a utility window, not
|
|
|
1124 * showing in the task bar and window list
|
|
|
1125 * - `SDL_WINDOW_TOOLTIP`: window should be treated as a tooltip and does not
|
|
|
1126 * get mouse or keyboard focus, requires a parent window
|
|
|
1127 * - `SDL_WINDOW_POPUP_MENU`: window should be treated as a popup menu,
|
|
|
1128 * requires a parent window
|
|
|
1129 * - `SDL_WINDOW_KEYBOARD_GRABBED`: window has grabbed keyboard input
|
|
|
1130 * - `SDL_WINDOW_VULKAN`: window usable with a Vulkan instance
|
|
|
1131 * - `SDL_WINDOW_METAL`: window usable with a Metal instance
|
|
|
1132 * - `SDL_WINDOW_TRANSPARENT`: window with transparent buffer
|
|
|
1133 * - `SDL_WINDOW_NOT_FOCUSABLE`: window should not be focusable
|
|
|
1134 *
|
|
|
1135 * The SDL_Window will be shown if SDL_WINDOW_HIDDEN is not set. If hidden at
|
|
|
1136 * creation time, SDL_ShowWindow() can be used to show it later.
|
|
|
1137 *
|
|
|
1138 * On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist
|
|
|
1139 * property to YES, otherwise you will not receive a High-DPI OpenGL canvas.
|
|
|
1140 *
|
|
|
1141 * The window pixel size may differ from its window coordinate size if the
|
|
|
1142 * window is on a high pixel density display. Use SDL_GetWindowSize() to query
|
|
|
1143 * the client area's size in window coordinates, and
|
|
|
1144 * SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize() to query the
|
|
|
1145 * drawable size in pixels. Note that the drawable size can vary after the
|
|
|
1146 * window is created and should be queried again if you get an
|
|
|
1147 * SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event.
|
|
|
1148 *
|
|
|
1149 * If the window is created with any of the SDL_WINDOW_OPENGL or
|
|
|
1150 * SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function
|
|
|
1151 * (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the
|
|
|
1152 * corresponding UnloadLibrary function is called by SDL_DestroyWindow().
|
|
|
1153 *
|
|
|
1154 * If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver,
|
|
|
1155 * SDL_CreateWindow() will fail, because SDL_Vulkan_LoadLibrary() will fail.
|
|
|
1156 *
|
|
|
1157 * If SDL_WINDOW_METAL is specified on an OS that does not support Metal,
|
|
|
1158 * SDL_CreateWindow() will fail.
|
|
|
1159 *
|
|
|
1160 * If you intend to use this window with an SDL_Renderer, you should use
|
|
|
1161 * SDL_CreateWindowAndRenderer() instead of this function, to avoid window
|
|
|
1162 * flicker.
|
|
|
1163 *
|
|
|
1164 * On non-Apple devices, SDL requires you to either not link to the Vulkan
|
|
|
1165 * loader or link to a dynamic library version. This limitation may be removed
|
|
|
1166 * in a future version of SDL.
|
|
|
1167 *
|
|
|
1168 * \param title the title of the window, in UTF-8 encoding.
|
|
|
1169 * \param w the width of the window.
|
|
|
1170 * \param h the height of the window.
|
|
|
1171 * \param flags 0, or one or more SDL_WindowFlags OR'd together.
|
|
|
1172 * \returns the window that was created or NULL on failure; call
|
|
|
1173 * SDL_GetError() for more information.
|
|
|
1174 *
|
|
|
1175 * \threadsafety This function should only be called on the main thread.
|
|
|
1176 *
|
|
|
1177 * \since This function is available since SDL 3.2.0.
|
|
|
1178 *
|
|
|
1179 * \sa SDL_CreateWindowAndRenderer
|
|
|
1180 * \sa SDL_CreatePopupWindow
|
|
|
1181 * \sa SDL_CreateWindowWithProperties
|
|
|
1182 * \sa SDL_DestroyWindow
|
|
|
1183 */
|
|
|
1184 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int w, int h, SDL_WindowFlags flags);
|
|
|
1185
|
|
|
1186 /**
|
|
|
1187 * Create a child popup window of the specified parent window.
|
|
|
1188 *
|
|
|
1189 * The window size is a request and may be different than expected based on
|
|
|
1190 * the desktop layout and window manager policies. Your application should be
|
|
|
1191 * prepared to handle a window of any size.
|
|
|
1192 *
|
|
|
1193 * The flags parameter **must** contain at least one of the following:
|
|
|
1194 *
|
|
|
1195 * - `SDL_WINDOW_TOOLTIP`: The popup window is a tooltip and will not pass any
|
|
|
1196 * input events.
|
|
|
1197 * - `SDL_WINDOW_POPUP_MENU`: The popup window is a popup menu. The topmost
|
|
|
1198 * popup menu will implicitly gain the keyboard focus.
|
|
|
1199 *
|
|
|
1200 * The following flags are not relevant to popup window creation and will be
|
|
|
1201 * ignored:
|
|
|
1202 *
|
|
|
1203 * - `SDL_WINDOW_MINIMIZED`
|
|
|
1204 * - `SDL_WINDOW_MAXIMIZED`
|
|
|
1205 * - `SDL_WINDOW_FULLSCREEN`
|
|
|
1206 * - `SDL_WINDOW_BORDERLESS`
|
|
|
1207 *
|
|
|
1208 * The following flags are incompatible with popup window creation and will
|
|
|
1209 * cause it to fail:
|
|
|
1210 *
|
|
|
1211 * - `SDL_WINDOW_UTILITY`
|
|
|
1212 * - `SDL_WINDOW_MODAL`
|
|
|
1213 *
|
|
|
1214 * The parent parameter **must** be non-null and a valid window. The parent of
|
|
|
1215 * a popup window can be either a regular, toplevel window, or another popup
|
|
|
1216 * window.
|
|
|
1217 *
|
|
|
1218 * Popup windows cannot be minimized, maximized, made fullscreen, raised,
|
|
|
1219 * flash, be made a modal window, be the parent of a toplevel window, or grab
|
|
|
1220 * the mouse and/or keyboard. Attempts to do so will fail.
|
|
|
1221 *
|
|
|
1222 * Popup windows implicitly do not have a border/decorations and do not appear
|
|
|
1223 * on the taskbar/dock or in lists of windows such as alt-tab menus.
|
|
|
1224 *
|
|
|
1225 * By default, popup window positions will automatically be constrained to
|
|
|
1226 * keep the entire window within display bounds. This can be overridden with
|
|
|
1227 * the `SDL_PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN` property.
|
|
|
1228 *
|
|
|
1229 * By default, popup menus will automatically grab keyboard focus from the
|
|
|
1230 * parent when shown. This behavior can be overridden by setting the
|
|
|
1231 * `SDL_WINDOW_NOT_FOCUSABLE` flag, setting the
|
|
|
1232 * `SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN` property to false, or toggling
|
|
|
1233 * it after creation via the `SDL_SetWindowFocusable()` function.
|
|
|
1234 *
|
|
|
1235 * If a parent window is hidden or destroyed, any child popup windows will be
|
|
|
1236 * recursively hidden or destroyed as well. Child popup windows not explicitly
|
|
|
1237 * hidden will be restored when the parent is shown.
|
|
|
1238 *
|
|
|
1239 * \param parent the parent of the window, must not be NULL.
|
|
|
1240 * \param offset_x the x position of the popup window relative to the origin
|
|
|
1241 * of the parent.
|
|
|
1242 * \param offset_y the y position of the popup window relative to the origin
|
|
|
1243 * of the parent window.
|
|
|
1244 * \param w the width of the window.
|
|
|
1245 * \param h the height of the window.
|
|
|
1246 * \param flags SDL_WINDOW_TOOLTIP or SDL_WINDOW_POPUP_MENU, and zero or more
|
|
|
1247 * additional SDL_WindowFlags OR'd together.
|
|
|
1248 * \returns the window that was created or NULL on failure; call
|
|
|
1249 * SDL_GetError() for more information.
|
|
|
1250 *
|
|
|
1251 * \threadsafety This function should only be called on the main thread.
|
|
|
1252 *
|
|
|
1253 * \since This function is available since SDL 3.2.0.
|
|
|
1254 *
|
|
|
1255 * \sa SDL_CreateWindow
|
|
|
1256 * \sa SDL_CreateWindowWithProperties
|
|
|
1257 * \sa SDL_DestroyWindow
|
|
|
1258 * \sa SDL_GetWindowParent
|
|
|
1259 */
|
|
|
1260 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *parent, int offset_x, int offset_y, int w, int h, SDL_WindowFlags flags);
|
|
|
1261
|
|
|
1262 /**
|
|
|
1263 * Create a window with the specified properties.
|
|
|
1264 *
|
|
|
1265 * The window size is a request and may be different than expected based on
|
|
|
1266 * the desktop layout and window manager policies. Your application should be
|
|
|
1267 * prepared to handle a window of any size.
|
|
|
1268 *
|
|
|
1269 * These are the supported properties:
|
|
|
1270 *
|
|
|
1271 * - `SDL_PROP_WINDOW_CREATE_ALWAYS_ON_TOP_BOOLEAN`: true if the window should
|
|
|
1272 * be always on top
|
|
|
1273 * - `SDL_PROP_WINDOW_CREATE_BORDERLESS_BOOLEAN`: true if the window has no
|
|
|
1274 * window decoration
|
|
|
1275 * - `SDL_PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN`: true if the "tooltip"
|
|
|
1276 * and "menu" window types should be automatically constrained to be
|
|
|
1277 * entirely within display bounds (default), false if no constraints on the
|
|
|
1278 * position are desired.
|
|
|
1279 * - `SDL_PROP_WINDOW_CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN`: true if the
|
|
|
1280 * window will be used with an externally managed graphics context.
|
|
|
1281 * - `SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN`: true if the window should
|
|
|
1282 * accept keyboard input (defaults true)
|
|
|
1283 * - `SDL_PROP_WINDOW_CREATE_FULLSCREEN_BOOLEAN`: true if the window should
|
|
|
1284 * start in fullscreen mode at desktop resolution
|
|
|
1285 * - `SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER`: the height of the window
|
|
|
1286 * - `SDL_PROP_WINDOW_CREATE_HIDDEN_BOOLEAN`: true if the window should start
|
|
|
1287 * hidden
|
|
|
1288 * - `SDL_PROP_WINDOW_CREATE_HIGH_PIXEL_DENSITY_BOOLEAN`: true if the window
|
|
|
1289 * uses a high pixel density buffer if possible
|
|
|
1290 * - `SDL_PROP_WINDOW_CREATE_MAXIMIZED_BOOLEAN`: true if the window should
|
|
|
1291 * start maximized
|
|
|
1292 * - `SDL_PROP_WINDOW_CREATE_MENU_BOOLEAN`: true if the window is a popup menu
|
|
|
1293 * - `SDL_PROP_WINDOW_CREATE_METAL_BOOLEAN`: true if the window will be used
|
|
|
1294 * with Metal rendering
|
|
|
1295 * - `SDL_PROP_WINDOW_CREATE_MINIMIZED_BOOLEAN`: true if the window should
|
|
|
1296 * start minimized
|
|
|
1297 * - `SDL_PROP_WINDOW_CREATE_MODAL_BOOLEAN`: true if the window is modal to
|
|
|
1298 * its parent
|
|
|
1299 * - `SDL_PROP_WINDOW_CREATE_MOUSE_GRABBED_BOOLEAN`: true if the window starts
|
|
|
1300 * with grabbed mouse focus
|
|
|
1301 * - `SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN`: true if the window will be used
|
|
|
1302 * with OpenGL rendering
|
|
|
1303 * - `SDL_PROP_WINDOW_CREATE_PARENT_POINTER`: an SDL_Window that will be the
|
|
|
1304 * parent of this window, required for windows with the "tooltip", "menu",
|
|
|
1305 * and "modal" properties
|
|
|
1306 * - `SDL_PROP_WINDOW_CREATE_RESIZABLE_BOOLEAN`: true if the window should be
|
|
|
1307 * resizable
|
|
|
1308 * - `SDL_PROP_WINDOW_CREATE_TITLE_STRING`: the title of the window, in UTF-8
|
|
|
1309 * encoding
|
|
|
1310 * - `SDL_PROP_WINDOW_CREATE_TRANSPARENT_BOOLEAN`: true if the window show
|
|
|
1311 * transparent in the areas with alpha of 0
|
|
|
1312 * - `SDL_PROP_WINDOW_CREATE_TOOLTIP_BOOLEAN`: true if the window is a tooltip
|
|
|
1313 * - `SDL_PROP_WINDOW_CREATE_UTILITY_BOOLEAN`: true if the window is a utility
|
|
|
1314 * window, not showing in the task bar and window list
|
|
|
1315 * - `SDL_PROP_WINDOW_CREATE_VULKAN_BOOLEAN`: true if the window will be used
|
|
|
1316 * with Vulkan rendering
|
|
|
1317 * - `SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER`: the width of the window
|
|
|
1318 * - `SDL_PROP_WINDOW_CREATE_X_NUMBER`: the x position of the window, or
|
|
|
1319 * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is
|
|
|
1320 * relative to the parent for windows with the "tooltip" or "menu" property
|
|
|
1321 * set.
|
|
|
1322 * - `SDL_PROP_WINDOW_CREATE_Y_NUMBER`: the y position of the window, or
|
|
|
1323 * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is
|
|
|
1324 * relative to the parent for windows with the "tooltip" or "menu" property
|
|
|
1325 * set.
|
|
|
1326 *
|
|
|
1327 * These are additional supported properties on macOS:
|
|
|
1328 *
|
|
|
1329 * - `SDL_PROP_WINDOW_CREATE_COCOA_WINDOW_POINTER`: the
|
|
|
1330 * `(__unsafe_unretained)` NSWindow associated with the window, if you want
|
|
|
1331 * to wrap an existing window.
|
|
|
1332 * - `SDL_PROP_WINDOW_CREATE_COCOA_VIEW_POINTER`: the `(__unsafe_unretained)`
|
|
|
1333 * NSView associated with the window, defaults to `[window contentView]`
|
|
|
1334 *
|
|
|
1335 * These are additional supported properties on iOS, tvOS, and visionOS:
|
|
|
1336 *
|
|
|
1337 * - `SDL_PROP_WINDOW_CREATE_WINDOWSCENE_POINTER`: the `(__unsafe_unretained)`
|
|
|
1338 * UIWindowScene associated with the window, defaults to the active window
|
|
|
1339 * scene.
|
|
|
1340 *
|
|
|
1341 * These are additional supported properties on Wayland:
|
|
|
1342 *
|
|
|
1343 * - `SDL_PROP_WINDOW_CREATE_WAYLAND_SURFACE_ROLE_CUSTOM_BOOLEAN` - true if
|
|
|
1344 * the application wants to use the Wayland surface for a custom role and
|
|
|
1345 * does not want it attached to an XDG toplevel window. See
|
|
|
1346 * [README-wayland](README-wayland) for more information on using custom
|
|
|
1347 * surfaces.
|
|
|
1348 * - `SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN` - true if the
|
|
|
1349 * application wants an associated `wl_egl_window` object to be created and
|
|
|
1350 * attached to the window, even if the window does not have the OpenGL
|
|
|
1351 * property or `SDL_WINDOW_OPENGL` flag set.
|
|
|
1352 * - `SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER` - the wl_surface
|
|
|
1353 * associated with the window, if you want to wrap an existing window. See
|
|
|
1354 * [README-wayland](README-wayland) for more information.
|
|
|
1355 *
|
|
|
1356 * These are additional supported properties on Windows:
|
|
|
1357 *
|
|
|
1358 * - `SDL_PROP_WINDOW_CREATE_WIN32_HWND_POINTER`: the HWND associated with the
|
|
|
1359 * window, if you want to wrap an existing window.
|
|
|
1360 * - `SDL_PROP_WINDOW_CREATE_WIN32_PIXEL_FORMAT_HWND_POINTER`: optional,
|
|
|
1361 * another window to share pixel format with, useful for OpenGL windows
|
|
|
1362 *
|
|
|
1363 * These are additional supported properties with X11:
|
|
|
1364 *
|
|
|
1365 * - `SDL_PROP_WINDOW_CREATE_X11_WINDOW_NUMBER`: the X11 Window associated
|
|
|
1366 * with the window, if you want to wrap an existing window.
|
|
|
1367 *
|
|
|
1368 * The window is implicitly shown if the "hidden" property is not set.
|
|
|
1369 *
|
|
|
1370 * These are additional supported properties with Emscripten:
|
|
|
1371 *
|
|
|
1372 * - `SDL_PROP_WINDOW_CREATE_EMSCRIPTEN_CANVAS_ID_STRING`: the id given to the
|
|
|
1373 * canvas element. This should start with a '#' sign
|
|
|
1374 * - `SDL_PROP_WINDOW_CREATE_EMSCRIPTEN_KEYBOARD_ELEMENT_STRING`: override the
|
|
|
1375 * binding element for keyboard inputs for this canvas. The variable can be
|
|
|
1376 * one of:
|
|
|
1377 * - "#window": the javascript window object (default)
|
|
|
1378 * - "#document": the javascript document object
|
|
|
1379 * - "#screen": the javascript window.screen object
|
|
|
1380 * - "#canvas": the WebGL canvas element
|
|
|
1381 * - "#none": Don't bind anything at all
|
|
|
1382 * - any other string without a leading # sign applies to the element on the
|
|
|
1383 * page with that ID. Windows with the "tooltip" and "menu" properties are
|
|
|
1384 * popup windows and have the behaviors and guidelines outlined in
|
|
|
1385 * SDL_CreatePopupWindow().
|
|
|
1386 *
|
|
|
1387 * If this window is being created to be used with an SDL_Renderer, you should
|
|
|
1388 * not add a graphics API specific property
|
|
|
1389 * (`SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN`, etc), as SDL will handle that
|
|
|
1390 * internally when it chooses a renderer. However, SDL might need to recreate
|
|
|
1391 * your window at that point, which may cause the window to appear briefly,
|
|
|
1392 * and then flicker as it is recreated. The correct approach to this is to
|
|
|
1393 * create the window with the `SDL_PROP_WINDOW_CREATE_HIDDEN_BOOLEAN` property
|
|
|
1394 * set to true, then create the renderer, then show the window with
|
|
|
1395 * SDL_ShowWindow().
|
|
|
1396 *
|
|
|
1397 * \param props the properties to use.
|
|
|
1398 * \returns the window that was created or NULL on failure; call
|
|
|
1399 * SDL_GetError() for more information.
|
|
|
1400 *
|
|
|
1401 * \threadsafety This function should only be called on the main thread.
|
|
|
1402 *
|
|
|
1403 * \since This function is available since SDL 3.2.0.
|
|
|
1404 *
|
|
|
1405 * \sa SDL_CreateProperties
|
|
|
1406 * \sa SDL_CreateWindow
|
|
|
1407 * \sa SDL_DestroyWindow
|
|
|
1408 */
|
|
|
1409 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowWithProperties(SDL_PropertiesID props);
|
|
|
1410
|
|
|
1411 #define SDL_PROP_WINDOW_CREATE_ALWAYS_ON_TOP_BOOLEAN "SDL.window.create.always_on_top"
|
|
|
1412 #define SDL_PROP_WINDOW_CREATE_BORDERLESS_BOOLEAN "SDL.window.create.borderless"
|
|
|
1413 #define SDL_PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN "SDL.window.create.constrain_popup"
|
|
|
1414 #define SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN "SDL.window.create.focusable"
|
|
|
1415 #define SDL_PROP_WINDOW_CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN "SDL.window.create.external_graphics_context"
|
|
|
1416 #define SDL_PROP_WINDOW_CREATE_FLAGS_NUMBER "SDL.window.create.flags"
|
|
|
1417 #define SDL_PROP_WINDOW_CREATE_FULLSCREEN_BOOLEAN "SDL.window.create.fullscreen"
|
|
|
1418 #define SDL_PROP_WINDOW_CREATE_HEIGHT_NUMBER "SDL.window.create.height"
|
|
|
1419 #define SDL_PROP_WINDOW_CREATE_HIDDEN_BOOLEAN "SDL.window.create.hidden"
|
|
|
1420 #define SDL_PROP_WINDOW_CREATE_HIGH_PIXEL_DENSITY_BOOLEAN "SDL.window.create.high_pixel_density"
|
|
|
1421 #define SDL_PROP_WINDOW_CREATE_MAXIMIZED_BOOLEAN "SDL.window.create.maximized"
|
|
|
1422 #define SDL_PROP_WINDOW_CREATE_MENU_BOOLEAN "SDL.window.create.menu"
|
|
|
1423 #define SDL_PROP_WINDOW_CREATE_METAL_BOOLEAN "SDL.window.create.metal"
|
|
|
1424 #define SDL_PROP_WINDOW_CREATE_MINIMIZED_BOOLEAN "SDL.window.create.minimized"
|
|
|
1425 #define SDL_PROP_WINDOW_CREATE_MODAL_BOOLEAN "SDL.window.create.modal"
|
|
|
1426 #define SDL_PROP_WINDOW_CREATE_MOUSE_GRABBED_BOOLEAN "SDL.window.create.mouse_grabbed"
|
|
|
1427 #define SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN "SDL.window.create.opengl"
|
|
|
1428 #define SDL_PROP_WINDOW_CREATE_PARENT_POINTER "SDL.window.create.parent"
|
|
|
1429 #define SDL_PROP_WINDOW_CREATE_RESIZABLE_BOOLEAN "SDL.window.create.resizable"
|
|
|
1430 #define SDL_PROP_WINDOW_CREATE_TITLE_STRING "SDL.window.create.title"
|
|
|
1431 #define SDL_PROP_WINDOW_CREATE_TRANSPARENT_BOOLEAN "SDL.window.create.transparent"
|
|
|
1432 #define SDL_PROP_WINDOW_CREATE_TOOLTIP_BOOLEAN "SDL.window.create.tooltip"
|
|
|
1433 #define SDL_PROP_WINDOW_CREATE_UTILITY_BOOLEAN "SDL.window.create.utility"
|
|
|
1434 #define SDL_PROP_WINDOW_CREATE_VULKAN_BOOLEAN "SDL.window.create.vulkan"
|
|
|
1435 #define SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER "SDL.window.create.width"
|
|
|
1436 #define SDL_PROP_WINDOW_CREATE_X_NUMBER "SDL.window.create.x"
|
|
|
1437 #define SDL_PROP_WINDOW_CREATE_Y_NUMBER "SDL.window.create.y"
|
|
|
1438 #define SDL_PROP_WINDOW_CREATE_COCOA_WINDOW_POINTER "SDL.window.create.cocoa.window"
|
|
|
1439 #define SDL_PROP_WINDOW_CREATE_COCOA_VIEW_POINTER "SDL.window.create.cocoa.view"
|
|
|
1440 #define SDL_PROP_WINDOW_CREATE_WINDOWSCENE_POINTER "SDL.window.create.uikit.windowscene"
|
|
|
1441 #define SDL_PROP_WINDOW_CREATE_WAYLAND_SURFACE_ROLE_CUSTOM_BOOLEAN "SDL.window.create.wayland.surface_role_custom"
|
|
|
1442 #define SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN "SDL.window.create.wayland.create_egl_window"
|
|
|
1443 #define SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER "SDL.window.create.wayland.wl_surface"
|
|
|
1444 #define SDL_PROP_WINDOW_CREATE_WIN32_HWND_POINTER "SDL.window.create.win32.hwnd"
|
|
|
1445 #define SDL_PROP_WINDOW_CREATE_WIN32_PIXEL_FORMAT_HWND_POINTER "SDL.window.create.win32.pixel_format_hwnd"
|
|
|
1446 #define SDL_PROP_WINDOW_CREATE_X11_WINDOW_NUMBER "SDL.window.create.x11.window"
|
|
|
1447 #define SDL_PROP_WINDOW_CREATE_EMSCRIPTEN_CANVAS_ID_STRING "SDL.window.create.emscripten.canvas_id"
|
|
|
1448 #define SDL_PROP_WINDOW_CREATE_EMSCRIPTEN_KEYBOARD_ELEMENT_STRING "SDL.window.create.emscripten.keyboard_element"
|
|
|
1449
|
|
|
1450 /**
|
|
|
1451 * Get the numeric ID of a window.
|
|
|
1452 *
|
|
|
1453 * The numeric ID is what SDL_WindowEvent references, and is necessary to map
|
|
|
1454 * these events to specific SDL_Window objects.
|
|
|
1455 *
|
|
|
1456 * \param window the window to query.
|
|
|
1457 * \returns the ID of the window on success or 0 on failure; call
|
|
|
1458 * SDL_GetError() for more information.
|
|
|
1459 *
|
|
|
1460 * \threadsafety This function should only be called on the main thread.
|
|
|
1461 *
|
|
|
1462 * \since This function is available since SDL 3.2.0.
|
|
|
1463 *
|
|
|
1464 * \sa SDL_GetWindowFromID
|
|
|
1465 */
|
|
|
1466 extern SDL_DECLSPEC SDL_WindowID SDLCALL SDL_GetWindowID(SDL_Window *window);
|
|
|
1467
|
|
|
1468 /**
|
|
|
1469 * Get a window from a stored ID.
|
|
|
1470 *
|
|
|
1471 * The numeric ID is what SDL_WindowEvent references, and is necessary to map
|
|
|
1472 * these events to specific SDL_Window objects.
|
|
|
1473 *
|
|
|
1474 * \param id the ID of the window.
|
|
|
1475 * \returns the window associated with `id` or NULL if it doesn't exist; call
|
|
|
1476 * SDL_GetError() for more information.
|
|
|
1477 *
|
|
|
1478 * \threadsafety This function should only be called on the main thread.
|
|
|
1479 *
|
|
|
1480 * \since This function is available since SDL 3.2.0.
|
|
|
1481 *
|
|
|
1482 * \sa SDL_GetWindowID
|
|
|
1483 */
|
|
|
1484 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(SDL_WindowID id);
|
|
|
1485
|
|
|
1486 /**
|
|
|
1487 * Get parent of a window.
|
|
|
1488 *
|
|
|
1489 * \param window the window to query.
|
|
|
1490 * \returns the parent of the window on success or NULL if the window has no
|
|
|
1491 * parent.
|
|
|
1492 *
|
|
|
1493 * \threadsafety This function should only be called on the main thread.
|
|
|
1494 *
|
|
|
1495 * \since This function is available since SDL 3.2.0.
|
|
|
1496 *
|
|
|
1497 * \sa SDL_CreatePopupWindow
|
|
|
1498 */
|
|
|
1499 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window);
|
|
|
1500
|
|
|
1501 /**
|
|
|
1502 * Get the properties associated with a window.
|
|
|
1503 *
|
|
|
1504 * The following read-only properties are provided by SDL:
|
|
|
1505 *
|
|
|
1506 * - `SDL_PROP_WINDOW_SHAPE_POINTER`: the surface associated with a shaped
|
|
|
1507 * window
|
|
|
1508 * - `SDL_PROP_WINDOW_HDR_ENABLED_BOOLEAN`: true if the window has HDR
|
|
|
1509 * headroom above the SDR white point. This property can change dynamically
|
|
|
1510 * when SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent.
|
|
|
1511 * - `SDL_PROP_WINDOW_SDR_WHITE_LEVEL_FLOAT`: the value of SDR white in the
|
|
|
1512 * SDL_COLORSPACE_SRGB_LINEAR colorspace. On Windows this corresponds to the
|
|
|
1513 * SDR white level in scRGB colorspace, and on Apple platforms this is
|
|
|
1514 * always 1.0 for EDR content. This property can change dynamically when
|
|
|
1515 * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent.
|
|
|
1516 * - `SDL_PROP_WINDOW_HDR_HEADROOM_FLOAT`: the additional high dynamic range
|
|
|
1517 * that can be displayed, in terms of the SDR white point. When HDR is not
|
|
|
1518 * enabled, this will be 1.0. This property can change dynamically when
|
|
|
1519 * SDL_EVENT_WINDOW_HDR_STATE_CHANGED is sent.
|
|
|
1520 *
|
|
|
1521 * On Android:
|
|
|
1522 *
|
|
|
1523 * - `SDL_PROP_WINDOW_ANDROID_WINDOW_POINTER`: the ANativeWindow associated
|
|
|
1524 * with the window
|
|
|
1525 * - `SDL_PROP_WINDOW_ANDROID_SURFACE_POINTER`: the EGLSurface associated with
|
|
|
1526 * the window
|
|
|
1527 *
|
|
|
1528 * On iOS:
|
|
|
1529 *
|
|
|
1530 * - `SDL_PROP_WINDOW_UIKIT_WINDOW_POINTER`: the `(__unsafe_unretained)`
|
|
|
1531 * UIWindow associated with the window
|
|
|
1532 * - `SDL_PROP_WINDOW_UIKIT_METAL_VIEW_TAG_NUMBER`: the NSInteger tag
|
|
|
1533 * associated with metal views on the window
|
|
|
1534 * - `SDL_PROP_WINDOW_UIKIT_OPENGL_FRAMEBUFFER_NUMBER`: the OpenGL view's
|
|
|
1535 * framebuffer object. It must be bound when rendering to the screen using
|
|
|
1536 * OpenGL.
|
|
|
1537 * - `SDL_PROP_WINDOW_UIKIT_OPENGL_RENDERBUFFER_NUMBER`: the OpenGL view's
|
|
|
1538 * renderbuffer object. It must be bound when SDL_GL_SwapWindow is called.
|
|
|
1539 * - `SDL_PROP_WINDOW_UIKIT_OPENGL_RESOLVE_FRAMEBUFFER_NUMBER`: the OpenGL
|
|
|
1540 * view's resolve framebuffer, when MSAA is used.
|
|
|
1541 *
|
|
|
1542 * On KMS/DRM:
|
|
|
1543 *
|
|
|
1544 * - `SDL_PROP_WINDOW_KMSDRM_DEVICE_INDEX_NUMBER`: the device index associated
|
|
|
1545 * with the window (e.g. the X in /dev/dri/cardX)
|
|
|
1546 * - `SDL_PROP_WINDOW_KMSDRM_DRM_FD_NUMBER`: the DRM FD associated with the
|
|
|
1547 * window
|
|
|
1548 * - `SDL_PROP_WINDOW_KMSDRM_GBM_DEVICE_POINTER`: the GBM device associated
|
|
|
1549 * with the window
|
|
|
1550 *
|
|
|
1551 * On macOS:
|
|
|
1552 *
|
|
|
1553 * - `SDL_PROP_WINDOW_COCOA_WINDOW_POINTER`: the `(__unsafe_unretained)`
|
|
|
1554 * NSWindow associated with the window
|
|
|
1555 * - `SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER`: the NSInteger tag
|
|
|
1556 * associated with metal views on the window
|
|
|
1557 *
|
|
|
1558 * On OpenVR:
|
|
|
1559 *
|
|
|
1560 * - `SDL_PROP_WINDOW_OPENVR_OVERLAY_ID_NUMBER`: the OpenVR Overlay Handle ID
|
|
|
1561 * for the associated overlay window.
|
|
|
1562 *
|
|
|
1563 * On Vivante:
|
|
|
1564 *
|
|
|
1565 * - `SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER`: the EGLNativeDisplayType
|
|
|
1566 * associated with the window
|
|
|
1567 * - `SDL_PROP_WINDOW_VIVANTE_WINDOW_POINTER`: the EGLNativeWindowType
|
|
|
1568 * associated with the window
|
|
|
1569 * - `SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER`: the EGLSurface associated with
|
|
|
1570 * the window
|
|
|
1571 *
|
|
|
1572 * On Windows:
|
|
|
1573 *
|
|
|
1574 * - `SDL_PROP_WINDOW_WIN32_HWND_POINTER`: the HWND associated with the window
|
|
|
1575 * - `SDL_PROP_WINDOW_WIN32_HDC_POINTER`: the HDC associated with the window
|
|
|
1576 * - `SDL_PROP_WINDOW_WIN32_INSTANCE_POINTER`: the HINSTANCE associated with
|
|
|
1577 * the window
|
|
|
1578 *
|
|
|
1579 * On Wayland:
|
|
|
1580 *
|
|
|
1581 * Note: The `xdg_*` window objects do not internally persist across window
|
|
|
1582 * show/hide calls. They will be null if the window is hidden and must be
|
|
|
1583 * queried each time it is shown.
|
|
|
1584 *
|
|
|
1585 * - `SDL_PROP_WINDOW_WAYLAND_DISPLAY_POINTER`: the wl_display associated with
|
|
|
1586 * the window
|
|
|
1587 * - `SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER`: the wl_surface associated with
|
|
|
1588 * the window
|
|
|
1589 * - `SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER`: the wp_viewport associated
|
|
|
1590 * with the window
|
|
|
1591 * - `SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER`: the wl_egl_window
|
|
|
1592 * associated with the window
|
|
|
1593 * - `SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER`: the xdg_surface associated
|
|
|
1594 * with the window
|
|
|
1595 * - `SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_POINTER`: the xdg_toplevel role
|
|
|
1596 * associated with the window
|
|
|
1597 * - 'SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_EXPORT_HANDLE_STRING': the export
|
|
|
1598 * handle associated with the window
|
|
|
1599 * - `SDL_PROP_WINDOW_WAYLAND_XDG_POPUP_POINTER`: the xdg_popup role
|
|
|
1600 * associated with the window
|
|
|
1601 * - `SDL_PROP_WINDOW_WAYLAND_XDG_POSITIONER_POINTER`: the xdg_positioner
|
|
|
1602 * associated with the window, in popup mode
|
|
|
1603 *
|
|
|
1604 * On X11:
|
|
|
1605 *
|
|
|
1606 * - `SDL_PROP_WINDOW_X11_DISPLAY_POINTER`: the X11 Display associated with
|
|
|
1607 * the window
|
|
|
1608 * - `SDL_PROP_WINDOW_X11_SCREEN_NUMBER`: the screen number associated with
|
|
|
1609 * the window
|
|
|
1610 * - `SDL_PROP_WINDOW_X11_WINDOW_NUMBER`: the X11 Window associated with the
|
|
|
1611 * window
|
|
|
1612 *
|
|
|
1613 * On Emscripten:
|
|
|
1614 *
|
|
|
1615 * - `SDL_PROP_WINDOW_EMSCRIPTEN_CANVAS_ID_STRING`: the id the canvas element
|
|
|
1616 * will have
|
|
|
1617 * - `SDL_PROP_WINDOW_EMSCRIPTEN_KEYBOARD_ELEMENT_STRING`: the keyboard
|
|
|
1618 * element that associates keyboard events to this window
|
|
|
1619 *
|
|
|
1620 * \param window the window to query.
|
|
|
1621 * \returns a valid property ID on success or 0 on failure; call
|
|
|
1622 * SDL_GetError() for more information.
|
|
|
1623 *
|
|
|
1624 * \threadsafety This function should only be called on the main thread.
|
|
|
1625 *
|
|
|
1626 * \since This function is available since SDL 3.2.0.
|
|
|
1627 */
|
|
|
1628 extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window *window);
|
|
|
1629
|
|
|
1630 #define SDL_PROP_WINDOW_SHAPE_POINTER "SDL.window.shape"
|
|
|
1631 #define SDL_PROP_WINDOW_HDR_ENABLED_BOOLEAN "SDL.window.HDR_enabled"
|
|
|
1632 #define SDL_PROP_WINDOW_SDR_WHITE_LEVEL_FLOAT "SDL.window.SDR_white_level"
|
|
|
1633 #define SDL_PROP_WINDOW_HDR_HEADROOM_FLOAT "SDL.window.HDR_headroom"
|
|
|
1634 #define SDL_PROP_WINDOW_ANDROID_WINDOW_POINTER "SDL.window.android.window"
|
|
|
1635 #define SDL_PROP_WINDOW_ANDROID_SURFACE_POINTER "SDL.window.android.surface"
|
|
|
1636 #define SDL_PROP_WINDOW_UIKIT_WINDOW_POINTER "SDL.window.uikit.window"
|
|
|
1637 #define SDL_PROP_WINDOW_UIKIT_METAL_VIEW_TAG_NUMBER "SDL.window.uikit.metal_view_tag"
|
|
|
1638 #define SDL_PROP_WINDOW_UIKIT_OPENGL_FRAMEBUFFER_NUMBER "SDL.window.uikit.opengl.framebuffer"
|
|
|
1639 #define SDL_PROP_WINDOW_UIKIT_OPENGL_RENDERBUFFER_NUMBER "SDL.window.uikit.opengl.renderbuffer"
|
|
|
1640 #define SDL_PROP_WINDOW_UIKIT_OPENGL_RESOLVE_FRAMEBUFFER_NUMBER "SDL.window.uikit.opengl.resolve_framebuffer"
|
|
|
1641 #define SDL_PROP_WINDOW_KMSDRM_DEVICE_INDEX_NUMBER "SDL.window.kmsdrm.dev_index"
|
|
|
1642 #define SDL_PROP_WINDOW_KMSDRM_DRM_FD_NUMBER "SDL.window.kmsdrm.drm_fd"
|
|
|
1643 #define SDL_PROP_WINDOW_KMSDRM_GBM_DEVICE_POINTER "SDL.window.kmsdrm.gbm_dev"
|
|
|
1644 #define SDL_PROP_WINDOW_COCOA_WINDOW_POINTER "SDL.window.cocoa.window"
|
|
|
1645 #define SDL_PROP_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER "SDL.window.cocoa.metal_view_tag"
|
|
|
1646 #define SDL_PROP_WINDOW_OPENVR_OVERLAY_ID_NUMBER "SDL.window.openvr.overlay_id"
|
|
|
1647 #define SDL_PROP_WINDOW_VIVANTE_DISPLAY_POINTER "SDL.window.vivante.display"
|
|
|
1648 #define SDL_PROP_WINDOW_VIVANTE_WINDOW_POINTER "SDL.window.vivante.window"
|
|
|
1649 #define SDL_PROP_WINDOW_VIVANTE_SURFACE_POINTER "SDL.window.vivante.surface"
|
|
|
1650 #define SDL_PROP_WINDOW_WIN32_HWND_POINTER "SDL.window.win32.hwnd"
|
|
|
1651 #define SDL_PROP_WINDOW_WIN32_HDC_POINTER "SDL.window.win32.hdc"
|
|
|
1652 #define SDL_PROP_WINDOW_WIN32_INSTANCE_POINTER "SDL.window.win32.instance"
|
|
|
1653 #define SDL_PROP_WINDOW_WAYLAND_DISPLAY_POINTER "SDL.window.wayland.display"
|
|
|
1654 #define SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER "SDL.window.wayland.surface"
|
|
|
1655 #define SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER "SDL.window.wayland.viewport"
|
|
|
1656 #define SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER "SDL.window.wayland.egl_window"
|
|
|
1657 #define SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER "SDL.window.wayland.xdg_surface"
|
|
|
1658 #define SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_POINTER "SDL.window.wayland.xdg_toplevel"
|
|
|
1659 #define SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_EXPORT_HANDLE_STRING "SDL.window.wayland.xdg_toplevel_export_handle"
|
|
|
1660 #define SDL_PROP_WINDOW_WAYLAND_XDG_POPUP_POINTER "SDL.window.wayland.xdg_popup"
|
|
|
1661 #define SDL_PROP_WINDOW_WAYLAND_XDG_POSITIONER_POINTER "SDL.window.wayland.xdg_positioner"
|
|
|
1662 #define SDL_PROP_WINDOW_X11_DISPLAY_POINTER "SDL.window.x11.display"
|
|
|
1663 #define SDL_PROP_WINDOW_X11_SCREEN_NUMBER "SDL.window.x11.screen"
|
|
|
1664 #define SDL_PROP_WINDOW_X11_WINDOW_NUMBER "SDL.window.x11.window"
|
|
|
1665 #define SDL_PROP_WINDOW_EMSCRIPTEN_CANVAS_ID_STRING "SDL.window.emscripten.canvas_id"
|
|
|
1666 #define SDL_PROP_WINDOW_EMSCRIPTEN_KEYBOARD_ELEMENT_STRING "SDL.window.emscripten.keyboard_element"
|
|
|
1667
|
|
|
1668 /**
|
|
|
1669 * Get the window flags.
|
|
|
1670 *
|
|
|
1671 * \param window the window to query.
|
|
|
1672 * \returns a mask of the SDL_WindowFlags associated with `window`.
|
|
|
1673 *
|
|
|
1674 * \threadsafety This function should only be called on the main thread.
|
|
|
1675 *
|
|
|
1676 * \since This function is available since SDL 3.2.0.
|
|
|
1677 *
|
|
|
1678 * \sa SDL_CreateWindow
|
|
|
1679 * \sa SDL_HideWindow
|
|
|
1680 * \sa SDL_MaximizeWindow
|
|
|
1681 * \sa SDL_MinimizeWindow
|
|
|
1682 * \sa SDL_SetWindowFullscreen
|
|
|
1683 * \sa SDL_SetWindowMouseGrab
|
|
|
1684 * \sa SDL_SetWindowFillDocument
|
|
|
1685 * \sa SDL_ShowWindow
|
|
|
1686 */
|
|
|
1687 extern SDL_DECLSPEC SDL_WindowFlags SDLCALL SDL_GetWindowFlags(SDL_Window *window);
|
|
|
1688
|
|
|
1689 /**
|
|
|
1690 * Set the title of a window.
|
|
|
1691 *
|
|
|
1692 * This string is expected to be in UTF-8 encoding.
|
|
|
1693 *
|
|
|
1694 * \param window the window to change.
|
|
|
1695 * \param title the desired window title in UTF-8 format.
|
|
|
1696 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1697 * information.
|
|
|
1698 *
|
|
|
1699 * \threadsafety This function should only be called on the main thread.
|
|
|
1700 *
|
|
|
1701 * \since This function is available since SDL 3.2.0.
|
|
|
1702 *
|
|
|
1703 * \sa SDL_GetWindowTitle
|
|
|
1704 */
|
|
|
1705 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowTitle(SDL_Window *window, const char *title);
|
|
|
1706
|
|
|
1707 /**
|
|
|
1708 * Get the title of a window.
|
|
|
1709 *
|
|
|
1710 * \param window the window to query.
|
|
|
1711 * \returns the title of the window in UTF-8 format or "" if there is no
|
|
|
1712 * title.
|
|
|
1713 *
|
|
|
1714 * \threadsafety This function should only be called on the main thread.
|
|
|
1715 *
|
|
|
1716 * \since This function is available since SDL 3.2.0.
|
|
|
1717 *
|
|
|
1718 * \sa SDL_SetWindowTitle
|
|
|
1719 */
|
|
|
1720 extern SDL_DECLSPEC const char * SDLCALL SDL_GetWindowTitle(SDL_Window *window);
|
|
|
1721
|
|
|
1722 /**
|
|
|
1723 * Set the icon for a window.
|
|
|
1724 *
|
|
|
1725 * If this function is passed a surface with alternate representations added
|
|
|
1726 * using SDL_AddSurfaceAlternateImage(), the surface will be interpreted as
|
|
|
1727 * the content to be used for 100% display scale, and the alternate
|
|
|
1728 * representations will be used for high DPI situations. For example, if the
|
|
|
1729 * original surface is 32x32, then on a 2x macOS display or 200% display scale
|
|
|
1730 * on Windows, a 64x64 version of the image will be used, if available. If a
|
|
|
1731 * matching version of the image isn't available, the closest larger size
|
|
|
1732 * image will be downscaled to the appropriate size and be used instead, if
|
|
|
1733 * available. Otherwise, the closest smaller image will be upscaled and be
|
|
|
1734 * used instead.
|
|
|
1735 *
|
|
|
1736 * \param window the window to change.
|
|
|
1737 * \param icon an SDL_Surface structure containing the icon for the window.
|
|
|
1738 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1739 * information.
|
|
|
1740 *
|
|
|
1741 * \threadsafety This function should only be called on the main thread.
|
|
|
1742 *
|
|
|
1743 * \since This function is available since SDL 3.2.0.
|
|
|
1744 *
|
|
|
1745 * \sa SDL_AddSurfaceAlternateImage
|
|
|
1746 */
|
|
|
1747 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon);
|
|
|
1748
|
|
|
1749 /**
|
|
|
1750 * Request that the window's position be set.
|
|
|
1751 *
|
|
|
1752 * If the window is in an exclusive fullscreen or maximized state, this
|
|
|
1753 * request has no effect.
|
|
|
1754 *
|
|
|
1755 * This can be used to reposition fullscreen-desktop windows onto a different
|
|
|
1756 * display, however, as exclusive fullscreen windows are locked to a specific
|
|
|
1757 * display, they can only be repositioned programmatically via
|
|
|
1758 * SDL_SetWindowFullscreenMode().
|
|
|
1759 *
|
|
|
1760 * On some windowing systems this request is asynchronous and the new
|
|
|
1761 * coordinates may not have have been applied immediately upon the return of
|
|
|
1762 * this function. If an immediate change is required, call SDL_SyncWindow() to
|
|
|
1763 * block until the changes have taken effect.
|
|
|
1764 *
|
|
|
1765 * When the window position changes, an SDL_EVENT_WINDOW_MOVED event will be
|
|
|
1766 * emitted with the window's new coordinates. Note that the new coordinates
|
|
|
1767 * may not match the exact coordinates requested, as some windowing systems
|
|
|
1768 * can restrict the position of the window in certain scenarios (e.g.
|
|
|
1769 * constraining the position so the window is always within desktop bounds).
|
|
|
1770 * Additionally, as this is just a request, it can be denied by the windowing
|
|
|
1771 * system.
|
|
|
1772 *
|
|
|
1773 * \param window the window to reposition.
|
|
|
1774 * \param x the x coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or
|
|
|
1775 * `SDL_WINDOWPOS_UNDEFINED`.
|
|
|
1776 * \param y the y coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or
|
|
|
1777 * `SDL_WINDOWPOS_UNDEFINED`.
|
|
|
1778 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1779 * information.
|
|
|
1780 *
|
|
|
1781 * \threadsafety This function should only be called on the main thread.
|
|
|
1782 *
|
|
|
1783 * \since This function is available since SDL 3.2.0.
|
|
|
1784 *
|
|
|
1785 * \sa SDL_GetWindowPosition
|
|
|
1786 * \sa SDL_SyncWindow
|
|
|
1787 */
|
|
|
1788 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y);
|
|
|
1789
|
|
|
1790 /**
|
|
|
1791 * Get the position of a window.
|
|
|
1792 *
|
|
|
1793 * This is the current position of the window as last reported by the
|
|
|
1794 * windowing system.
|
|
|
1795 *
|
|
|
1796 * If you do not need the value for one of the positions a NULL may be passed
|
|
|
1797 * in the `x` or `y` parameter.
|
|
|
1798 *
|
|
|
1799 * \param window the window to query.
|
|
|
1800 * \param x a pointer filled in with the x position of the window, may be
|
|
|
1801 * NULL.
|
|
|
1802 * \param y a pointer filled in with the y position of the window, may be
|
|
|
1803 * NULL.
|
|
|
1804 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1805 * information.
|
|
|
1806 *
|
|
|
1807 * \threadsafety This function should only be called on the main thread.
|
|
|
1808 *
|
|
|
1809 * \since This function is available since SDL 3.2.0.
|
|
|
1810 *
|
|
|
1811 * \sa SDL_SetWindowPosition
|
|
|
1812 */
|
|
|
1813 extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y);
|
|
|
1814
|
|
|
1815 /**
|
|
|
1816 * Request that the size of a window's client area be set.
|
|
|
1817 *
|
|
|
1818 * If the window is in a fullscreen or maximized state, this request has no
|
|
|
1819 * effect.
|
|
|
1820 *
|
|
|
1821 * To change the exclusive fullscreen mode of a window, use
|
|
|
1822 * SDL_SetWindowFullscreenMode().
|
|
|
1823 *
|
|
|
1824 * On some windowing systems, this request is asynchronous and the new window
|
|
|
1825 * size may not have have been applied immediately upon the return of this
|
|
|
1826 * function. If an immediate change is required, call SDL_SyncWindow() to
|
|
|
1827 * block until the changes have taken effect.
|
|
|
1828 *
|
|
|
1829 * When the window size changes, an SDL_EVENT_WINDOW_RESIZED event will be
|
|
|
1830 * emitted with the new window dimensions. Note that the new dimensions may
|
|
|
1831 * not match the exact size requested, as some windowing systems can restrict
|
|
|
1832 * the window size in certain scenarios (e.g. constraining the size of the
|
|
|
1833 * content area to remain within the usable desktop bounds). Additionally, as
|
|
|
1834 * this is just a request, it can be denied by the windowing system.
|
|
|
1835 *
|
|
|
1836 * \param window the window to change.
|
|
|
1837 * \param w the width of the window, must be > 0.
|
|
|
1838 * \param h the height of the window, must be > 0.
|
|
|
1839 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1840 * information.
|
|
|
1841 *
|
|
|
1842 * \threadsafety This function should only be called on the main thread.
|
|
|
1843 *
|
|
|
1844 * \since This function is available since SDL 3.2.0.
|
|
|
1845 *
|
|
|
1846 * \sa SDL_GetWindowSize
|
|
|
1847 * \sa SDL_SetWindowFullscreenMode
|
|
|
1848 * \sa SDL_SyncWindow
|
|
|
1849 */
|
|
|
1850 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h);
|
|
|
1851
|
|
|
1852 /**
|
|
|
1853 * Get the size of a window's client area.
|
|
|
1854 *
|
|
|
1855 * The window pixel size may differ from its window coordinate size if the
|
|
|
1856 * window is on a high pixel density display. Use SDL_GetWindowSizeInPixels()
|
|
|
1857 * or SDL_GetRenderOutputSize() to get the real client area size in pixels.
|
|
|
1858 *
|
|
|
1859 * \param window the window to query the width and height from.
|
|
|
1860 * \param w a pointer filled in with the width of the window, may be NULL.
|
|
|
1861 * \param h a pointer filled in with the height of the window, may be NULL.
|
|
|
1862 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1863 * information.
|
|
|
1864 *
|
|
|
1865 * \threadsafety This function should only be called on the main thread.
|
|
|
1866 *
|
|
|
1867 * \since This function is available since SDL 3.2.0.
|
|
|
1868 *
|
|
|
1869 * \sa SDL_GetRenderOutputSize
|
|
|
1870 * \sa SDL_GetWindowSizeInPixels
|
|
|
1871 * \sa SDL_SetWindowSize
|
|
|
1872 * \sa SDL_EVENT_WINDOW_RESIZED
|
|
|
1873 */
|
|
|
1874 extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h);
|
|
|
1875
|
|
|
1876 /**
|
|
|
1877 * Get the safe area for this window.
|
|
|
1878 *
|
|
|
1879 * Some devices have portions of the screen which are partially obscured or
|
|
|
1880 * not interactive, possibly due to on-screen controls, curved edges, camera
|
|
|
1881 * notches, TV overscan, etc. This function provides the area of the window
|
|
|
1882 * which is safe to have interactable content. You should continue rendering
|
|
|
1883 * into the rest of the window, but it should not contain visually important
|
|
|
1884 * or interactable content.
|
|
|
1885 *
|
|
|
1886 * \param window the window to query.
|
|
|
1887 * \param rect a pointer filled in with the client area that is safe for
|
|
|
1888 * interactive content.
|
|
|
1889 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1890 * information.
|
|
|
1891 *
|
|
|
1892 * \threadsafety This function should only be called on the main thread.
|
|
|
1893 *
|
|
|
1894 * \since This function is available since SDL 3.2.0.
|
|
|
1895 */
|
|
|
1896 extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSafeArea(SDL_Window *window, SDL_Rect *rect);
|
|
|
1897
|
|
|
1898 /**
|
|
|
1899 * Request that the aspect ratio of a window's client area be set.
|
|
|
1900 *
|
|
|
1901 * The aspect ratio is the ratio of width divided by height, e.g. 2560x1600
|
|
|
1902 * would be 1.6. Larger aspect ratios are wider and smaller aspect ratios are
|
|
|
1903 * narrower.
|
|
|
1904 *
|
|
|
1905 * If, at the time of this request, the window in a fixed-size state, such as
|
|
|
1906 * maximized or fullscreen, the request will be deferred until the window
|
|
|
1907 * exits this state and becomes resizable again.
|
|
|
1908 *
|
|
|
1909 * On some windowing systems, this request is asynchronous and the new window
|
|
|
1910 * aspect ratio may not have have been applied immediately upon the return of
|
|
|
1911 * this function. If an immediate change is required, call SDL_SyncWindow() to
|
|
|
1912 * block until the changes have taken effect.
|
|
|
1913 *
|
|
|
1914 * When the window size changes, an SDL_EVENT_WINDOW_RESIZED event will be
|
|
|
1915 * emitted with the new window dimensions. Note that the new dimensions may
|
|
|
1916 * not match the exact aspect ratio requested, as some windowing systems can
|
|
|
1917 * restrict the window size in certain scenarios (e.g. constraining the size
|
|
|
1918 * of the content area to remain within the usable desktop bounds).
|
|
|
1919 * Additionally, as this is just a request, it can be denied by the windowing
|
|
|
1920 * system.
|
|
|
1921 *
|
|
|
1922 * \param window the window to change.
|
|
|
1923 * \param min_aspect the minimum aspect ratio of the window, or 0.0f for no
|
|
|
1924 * limit.
|
|
|
1925 * \param max_aspect the maximum aspect ratio of the window, or 0.0f for no
|
|
|
1926 * limit.
|
|
|
1927 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1928 * information.
|
|
|
1929 *
|
|
|
1930 * \threadsafety This function should only be called on the main thread.
|
|
|
1931 *
|
|
|
1932 * \since This function is available since SDL 3.2.0.
|
|
|
1933 *
|
|
|
1934 * \sa SDL_GetWindowAspectRatio
|
|
|
1935 * \sa SDL_SyncWindow
|
|
|
1936 */
|
|
|
1937 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAspectRatio(SDL_Window *window, float min_aspect, float max_aspect);
|
|
|
1938
|
|
|
1939 /**
|
|
|
1940 * Get the aspect ratio of a window's client area.
|
|
|
1941 *
|
|
|
1942 * \param window the window to query the width and height from.
|
|
|
1943 * \param min_aspect a pointer filled in with the minimum aspect ratio of the
|
|
|
1944 * window, may be NULL.
|
|
|
1945 * \param max_aspect a pointer filled in with the maximum aspect ratio of the
|
|
|
1946 * window, may be NULL.
|
|
|
1947 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1948 * information.
|
|
|
1949 *
|
|
|
1950 * \threadsafety This function should only be called on the main thread.
|
|
|
1951 *
|
|
|
1952 * \since This function is available since SDL 3.2.0.
|
|
|
1953 *
|
|
|
1954 * \sa SDL_SetWindowAspectRatio
|
|
|
1955 */
|
|
|
1956 extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window, float *min_aspect, float *max_aspect);
|
|
|
1957
|
|
|
1958 /**
|
|
|
1959 * Get the size of a window's borders (decorations) around the client area.
|
|
|
1960 *
|
|
|
1961 * Note: If this function fails (returns false), the size values will be
|
|
|
1962 * initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the
|
|
|
1963 * window in question was borderless.
|
|
|
1964 *
|
|
|
1965 * Note: This function may fail on systems where the window has not yet been
|
|
|
1966 * decorated by the display server (for example, immediately after calling
|
|
|
1967 * SDL_CreateWindow). It is recommended that you wait at least until the
|
|
|
1968 * window has been presented and composited, so that the window system has a
|
|
|
1969 * chance to decorate the window and provide the border dimensions to SDL.
|
|
|
1970 *
|
|
|
1971 * This function also returns false if getting the information is not
|
|
|
1972 * supported.
|
|
|
1973 *
|
|
|
1974 * \param window the window to query the size values of the border
|
|
|
1975 * (decorations) from.
|
|
|
1976 * \param top pointer to variable for storing the size of the top border; NULL
|
|
|
1977 * is permitted.
|
|
|
1978 * \param left pointer to variable for storing the size of the left border;
|
|
|
1979 * NULL is permitted.
|
|
|
1980 * \param bottom pointer to variable for storing the size of the bottom
|
|
|
1981 * border; NULL is permitted.
|
|
|
1982 * \param right pointer to variable for storing the size of the right border;
|
|
|
1983 * NULL is permitted.
|
|
|
1984 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
1985 * information.
|
|
|
1986 *
|
|
|
1987 * \threadsafety This function should only be called on the main thread.
|
|
|
1988 *
|
|
|
1989 * \since This function is available since SDL 3.2.0.
|
|
|
1990 *
|
|
|
1991 * \sa SDL_GetWindowSize
|
|
|
1992 */
|
|
|
1993 extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowBordersSize(SDL_Window *window, int *top, int *left, int *bottom, int *right);
|
|
|
1994
|
|
|
1995 /**
|
|
|
1996 * Get the size of a window's client area, in pixels.
|
|
|
1997 *
|
|
|
1998 * \param window the window from which the drawable size should be queried.
|
|
|
1999 * \param w a pointer to variable for storing the width in pixels, may be
|
|
|
2000 * NULL.
|
|
|
2001 * \param h a pointer to variable for storing the height in pixels, may be
|
|
|
2002 * NULL.
|
|
|
2003 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2004 * information.
|
|
|
2005 *
|
|
|
2006 * \threadsafety This function should only be called on the main thread.
|
|
|
2007 *
|
|
|
2008 * \since This function is available since SDL 3.2.0.
|
|
|
2009 *
|
|
|
2010 * \sa SDL_CreateWindow
|
|
|
2011 * \sa SDL_GetWindowSize
|
|
|
2012 */
|
|
|
2013 extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSizeInPixels(SDL_Window *window, int *w, int *h);
|
|
|
2014
|
|
|
2015 /**
|
|
|
2016 * Set the minimum size of a window's client area.
|
|
|
2017 *
|
|
|
2018 * \param window the window to change.
|
|
|
2019 * \param min_w the minimum width of the window, or 0 for no limit.
|
|
|
2020 * \param min_h the minimum height of the window, or 0 for no limit.
|
|
|
2021 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2022 * information.
|
|
|
2023 *
|
|
|
2024 * \threadsafety This function should only be called on the main thread.
|
|
|
2025 *
|
|
|
2026 * \since This function is available since SDL 3.2.0.
|
|
|
2027 *
|
|
|
2028 * \sa SDL_GetWindowMinimumSize
|
|
|
2029 * \sa SDL_SetWindowMaximumSize
|
|
|
2030 */
|
|
|
2031 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMinimumSize(SDL_Window *window, int min_w, int min_h);
|
|
|
2032
|
|
|
2033 /**
|
|
|
2034 * Get the minimum size of a window's client area.
|
|
|
2035 *
|
|
|
2036 * \param window the window to query.
|
|
|
2037 * \param w a pointer filled in with the minimum width of the window, may be
|
|
|
2038 * NULL.
|
|
|
2039 * \param h a pointer filled in with the minimum height of the window, may be
|
|
|
2040 * NULL.
|
|
|
2041 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2042 * information.
|
|
|
2043 *
|
|
|
2044 * \threadsafety This function should only be called on the main thread.
|
|
|
2045 *
|
|
|
2046 * \since This function is available since SDL 3.2.0.
|
|
|
2047 *
|
|
|
2048 * \sa SDL_GetWindowMaximumSize
|
|
|
2049 * \sa SDL_SetWindowMinimumSize
|
|
|
2050 */
|
|
|
2051 extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMinimumSize(SDL_Window *window, int *w, int *h);
|
|
|
2052
|
|
|
2053 /**
|
|
|
2054 * Set the maximum size of a window's client area.
|
|
|
2055 *
|
|
|
2056 * \param window the window to change.
|
|
|
2057 * \param max_w the maximum width of the window, or 0 for no limit.
|
|
|
2058 * \param max_h the maximum height of the window, or 0 for no limit.
|
|
|
2059 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2060 * information.
|
|
|
2061 *
|
|
|
2062 * \threadsafety This function should only be called on the main thread.
|
|
|
2063 *
|
|
|
2064 * \since This function is available since SDL 3.2.0.
|
|
|
2065 *
|
|
|
2066 * \sa SDL_GetWindowMaximumSize
|
|
|
2067 * \sa SDL_SetWindowMinimumSize
|
|
|
2068 */
|
|
|
2069 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMaximumSize(SDL_Window *window, int max_w, int max_h);
|
|
|
2070
|
|
|
2071 /**
|
|
|
2072 * Get the maximum size of a window's client area.
|
|
|
2073 *
|
|
|
2074 * \param window the window to query.
|
|
|
2075 * \param w a pointer filled in with the maximum width of the window, may be
|
|
|
2076 * NULL.
|
|
|
2077 * \param h a pointer filled in with the maximum height of the window, may be
|
|
|
2078 * NULL.
|
|
|
2079 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2080 * information.
|
|
|
2081 *
|
|
|
2082 * \threadsafety This function should only be called on the main thread.
|
|
|
2083 *
|
|
|
2084 * \since This function is available since SDL 3.2.0.
|
|
|
2085 *
|
|
|
2086 * \sa SDL_GetWindowMinimumSize
|
|
|
2087 * \sa SDL_SetWindowMaximumSize
|
|
|
2088 */
|
|
|
2089 extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMaximumSize(SDL_Window *window, int *w, int *h);
|
|
|
2090
|
|
|
2091 /**
|
|
|
2092 * Set the border state of a window.
|
|
|
2093 *
|
|
|
2094 * This will add or remove the window's `SDL_WINDOW_BORDERLESS` flag and add
|
|
|
2095 * or remove the border from the actual window. This is a no-op if the
|
|
|
2096 * window's border already matches the requested state.
|
|
|
2097 *
|
|
|
2098 * You can't change the border state of a fullscreen window.
|
|
|
2099 *
|
|
|
2100 * \param window the window of which to change the border state.
|
|
|
2101 * \param bordered false to remove border, true to add border.
|
|
|
2102 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2103 * information.
|
|
|
2104 *
|
|
|
2105 * \threadsafety This function should only be called on the main thread.
|
|
|
2106 *
|
|
|
2107 * \since This function is available since SDL 3.2.0.
|
|
|
2108 *
|
|
|
2109 * \sa SDL_GetWindowFlags
|
|
|
2110 */
|
|
|
2111 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowBordered(SDL_Window *window, bool bordered);
|
|
|
2112
|
|
|
2113 /**
|
|
|
2114 * Set the user-resizable state of a window.
|
|
|
2115 *
|
|
|
2116 * This will add or remove the window's `SDL_WINDOW_RESIZABLE` flag and
|
|
|
2117 * allow/disallow user resizing of the window. This is a no-op if the window's
|
|
|
2118 * resizable state already matches the requested state.
|
|
|
2119 *
|
|
|
2120 * You can't change the resizable state of a fullscreen window.
|
|
|
2121 *
|
|
|
2122 * \param window the window of which to change the resizable state.
|
|
|
2123 * \param resizable true to allow resizing, false to disallow.
|
|
|
2124 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2125 * information.
|
|
|
2126 *
|
|
|
2127 * \threadsafety This function should only be called on the main thread.
|
|
|
2128 *
|
|
|
2129 * \since This function is available since SDL 3.2.0.
|
|
|
2130 *
|
|
|
2131 * \sa SDL_GetWindowFlags
|
|
|
2132 */
|
|
|
2133 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowResizable(SDL_Window *window, bool resizable);
|
|
|
2134
|
|
|
2135 /**
|
|
|
2136 * Set the window to always be above the others.
|
|
|
2137 *
|
|
|
2138 * This will add or remove the window's `SDL_WINDOW_ALWAYS_ON_TOP` flag. This
|
|
|
2139 * will bring the window to the front and keep the window above the rest.
|
|
|
2140 *
|
|
|
2141 * \param window the window of which to change the always on top state.
|
|
|
2142 * \param on_top true to set the window always on top, false to disable.
|
|
|
2143 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2144 * information.
|
|
|
2145 *
|
|
|
2146 * \threadsafety This function should only be called on the main thread.
|
|
|
2147 *
|
|
|
2148 * \since This function is available since SDL 3.2.0.
|
|
|
2149 *
|
|
|
2150 * \sa SDL_GetWindowFlags
|
|
|
2151 */
|
|
|
2152 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window *window, bool on_top);
|
|
|
2153
|
|
|
2154 /**
|
|
|
2155 * Set the window to fill the current document space (Emscripten only).
|
|
|
2156 *
|
|
|
2157 * This will add or remove the window's `SDL_WINDOW_FILL_DOCUMENT` flag.
|
|
|
2158 *
|
|
|
2159 * Currently this flag only applies to the Emscripten target.
|
|
|
2160 *
|
|
|
2161 * When enabled, the canvas element fills the entire document. Resize events
|
|
|
2162 * will be generated as the browser window is resized, as that will adjust the
|
|
|
2163 * canvas size as well. The canvas will cover anything else on the page,
|
|
|
2164 * including any controls provided by Emscripten in its generated HTML file
|
|
|
2165 * (in fact, any elements on the page that aren't the canvas will be moved
|
|
|
2166 * into a hidden `div` element).
|
|
|
2167 *
|
|
|
2168 * Often times this is desirable for a browser-based game, but it means
|
|
|
2169 * several things that we expect of an SDL window on other platforms might not
|
|
|
2170 * work as expected, such as minimum window sizes and aspect ratios.
|
|
|
2171 *
|
|
|
2172 * \param window the window of which to change the fill-document state.
|
|
|
2173 * \param fill true to set the window to fill the document, false to disable.
|
|
|
2174 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2175 * information.
|
|
|
2176 *
|
|
|
2177 * \threadsafety This function should only be called on the main thread.
|
|
|
2178 *
|
|
|
2179 * \since This function is available since SDL 3.4.0.
|
|
|
2180 *
|
|
|
2181 * \sa SDL_GetWindowFlags
|
|
|
2182 */
|
|
|
2183 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFillDocument(SDL_Window *window, bool fill);
|
|
|
2184
|
|
|
2185 /**
|
|
|
2186 * Show a window.
|
|
|
2187 *
|
|
|
2188 * \param window the window to show.
|
|
|
2189 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2190 * information.
|
|
|
2191 *
|
|
|
2192 * \threadsafety This function should only be called on the main thread.
|
|
|
2193 *
|
|
|
2194 * \since This function is available since SDL 3.2.0.
|
|
|
2195 *
|
|
|
2196 * \sa SDL_HideWindow
|
|
|
2197 * \sa SDL_RaiseWindow
|
|
|
2198 */
|
|
|
2199 extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindow(SDL_Window *window);
|
|
|
2200
|
|
|
2201 /**
|
|
|
2202 * Hide a window.
|
|
|
2203 *
|
|
|
2204 * \param window the window to hide.
|
|
|
2205 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2206 * information.
|
|
|
2207 *
|
|
|
2208 * \threadsafety This function should only be called on the main thread.
|
|
|
2209 *
|
|
|
2210 * \since This function is available since SDL 3.2.0.
|
|
|
2211 *
|
|
|
2212 * \sa SDL_ShowWindow
|
|
|
2213 * \sa SDL_WINDOW_HIDDEN
|
|
|
2214 */
|
|
|
2215 extern SDL_DECLSPEC bool SDLCALL SDL_HideWindow(SDL_Window *window);
|
|
|
2216
|
|
|
2217 /**
|
|
|
2218 * Request that a window be raised above other windows and gain the input
|
|
|
2219 * focus.
|
|
|
2220 *
|
|
|
2221 * The result of this request is subject to desktop window manager policy,
|
|
|
2222 * particularly if raising the requested window would result in stealing focus
|
|
|
2223 * from another application. If the window is successfully raised and gains
|
|
|
2224 * input focus, an SDL_EVENT_WINDOW_FOCUS_GAINED event will be emitted, and
|
|
|
2225 * the window will have the SDL_WINDOW_INPUT_FOCUS flag set.
|
|
|
2226 *
|
|
|
2227 * \param window the window to raise.
|
|
|
2228 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2229 * information.
|
|
|
2230 *
|
|
|
2231 * \threadsafety This function should only be called on the main thread.
|
|
|
2232 *
|
|
|
2233 * \since This function is available since SDL 3.2.0.
|
|
|
2234 */
|
|
|
2235 extern SDL_DECLSPEC bool SDLCALL SDL_RaiseWindow(SDL_Window *window);
|
|
|
2236
|
|
|
2237 /**
|
|
|
2238 * Request that the window be made as large as possible.
|
|
|
2239 *
|
|
|
2240 * Non-resizable windows can't be maximized. The window must have the
|
|
|
2241 * SDL_WINDOW_RESIZABLE flag set, or this will have no effect.
|
|
|
2242 *
|
|
|
2243 * On some windowing systems this request is asynchronous and the new window
|
|
|
2244 * state may not have have been applied immediately upon the return of this
|
|
|
2245 * function. If an immediate change is required, call SDL_SyncWindow() to
|
|
|
2246 * block until the changes have taken effect.
|
|
|
2247 *
|
|
|
2248 * When the window state changes, an SDL_EVENT_WINDOW_MAXIMIZED event will be
|
|
|
2249 * emitted. Note that, as this is just a request, the windowing system can
|
|
|
2250 * deny the state change.
|
|
|
2251 *
|
|
|
2252 * When maximizing a window, whether the constraints set via
|
|
|
2253 * SDL_SetWindowMaximumSize() are honored depends on the policy of the window
|
|
|
2254 * manager. Win32 and macOS enforce the constraints when maximizing, while X11
|
|
|
2255 * and Wayland window managers may vary.
|
|
|
2256 *
|
|
|
2257 * \param window the window to maximize.
|
|
|
2258 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2259 * information.
|
|
|
2260 *
|
|
|
2261 * \threadsafety This function should only be called on the main thread.
|
|
|
2262 *
|
|
|
2263 * \since This function is available since SDL 3.2.0.
|
|
|
2264 *
|
|
|
2265 * \sa SDL_MinimizeWindow
|
|
|
2266 * \sa SDL_RestoreWindow
|
|
|
2267 * \sa SDL_SyncWindow
|
|
|
2268 */
|
|
|
2269 extern SDL_DECLSPEC bool SDLCALL SDL_MaximizeWindow(SDL_Window *window);
|
|
|
2270
|
|
|
2271 /**
|
|
|
2272 * Request that the window be minimized to an iconic representation.
|
|
|
2273 *
|
|
|
2274 * If the window is in a fullscreen state, this request has no direct effect.
|
|
|
2275 * It may alter the state the window is returned to when leaving fullscreen.
|
|
|
2276 *
|
|
|
2277 * On some windowing systems this request is asynchronous and the new window
|
|
|
2278 * state may not have been applied immediately upon the return of this
|
|
|
2279 * function. If an immediate change is required, call SDL_SyncWindow() to
|
|
|
2280 * block until the changes have taken effect.
|
|
|
2281 *
|
|
|
2282 * When the window state changes, an SDL_EVENT_WINDOW_MINIMIZED event will be
|
|
|
2283 * emitted. Note that, as this is just a request, the windowing system can
|
|
|
2284 * deny the state change.
|
|
|
2285 *
|
|
|
2286 * \param window the window to minimize.
|
|
|
2287 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2288 * information.
|
|
|
2289 *
|
|
|
2290 * \threadsafety This function should only be called on the main thread.
|
|
|
2291 *
|
|
|
2292 * \since This function is available since SDL 3.2.0.
|
|
|
2293 *
|
|
|
2294 * \sa SDL_MaximizeWindow
|
|
|
2295 * \sa SDL_RestoreWindow
|
|
|
2296 * \sa SDL_SyncWindow
|
|
|
2297 */
|
|
|
2298 extern SDL_DECLSPEC bool SDLCALL SDL_MinimizeWindow(SDL_Window *window);
|
|
|
2299
|
|
|
2300 /**
|
|
|
2301 * Request that the size and position of a minimized or maximized window be
|
|
|
2302 * restored.
|
|
|
2303 *
|
|
|
2304 * If the window is in a fullscreen state, this request has no direct effect.
|
|
|
2305 * It may alter the state the window is returned to when leaving fullscreen.
|
|
|
2306 *
|
|
|
2307 * On some windowing systems this request is asynchronous and the new window
|
|
|
2308 * state may not have have been applied immediately upon the return of this
|
|
|
2309 * function. If an immediate change is required, call SDL_SyncWindow() to
|
|
|
2310 * block until the changes have taken effect.
|
|
|
2311 *
|
|
|
2312 * When the window state changes, an SDL_EVENT_WINDOW_RESTORED event will be
|
|
|
2313 * emitted. Note that, as this is just a request, the windowing system can
|
|
|
2314 * deny the state change.
|
|
|
2315 *
|
|
|
2316 * \param window the window to restore.
|
|
|
2317 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2318 * information.
|
|
|
2319 *
|
|
|
2320 * \threadsafety This function should only be called on the main thread.
|
|
|
2321 *
|
|
|
2322 * \since This function is available since SDL 3.2.0.
|
|
|
2323 *
|
|
|
2324 * \sa SDL_MaximizeWindow
|
|
|
2325 * \sa SDL_MinimizeWindow
|
|
|
2326 * \sa SDL_SyncWindow
|
|
|
2327 */
|
|
|
2328 extern SDL_DECLSPEC bool SDLCALL SDL_RestoreWindow(SDL_Window *window);
|
|
|
2329
|
|
|
2330 /**
|
|
|
2331 * Request that the window's fullscreen state be changed.
|
|
|
2332 *
|
|
|
2333 * By default a window in fullscreen state uses borderless fullscreen desktop
|
|
|
2334 * mode, but a specific exclusive display mode can be set using
|
|
|
2335 * SDL_SetWindowFullscreenMode().
|
|
|
2336 *
|
|
|
2337 * On some windowing systems this request is asynchronous and the new
|
|
|
2338 * fullscreen state may not have have been applied immediately upon the return
|
|
|
2339 * of this function. If an immediate change is required, call SDL_SyncWindow()
|
|
|
2340 * to block until the changes have taken effect.
|
|
|
2341 *
|
|
|
2342 * When the window state changes, an SDL_EVENT_WINDOW_ENTER_FULLSCREEN or
|
|
|
2343 * SDL_EVENT_WINDOW_LEAVE_FULLSCREEN event will be emitted. Note that, as this
|
|
|
2344 * is just a request, it can be denied by the windowing system.
|
|
|
2345 *
|
|
|
2346 * \param window the window to change.
|
|
|
2347 * \param fullscreen true for fullscreen mode, false for windowed mode.
|
|
|
2348 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2349 * information.
|
|
|
2350 *
|
|
|
2351 * \threadsafety This function should only be called on the main thread.
|
|
|
2352 *
|
|
|
2353 * \since This function is available since SDL 3.2.0.
|
|
|
2354 *
|
|
|
2355 * \sa SDL_GetWindowFullscreenMode
|
|
|
2356 * \sa SDL_SetWindowFullscreenMode
|
|
|
2357 * \sa SDL_SyncWindow
|
|
|
2358 * \sa SDL_WINDOW_FULLSCREEN
|
|
|
2359 */
|
|
|
2360 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, bool fullscreen);
|
|
|
2361
|
|
|
2362 /**
|
|
|
2363 * Block until any pending window state is finalized.
|
|
|
2364 *
|
|
|
2365 * On asynchronous windowing systems, this acts as a synchronization barrier
|
|
|
2366 * for pending window state. It will attempt to wait until any pending window
|
|
|
2367 * state has been applied and is guaranteed to return within finite time. Note
|
|
|
2368 * that for how long it can potentially block depends on the underlying window
|
|
|
2369 * system, as window state changes may involve somewhat lengthy animations
|
|
|
2370 * that must complete before the window is in its final requested state.
|
|
|
2371 *
|
|
|
2372 * On windowing systems where changes are immediate, this does nothing.
|
|
|
2373 *
|
|
|
2374 * \param window the window for which to wait for the pending state to be
|
|
|
2375 * applied.
|
|
|
2376 * \returns true on success or false if the operation timed out before the
|
|
|
2377 * window was in the requested state.
|
|
|
2378 *
|
|
|
2379 * \threadsafety This function should only be called on the main thread.
|
|
|
2380 *
|
|
|
2381 * \since This function is available since SDL 3.2.0.
|
|
|
2382 *
|
|
|
2383 * \sa SDL_SetWindowSize
|
|
|
2384 * \sa SDL_SetWindowPosition
|
|
|
2385 * \sa SDL_SetWindowFullscreen
|
|
|
2386 * \sa SDL_MinimizeWindow
|
|
|
2387 * \sa SDL_MaximizeWindow
|
|
|
2388 * \sa SDL_RestoreWindow
|
|
|
2389 * \sa SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS
|
|
|
2390 */
|
|
|
2391 extern SDL_DECLSPEC bool SDLCALL SDL_SyncWindow(SDL_Window *window);
|
|
|
2392
|
|
|
2393 /**
|
|
|
2394 * Return whether the window has a surface associated with it.
|
|
|
2395 *
|
|
|
2396 * \param window the window to query.
|
|
|
2397 * \returns true if there is a surface associated with the window, or false
|
|
|
2398 * otherwise.
|
|
|
2399 *
|
|
|
2400 * \threadsafety This function should only be called on the main thread.
|
|
|
2401 *
|
|
|
2402 * \since This function is available since SDL 3.2.0.
|
|
|
2403 *
|
|
|
2404 * \sa SDL_GetWindowSurface
|
|
|
2405 */
|
|
|
2406 extern SDL_DECLSPEC bool SDLCALL SDL_WindowHasSurface(SDL_Window *window);
|
|
|
2407
|
|
|
2408 /**
|
|
|
2409 * Get the SDL surface associated with the window.
|
|
|
2410 *
|
|
|
2411 * A new surface will be created with the optimal format for the window, if
|
|
|
2412 * necessary. This surface will be freed when the window is destroyed. Do not
|
|
|
2413 * free this surface.
|
|
|
2414 *
|
|
|
2415 * This surface will be invalidated if the window is resized. After resizing a
|
|
|
2416 * window this function must be called again to return a valid surface.
|
|
|
2417 *
|
|
|
2418 * You may not combine this with 3D or the rendering API on this window.
|
|
|
2419 *
|
|
|
2420 * This function is affected by `SDL_HINT_FRAMEBUFFER_ACCELERATION`.
|
|
|
2421 *
|
|
|
2422 * \param window the window to query.
|
|
|
2423 * \returns the surface associated with the window, or NULL on failure; call
|
|
|
2424 * SDL_GetError() for more information.
|
|
|
2425 *
|
|
|
2426 * \threadsafety This function should only be called on the main thread.
|
|
|
2427 *
|
|
|
2428 * \since This function is available since SDL 3.2.0.
|
|
|
2429 *
|
|
|
2430 * \sa SDL_DestroyWindowSurface
|
|
|
2431 * \sa SDL_WindowHasSurface
|
|
|
2432 * \sa SDL_UpdateWindowSurface
|
|
|
2433 * \sa SDL_UpdateWindowSurfaceRects
|
|
|
2434 */
|
|
|
2435 extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window *window);
|
|
|
2436
|
|
|
2437 /**
|
|
|
2438 * Toggle VSync for the window surface.
|
|
|
2439 *
|
|
|
2440 * When a window surface is created, vsync defaults to
|
|
|
2441 * SDL_WINDOW_SURFACE_VSYNC_DISABLED.
|
|
|
2442 *
|
|
|
2443 * The `vsync` parameter can be 1 to synchronize present with every vertical
|
|
|
2444 * refresh, 2 to synchronize present with every second vertical refresh, etc.,
|
|
|
2445 * SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE for late swap tearing (adaptive vsync),
|
|
|
2446 * or SDL_WINDOW_SURFACE_VSYNC_DISABLED to disable. Not every value is
|
|
|
2447 * supported by every driver, so you should check the return value to see
|
|
|
2448 * whether the requested setting is supported.
|
|
|
2449 *
|
|
|
2450 * \param window the window.
|
|
|
2451 * \param vsync the vertical refresh sync interval.
|
|
|
2452 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2453 * information.
|
|
|
2454 *
|
|
|
2455 * \threadsafety This function should only be called on the main thread.
|
|
|
2456 *
|
|
|
2457 * \since This function is available since SDL 3.2.0.
|
|
|
2458 *
|
|
|
2459 * \sa SDL_GetWindowSurfaceVSync
|
|
|
2460 */
|
|
|
2461 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowSurfaceVSync(SDL_Window *window, int vsync);
|
|
|
2462
|
|
|
2463 #define SDL_WINDOW_SURFACE_VSYNC_DISABLED 0
|
|
|
2464 #define SDL_WINDOW_SURFACE_VSYNC_ADAPTIVE (-1)
|
|
|
2465
|
|
|
2466 /**
|
|
|
2467 * Get VSync for the window surface.
|
|
|
2468 *
|
|
|
2469 * \param window the window to query.
|
|
|
2470 * \param vsync an int filled with the current vertical refresh sync interval.
|
|
|
2471 * See SDL_SetWindowSurfaceVSync() for the meaning of the value.
|
|
|
2472 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2473 * information.
|
|
|
2474 *
|
|
|
2475 * \threadsafety This function should only be called on the main thread.
|
|
|
2476 *
|
|
|
2477 * \since This function is available since SDL 3.2.0.
|
|
|
2478 *
|
|
|
2479 * \sa SDL_SetWindowSurfaceVSync
|
|
|
2480 */
|
|
|
2481 extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSurfaceVSync(SDL_Window *window, int *vsync);
|
|
|
2482
|
|
|
2483 /**
|
|
|
2484 * Copy the window surface to the screen.
|
|
|
2485 *
|
|
|
2486 * This is the function you use to reflect any changes to the surface on the
|
|
|
2487 * screen.
|
|
|
2488 *
|
|
|
2489 * This function is equivalent to the SDL 1.2 API SDL_Flip().
|
|
|
2490 *
|
|
|
2491 * \param window the window to update.
|
|
|
2492 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2493 * information.
|
|
|
2494 *
|
|
|
2495 * \threadsafety This function should only be called on the main thread.
|
|
|
2496 *
|
|
|
2497 * \since This function is available since SDL 3.2.0.
|
|
|
2498 *
|
|
|
2499 * \sa SDL_GetWindowSurface
|
|
|
2500 * \sa SDL_UpdateWindowSurfaceRects
|
|
|
2501 */
|
|
|
2502 extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurface(SDL_Window *window);
|
|
|
2503
|
|
|
2504 /**
|
|
|
2505 * Copy areas of the window surface to the screen.
|
|
|
2506 *
|
|
|
2507 * This is the function you use to reflect changes to portions of the surface
|
|
|
2508 * on the screen.
|
|
|
2509 *
|
|
|
2510 * This function is equivalent to the SDL 1.2 API SDL_UpdateRects().
|
|
|
2511 *
|
|
|
2512 * Note that this function will update _at least_ the rectangles specified,
|
|
|
2513 * but this is only intended as an optimization; in practice, this might
|
|
|
2514 * update more of the screen (or all of the screen!), depending on what method
|
|
|
2515 * SDL uses to send pixels to the system.
|
|
|
2516 *
|
|
|
2517 * \param window the window to update.
|
|
|
2518 * \param rects an array of SDL_Rect structures representing areas of the
|
|
|
2519 * surface to copy, in pixels.
|
|
|
2520 * \param numrects the number of rectangles.
|
|
|
2521 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2522 * information.
|
|
|
2523 *
|
|
|
2524 * \threadsafety This function should only be called on the main thread.
|
|
|
2525 *
|
|
|
2526 * \since This function is available since SDL 3.2.0.
|
|
|
2527 *
|
|
|
2528 * \sa SDL_GetWindowSurface
|
|
|
2529 * \sa SDL_UpdateWindowSurface
|
|
|
2530 */
|
|
|
2531 extern SDL_DECLSPEC bool SDLCALL SDL_UpdateWindowSurfaceRects(SDL_Window *window, const SDL_Rect *rects, int numrects);
|
|
|
2532
|
|
|
2533 /**
|
|
|
2534 * Destroy the surface associated with the window.
|
|
|
2535 *
|
|
|
2536 * \param window the window to update.
|
|
|
2537 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2538 * information.
|
|
|
2539 *
|
|
|
2540 * \threadsafety This function should only be called on the main thread.
|
|
|
2541 *
|
|
|
2542 * \since This function is available since SDL 3.2.0.
|
|
|
2543 *
|
|
|
2544 * \sa SDL_GetWindowSurface
|
|
|
2545 * \sa SDL_WindowHasSurface
|
|
|
2546 */
|
|
|
2547 extern SDL_DECLSPEC bool SDLCALL SDL_DestroyWindowSurface(SDL_Window *window);
|
|
|
2548
|
|
|
2549 /**
|
|
|
2550 * Set a window's keyboard grab mode.
|
|
|
2551 *
|
|
|
2552 * Keyboard grab enables capture of system keyboard shortcuts like Alt+Tab or
|
|
|
2553 * the Meta/Super key. Note that not all system keyboard shortcuts can be
|
|
|
2554 * captured by applications (one example is Ctrl+Alt+Del on Windows).
|
|
|
2555 *
|
|
|
2556 * This is primarily intended for specialized applications such as VNC clients
|
|
|
2557 * or VM frontends. Normal games should not use keyboard grab.
|
|
|
2558 *
|
|
|
2559 * When keyboard grab is enabled, SDL will continue to handle Alt+Tab when the
|
|
|
2560 * window is full-screen to ensure the user is not trapped in your
|
|
|
2561 * application. If you have a custom keyboard shortcut to exit fullscreen
|
|
|
2562 * mode, you may suppress this behavior with
|
|
|
2563 * `SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED`.
|
|
|
2564 *
|
|
|
2565 * If the caller enables a grab while another window is currently grabbed, the
|
|
|
2566 * other window loses its grab in favor of the caller's window.
|
|
|
2567 *
|
|
|
2568 * \param window the window for which the keyboard grab mode should be set.
|
|
|
2569 * \param grabbed this is true to grab keyboard, and false to release.
|
|
|
2570 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2571 * information.
|
|
|
2572 *
|
|
|
2573 * \threadsafety This function should only be called on the main thread.
|
|
|
2574 *
|
|
|
2575 * \since This function is available since SDL 3.2.0.
|
|
|
2576 *
|
|
|
2577 * \sa SDL_GetWindowKeyboardGrab
|
|
|
2578 * \sa SDL_SetWindowMouseGrab
|
|
|
2579 */
|
|
|
2580 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowKeyboardGrab(SDL_Window *window, bool grabbed);
|
|
|
2581
|
|
|
2582 /**
|
|
|
2583 * Set a window's mouse grab mode.
|
|
|
2584 *
|
|
|
2585 * Mouse grab confines the mouse cursor to the window.
|
|
|
2586 *
|
|
|
2587 * \param window the window for which the mouse grab mode should be set.
|
|
|
2588 * \param grabbed this is true to grab mouse, and false to release.
|
|
|
2589 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2590 * information.
|
|
|
2591 *
|
|
|
2592 * \threadsafety This function should only be called on the main thread.
|
|
|
2593 *
|
|
|
2594 * \since This function is available since SDL 3.2.0.
|
|
|
2595 *
|
|
|
2596 * \sa SDL_GetWindowMouseRect
|
|
|
2597 * \sa SDL_SetWindowMouseRect
|
|
|
2598 * \sa SDL_SetWindowKeyboardGrab
|
|
|
2599 */
|
|
|
2600 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseGrab(SDL_Window *window, bool grabbed);
|
|
|
2601
|
|
|
2602 /**
|
|
|
2603 * Get a window's keyboard grab mode.
|
|
|
2604 *
|
|
|
2605 * \param window the window to query.
|
|
|
2606 * \returns true if keyboard is grabbed, and false otherwise.
|
|
|
2607 *
|
|
|
2608 * \threadsafety This function should only be called on the main thread.
|
|
|
2609 *
|
|
|
2610 * \since This function is available since SDL 3.2.0.
|
|
|
2611 *
|
|
|
2612 * \sa SDL_SetWindowKeyboardGrab
|
|
|
2613 */
|
|
|
2614 extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window *window);
|
|
|
2615
|
|
|
2616 /**
|
|
|
2617 * Get a window's mouse grab mode.
|
|
|
2618 *
|
|
|
2619 * \param window the window to query.
|
|
|
2620 * \returns true if mouse is grabbed, and false otherwise.
|
|
|
2621 *
|
|
|
2622 * \threadsafety This function should only be called on the main thread.
|
|
|
2623 *
|
|
|
2624 * \since This function is available since SDL 3.2.0.
|
|
|
2625 *
|
|
|
2626 * \sa SDL_GetWindowMouseRect
|
|
|
2627 * \sa SDL_SetWindowMouseRect
|
|
|
2628 * \sa SDL_SetWindowMouseGrab
|
|
|
2629 * \sa SDL_SetWindowKeyboardGrab
|
|
|
2630 */
|
|
|
2631 extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowMouseGrab(SDL_Window *window);
|
|
|
2632
|
|
|
2633 /**
|
|
|
2634 * Get the window that currently has an input grab enabled.
|
|
|
2635 *
|
|
|
2636 * \returns the window if input is grabbed or NULL otherwise.
|
|
|
2637 *
|
|
|
2638 * \threadsafety This function should only be called on the main thread.
|
|
|
2639 *
|
|
|
2640 * \since This function is available since SDL 3.2.0.
|
|
|
2641 *
|
|
|
2642 * \sa SDL_SetWindowMouseGrab
|
|
|
2643 * \sa SDL_SetWindowKeyboardGrab
|
|
|
2644 */
|
|
|
2645 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetGrabbedWindow(void);
|
|
|
2646
|
|
|
2647 /**
|
|
|
2648 * Confines the cursor to the specified area of a window.
|
|
|
2649 *
|
|
|
2650 * Note that this does NOT grab the cursor, it only defines the area a cursor
|
|
|
2651 * is restricted to when the window has mouse focus.
|
|
|
2652 *
|
|
|
2653 * \param window the window that will be associated with the barrier.
|
|
|
2654 * \param rect a rectangle area in window-relative coordinates. If NULL the
|
|
|
2655 * barrier for the specified window will be destroyed.
|
|
|
2656 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2657 * information.
|
|
|
2658 *
|
|
|
2659 * \threadsafety This function should only be called on the main thread.
|
|
|
2660 *
|
|
|
2661 * \since This function is available since SDL 3.2.0.
|
|
|
2662 *
|
|
|
2663 * \sa SDL_GetWindowMouseRect
|
|
|
2664 * \sa SDL_GetWindowMouseGrab
|
|
|
2665 * \sa SDL_SetWindowMouseGrab
|
|
|
2666 */
|
|
|
2667 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const SDL_Rect *rect);
|
|
|
2668
|
|
|
2669 /**
|
|
|
2670 * Get the mouse confinement rectangle of a window.
|
|
|
2671 *
|
|
|
2672 * \param window the window to query.
|
|
|
2673 * \returns a pointer to the mouse confinement rectangle of a window, or NULL
|
|
|
2674 * if there isn't one.
|
|
|
2675 *
|
|
|
2676 * \threadsafety This function should only be called on the main thread.
|
|
|
2677 *
|
|
|
2678 * \since This function is available since SDL 3.2.0.
|
|
|
2679 *
|
|
|
2680 * \sa SDL_SetWindowMouseRect
|
|
|
2681 * \sa SDL_GetWindowMouseGrab
|
|
|
2682 * \sa SDL_SetWindowMouseGrab
|
|
|
2683 */
|
|
|
2684 extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window *window);
|
|
|
2685
|
|
|
2686 /**
|
|
|
2687 * Set the opacity for a window.
|
|
|
2688 *
|
|
|
2689 * The parameter `opacity` will be clamped internally between 0.0f
|
|
|
2690 * (transparent) and 1.0f (opaque).
|
|
|
2691 *
|
|
|
2692 * This function also returns false if setting the opacity isn't supported.
|
|
|
2693 *
|
|
|
2694 * \param window the window which will be made transparent or opaque.
|
|
|
2695 * \param opacity the opacity value (0.0f - transparent, 1.0f - opaque).
|
|
|
2696 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2697 * information.
|
|
|
2698 *
|
|
|
2699 * \threadsafety This function should only be called on the main thread.
|
|
|
2700 *
|
|
|
2701 * \since This function is available since SDL 3.2.0.
|
|
|
2702 *
|
|
|
2703 * \sa SDL_GetWindowOpacity
|
|
|
2704 */
|
|
|
2705 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opacity);
|
|
|
2706
|
|
|
2707 /**
|
|
|
2708 * Get the opacity of a window.
|
|
|
2709 *
|
|
|
2710 * If transparency isn't supported on this platform, opacity will be returned
|
|
|
2711 * as 1.0f without error.
|
|
|
2712 *
|
|
|
2713 * \param window the window to get the current opacity value from.
|
|
|
2714 * \returns the opacity, (0.0f - transparent, 1.0f - opaque), or -1.0f on
|
|
|
2715 * failure; call SDL_GetError() for more information.
|
|
|
2716 *
|
|
|
2717 * \threadsafety This function should only be called on the main thread.
|
|
|
2718 *
|
|
|
2719 * \since This function is available since SDL 3.2.0.
|
|
|
2720 *
|
|
|
2721 * \sa SDL_SetWindowOpacity
|
|
|
2722 */
|
|
|
2723 extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *window);
|
|
|
2724
|
|
|
2725 /**
|
|
|
2726 * Set the window as a child of a parent window.
|
|
|
2727 *
|
|
|
2728 * If the window is already the child of an existing window, it will be
|
|
|
2729 * reparented to the new owner. Setting the parent window to NULL unparents
|
|
|
2730 * the window and removes child window status.
|
|
|
2731 *
|
|
|
2732 * If a parent window is hidden or destroyed, the operation will be
|
|
|
2733 * recursively applied to child windows. Child windows hidden with the parent
|
|
|
2734 * that did not have their hidden status explicitly set will be restored when
|
|
|
2735 * the parent is shown.
|
|
|
2736 *
|
|
|
2737 * Attempting to set the parent of a window that is currently in the modal
|
|
|
2738 * state will fail. Use SDL_SetWindowModal() to cancel the modal status before
|
|
|
2739 * attempting to change the parent.
|
|
|
2740 *
|
|
|
2741 * Popup windows cannot change parents and attempts to do so will fail.
|
|
|
2742 *
|
|
|
2743 * Setting a parent window that is currently the sibling or descendent of the
|
|
|
2744 * child window results in undefined behavior.
|
|
|
2745 *
|
|
|
2746 * \param window the window that should become the child of a parent.
|
|
|
2747 * \param parent the new parent window for the child window.
|
|
|
2748 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2749 * information.
|
|
|
2750 *
|
|
|
2751 * \threadsafety This function should only be called on the main thread.
|
|
|
2752 *
|
|
|
2753 * \since This function is available since SDL 3.2.0.
|
|
|
2754 *
|
|
|
2755 * \sa SDL_SetWindowModal
|
|
|
2756 */
|
|
|
2757 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowParent(SDL_Window *window, SDL_Window *parent);
|
|
|
2758
|
|
|
2759 /**
|
|
|
2760 * Toggle the state of the window as modal.
|
|
|
2761 *
|
|
|
2762 * To enable modal status on a window, the window must currently be the child
|
|
|
2763 * window of a parent, or toggling modal status on will fail.
|
|
|
2764 *
|
|
|
2765 * \param window the window on which to set the modal state.
|
|
|
2766 * \param modal true to toggle modal status on, false to toggle it off.
|
|
|
2767 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2768 * information.
|
|
|
2769 *
|
|
|
2770 * \threadsafety This function should only be called on the main thread.
|
|
|
2771 *
|
|
|
2772 * \since This function is available since SDL 3.2.0.
|
|
|
2773 *
|
|
|
2774 * \sa SDL_SetWindowParent
|
|
|
2775 * \sa SDL_WINDOW_MODAL
|
|
|
2776 */
|
|
|
2777 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowModal(SDL_Window *window, bool modal);
|
|
|
2778
|
|
|
2779 /**
|
|
|
2780 * Set whether the window may have input focus.
|
|
|
2781 *
|
|
|
2782 * \param window the window to set focusable state.
|
|
|
2783 * \param focusable true to allow input focus, false to not allow input focus.
|
|
|
2784 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2785 * information.
|
|
|
2786 *
|
|
|
2787 * \threadsafety This function should only be called on the main thread.
|
|
|
2788 *
|
|
|
2789 * \since This function is available since SDL 3.2.0.
|
|
|
2790 */
|
|
|
2791 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowFocusable(SDL_Window *window, bool focusable);
|
|
|
2792
|
|
|
2793
|
|
|
2794 /**
|
|
|
2795 * Display the system-level window menu.
|
|
|
2796 *
|
|
|
2797 * This default window menu is provided by the system and on some platforms
|
|
|
2798 * provides functionality for setting or changing privileged state on the
|
|
|
2799 * window, such as moving it between workspaces or displays, or toggling the
|
|
|
2800 * always-on-top property.
|
|
|
2801 *
|
|
|
2802 * On platforms or desktops where this is unsupported, this function does
|
|
|
2803 * nothing.
|
|
|
2804 *
|
|
|
2805 * \param window the window for which the menu will be displayed.
|
|
|
2806 * \param x the x coordinate of the menu, relative to the origin (top-left) of
|
|
|
2807 * the client area.
|
|
|
2808 * \param y the y coordinate of the menu, relative to the origin (top-left) of
|
|
|
2809 * the client area.
|
|
|
2810 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2811 * information.
|
|
|
2812 *
|
|
|
2813 * \threadsafety This function should only be called on the main thread.
|
|
|
2814 *
|
|
|
2815 * \since This function is available since SDL 3.2.0.
|
|
|
2816 */
|
|
|
2817 extern SDL_DECLSPEC bool SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, int y);
|
|
|
2818
|
|
|
2819 /**
|
|
|
2820 * Possible return values from the SDL_HitTest callback.
|
|
|
2821 *
|
|
|
2822 * \threadsafety This function should only be called on the main thread.
|
|
|
2823 *
|
|
|
2824 * \since This enum is available since SDL 3.2.0.
|
|
|
2825 *
|
|
|
2826 * \sa SDL_HitTest
|
|
|
2827 */
|
|
|
2828 typedef enum SDL_HitTestResult
|
|
|
2829 {
|
|
|
2830 SDL_HITTEST_NORMAL, /**< Region is normal. No special properties. */
|
|
|
2831 SDL_HITTEST_DRAGGABLE, /**< Region can drag entire window. */
|
|
|
2832 SDL_HITTEST_RESIZE_TOPLEFT, /**< Region is the resizable top-left corner border. */
|
|
|
2833 SDL_HITTEST_RESIZE_TOP, /**< Region is the resizable top border. */
|
|
|
2834 SDL_HITTEST_RESIZE_TOPRIGHT, /**< Region is the resizable top-right corner border. */
|
|
|
2835 SDL_HITTEST_RESIZE_RIGHT, /**< Region is the resizable right border. */
|
|
|
2836 SDL_HITTEST_RESIZE_BOTTOMRIGHT, /**< Region is the resizable bottom-right corner border. */
|
|
|
2837 SDL_HITTEST_RESIZE_BOTTOM, /**< Region is the resizable bottom border. */
|
|
|
2838 SDL_HITTEST_RESIZE_BOTTOMLEFT, /**< Region is the resizable bottom-left corner border. */
|
|
|
2839 SDL_HITTEST_RESIZE_LEFT /**< Region is the resizable left border. */
|
|
|
2840 } SDL_HitTestResult;
|
|
|
2841
|
|
|
2842 /**
|
|
|
2843 * Callback used for hit-testing.
|
|
|
2844 *
|
|
|
2845 * \param win the SDL_Window where hit-testing was set on.
|
|
|
2846 * \param area an SDL_Point which should be hit-tested.
|
|
|
2847 * \param data what was passed as `callback_data` to SDL_SetWindowHitTest().
|
|
|
2848 * \returns an SDL_HitTestResult value.
|
|
|
2849 *
|
|
|
2850 * \sa SDL_SetWindowHitTest
|
|
|
2851 */
|
|
|
2852 typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win,
|
|
|
2853 const SDL_Point *area,
|
|
|
2854 void *data);
|
|
|
2855
|
|
|
2856 /**
|
|
|
2857 * Provide a callback that decides if a window region has special properties.
|
|
|
2858 *
|
|
|
2859 * Normally windows are dragged and resized by decorations provided by the
|
|
|
2860 * system window manager (a title bar, borders, etc), but for some apps, it
|
|
|
2861 * makes sense to drag them from somewhere else inside the window itself; for
|
|
|
2862 * example, one might have a borderless window that wants to be draggable from
|
|
|
2863 * any part, or simulate its own title bar, etc.
|
|
|
2864 *
|
|
|
2865 * This function lets the app provide a callback that designates pieces of a
|
|
|
2866 * given window as special. This callback is run during event processing if we
|
|
|
2867 * need to tell the OS to treat a region of the window specially; the use of
|
|
|
2868 * this callback is known as "hit testing."
|
|
|
2869 *
|
|
|
2870 * Mouse input may not be delivered to your application if it is within a
|
|
|
2871 * special area; the OS will often apply that input to moving the window or
|
|
|
2872 * resizing the window and not deliver it to the application.
|
|
|
2873 *
|
|
|
2874 * Specifying NULL for a callback disables hit-testing. Hit-testing is
|
|
|
2875 * disabled by default.
|
|
|
2876 *
|
|
|
2877 * Platforms that don't support this functionality will return false
|
|
|
2878 * unconditionally, even if you're attempting to disable hit-testing.
|
|
|
2879 *
|
|
|
2880 * Your callback may fire at any time, and its firing does not indicate any
|
|
|
2881 * specific behavior (for example, on Windows, this certainly might fire when
|
|
|
2882 * the OS is deciding whether to drag your window, but it fires for lots of
|
|
|
2883 * other reasons, too, some unrelated to anything you probably care about _and
|
|
|
2884 * when the mouse isn't actually at the location it is testing_). Since this
|
|
|
2885 * can fire at any time, you should try to keep your callback efficient,
|
|
|
2886 * devoid of allocations, etc.
|
|
|
2887 *
|
|
|
2888 * \param window the window to set hit-testing on.
|
|
|
2889 * \param callback the function to call when doing a hit-test.
|
|
|
2890 * \param callback_data an app-defined void pointer passed to **callback**.
|
|
|
2891 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2892 * information.
|
|
|
2893 *
|
|
|
2894 * \threadsafety This function should only be called on the main thread.
|
|
|
2895 *
|
|
|
2896 * \since This function is available since SDL 3.2.0.
|
|
|
2897 */
|
|
|
2898 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data);
|
|
|
2899
|
|
|
2900 /**
|
|
|
2901 * Set the shape of a transparent window.
|
|
|
2902 *
|
|
|
2903 * This sets the alpha channel of a transparent window and any fully
|
|
|
2904 * transparent areas are also transparent to mouse clicks. If you are using
|
|
|
2905 * something besides the SDL render API, then you are responsible for drawing
|
|
|
2906 * the alpha channel of the window to match the shape alpha channel to get
|
|
|
2907 * consistent cross-platform results.
|
|
|
2908 *
|
|
|
2909 * The shape is copied inside this function, so you can free it afterwards. If
|
|
|
2910 * your shape surface changes, you should call SDL_SetWindowShape() again to
|
|
|
2911 * update the window. This is an expensive operation, so should be done
|
|
|
2912 * sparingly.
|
|
|
2913 *
|
|
|
2914 * The window must have been created with the SDL_WINDOW_TRANSPARENT flag.
|
|
|
2915 *
|
|
|
2916 * \param window the window.
|
|
|
2917 * \param shape the surface representing the shape of the window, or NULL to
|
|
|
2918 * remove any current shape.
|
|
|
2919 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2920 * information.
|
|
|
2921 *
|
|
|
2922 * \threadsafety This function should only be called on the main thread.
|
|
|
2923 *
|
|
|
2924 * \since This function is available since SDL 3.2.0.
|
|
|
2925 */
|
|
|
2926 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowShape(SDL_Window *window, SDL_Surface *shape);
|
|
|
2927
|
|
|
2928 /**
|
|
|
2929 * Request a window to demand attention from the user.
|
|
|
2930 *
|
|
|
2931 * \param window the window to be flashed.
|
|
|
2932 * \param operation the operation to perform.
|
|
|
2933 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2934 * information.
|
|
|
2935 *
|
|
|
2936 * \threadsafety This function should only be called on the main thread.
|
|
|
2937 *
|
|
|
2938 * \since This function is available since SDL 3.2.0.
|
|
|
2939 */
|
|
|
2940 extern SDL_DECLSPEC bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperation operation);
|
|
|
2941
|
|
|
2942 /**
|
|
|
2943 * Sets the state of the progress bar for the given window’s taskbar icon.
|
|
|
2944 *
|
|
|
2945 * \param window the window whose progress state is to be modified.
|
|
|
2946 * \param state the progress state. `SDL_PROGRESS_STATE_NONE` stops displaying
|
|
|
2947 * the progress bar.
|
|
|
2948 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2949 * information.
|
|
|
2950 *
|
|
|
2951 * \threadsafety This function should only be called on the main thread.
|
|
|
2952 *
|
|
|
2953 * \since This function is available since SDL 3.4.0.
|
|
|
2954 */
|
|
|
2955 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowProgressState(SDL_Window *window, SDL_ProgressState state);
|
|
|
2956
|
|
|
2957 /**
|
|
|
2958 * Get the state of the progress bar for the given window’s taskbar icon.
|
|
|
2959 *
|
|
|
2960 * \param window the window to get the current progress state from.
|
|
|
2961 * \returns the progress state, or `SDL_PROGRESS_STATE_INVALID` on failure;
|
|
|
2962 * call SDL_GetError() for more information.
|
|
|
2963 *
|
|
|
2964 * \threadsafety This function should only be called on the main thread.
|
|
|
2965 *
|
|
|
2966 * \since This function is available since SDL 3.4.0.
|
|
|
2967 */
|
|
|
2968 extern SDL_DECLSPEC SDL_ProgressState SDLCALL SDL_GetWindowProgressState(SDL_Window *window);
|
|
|
2969
|
|
|
2970 /**
|
|
|
2971 * Sets the value of the progress bar for the given window’s taskbar icon.
|
|
|
2972 *
|
|
|
2973 * \param window the window whose progress value is to be modified.
|
|
|
2974 * \param value the progress value in the range of [0.0f - 1.0f]. If the value
|
|
|
2975 * is outside the valid range, it gets clamped.
|
|
|
2976 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
2977 * information.
|
|
|
2978 *
|
|
|
2979 * \threadsafety This function should only be called on the main thread.
|
|
|
2980 *
|
|
|
2981 * \since This function is available since SDL 3.4.0.
|
|
|
2982 */
|
|
|
2983 extern SDL_DECLSPEC bool SDLCALL SDL_SetWindowProgressValue(SDL_Window *window, float value);
|
|
|
2984
|
|
|
2985 /**
|
|
|
2986 * Get the value of the progress bar for the given window’s taskbar icon.
|
|
|
2987 *
|
|
|
2988 * \param window the window to get the current progress value from.
|
|
|
2989 * \returns the progress value in the range of [0.0f - 1.0f], or -1.0f on
|
|
|
2990 * failure; call SDL_GetError() for more information.
|
|
|
2991 *
|
|
|
2992 * \threadsafety This function should only be called on the main thread.
|
|
|
2993 *
|
|
|
2994 * \since This function is available since SDL 3.4.0.
|
|
|
2995 */
|
|
|
2996 extern SDL_DECLSPEC float SDLCALL SDL_GetWindowProgressValue(SDL_Window *window);
|
|
|
2997
|
|
|
2998 /**
|
|
|
2999 * Destroy a window.
|
|
|
3000 *
|
|
|
3001 * Any child windows owned by the window will be recursively destroyed as
|
|
|
3002 * well.
|
|
|
3003 *
|
|
|
3004 * Note that on some platforms, the visible window may not actually be removed
|
|
|
3005 * from the screen until the SDL event loop is pumped again, even though the
|
|
|
3006 * SDL_Window is no longer valid after this call.
|
|
|
3007 *
|
|
|
3008 * \param window the window to destroy.
|
|
|
3009 *
|
|
|
3010 * \threadsafety This function should only be called on the main thread.
|
|
|
3011 *
|
|
|
3012 * \since This function is available since SDL 3.2.0.
|
|
|
3013 *
|
|
|
3014 * \sa SDL_CreatePopupWindow
|
|
|
3015 * \sa SDL_CreateWindow
|
|
|
3016 * \sa SDL_CreateWindowWithProperties
|
|
|
3017 */
|
|
|
3018 extern SDL_DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window *window);
|
|
|
3019
|
|
|
3020
|
|
|
3021 /**
|
|
|
3022 * Check whether the screensaver is currently enabled.
|
|
|
3023 *
|
|
|
3024 * The screensaver is disabled by default.
|
|
|
3025 *
|
|
|
3026 * The default can also be changed using `SDL_HINT_VIDEO_ALLOW_SCREENSAVER`.
|
|
|
3027 *
|
|
|
3028 * \returns true if the screensaver is enabled, false if it is disabled.
|
|
|
3029 *
|
|
|
3030 * \threadsafety This function should only be called on the main thread.
|
|
|
3031 *
|
|
|
3032 * \since This function is available since SDL 3.2.0.
|
|
|
3033 *
|
|
|
3034 * \sa SDL_DisableScreenSaver
|
|
|
3035 * \sa SDL_EnableScreenSaver
|
|
|
3036 */
|
|
|
3037 extern SDL_DECLSPEC bool SDLCALL SDL_ScreenSaverEnabled(void);
|
|
|
3038
|
|
|
3039 /**
|
|
|
3040 * Allow the screen to be blanked by a screen saver.
|
|
|
3041 *
|
|
|
3042 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
3043 * information.
|
|
|
3044 *
|
|
|
3045 * \threadsafety This function should only be called on the main thread.
|
|
|
3046 *
|
|
|
3047 * \since This function is available since SDL 3.2.0.
|
|
|
3048 *
|
|
|
3049 * \sa SDL_DisableScreenSaver
|
|
|
3050 * \sa SDL_ScreenSaverEnabled
|
|
|
3051 */
|
|
|
3052 extern SDL_DECLSPEC bool SDLCALL SDL_EnableScreenSaver(void);
|
|
|
3053
|
|
|
3054 /**
|
|
|
3055 * Prevent the screen from being blanked by a screen saver.
|
|
|
3056 *
|
|
|
3057 * If you disable the screensaver, it is automatically re-enabled when SDL
|
|
|
3058 * quits.
|
|
|
3059 *
|
|
|
3060 * The screensaver is disabled by default, but this may by changed by
|
|
|
3061 * SDL_HINT_VIDEO_ALLOW_SCREENSAVER.
|
|
|
3062 *
|
|
|
3063 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
3064 * information.
|
|
|
3065 *
|
|
|
3066 * \threadsafety This function should only be called on the main thread.
|
|
|
3067 *
|
|
|
3068 * \since This function is available since SDL 3.2.0.
|
|
|
3069 *
|
|
|
3070 * \sa SDL_EnableScreenSaver
|
|
|
3071 * \sa SDL_ScreenSaverEnabled
|
|
|
3072 */
|
|
|
3073 extern SDL_DECLSPEC bool SDLCALL SDL_DisableScreenSaver(void);
|
|
|
3074
|
|
|
3075
|
|
|
3076 /**
|
|
|
3077 * \name OpenGL support functions
|
|
|
3078 */
|
|
|
3079 /* @{ */
|
|
|
3080
|
|
|
3081 /**
|
|
|
3082 * Dynamically load an OpenGL library.
|
|
|
3083 *
|
|
|
3084 * This should be done after initializing the video driver, but before
|
|
|
3085 * creating any OpenGL windows. If no OpenGL library is loaded, the default
|
|
|
3086 * library will be loaded upon creation of the first OpenGL window.
|
|
|
3087 *
|
|
|
3088 * If you do this, you need to retrieve all of the GL functions used in your
|
|
|
3089 * program from the dynamic library using SDL_GL_GetProcAddress().
|
|
|
3090 *
|
|
|
3091 * \param path the platform dependent OpenGL library name, or NULL to open the
|
|
|
3092 * default OpenGL library.
|
|
|
3093 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
3094 * information.
|
|
|
3095 *
|
|
|
3096 * \threadsafety This function should only be called on the main thread.
|
|
|
3097 *
|
|
|
3098 * \since This function is available since SDL 3.2.0.
|
|
|
3099 *
|
|
|
3100 * \sa SDL_GL_GetProcAddress
|
|
|
3101 * \sa SDL_GL_UnloadLibrary
|
|
|
3102 */
|
|
|
3103 extern SDL_DECLSPEC bool SDLCALL SDL_GL_LoadLibrary(const char *path);
|
|
|
3104
|
|
|
3105 /**
|
|
|
3106 * Get an OpenGL function by name.
|
|
|
3107 *
|
|
|
3108 * If the GL library is loaded at runtime with SDL_GL_LoadLibrary(), then all
|
|
|
3109 * GL functions must be retrieved this way. Usually this is used to retrieve
|
|
|
3110 * function pointers to OpenGL extensions.
|
|
|
3111 *
|
|
|
3112 * There are some quirks to looking up OpenGL functions that require some
|
|
|
3113 * extra care from the application. If you code carefully, you can handle
|
|
|
3114 * these quirks without any platform-specific code, though:
|
|
|
3115 *
|
|
|
3116 * - On Windows, function pointers are specific to the current GL context;
|
|
|
3117 * this means you need to have created a GL context and made it current
|
|
|
3118 * before calling SDL_GL_GetProcAddress(). If you recreate your context or
|
|
|
3119 * create a second context, you should assume that any existing function
|
|
|
3120 * pointers aren't valid to use with it. This is (currently) a
|
|
|
3121 * Windows-specific limitation, and in practice lots of drivers don't suffer
|
|
|
3122 * this limitation, but it is still the way the wgl API is documented to
|
|
|
3123 * work and you should expect crashes if you don't respect it. Store a copy
|
|
|
3124 * of the function pointers that comes and goes with context lifespan.
|
|
|
3125 * - On X11, function pointers returned by this function are valid for any
|
|
|
3126 * context, and can even be looked up before a context is created at all.
|
|
|
3127 * This means that, for at least some common OpenGL implementations, if you
|
|
|
3128 * look up a function that doesn't exist, you'll get a non-NULL result that
|
|
|
3129 * is _NOT_ safe to call. You must always make sure the function is actually
|
|
|
3130 * available for a given GL context before calling it, by checking for the
|
|
|
3131 * existence of the appropriate extension with SDL_GL_ExtensionSupported(),
|
|
|
3132 * or verifying that the version of OpenGL you're using offers the function
|
|
|
3133 * as core functionality.
|
|
|
3134 * - Some OpenGL drivers, on all platforms, *will* return NULL if a function
|
|
|
3135 * isn't supported, but you can't count on this behavior. Check for
|
|
|
3136 * extensions you use, and if you get a NULL anyway, act as if that
|
|
|
3137 * extension wasn't available. This is probably a bug in the driver, but you
|
|
|
3138 * can code defensively for this scenario anyhow.
|
|
|
3139 * - Just because you're on Linux/Unix, don't assume you'll be using X11.
|
|
|
3140 * Next-gen display servers are waiting to replace it, and may or may not
|
|
|
3141 * make the same promises about function pointers.
|
|
|
3142 * - OpenGL function pointers must be declared `APIENTRY` as in the example
|
|
|
3143 * code. This will ensure the proper calling convention is followed on
|
|
|
3144 * platforms where this matters (Win32) thereby avoiding stack corruption.
|
|
|
3145 *
|
|
|
3146 * \param proc the name of an OpenGL function.
|
|
|
3147 * \returns a pointer to the named OpenGL function. The returned pointer
|
|
|
3148 * should be cast to the appropriate function signature.
|
|
|
3149 *
|
|
|
3150 * \threadsafety This function should only be called on the main thread.
|
|
|
3151 *
|
|
|
3152 * \since This function is available since SDL 3.2.0.
|
|
|
3153 *
|
|
|
3154 * \sa SDL_GL_ExtensionSupported
|
|
|
3155 * \sa SDL_GL_LoadLibrary
|
|
|
3156 * \sa SDL_GL_UnloadLibrary
|
|
|
3157 */
|
|
|
3158 extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_GL_GetProcAddress(const char *proc);
|
|
|
3159
|
|
|
3160 /**
|
|
|
3161 * Get an EGL library function by name.
|
|
|
3162 *
|
|
|
3163 * If an EGL library is loaded, this function allows applications to get entry
|
|
|
3164 * points for EGL functions. This is useful to provide to an EGL API and
|
|
|
3165 * extension loader.
|
|
|
3166 *
|
|
|
3167 * \param proc the name of an EGL function.
|
|
|
3168 * \returns a pointer to the named EGL function. The returned pointer should
|
|
|
3169 * be cast to the appropriate function signature.
|
|
|
3170 *
|
|
|
3171 * \threadsafety This function should only be called on the main thread.
|
|
|
3172 *
|
|
|
3173 * \since This function is available since SDL 3.2.0.
|
|
|
3174 *
|
|
|
3175 * \sa SDL_EGL_GetCurrentDisplay
|
|
|
3176 */
|
|
|
3177 extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_EGL_GetProcAddress(const char *proc);
|
|
|
3178
|
|
|
3179 /**
|
|
|
3180 * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary().
|
|
|
3181 *
|
|
|
3182 * \threadsafety This function should only be called on the main thread.
|
|
|
3183 *
|
|
|
3184 * \since This function is available since SDL 3.2.0.
|
|
|
3185 *
|
|
|
3186 * \sa SDL_GL_LoadLibrary
|
|
|
3187 */
|
|
|
3188 extern SDL_DECLSPEC void SDLCALL SDL_GL_UnloadLibrary(void);
|
|
|
3189
|
|
|
3190 /**
|
|
|
3191 * Check if an OpenGL extension is supported for the current context.
|
|
|
3192 *
|
|
|
3193 * This function operates on the current GL context; you must have created a
|
|
|
3194 * context and it must be current before calling this function. Do not assume
|
|
|
3195 * that all contexts you create will have the same set of extensions
|
|
|
3196 * available, or that recreating an existing context will offer the same
|
|
|
3197 * extensions again.
|
|
|
3198 *
|
|
|
3199 * While it's probably not a massive overhead, this function is not an O(1)
|
|
|
3200 * operation. Check the extensions you care about after creating the GL
|
|
|
3201 * context and save that information somewhere instead of calling the function
|
|
|
3202 * every time you need to know.
|
|
|
3203 *
|
|
|
3204 * \param extension the name of the extension to check.
|
|
|
3205 * \returns true if the extension is supported, false otherwise.
|
|
|
3206 *
|
|
|
3207 * \threadsafety This function should only be called on the main thread.
|
|
|
3208 *
|
|
|
3209 * \since This function is available since SDL 3.2.0.
|
|
|
3210 */
|
|
|
3211 extern SDL_DECLSPEC bool SDLCALL SDL_GL_ExtensionSupported(const char *extension);
|
|
|
3212
|
|
|
3213 /**
|
|
|
3214 * Reset all previously set OpenGL context attributes to their default values.
|
|
|
3215 *
|
|
|
3216 * \threadsafety This function should only be called on the main thread.
|
|
|
3217 *
|
|
|
3218 * \since This function is available since SDL 3.2.0.
|
|
|
3219 *
|
|
|
3220 * \sa SDL_GL_GetAttribute
|
|
|
3221 * \sa SDL_GL_SetAttribute
|
|
|
3222 */
|
|
|
3223 extern SDL_DECLSPEC void SDLCALL SDL_GL_ResetAttributes(void);
|
|
|
3224
|
|
|
3225 /**
|
|
|
3226 * Set an OpenGL window attribute before window creation.
|
|
|
3227 *
|
|
|
3228 * This function sets the OpenGL attribute `attr` to `value`. The requested
|
|
|
3229 * attributes should be set before creating an OpenGL window. You should use
|
|
|
3230 * SDL_GL_GetAttribute() to check the values after creating the OpenGL
|
|
|
3231 * context, since the values obtained can differ from the requested ones.
|
|
|
3232 *
|
|
|
3233 * \param attr an enum value specifying the OpenGL attribute to set.
|
|
|
3234 * \param value the desired value for the attribute.
|
|
|
3235 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
3236 * information.
|
|
|
3237 *
|
|
|
3238 * \threadsafety This function should only be called on the main thread.
|
|
|
3239 *
|
|
|
3240 * \since This function is available since SDL 3.2.0.
|
|
|
3241 *
|
|
|
3242 * \sa SDL_GL_CreateContext
|
|
|
3243 * \sa SDL_GL_GetAttribute
|
|
|
3244 * \sa SDL_GL_ResetAttributes
|
|
|
3245 */
|
|
|
3246 extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetAttribute(SDL_GLAttr attr, int value);
|
|
|
3247
|
|
|
3248 /**
|
|
|
3249 * Get the actual value for an attribute from the current context.
|
|
|
3250 *
|
|
|
3251 * \param attr an SDL_GLAttr enum value specifying the OpenGL attribute to
|
|
|
3252 * get.
|
|
|
3253 * \param value a pointer filled in with the current value of `attr`.
|
|
|
3254 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
3255 * information.
|
|
|
3256 *
|
|
|
3257 * \threadsafety This function should only be called on the main thread.
|
|
|
3258 *
|
|
|
3259 * \since This function is available since SDL 3.2.0.
|
|
|
3260 *
|
|
|
3261 * \sa SDL_GL_ResetAttributes
|
|
|
3262 * \sa SDL_GL_SetAttribute
|
|
|
3263 */
|
|
|
3264 extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetAttribute(SDL_GLAttr attr, int *value);
|
|
|
3265
|
|
|
3266 /**
|
|
|
3267 * Create an OpenGL context for an OpenGL window, and make it current.
|
|
|
3268 *
|
|
|
3269 * The OpenGL context will be created with the current states set through
|
|
|
3270 * SDL_GL_SetAttribute().
|
|
|
3271 *
|
|
|
3272 * The SDL_Window specified must have been created with the SDL_WINDOW_OPENGL
|
|
|
3273 * flag, or context creation will fail.
|
|
|
3274 *
|
|
|
3275 * Windows users new to OpenGL should note that, for historical reasons, GL
|
|
|
3276 * functions added after OpenGL version 1.1 are not available by default.
|
|
|
3277 * Those functions must be loaded at run-time, either with an OpenGL
|
|
|
3278 * extension-handling library or with SDL_GL_GetProcAddress() and its related
|
|
|
3279 * functions.
|
|
|
3280 *
|
|
|
3281 * SDL_GLContext is opaque to the application.
|
|
|
3282 *
|
|
|
3283 * \param window the window to associate with the context.
|
|
|
3284 * \returns the OpenGL context associated with `window` or NULL on failure;
|
|
|
3285 * call SDL_GetError() for more information.
|
|
|
3286 *
|
|
|
3287 * \threadsafety This function should only be called on the main thread.
|
|
|
3288 *
|
|
|
3289 * \since This function is available since SDL 3.2.0.
|
|
|
3290 *
|
|
|
3291 * \sa SDL_GL_DestroyContext
|
|
|
3292 * \sa SDL_GL_MakeCurrent
|
|
|
3293 */
|
|
|
3294 extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window *window);
|
|
|
3295
|
|
|
3296 /**
|
|
|
3297 * Set up an OpenGL context for rendering into an OpenGL window.
|
|
|
3298 *
|
|
|
3299 * The context must have been created with a compatible window.
|
|
|
3300 *
|
|
|
3301 * \param window the window to associate with the context.
|
|
|
3302 * \param context the OpenGL context to associate with the window.
|
|
|
3303 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
3304 * information.
|
|
|
3305 *
|
|
|
3306 * \threadsafety This function should only be called on the main thread.
|
|
|
3307 *
|
|
|
3308 * \since This function is available since SDL 3.2.0.
|
|
|
3309 *
|
|
|
3310 * \sa SDL_GL_CreateContext
|
|
|
3311 */
|
|
|
3312 extern SDL_DECLSPEC bool SDLCALL SDL_GL_MakeCurrent(SDL_Window *window, SDL_GLContext context);
|
|
|
3313
|
|
|
3314 /**
|
|
|
3315 * Get the currently active OpenGL window.
|
|
|
3316 *
|
|
|
3317 * \returns the currently active OpenGL window on success or NULL on failure;
|
|
|
3318 * call SDL_GetError() for more information.
|
|
|
3319 *
|
|
|
3320 * \threadsafety This function should only be called on the main thread.
|
|
|
3321 *
|
|
|
3322 * \since This function is available since SDL 3.2.0.
|
|
|
3323 */
|
|
|
3324 extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GL_GetCurrentWindow(void);
|
|
|
3325
|
|
|
3326 /**
|
|
|
3327 * Get the currently active OpenGL context.
|
|
|
3328 *
|
|
|
3329 * \returns the currently active OpenGL context or NULL on failure; call
|
|
|
3330 * SDL_GetError() for more information.
|
|
|
3331 *
|
|
|
3332 * \threadsafety This function should only be called on the main thread.
|
|
|
3333 *
|
|
|
3334 * \since This function is available since SDL 3.2.0.
|
|
|
3335 *
|
|
|
3336 * \sa SDL_GL_MakeCurrent
|
|
|
3337 */
|
|
|
3338 extern SDL_DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void);
|
|
|
3339
|
|
|
3340 /**
|
|
|
3341 * Get the currently active EGL display.
|
|
|
3342 *
|
|
|
3343 * \returns the currently active EGL display or NULL on failure; call
|
|
|
3344 * SDL_GetError() for more information.
|
|
|
3345 *
|
|
|
3346 * \threadsafety This function should only be called on the main thread.
|
|
|
3347 *
|
|
|
3348 * \since This function is available since SDL 3.2.0.
|
|
|
3349 */
|
|
|
3350 extern SDL_DECLSPEC SDL_EGLDisplay SDLCALL SDL_EGL_GetCurrentDisplay(void);
|
|
|
3351
|
|
|
3352 /**
|
|
|
3353 * Get the currently active EGL config.
|
|
|
3354 *
|
|
|
3355 * \returns the currently active EGL config or NULL on failure; call
|
|
|
3356 * SDL_GetError() for more information.
|
|
|
3357 *
|
|
|
3358 * \threadsafety This function should only be called on the main thread.
|
|
|
3359 *
|
|
|
3360 * \since This function is available since SDL 3.2.0.
|
|
|
3361 */
|
|
|
3362 extern SDL_DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentConfig(void);
|
|
|
3363
|
|
|
3364 /**
|
|
|
3365 * Get the EGL surface associated with the window.
|
|
|
3366 *
|
|
|
3367 * \param window the window to query.
|
|
|
3368 * \returns the EGLSurface pointer associated with the window, or NULL on
|
|
|
3369 * failure.
|
|
|
3370 *
|
|
|
3371 * \threadsafety This function should only be called on the main thread.
|
|
|
3372 *
|
|
|
3373 * \since This function is available since SDL 3.2.0.
|
|
|
3374 */
|
|
|
3375 extern SDL_DECLSPEC SDL_EGLSurface SDLCALL SDL_EGL_GetWindowSurface(SDL_Window *window);
|
|
|
3376
|
|
|
3377 /**
|
|
|
3378 * Sets the callbacks for defining custom EGLAttrib arrays for EGL
|
|
|
3379 * initialization.
|
|
|
3380 *
|
|
|
3381 * Callbacks that aren't needed can be set to NULL.
|
|
|
3382 *
|
|
|
3383 * NOTE: These callback pointers will be reset after SDL_GL_ResetAttributes.
|
|
|
3384 *
|
|
|
3385 * \param platformAttribCallback callback for attributes to pass to
|
|
|
3386 * eglGetPlatformDisplay. May be NULL.
|
|
|
3387 * \param surfaceAttribCallback callback for attributes to pass to
|
|
|
3388 * eglCreateSurface. May be NULL.
|
|
|
3389 * \param contextAttribCallback callback for attributes to pass to
|
|
|
3390 * eglCreateContext. May be NULL.
|
|
|
3391 * \param userdata a pointer that is passed to the callbacks.
|
|
|
3392 *
|
|
|
3393 * \threadsafety This function should only be called on the main thread.
|
|
|
3394 *
|
|
|
3395 * \since This function is available since SDL 3.2.0.
|
|
|
3396 */
|
|
|
3397 extern SDL_DECLSPEC void SDLCALL SDL_EGL_SetAttributeCallbacks(SDL_EGLAttribArrayCallback platformAttribCallback,
|
|
|
3398 SDL_EGLIntArrayCallback surfaceAttribCallback,
|
|
|
3399 SDL_EGLIntArrayCallback contextAttribCallback, void *userdata);
|
|
|
3400
|
|
|
3401 /**
|
|
|
3402 * Set the swap interval for the current OpenGL context.
|
|
|
3403 *
|
|
|
3404 * Some systems allow specifying -1 for the interval, to enable adaptive
|
|
|
3405 * vsync. Adaptive vsync works the same as vsync, but if you've already missed
|
|
|
3406 * the vertical retrace for a given frame, it swaps buffers immediately, which
|
|
|
3407 * might be less jarring for the user during occasional framerate drops. If an
|
|
|
3408 * application requests adaptive vsync and the system does not support it,
|
|
|
3409 * this function will fail and return false. In such a case, you should
|
|
|
3410 * probably retry the call with 1 for the interval.
|
|
|
3411 *
|
|
|
3412 * Adaptive vsync is implemented for some glX drivers with
|
|
|
3413 * GLX_EXT_swap_control_tear, and for some Windows drivers with
|
|
|
3414 * WGL_EXT_swap_control_tear.
|
|
|
3415 *
|
|
|
3416 * Read more on the Khronos wiki:
|
|
|
3417 * https://www.khronos.org/opengl/wiki/Swap_Interval#Adaptive_Vsync
|
|
|
3418 *
|
|
|
3419 * \param interval 0 for immediate updates, 1 for updates synchronized with
|
|
|
3420 * the vertical retrace, -1 for adaptive vsync.
|
|
|
3421 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
3422 * information.
|
|
|
3423 *
|
|
|
3424 * \threadsafety This function should only be called on the main thread.
|
|
|
3425 *
|
|
|
3426 * \since This function is available since SDL 3.2.0.
|
|
|
3427 *
|
|
|
3428 * \sa SDL_GL_GetSwapInterval
|
|
|
3429 */
|
|
|
3430 extern SDL_DECLSPEC bool SDLCALL SDL_GL_SetSwapInterval(int interval);
|
|
|
3431
|
|
|
3432 /**
|
|
|
3433 * Get the swap interval for the current OpenGL context.
|
|
|
3434 *
|
|
|
3435 * If the system can't determine the swap interval, or there isn't a valid
|
|
|
3436 * current context, this function will set *interval to 0 as a safe default.
|
|
|
3437 *
|
|
|
3438 * \param interval output interval value. 0 if there is no vertical retrace
|
|
|
3439 * synchronization, 1 if the buffer swap is synchronized with
|
|
|
3440 * the vertical retrace, and -1 if late swaps happen
|
|
|
3441 * immediately instead of waiting for the next retrace.
|
|
|
3442 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
3443 * information.
|
|
|
3444 *
|
|
|
3445 * \threadsafety This function should only be called on the main thread.
|
|
|
3446 *
|
|
|
3447 * \since This function is available since SDL 3.2.0.
|
|
|
3448 *
|
|
|
3449 * \sa SDL_GL_SetSwapInterval
|
|
|
3450 */
|
|
|
3451 extern SDL_DECLSPEC bool SDLCALL SDL_GL_GetSwapInterval(int *interval);
|
|
|
3452
|
|
|
3453 /**
|
|
|
3454 * Update a window with OpenGL rendering.
|
|
|
3455 *
|
|
|
3456 * This is used with double-buffered OpenGL contexts, which are the default.
|
|
|
3457 *
|
|
|
3458 * On macOS, make sure you bind 0 to the draw framebuffer before swapping the
|
|
|
3459 * window, otherwise nothing will happen. If you aren't using
|
|
|
3460 * glBindFramebuffer(), this is the default and you won't have to do anything
|
|
|
3461 * extra.
|
|
|
3462 *
|
|
|
3463 * \param window the window to change.
|
|
|
3464 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
3465 * information.
|
|
|
3466 *
|
|
|
3467 * \threadsafety This function should only be called on the main thread.
|
|
|
3468 *
|
|
|
3469 * \since This function is available since SDL 3.2.0.
|
|
|
3470 */
|
|
|
3471 extern SDL_DECLSPEC bool SDLCALL SDL_GL_SwapWindow(SDL_Window *window);
|
|
|
3472
|
|
|
3473 /**
|
|
|
3474 * Delete an OpenGL context.
|
|
|
3475 *
|
|
|
3476 * \param context the OpenGL context to be deleted.
|
|
|
3477 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
3478 * information.
|
|
|
3479 *
|
|
|
3480 * \threadsafety This function should only be called on the main thread.
|
|
|
3481 *
|
|
|
3482 * \since This function is available since SDL 3.2.0.
|
|
|
3483 *
|
|
|
3484 * \sa SDL_GL_CreateContext
|
|
|
3485 */
|
|
|
3486 extern SDL_DECLSPEC bool SDLCALL SDL_GL_DestroyContext(SDL_GLContext context);
|
|
|
3487
|
|
|
3488 /* @} *//* OpenGL support functions */
|
|
|
3489
|
|
|
3490
|
|
|
3491 /* Ends C function definitions when using C++ */
|
|
|
3492 #ifdef __cplusplus
|
|
|
3493 }
|
|
|
3494 #endif
|
|
|
3495 #include <SDL3/SDL_close_code.h>
|
|
|
3496
|
|
|
3497 #endif /* SDL_video_h_ */
|
