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