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