SDL 3.0
SDL_system.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 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 * # CategorySystem
24 *
25 * Platform-specific SDL API functions.
26 */
27
28#ifndef SDL_system_h_
29#define SDL_system_h_
30
31#include <SDL3/SDL_stdinc.h>
32#include <SDL3/SDL_error.h>
33#include <SDL3/SDL_keyboard.h>
34#include <SDL3/SDL_video.h>
35
36#include <SDL3/SDL_begin_code.h>
37/* Set up for C function definitions, even when using C++ */
38#ifdef __cplusplus
39extern "C" {
40#endif
41
42
43/*
44 * Platform specific functions for Windows
45 */
46#if defined(SDL_PLATFORM_WINDOWS)
47
48typedef struct tagMSG MSG;
49
50/**
51 * A callback to be used with SDL_SetWindowsMessageHook.
52 *
53 * This callback may modify the message, and should return true if the message
54 * should continue to be processed, or false to prevent further processing.
55 *
56 * As this is processing a message directly from the Windows event loop, this
57 * callback should do the minimum required work and return quickly.
58 *
59 * \param userdata the app-defined pointer provided to
60 * SDL_SetWindowsMessageHook.
61 * \param msg a pointer to a Win32 event structure to process.
62 * \returns true to let event continue on, false to drop it.
63 *
64 * \threadsafety This may only be called (by SDL) from the thread handling the
65 * Windows event loop.
66 *
67 * \since This datatype is available since SDL 3.1.3.
68 *
69 * \sa SDL_SetWindowsMessageHook
70 * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP
71 */
72typedef bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg);
73
74/**
75 * Set a callback for every Windows message, run before TranslateMessage().
76 *
77 * The callback may modify the message, and should return true if the message
78 * should continue to be processed, or false to prevent further processing.
79 *
80 * \param callback the SDL_WindowsMessageHook function to call.
81 * \param userdata a pointer to pass to every iteration of `callback`.
82 *
83 * \since This function is available since SDL 3.1.3.
84 *
85 * \sa SDL_WindowsMessageHook
86 * \sa SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP
87 */
88extern SDL_DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook callback, void *userdata);
89
90#endif /* defined(SDL_PLATFORM_WINDOWS) */
91
92#if defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK)
93
94/**
95 * Get the D3D9 adapter index that matches the specified display.
96 *
97 * The returned adapter index can be passed to `IDirect3D9::CreateDevice` and
98 * controls on which monitor a full screen application will appear.
99 *
100 * \param displayID the instance of the display to query.
101 * \returns the D3D9 adapter index on success or -1 on failure; call
102 * SDL_GetError() for more information.
103 *
104 * \since This function is available since SDL 3.1.3.
105 */
106extern SDL_DECLSPEC int SDLCALL SDL_GetDirect3D9AdapterIndex(SDL_DisplayID displayID);
107
108/**
109 * Get the DXGI Adapter and Output indices for the specified display.
110 *
111 * The DXGI Adapter and Output indices can be passed to `EnumAdapters` and
112 * `EnumOutputs` respectively to get the objects required to create a DX10 or
113 * DX11 device and swap chain.
114 *
115 * \param displayID the instance of the display to query.
116 * \param adapterIndex a pointer to be filled in with the adapter index.
117 * \param outputIndex a pointer to be filled in with the output index.
118 * \returns true on success or false on failure; call SDL_GetError() for more
119 * information.
120 *
121 * \since This function is available since SDL 3.1.3.
122 */
123extern SDL_DECLSPEC bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, int *adapterIndex, int *outputIndex);
124
125#endif /* defined(SDL_PLATFORM_WIN32) || defined(SDL_PLATFORM_WINGDK) */
126
127
128/*
129 * Platform specific functions for UNIX
130 */
131
132typedef union _XEvent XEvent;
133typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent);
134
135/**
136 * Set a callback for every X11 event.
137 *
138 * The callback may modify the event, and should return true if the event
139 * should continue to be processed, or false to prevent further processing.
140 *
141 * \param callback the SDL_X11EventHook function to call.
142 * \param userdata a pointer to pass to every iteration of `callback`.
143 *
144 * \since This function is available since SDL 3.1.3.
145 */
146extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata);
147
148/* Platform specific functions for Linux*/
149#ifdef SDL_PLATFORM_LINUX
150
151/**
152 * Sets the UNIX nice value for a thread.
153 *
154 * This uses setpriority() if possible, and RealtimeKit if available.
155 *
156 * \param threadID the Unix thread ID to change priority of.
157 * \param priority the new, Unix-specific, priority value.
158 * \returns true on success or false on failure; call SDL_GetError() for more
159 * information.
160 *
161 * \since This function is available since SDL 3.1.3.
162 */
163extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority);
164
165/**
166 * Sets the priority (not nice level) and scheduling policy for a thread.
167 *
168 * This uses setpriority() if possible, and RealtimeKit if available.
169 *
170 * \param threadID the Unix thread ID to change priority of.
171 * \param sdlPriority the new SDL_ThreadPriority value.
172 * \param schedPolicy the new scheduling policy (SCHED_FIFO, SCHED_RR,
173 * SCHED_OTHER, etc...).
174 * \returns true on success or false on failure; call SDL_GetError() for more
175 * information.
176 *
177 * \since This function is available since SDL 3.1.3.
178 */
179extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy);
180
181#endif /* SDL_PLATFORM_LINUX */
182
183/*
184 * Platform specific functions for iOS
185 */
186#ifdef SDL_PLATFORM_IOS
187
188/**
189 * The prototype for an Apple iOS animation callback.
190 *
191 * This datatype is only useful on Apple iOS.
192 *
193 * After passing a function pointer of this type to
194 * SDL_SetiOSAnimationCallback, the system will call that function pointer at
195 * a regular interval.
196 *
197 * \param userdata what was passed as `callbackParam` to
198 * SDL_SetiOSAnimationCallback as `callbackParam`.
199 *
200 * \since This datatype is available since SDL 3.1.3.
201 *
202 * \sa SDL_SetiOSAnimationCallback
203 */
204typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata);
205
206/**
207 * Use this function to set the animation callback on Apple iOS.
208 *
209 * The function prototype for `callback` is:
210 *
211 * ```c
212 * void callback(void *callbackParam);
213 * ```
214 *
215 * Where its parameter, `callbackParam`, is what was passed as `callbackParam`
216 * to SDL_SetiOSAnimationCallback().
217 *
218 * This function is only available on Apple iOS.
219 *
220 * For more information see:
221 *
222 * https://wiki.libsdl.org/SDL3/README/ios
223 *
224 * Note that if you use the "main callbacks" instead of a standard C `main`
225 * function, you don't have to use this API, as SDL will manage this for you.
226 *
227 * Details on main callbacks are here:
228 *
229 * https://wiki.libsdl.org/SDL3/README/main-functions
230 *
231 * \param window the window for which the animation callback should be set.
232 * \param interval the number of frames after which **callback** will be
233 * called.
234 * \param callback the function to call for every frame.
235 * \param callbackParam a pointer that is passed to `callback`.
236 * \returns true on success or false on failure; call SDL_GetError() for more
237 * information.
238 *
239 * \since This function is available since SDL 3.1.3.
240 *
241 * \sa SDL_SetiOSEventPump
242 */
243extern SDL_DECLSPEC bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window, int interval, SDL_iOSAnimationCallback callback, void *callbackParam);
244
245/**
246 * Use this function to enable or disable the SDL event pump on Apple iOS.
247 *
248 * This function is only available on Apple iOS.
249 *
250 * \param enabled true to enable the event pump, false to disable it.
251 *
252 * \since This function is available since SDL 3.1.3.
253 *
254 * \sa SDL_SetiOSAnimationCallback
255 */
256extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(bool enabled);
257
258#endif /* SDL_PLATFORM_IOS */
259
260
261/*
262 * Platform specific functions for Android
263 */
264#ifdef SDL_PLATFORM_ANDROID
265
266/**
267 * Get the Android Java Native Interface Environment of the current thread.
268 *
269 * This is the JNIEnv one needs to access the Java virtual machine from native
270 * code, and is needed for many Android APIs to be usable from C.
271 *
272 * The prototype of the function in SDL's code actually declare a void* return
273 * type, even if the implementation returns a pointer to a JNIEnv. The
274 * rationale being that the SDL headers can avoid including jni.h.
275 *
276 * \returns a pointer to Java native interface object (JNIEnv) to which the
277 * current thread is attached, or NULL on failure; call
278 * SDL_GetError() for more information.
279 *
280 * \threadsafety It is safe to call this function from any thread.
281 *
282 * \since This function is available since SDL 3.1.3.
283 *
284 * \sa SDL_GetAndroidActivity
285 */
286extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidJNIEnv(void);
287
288/**
289 * Retrieve the Java instance of the Android activity class.
290 *
291 * The prototype of the function in SDL's code actually declares a void*
292 * return type, even if the implementation returns a jobject. The rationale
293 * being that the SDL headers can avoid including jni.h.
294 *
295 * The jobject returned by the function is a local reference and must be
296 * released by the caller. See the PushLocalFrame() and PopLocalFrame() or
297 * DeleteLocalRef() functions of the Java native interface:
298 *
299 * https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html
300 *
301 * \returns the jobject representing the instance of the Activity class of the
302 * Android application, or NULL on failure; call SDL_GetError() for
303 * more information.
304 *
305 * \threadsafety It is safe to call this function from any thread.
306 *
307 * \since This function is available since SDL 3.1.3.
308 *
309 * \sa SDL_GetAndroidJNIEnv
310 */
311extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidActivity(void);
312
313/**
314 * Query Android API level of the current device.
315 *
316 * - API level 35: Android 15 (VANILLA_ICE_CREAM)
317 * - API level 34: Android 14 (UPSIDE_DOWN_CAKE)
318 * - API level 33: Android 13 (TIRAMISU)
319 * - API level 32: Android 12L (S_V2)
320 * - API level 31: Android 12 (S)
321 * - API level 30: Android 11 (R)
322 * - API level 29: Android 10 (Q)
323 * - API level 28: Android 9 (P)
324 * - API level 27: Android 8.1 (O_MR1)
325 * - API level 26: Android 8.0 (O)
326 * - API level 25: Android 7.1 (N_MR1)
327 * - API level 24: Android 7.0 (N)
328 * - API level 23: Android 6.0 (M)
329 * - API level 22: Android 5.1 (LOLLIPOP_MR1)
330 * - API level 21: Android 5.0 (LOLLIPOP, L)
331 * - API level 20: Android 4.4W (KITKAT_WATCH)
332 * - API level 19: Android 4.4 (KITKAT)
333 * - API level 18: Android 4.3 (JELLY_BEAN_MR2)
334 * - API level 17: Android 4.2 (JELLY_BEAN_MR1)
335 * - API level 16: Android 4.1 (JELLY_BEAN)
336 * - API level 15: Android 4.0.3 (ICE_CREAM_SANDWICH_MR1)
337 * - API level 14: Android 4.0 (ICE_CREAM_SANDWICH)
338 * - API level 13: Android 3.2 (HONEYCOMB_MR2)
339 * - API level 12: Android 3.1 (HONEYCOMB_MR1)
340 * - API level 11: Android 3.0 (HONEYCOMB)
341 * - API level 10: Android 2.3.3 (GINGERBREAD_MR1)
342 *
343 * \returns the Android API level.
344 *
345 * \since This function is available since SDL 3.1.3.
346 */
347extern SDL_DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void);
348
349/**
350 * Query if the application is running on a Chromebook.
351 *
352 * \returns true if this is a Chromebook, false otherwise.
353 *
354 * \since This function is available since SDL 3.1.3.
355 */
356extern SDL_DECLSPEC bool SDLCALL SDL_IsChromebook(void);
357
358/**
359 * Query if the application is running on a Samsung DeX docking station.
360 *
361 * \returns true if this is a DeX docking station, false otherwise.
362 *
363 * \since This function is available since SDL 3.1.3.
364 */
365extern SDL_DECLSPEC bool SDLCALL SDL_IsDeXMode(void);
366
367/**
368 * Trigger the Android system back button behavior.
369 *
370 * \threadsafety It is safe to call this function from any thread.
371 *
372 * \since This function is available since SDL 3.1.3.
373 */
374extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void);
375
376/**
377 * See the official Android developer guide for more information:
378 * http://developer.android.com/guide/topics/data/data-storage.html
379 *
380 * \since This macro is available since SDL 3.1.3.
381 */
382#define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01
383#define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02
384
385/**
386 * Get the path used for internal storage for this Android application.
387 *
388 * This path is unique to your application and cannot be written to by other
389 * applications.
390 *
391 * Your internal storage path is typically:
392 * `/data/data/your.app.package/files`.
393 *
394 * This is a C wrapper over `android.content.Context.getFilesDir()`:
395 *
396 * https://developer.android.com/reference/android/content/Context#getFilesDir()
397 *
398 * \returns the path used for internal storage or NULL on failure; call
399 * SDL_GetError() for more information.
400 *
401 * \since This function is available since SDL 3.1.3.
402 *
403 * \sa SDL_GetAndroidExternalStoragePath
404 * \sa SDL_GetAndroidCachePath
405 */
406extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void);
407
408/**
409 * Get the current state of external storage for this Android application.
410 *
411 * The current state of external storage, a bitmask of these values:
412 * `SDL_ANDROID_EXTERNAL_STORAGE_READ`, `SDL_ANDROID_EXTERNAL_STORAGE_WRITE`.
413 *
414 * If external storage is currently unavailable, this will return 0.
415 *
416 * \returns the current state of external storage, or 0 if external storage is
417 * currently unavailable.
418 *
419 * \since This function is available since SDL 3.1.3.
420 *
421 * \sa SDL_GetAndroidExternalStoragePath
422 */
423extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void);
424
425/**
426 * Get the path used for external storage for this Android application.
427 *
428 * This path is unique to your application, but is public and can be written
429 * to by other applications.
430 *
431 * Your external storage path is typically:
432 * `/storage/sdcard0/Android/data/your.app.package/files`.
433 *
434 * This is a C wrapper over `android.content.Context.getExternalFilesDir()`:
435 *
436 * https://developer.android.com/reference/android/content/Context#getExternalFilesDir()
437 *
438 * \returns the path used for external storage for this application on success
439 * or NULL on failure; call SDL_GetError() for more information.
440 *
441 * \since This function is available since SDL 3.1.3.
442 *
443 * \sa SDL_GetAndroidExternalStorageState
444 * \sa SDL_GetAndroidInternalStoragePath
445 * \sa SDL_GetAndroidCachePath
446 */
447extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void);
448
449/**
450 * Get the path used for caching data for this Android application.
451 *
452 * This path is unique to your application, but is public and can be written
453 * to by other applications.
454 *
455 * Your cache path is typically: `/data/data/your.app.package/cache/`.
456 *
457 * This is a C wrapper over `android.content.Context.getCacheDir()`:
458 *
459 * https://developer.android.com/reference/android/content/Context#getCacheDir()
460 *
461 * \returns the path used for caches for this application on success or NULL
462 * on failure; call SDL_GetError() for more information.
463 *
464 * \since This function is available since SDL 3.1.3.
465 *
466 * \sa SDL_GetAndroidInternalStoragePath
467 * \sa SDL_GetAndroidExternalStoragePath
468 */
469extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void);
470
471
472typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, bool granted);
473
474/**
475 * Request permissions at runtime, asynchronously.
476 *
477 * You do not need to call this for built-in functionality of SDL; recording
478 * from a microphone or reading images from a camera, using standard SDL APIs,
479 * will manage permission requests for you.
480 *
481 * This function never blocks. Instead, the app-supplied callback will be
482 * called when a decision has been made. This callback may happen on a
483 * different thread, and possibly much later, as it might wait on a user to
484 * respond to a system dialog. If permission has already been granted for a
485 * specific entitlement, the callback will still fire, probably on the current
486 * thread and before this function returns.
487 *
488 * If the request submission fails, this function returns -1 and the callback
489 * will NOT be called, but this should only happen in catastrophic conditions,
490 * like memory running out. Normally there will be a yes or no to the request
491 * through the callback.
492 *
493 * For the `permission` parameter, choose a value from here:
494 *
495 * https://developer.android.com/reference/android/Manifest.permission
496 *
497 * \param permission the permission to request.
498 * \param cb the callback to trigger when the request has a response.
499 * \param userdata an app-controlled pointer that is passed to the callback.
500 * \returns true if the request was submitted, false if there was an error
501 * submitting. The result of the request is only ever reported
502 * through the callback, not this return value.
503 *
504 * \threadsafety It is safe to call this function from any thread.
505 *
506 * \since This function is available since SDL 3.1.3.
507 */
508extern SDL_DECLSPEC bool SDLCALL SDL_RequestAndroidPermission(const char *permission, SDL_RequestAndroidPermissionCallback cb, void *userdata);
509
510/**
511 * Shows an Android toast notification.
512 *
513 * Toasts are a sort of lightweight notification that are unique to Android.
514 *
515 * https://developer.android.com/guide/topics/ui/notifiers/toasts
516 *
517 * Shows toast in UI thread.
518 *
519 * For the `gravity` parameter, choose a value from here, or -1 if you don't
520 * have a preference:
521 *
522 * https://developer.android.com/reference/android/view/Gravity
523 *
524 * \param message text message to be shown.
525 * \param duration 0=short, 1=long.
526 * \param gravity where the notification should appear on the screen.
527 * \param xoffset set this parameter only when gravity >=0.
528 * \param yoffset set this parameter only when gravity >=0.
529 * \returns true on success or false on failure; call SDL_GetError() for more
530 * information.
531 *
532 * \threadsafety It is safe to call this function from any thread.
533 *
534 * \since This function is available since SDL 3.1.3.
535 */
536extern SDL_DECLSPEC bool SDLCALL SDL_ShowAndroidToast(const char *message, int duration, int gravity, int xoffset, int yoffset);
537
538/**
539 * Send a user command to SDLActivity.
540 *
541 * Override "boolean onUnhandledMessage(Message msg)" to handle the message.
542 *
543 * \param command user command that must be greater or equal to 0x8000.
544 * \param param user parameter.
545 * \returns true on success or false on failure; call SDL_GetError() for more
546 * information.
547 *
548 * \threadsafety It is safe to call this function from any thread.
549 *
550 * \since This function is available since SDL 3.1.3.
551 */
552extern SDL_DECLSPEC bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int param);
553
554#endif /* SDL_PLATFORM_ANDROID */
555
556/**
557 * Query if the current device is a tablet.
558 *
559 * If SDL can't determine this, it will return false.
560 *
561 * \returns true if the device is a tablet, false otherwise.
562 *
563 * \since This function is available since SDL 3.1.3.
564 */
565extern SDL_DECLSPEC bool SDLCALL SDL_IsTablet(void);
566
567/**
568 * Query if the current device is a TV.
569 *
570 * If SDL can't determine this, it will return false.
571 *
572 * \returns true if the device is a TV, false otherwise.
573 *
574 * \since This function is available since SDL 3.1.3.
575 */
576extern SDL_DECLSPEC bool SDLCALL SDL_IsTV(void);
577
578/**
579 * Application sandbox environment.
580 *
581 * \since This enum is available since SDL 3.2.0.
582 */
591
592/**
593 * Get the application sandbox environment, if any.
594 *
595 * \returns the application sandbox environment or SDL_SANDBOX_NONE if the
596 * application is not running in a sandbox environment.
597 *
598 * \since This function is available since SDL 3.2.0.
599 */
600extern SDL_DECLSPEC SDL_Sandbox SDLCALL SDL_GetSandbox(void);
601
602
603/* Functions used by iOS app delegates to notify SDL about state changes. */
604
605/**
606 * Let iOS apps with external event handling report
607 * onApplicationWillTerminate.
608 *
609 * This functions allows iOS apps that have their own event handling to hook
610 * into SDL to generate SDL events. This maps directly to an iOS-specific
611 * event, but since it doesn't do anything iOS-specific internally, it is
612 * available on all platforms, in case it might be useful for some specific
613 * paradigm. Most apps do not need to use this directly; SDL's internal event
614 * code will handle all this for windows created by SDL_CreateWindow!
615 *
616 * \threadsafety It is safe to call this function from any thread.
617 *
618 * \since This function is available since SDL 3.1.3.
619 */
620extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillTerminate(void);
621
622/**
623 * Let iOS apps with external event handling report
624 * onApplicationDidReceiveMemoryWarning.
625 *
626 * This functions allows iOS apps that have their own event handling to hook
627 * into SDL to generate SDL events. This maps directly to an iOS-specific
628 * event, but since it doesn't do anything iOS-specific internally, it is
629 * available on all platforms, in case it might be useful for some specific
630 * paradigm. Most apps do not need to use this directly; SDL's internal event
631 * code will handle all this for windows created by SDL_CreateWindow!
632 *
633 * \threadsafety It is safe to call this function from any thread.
634 *
635 * \since This function is available since SDL 3.1.3.
636 */
637extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidReceiveMemoryWarning(void);
638
639/**
640 * Let iOS apps with external event handling report
641 * onApplicationWillResignActive.
642 *
643 * This functions allows iOS apps that have their own event handling to hook
644 * into SDL to generate SDL events. This maps directly to an iOS-specific
645 * event, but since it doesn't do anything iOS-specific internally, it is
646 * available on all platforms, in case it might be useful for some specific
647 * paradigm. Most apps do not need to use this directly; SDL's internal event
648 * code will handle all this for windows created by SDL_CreateWindow!
649 *
650 * \threadsafety It is safe to call this function from any thread.
651 *
652 * \since This function is available since SDL 3.1.3.
653 */
654extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterBackground(void);
655
656/**
657 * Let iOS apps with external event handling report
658 * onApplicationDidEnterBackground.
659 *
660 * This functions allows iOS apps that have their own event handling to hook
661 * into SDL to generate SDL events. This maps directly to an iOS-specific
662 * event, but since it doesn't do anything iOS-specific internally, it is
663 * available on all platforms, in case it might be useful for some specific
664 * paradigm. Most apps do not need to use this directly; SDL's internal event
665 * code will handle all this for windows created by SDL_CreateWindow!
666 *
667 * \threadsafety It is safe to call this function from any thread.
668 *
669 * \since This function is available since SDL 3.1.3.
670 */
671extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterBackground(void);
672
673/**
674 * Let iOS apps with external event handling report
675 * onApplicationWillEnterForeground.
676 *
677 * This functions allows iOS apps that have their own event handling to hook
678 * into SDL to generate SDL events. This maps directly to an iOS-specific
679 * event, but since it doesn't do anything iOS-specific internally, it is
680 * available on all platforms, in case it might be useful for some specific
681 * paradigm. Most apps do not need to use this directly; SDL's internal event
682 * code will handle all this for windows created by SDL_CreateWindow!
683 *
684 * \threadsafety It is safe to call this function from any thread.
685 *
686 * \since This function is available since SDL 3.1.3.
687 */
688extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationWillEnterForeground(void);
689
690/**
691 * Let iOS apps with external event handling report
692 * onApplicationDidBecomeActive.
693 *
694 * This functions allows iOS apps that have their own event handling to hook
695 * into SDL to generate SDL events. This maps directly to an iOS-specific
696 * event, but since it doesn't do anything iOS-specific internally, it is
697 * available on all platforms, in case it might be useful for some specific
698 * paradigm. Most apps do not need to use this directly; SDL's internal event
699 * code will handle all this for windows created by SDL_CreateWindow!
700 *
701 * \threadsafety It is safe to call this function from any thread.
702 *
703 * \since This function is available since SDL 3.1.3.
704 */
705extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidEnterForeground(void);
706
707#ifdef SDL_PLATFORM_IOS
708
709/**
710 * Let iOS apps with external event handling report
711 * onApplicationDidChangeStatusBarOrientation.
712 *
713 * This functions allows iOS apps that have their own event handling to hook
714 * into SDL to generate SDL events. This maps directly to an iOS-specific
715 * event, but since it doesn't do anything iOS-specific internally, it is
716 * available on all platforms, in case it might be useful for some specific
717 * paradigm. Most apps do not need to use this directly; SDL's internal event
718 * code will handle all this for windows created by SDL_CreateWindow!
719 *
720 * \threadsafety It is safe to call this function from any thread.
721 *
722 * \since This function is available since SDL 3.1.3.
723 */
724extern SDL_DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void);
725#endif
726
727/*
728 * Functions used only by GDK
729 */
730#ifdef SDL_PLATFORM_GDK
731typedef struct XTaskQueueObject *XTaskQueueHandle;
732typedef struct XUser *XUserHandle;
733
734/**
735 * Gets a reference to the global async task queue handle for GDK,
736 * initializing if needed.
737 *
738 * Once you are done with the task queue, you should call
739 * XTaskQueueCloseHandle to reduce the reference count to avoid a resource
740 * leak.
741 *
742 * \param outTaskQueue a pointer to be filled in with task queue handle.
743 * \returns true on success or false on failure; call SDL_GetError() for more
744 * information.
745 *
746 * \since This function is available since SDL 3.1.3.
747 */
748extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQueue);
749
750/**
751 * Gets a reference to the default user handle for GDK.
752 *
753 * This is effectively a synchronous version of XUserAddAsync, which always
754 * prefers the default user and allows a sign-in UI.
755 *
756 * \param outUserHandle a pointer to be filled in with the default user
757 * handle.
758 * \returns true if success or false on failure; call SDL_GetError() for more
759 * information.
760 *
761 * \since This function is available since SDL 3.1.3.
762 */
763extern SDL_DECLSPEC bool SDLCALL SDL_GetGDKDefaultUser(XUserHandle *outUserHandle);
764
765#endif
766
767/* Ends C function definitions when using C++ */
768#ifdef __cplusplus
769}
770#endif
771#include <SDL3/SDL_close_code.h>
772
773#endif /* SDL_system_h_ */
int64_t Sint64
Definition SDL_stdinc.h:381
#define bool
Definition SDL_stdinc.h:53
uint32_t Uint32
Definition SDL_stdinc.h:370
union _XEvent XEvent
Definition SDL_system.h:132
void SDL_OnApplicationWillEnterForeground(void)
bool SDL_IsTV(void)
void SDL_OnApplicationDidEnterForeground(void)
SDL_Sandbox SDL_GetSandbox(void)
bool(* SDL_X11EventHook)(void *userdata, XEvent *xevent)
Definition SDL_system.h:133
void SDL_OnApplicationDidEnterBackground(void)
SDL_Sandbox
Definition SDL_system.h:584
@ SDL_SANDBOX_FLATPAK
Definition SDL_system.h:587
@ SDL_SANDBOX_SNAP
Definition SDL_system.h:588
@ SDL_SANDBOX_UNKNOWN_CONTAINER
Definition SDL_system.h:586
@ SDL_SANDBOX_MACOS
Definition SDL_system.h:589
@ SDL_SANDBOX_NONE
Definition SDL_system.h:585
void SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata)
void SDL_OnApplicationDidReceiveMemoryWarning(void)
void SDL_OnApplicationWillEnterBackground(void)
bool SDL_IsTablet(void)
void SDL_OnApplicationWillTerminate(void)
Uint32 SDL_DisplayID
Definition SDL_video.h:75
struct SDL_Window SDL_Window
Definition SDL_video.h:165